There are some formatting fixes on this change: - Some blocks weren't indented correctly; - Some statements needed escape. Also the text is improved in some ways: - Variables and options are bold now; - Files path are set to italic; - Inline commands are marked; - Added a section about the tests configuration file. 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
