Misc documentation improvements

 * Update the test running examples to use ./xtf-runner
 * Correct two descriptions of issues fixed in Xen 4.7

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

diff --git a/docs/introduction.dox b/docs/introduction.dox
index 5d2807d70a5165084f75c2bcfcdd2dac9fbee9ed..b178e9f943b5446876b11250acfe33165d2486aa 100644 (file)
--- a/docs/introduction.dox
+++ b/docs/introduction.dox
@@ -152,13 +152,19 @@ with paths appropriate for the system under test.
 
 A test will by default write synchronously to all available consoles:
 
-    # xl create tests/example/test-hvm64-example.cfg
-    # cat /var/log/xen/console/guest-test-hvm64-example.log
+    # ./xtf-runner test-hvm64-example
+    Executing 'xl create -p tests/example/test-hvm64-example.cfg'
+    Parsing config from tests/example/test-hvm64-example.cfg
+    Executing 'xl console test-hvm64-example'
+    Executing 'xl unpause test-hvm64-example'
     --- Xen Test Framework ---
     Environment: HVM 64bit (Long mode 4 levels)
     Hello World
     Test result: SUCCESS
 
+    Combined test results:
+    test-hvm64-example                       SUCCESS
+
 The result is covered by the report.h API.  In short, the options are:
 
 - Success

diff --git a/docs/mainpage.dox b/docs/mainpage.dox
index 942929ea537a42b198876ff3cd0c5100fa0ba4a2..ca86ca2aeed98d0825428238aef9478abb2a8035 100644 (file)
--- a/docs/mainpage.dox
+++ b/docs/mainpage.dox
@@ -44,21 +44,30 @@ To obtain and build:
 
 To run tests on a Xen host: (see @ref errata first)
 
-    # xl create tests/example/test-pv64-example.cfg
-    # cat /var/log/xen/console/guest-test-pv64-example.log
+    # ./xtf-runner test-pv64-example
+    Executing 'xl create -p tests/example/test-pv64-example.cfg'
+    Parsing config from tests/example/test-pv64-example.cfg
+    Executing 'xl console test-pv64-example'
+    Executing 'xl unpause test-pv64-example'
     --- Xen Test Framework ---
     Environment: PV 64bit (Long mode 4 levels)
     Hello World
     Test result: SUCCESS
 
+    Combined test results:
+    test-pv64-example                        SUCCESS
+
 
 @section errata Errata
 
-- Xen 4.7 and earlier running on hardware with SMEP (Intel IvyBridge/AMD
+- Xen 4.6 and earlier running on hardware with SMEP (Intel IvyBridge/AMD
   Excavator and later) or SMAP (Intel Broadwell/AMD Zen or later) leaked its
   SMEP/SMAP settings into 32bit PV guests, which interferes with some tests.
-  To run those tests against Xen 4.6 or earlier on that hardware, Xen must be
-  booted with `"smep=0 smap=0"`.
+  Xen 4.7 and later is fixed not to leak its SMAP/SMEP settings.
+
+  To run certain pv32pae tests against Xen 4.6 or earlier on such hardware,
+  Xen must be booted with `"smep=0 smap=0"`.  Affected pv32pae tests will
+  probe for leaked settings and panic with a suitable error.
 
 - For the paths of binaries, `xl` accepts either an absolute path, or certain
   relative paths (`/etc/xen/` or `$CWD` for `kernel=`, `$libdir/xen/boot` for

diff --git a/tests/invlpg/main.c b/tests/invlpg/main.c
index 11955bd7ae99017775c08f58eca69d7773821e0f..ba253709817ca3737d16f6acdb13ba1a8de34fcd 100644 (file)
--- a/tests/invlpg/main.c
+++ b/tests/invlpg/main.c
@@ -74,9 +74,9 @@
  *
  * This part of the test is applicable to non-paged environments.
  *
- * @todo Find a better way dealing with forced emulation.  Xen currently
- * crashes the domain if it finds an invlpg instruction while in hap mode,
- * which is unhelpful when trying to test behaviour.
+ * @todo Find a better way dealing with forced emulation.  Versions of Xen
+ * older than 4.7 crash the domain if they find an invlpg instruction while in
+ * hap mode, which is unhelpful when trying to test behaviour.
  *
  * @see tests/invlpg/main.c
  */

diff --git a/tests/xsa-168/main.c b/tests/xsa-168/main.c
index 9c02f03c506180806d17db594eb1bcc777403fd4..a330f47e67dff80124bd9280aae35e4560f987f2 100644 (file)
--- a/tests/xsa-168/main.c
+++ b/tests/xsa-168/main.c
@@ -13,10 +13,10 @@
  * for non-canonical addresses.  When using HAP, the instructions are not
  * intercepted, and dealt with by hardware.
  *
- * However with shadow paging, the instructions are intercepted to prevent
- * @#PF's from not-yet-populated shadows.  On VT-x hardware, this ends up
- * turning into a `invvpid` in Xen, which does suffer a @#GP on a
- * non-canonical address.
+ * However with shadow paging, the instructions are intercepted to allow the
+ * shadow subsystem to performance maintenance of the shadows themselves.  On
+ * VT-x hardware, this ends up turning into a `invvpid` in Xen, which does
+ * suffer a @#GP on a non-canonical address.
  *
  * To cause Xen to execute an `invvpid` instruction, the address (omitting the
  * sign extension) must be a small page.  This is covered in XTF because the