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