From: Andrew Cooper <andrew.cooper3@citrix.com>
Date: Wed, 6 Jan 2016 12:50:16 +0000 (+0000)
Subject: Introductory documentation
X-Git-Url: http://xenbits.xensource.com/gitweb?a=commitdiff_plain;h=d0a96ba4487ddd6b869c17b2457649d5ccc37629;p=people%2Froyger%2Fxen-test-framework.git

Introductory documentation

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

diff --git a/Doxyfile b/Doxyfile
index 4a2a21b..097edc0 100644
--- 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 c2cd9ce..71e3767 100644
--- 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
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
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 9d762a3..cb9d9b2 100644
--- 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 c07e934..d5428b5 100644
--- 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 e33df9a..fc917a6 100644
--- 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>