1# Welcome to kvm-unit-tests 2 3See http://www.linux-kvm.org/page/KVM-unit-tests for a high-level 4description of this project, as well as running tests and adding 5tests HOWTOs. 6 7# Building the tests 8 9This directory contains sources for a kvm test suite. 10 11To create the test images do: 12 13 ./configure 14 make 15 16in this directory. Test images are created in ./<ARCH>/*.flat 17 18## Standalone tests 19 20The tests can be built as standalone 21To create and use standalone tests do: 22 23 ./configure 24 make standalone 25 (send tests/some-test somewhere) 26 (go to somewhere) 27 ./some-test 28 29'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests, 30each as a standalone test. 31 32 33# Running the tests 34 35Then use the runner script to detect the correct invocation and 36invoke the test: 37 38 ./x86-run ./x86/msr.flat 39or: 40 41 ./run_tests.sh 42 43to run them all. 44 45To select a specific qemu binary, specify the QEMU=<path> 46environment variable: 47 48 QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat 49 50To select an accelerator, for example "kvm" or "tcg", specify the 51ACCEL=<name> environment variable: 52 53 ACCEL=kvm ./x86-run ./x86/msr.flat 54 55# Unit test inputs 56 57Unit tests use QEMU's '-append <args...>' parameter for command line 58inputs, i.e. all args will be available as argv strings in main(). 59Additionally a file of the form 60 61KEY=VAL 62KEY2=VAL 63... 64 65may be passed with '-initrd <file>' to become the unit test's environ, 66which can then be accessed in the usual ways, e.g. VAL = getenv("KEY") 67Any key=val strings can be passed, but some have reserved meanings in 68the framework. The list of reserved environment variables is below 69 70 QEMU_ACCEL ... either kvm or tcg 71 QEMU_VERSION_STRING ... string of the form `qemu -h | head -1` 72 KERNEL_VERSION_STRING ... string of the form `uname -r` 73 74Additionally these self-explanatory variables are reserved 75 76 QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, 77 KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION 78 79# Guarding unsafe tests 80 81Some tests are not safe to run by default, as they may crash the 82host. kvm-unit-tests provides two ways to handle tests like those. 83 84 1) Adding 'nodefault' to the groups field for the unit test in the 85 unittests.cfg file. When a unit test is in the nodefault group 86 it is only run when invoked 87 88 a) independently, arch-run arch/test 89 b) by specifying any other non-nodefault group it is in, 90 groups = nodefault,mygroup : ./run_tests.sh -g mygroup 91 c) by specifying all tests should be run, ./run_tests.sh -a 92 93 2) Making the test conditional on errata in the code, 94 if (ERRATA(abcdef012345)) { 95 do_unsafe_test(); 96 } 97 98 With the errata condition the unsafe unit test is only run 99 when 100 101 a) the ERRATA_abcdef012345 environ variable is provided and 'y' 102 b) the ERRATA_FORCE environ variable is provided and 'y' 103 c) by specifying all tests should be run, ./run_tests.sh -a 104 (The -a switch ensures the ERRATA_FORCE is provided and set 105 to 'y'.) 106 107The errata.txt file provides a mapping of the commits needed by errata 108conditionals to their respective minimum kernel versions. By default, 109when the user does not provide an environ, then an environ generated 110from the errata.txt file and the host's kernel version is provided to 111all unit tests. 112 113# Contributing 114 115## Directory structure 116 117 .: configure script, top-level Makefile, and run_tests.sh 118 ./scripts: helper scripts for building and running tests 119 ./lib: general architecture neutral services for the tests 120 ./lib/<ARCH>: architecture dependent services for the tests 121 ./<ARCH>: the sources of the tests and the created objects/images 122 123See <ARCH>/README for architecture specific documentation. 124 125## Style 126 127Currently there is a mix of indentation styles so any changes to 128existing files should be consistent with the existing style. For new 129files: 130 131 - C: please use standard linux-with-tabs, see Linux kernel 132 doc Documentation/process/coding-style.rst 133 - Shell: use TABs for indentation 134 135Exceptions: 136 137 - While the kernel standard requires 80 columns, we allow up to 120. 138 139## Patches 140 141Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. 142 143Please prefix messages with: [kvm-unit-tests PATCH] 144 145You can add the following to .git/config to do this automatically for you: 146 147 [format] 148 subjectprefix = kvm-unit-tests PATCH 149 150Additionally it's helpful to have a common order of file types in patches. 151Our chosen order attempts to place the more declarative files before 152the code files. We also start with common code and finish with unit test 153code. git-diff's orderFile feature allows us to specify the order in a 154file. The orderFile we use is `scripts/git.difforder`. Adding the config 155with `git config diff.orderFile scripts/git.difforder` enables it. 156