Signed-off-by: Wainer dos Santos Moschetta <wainersm@xxxxxxxxxx>
---
See the results here: https://github.com/wainersm/kvm-unit-tests/tree/docs
README.md | 100 ++++++++++++++++++++++++++++++------------------------
1 file changed, 55 insertions(+), 45 deletions(-)
diff --git a/README.md b/README.md
index 1a9a4ab..07c5a82 100644
--- a/README.md
+++ b/README.md
@@ -13,12 +13,11 @@ To create the test images do:
./configure
make
-in this directory. Test images are created in ./<ARCH>/*.flat
+in this directory. Test images are created in *./\<ARCH\>/\*.flat*
## Standalone tests
-The tests can be built as standalone
-To create and use standalone tests do:
+The tests can be built as standalone. To create and use standalone tests do:
./configure
make standalone
@@ -26,8 +25,8 @@ To create and use standalone tests do:
(go to somewhere)
./some-test
-'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests,
-each as a standalone test.
+They are created in *./tests*. Or run `make install` to install all tests in
+*PREFIX/share/kvm-unit-tests/tests*, each as a standalone test.
# Running the tests
@@ -42,85 +41,96 @@ or:
to run them all.
-To select a specific qemu binary, specify the QEMU=<path>
+By default the runner script searches for a suitable qemu binary in the system.
+To select a specific qemu binary though, specify the **QEMU=\<path\>**
environment variable:
QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat
To select an accelerator, for example "kvm" or "tcg", specify the
-ACCEL=<name> environment variable:
+**ACCEL=\<name\>** environment variable:
ACCEL=kvm ./x86-run ./x86/msr.flat
-# Unit test inputs
+# Tests suite configuration
-Unit tests use QEMU's '-append <args...>' parameter for command line
-inputs, i.e. all args will be available as argv strings in main().
-Additionally a file of the form
+Given that each test case may need specific runtime configurations as, for
+example, extra QEMU parameters and limited time to execute, the
+runner script reads those information from a configuration file found
+at *./\<ARCH\>/unittests.cfg*. This file also contain the group of tests which
+can be ran with the script's **-g** option.
+
+## Unit test inputs
-KEY=VAL
-KEY2=VAL
-...
+Unit tests use QEMU's **-append \<args...\>** parameter for command line
+inputs, i.e. all args will be available as *argv* strings in *main()*.
+Additionally a file of the form
-may be passed with '-initrd <file>' to become the unit test's environ,
-which can then be accessed in the usual ways, e.g. VAL = getenv("KEY")
-Any key=val strings can be passed, but some have reserved meanings in
-the framework. The list of reserved environment variables is below
+ KEY=VAL
+ KEY2=VAL
+ ...
- QEMU_ACCEL ... either kvm or tcg
- QEMU_VERSION_STRING ... string of the form `qemu -h | head -1`
- KERNEL_VERSION_STRING ... string of the form `uname -r`
+may be passed with **-initrd \<file\>** to become the unit test's environ,
+which can then be accessed in the usual ways, e.g. `VAL = getenv("KEY")`.
+ Any *key=val* strings can be passed, but some have reserved meanings in
+the framework. The list of reserved environment variables is:
-Additionally these self-explanatory variables are reserved
+ QEMU_ACCEL either kvm or tcg
+ QEMU_VERSION_STRING string of the form `qemu -h | head -1`
+ KERNEL_VERSION_STRING string of the form `uname -r`
- QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL,
- KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION
+Additionally these self-explanatory variables are reserved: *QEMU\_MAJOR*, *QEMU\_MINOR*, *QEMU\_MICRO*, *KERNEL\_VERSION*, *KERNEL\_PATCHLEVEL*, *KERNEL\_SUBLEVEL*, *KERNEL\_EXTRAVERSION*.
# Guarding unsafe tests
Some tests are not safe to run by default, as they may crash the
host. kvm-unit-tests provides two ways to handle tests like those.
- 1) Adding 'nodefault' to the groups field for the unit test in the
- unittests.cfg file. When a unit test is in the nodefault group
+ 1) Adding **nodefault** to the groups field for the unit test in the
+ *unittests.cfg* file. When a unit test is in the *nodefault* group
it is only run when invoked
- a) independently, arch-run arch/test
- b) by specifying any other non-nodefault group it is in,
- groups = nodefault,mygroup : ./run_tests.sh -g mygroup
- c) by specifying all tests should be run, ./run_tests.sh -a
+ a. independently, `<ARCH>-run <ARCH>/<TEST>.flat`
+
+ b. by specifying any other non-nodefault group it is in,
+ *groups = nodefault,mygroup* : `./run_tests.sh -g mygroup`
+
+ c. by specifying all tests should be run, `./run_tests.sh -a`
2) Making the test conditional on errata in the code,
+ ```
if (ERRATA(abcdef012345)) {
do_unsafe_test();
}
-
+ ```
With the errata condition the unsafe unit test is only run
when
- a) the ERRATA_abcdef012345 environ variable is provided and 'y'
- b) the ERRATA_FORCE environ variable is provided and 'y'
- c) by specifying all tests should be run, ./run_tests.sh -a
- (The -a switch ensures the ERRATA_FORCE is provided and set
+ a) the *ERRATA\_abcdef012345* environment variable is provided and 'y'
+
+ b) the **ERRATA_FORCE** environment variable is provided and 'y'
+
+ c) by specifying all tests should be run, `./run_tests.sh -a`
+ (The **-a** switch ensures the **ERRATA_FORCE** is provided and set
to 'y'.)
-The errata.txt file provides a mapping of the commits needed by errata
+The *./errata.txt* file provides a mapping of the commits needed by errata
conditionals to their respective minimum kernel versions. By default,
when the user does not provide an environ, then an environ generated
-from the errata.txt file and the host's kernel version is provided to
+from the *./errata.txt* file and the host's kernel version is provided to
all unit tests.
# Contributing
## Directory structure
- .: configure script, top-level Makefile, and run_tests.sh
- ./scripts: helper scripts for building and running tests
- ./lib: general architecture neutral services for the tests
- ./lib/<ARCH>: architecture dependent services for the tests
- ./<ARCH>: the sources of the tests and the created objects/images
+ .: configure script, top-level Makefile, and run_tests.sh
+ ./scripts: helper scripts for building and running tests
+ ./lib: general architecture neutral services for the tests
+ ./lib/<ARCH>: architecture dependent services for the tests
+ ./<ARCH>: the sources of the tests and the created objects/images
-See <ARCH>/README for architecture specific documentation.
+See *./\<ARCH\>/README* for architecture specific documentation.
## Style
@@ -129,7 +139,7 @@ existing files should be consistent with the existing style. For new
files:
- C: please use standard linux-with-tabs, see Linux kernel
- doc Documentation/process/coding-style.rst
+ doc *Documentation/process/coding-style.rst*
- Shell: use TABs for indentation
Exceptions:
@@ -142,7 +152,7 @@ Patches are welcome at the KVM mailing list <kvm@xxxxxxxxxxxxxxx>.
Please prefix messages with: [kvm-unit-tests PATCH]
-You can add the following to .git/config to do this automatically for you:
+You can add the following to *.git/config* to do this automatically for you:
[format]
subjectprefix = kvm-unit-tests PATCH
--
2.23.0
