Introductory documentation

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>

diff --git a/Doxyfile b/Doxyfile
index 4a2a21b534b6cf0e01c2eb9bc66f28112f009981..097edc0bd5ef20ab1c916cb8786bdb34042cccd7 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -871,7 +871,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = .
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and

diff --git a/Makefile b/Makefile
index c2cd9cea3000990ce8c63a3fd059c8dfb8c4faf1..71e3767a297ec0ddb2ccf2870559075305781263 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -29,4 +29,4 @@ distclean: clean
 
 .PHONY: doxygen
 doxygen: Doxyfile
-       doxygen Doxyfile
+       doxygen Doxyfile > /dev/null

diff --git a/docs/all-tests.dox b/docs/all-tests.dox
new file mode 100644 (file)
index 0000000..13e527f
--- /dev/null
+++ b/docs/all-tests.dox
@@ -0,0 +1,15 @@
+/**
+@page test-index Test index
+@tableofcontents
+
+Index of all tests, sorted by category.
+
+
+@section index-special Special tests
+
+@subpage test-example - A hello-world example, more as a development reference
+than useful test.
+
+@subpage test-selftest - A set of sanity tests of the framework environment
+and functionality.
+*/

diff --git a/docs/mainpage.dox b/docs/mainpage.dox
new file mode 100644 (file)
index 0000000..2fca21b
--- /dev/null
+++ b/docs/mainpage.dox
@@ -0,0 +1,70 @@
+/**
+@mainpage Xen Test Framework
+@tableofcontents
+
+@section intro Introduction
+
+This is both a framework for creating microkernel-based tests, and a suite of
+tests built using the framework.
+
+The microkernel boots, runs a set of related tests, and report the overall
+status on the configured consoles.  Automating a suite of tests simply
+involves booting each microkernel and checking the final printed line on the
+guest's console.
+
+The build system and library abstractions are specifically designed to make it
+easy to write code once and compile it for multiple different environments
+(virtual machines).
+
+The current environments supported are:
+- `pv32` - 32bit PV guest (PAE paging).
+- `pv64` - 64bit PV guest.
+- `hvm32` - 32bit HVM guest (PAE paging).
+- `hvm64` - 64bit HVM guest.
+
+
+@section getting-started Getting Started
+
+To obtain and build:
+
+    $ git clone git://xenbits.xen.org/people/andrewcoop/xen-test-framework.git
+    $ cd xen-test-framework
+    $ make -j4
+
+To run tests: (see @ref errata first)
+
+    # cd tests/example
+    # xl create test-pv32-example.cfg
+    # cat /var/log/xen/console/guest-test-pv32-example.log
+    --- Xen Test Framework ---
+    Environment: PV 32bit
+    Hello World
+    Test result: SUCCESS
+
+
+@section errata Errata
+
+- Running `pv32` tests requires booting Xen with `"smep=0"` on IvyBridge and
+  newer hardware, and with `"smap=0"` on Broadwell and newer hardware, as
+  there is not clean separation between the paging settings of Xen and the
+  guest.
+
+- For kernel paths, `xl` accepts either an absolute path, a path relative to
+  `/etc/xen/` or relative to `$CWD`.  The `kernel=` path for a PV guest
+  typically needs turning into an absolute path on the test system.
+
+- For firmware override, `xl` accepts either an absolute path, or a path
+  relative to `$libdir/xen/boot`.  The `firmware_override=` path for an HVM
+  test typically needs turning into an absolute path on the test system.
+
+
+@section further Further Information
+
+@subsection test-idx Test Index
+@subpage test-index
+
+
+@section licence Licence
+@include COPYING
+
+*/

diff --git a/include/arch/x86/symbolic-const.h b/include/arch/x86/symbolic-const.h
index 9d762a3948809f539887001a54eedbfa24ae5a91..cb9d9b2648e5e1db36161525b0fe33e9b550c781 100644 (file)
--- a/include/arch/x86/symbolic-const.h
+++ b/include/arch/x86/symbolic-const.h
@@ -14,7 +14,7 @@
 /**
  * Tokenise and OR together.
  *
- * For each varadic, tokenise with 't' and OR together.
+ * For each varadic parameter, tokenise with 't' and OR together.
  *
  * @param t   Common stem partial token.
  * @param ... Partial tokens.

diff --git a/tests/example/main.c b/tests/example/main.c
index c07e9342d2a44ef1e3f9fe63de8f53684d2a70e1..d5428b5c8e8d98dfb96060395f1898ce92e20a2f 100644 (file)
--- a/tests/example/main.c
+++ b/tests/example/main.c
@@ -1,3 +1,11 @@
+/**
+ * @file tests/example/main.c
+ * @ref test-example - Hello World testcase.
+ *
+ * @page test-example Example
+ *
+ * A Hello World XTF testcase.
+ */
 #include <xtf/lib.h>
 
 void test_main(void)

diff --git a/tests/selftest/main.c b/tests/selftest/main.c
index e33df9a0a5f5aa45df94d2f4e3f1ba606912756c..fc917a6c1a96b63ed21133fed2507dd820804a80 100644 (file)
--- a/tests/selftest/main.c
+++ b/tests/selftest/main.c
@@ -1,3 +1,12 @@
+/**
+ * @file tests/selftest/main.c
+ * @ref test-selftest - Sanity tests for the XTF environment.
+ *
+ * @page test-selftest Selftest
+ *
+ * Sanity tests for the framework environment and functionality.  Failure of
+ * these tests tend to suggest bugs with the framework itself.
+ */
 #include <xtf/lib.h>
 
 #include <arch/x86/processor.h>