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 50# Unit test inputs 51 52Unit tests use QEMU's '-append <args...>' parameter for command line 53inputs, i.e. all args will be available as argv strings in main(). 54Additionally a file of the form 55 56KEY=VAL 57KEY2=VAL 58... 59 60may be passed with '-initrd <file>' to become the unit test's environ, 61which can then be accessed in the usual ways, e.g. VAL = getenv("KEY") 62Any key=val strings can be passed, but some have reserved meanings in 63the framework. The list of reserved environment variables is below 64 65 QEMU_ACCEL ... either kvm or tcg 66 QEMU_VERSION_STRING ... string of the form `qemu -h | head -1` 67 KERNEL_VERSION_STRING ... string of the form `uname -r` 68 69Additionally these self-explanatory variables are reserved 70 71 QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, 72 KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION 73 74# Guarding unsafe tests 75 76Some tests are not safe to run by default, as they may crash the 77host. kvm-unit-tests provides two ways to handle tests like those. 78 79 1) Adding 'nodefault' to the groups field for the unit test in the 80 unittests.cfg file. When a unit test is in the nodefault group 81 it is only run when invoked 82 83 a) independently, arch-run arch/test 84 b) by specifying any other non-nodefault group it is in, 85 groups = nodefault,mygroup : ./run_tests.sh -g mygroup 86 c) by specifying all tests should be run, ./run_tests.sh -a 87 88 2) Making the test conditional on errata in the code, 89 if (ERRATA(abcdef012345)) { 90 do_unsafe_test(); 91 } 92 93 With the errata condition the unsafe unit test is only run 94 when 95 96 a) the ERRATA_abcdef012345 environ variable is provided and 'y' 97 b) the ERRATA_FORCE environ variable is provided and 'y' 98 c) by specifying all tests should be run, ./run_tests.sh -a 99 (The -a switch ensures the ERRATA_FORCE is provided and set 100 to 'y'.) 101 102The errata.txt file provides a mapping of the commits needed by errata 103conditionals to their respective minimum kernel versions. By default, 104when the user does not provide an environ, then an environ generated 105from the errata.txt file and the host's kernel version is provided to 106all unit tests. 107 108# Contributing 109 110## Directory structure 111 112 .: configure script, top-level Makefile, and run_tests.sh 113 ./scripts: helper scripts for building and running tests 114 ./lib: general architecture neutral services for the tests 115 ./lib/<ARCH>: architecture dependent services for the tests 116 ./<ARCH>: the sources of the tests and the created objects/images 117 118See <ARCH>/README for architecture specific documentation. 119 120## Style 121 122Currently there is a mix of indentation styles so any changes to 123existing files should be consistent with the existing style. For new 124files: 125 126 - C: please use standard linux-with-tabs, see Linux kernel 127 doc Documentation/process/coding-style.rst 128 - Shell: use TABs for indentation 129 130Exceptions: 131 132 - While the kernel standard requires 80 columns, we allow up to 120. 133 134## Patches 135 136Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. 137 138Please prefix messages with: [kvm-unit-tests PATCH] 139 140You can add the following to .git/config to do this automatically for you: 141 142 [format] 143 subjectprefix = kvm-unit-tests PATCH 144 145Additionally it's helpful to have a common order of file types in patches. 146Our chosen order attempts to place the more declarative files before 147the code files. We also start with common code and finish with unit test 148code. git-diff's orderFile feature allows us to specify the order in a 149file. The orderFile we use is `scripts/git.difforder`. Adding the config 150with `git config diff.orderFile scripts/git.difforder` enables it. 151