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## Cross-compiling 21 22A cross compiler may be configured by specifying a cross prefix. For example, 23for arm64 24 25 ./configure --arch=arm64 --cross-prefix=aarch64-linux-gnu- 26 make 27 28## clang 29 30clang may be used as an alternative to gcc. 31 32 ./configure --cc=clang 33 make 34 35clang may also be used with cross binutils when cross-compiling. For example, 36for riscv64 37 38 ./configure --arch=riscv64 --cc=clang --cflags='--target=riscv64' \ 39 --cross-prefix=riscv64-linux-gnu- 40 make 41 42## Standalone tests 43 44The tests can be built as standalone. To create and use standalone tests do: 45 46 ./configure 47 make standalone 48 (send tests/some-test somewhere) 49 (go to somewhere) 50 ./some-test 51 52`make install` will install all tests in PREFIX/share/kvm-unit-tests/tests, 53each as a standalone test. 54 55 56# Running the tests 57 58Then use the runner script to detect the correct invocation and 59invoke the test: 60 61 ./x86-run ./x86/msr.flat 62or: 63 64 ./run_tests.sh 65 66to run them all. 67 68All tests can be run using QEMU. On arm and arm64, tests can also be run using 69kvmtool. 70 71By default the runner script searches for a suitable QEMU binary in the system. 72To select a specific QEMU binary though, specify the QEMU=path/to/binary 73environment variable: 74 75 QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat 76 77To select an accelerator, for example "kvm", "hvf" or "tcg", specify the 78ACCEL=name environment variable: 79 80 ACCEL=kvm ./x86-run ./x86/msr.flat 81 82For running tests that involve migration from one QEMU instance to another 83you also need to have the "ncat" binary (from the nmap.org project) installed, 84otherwise the related tests will be skipped. kvmtool does not support migration. 85 86As for running a test with kvmtool, please configure kvm-unit-tests accordingly 87first: 88 89 ./configure --arch=arm64 --target=kvmtool 90 91then run the test(s) like with QEMU above. 92 93To select a kvmtool binary, specify the KVMTOOL=path/to/binary environment 94variable. kvmtool supports only kvm as the accelerator. 95 96## Running the tests with UEFI 97 98Check [x86/efi/README.md](./x86/efi/README.md). 99 100On arm and arm64, this is only supported with QEMU; kvmtool cannot run the 101tests under UEFI. 102 103# Tests configuration file 104 105The test case may need specific runtime configurations, for 106example, extra QEMU parameters and time to execute limited, the 107runner script reads those information from a configuration file found 108at ./ARCH/unittests.cfg. 109 110The configuration file also contain the groups (if any) each test belong 111to. So that a given group can be executed by specifying its name in the 112runner's -g option. 113 114# Unit test inputs 115 116Unit tests use QEMU's '-append args...' parameter for command line 117inputs, i.e. all args will be available as argv strings in main(). 118Additionally a file of the form 119 120 KEY=VAL 121 KEY2=VAL 122 ... 123 124may be passed with '-initrd file' to become the unit test's environ, 125which can then be accessed in the usual ways, e.g. VAL = getenv("KEY"). 126Any key=val strings can be passed, but some have reserved meanings in 127the framework. The list of reserved environment variables is below 128 129 QEMU_ACCEL either kvm, hvf or tcg 130 QEMU_VERSION_STRING string of the form `qemu -h | head -1` 131 KERNEL_VERSION_STRING string of the form `uname -r` 132 133Additionally these self-explanatory variables are reserved 134 135 QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, 136 KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION 137 138# Guarding unsafe tests 139 140Some tests are not safe to run by default, as they may crash the 141host. kvm-unit-tests provides two ways to handle tests like those. 142 143 1) Adding 'nodefault' to the groups field for the unit test in the 144 unittests.cfg file. When a unit test is in the nodefault group 145 it is only run when invoked 146 147 a) independently, `ARCH-run ARCH/test` 148 149 b) by specifying any other non-nodefault group it is in, 150 groups = nodefault mygroup : `./run_tests.sh -g mygroup` 151 152 c) by specifying all tests should be run, `./run_tests.sh -a` 153 154 2) Making the test conditional on errata in the code, 155 ``` 156 if (ERRATA(abcdef012345)) { 157 do_unsafe_test(); 158 } 159 ``` 160 161 With the errata condition the unsafe unit test is only run 162 when 163 164 a) the ERRATA_abcdef012345 environment variable is provided and 'y' 165 166 b) the ERRATA_FORCE environment variable is provided and 'y' 167 168 c) by specifying all tests should be run, `./run_tests.sh -a` 169 (The -a switch ensures the ERRATA_FORCE is provided and set 170 to 'y'.) 171 172The ./errata.txt file provides a mapping of the commits needed by errata 173conditionals to their respective minimum kernel versions. By default, 174when the user does not provide an environ, then an environ generated 175from the ./errata.txt file and the host's kernel version is provided to 176all unit tests. 177 178# Contributing 179 180## Directory structure 181 182 .: configure script, top-level Makefile, and run_tests.sh 183 ./scripts: general architecture neutral helper scripts for building and running tests 184 ./scripts/<ARCH>: architecture dependent helper scripts for building and running tests 185 ./lib: general architecture neutral services for the tests 186 ./lib/<ARCH>: architecture dependent services for the tests 187 ./<ARCH>: the sources of the tests and the created objects/images 188 189See ./ARCH/README for architecture specific documentation. 190 191## Style 192 193Currently there is a mix of indentation styles so any changes to 194existing files should be consistent with the existing style. For new 195files: 196 197 - C: please use standard linux-with-tabs, see Linux kernel 198 doc Documentation/process/coding-style.rst 199 - Shell: use TABs for indentation 200 201Exceptions: 202 203 - While the kernel standard requires 80 columns, we allow up to 120. 204 205Header guards: 206 207Please try to adhere to the following patterns when adding 208"#ifndef <...> #define <...>" header guards: 209 ./lib: _HEADER_H_ 210 ./lib/<ARCH>: _ARCH_HEADER_H_ 211 ./lib/<ARCH>/asm: _ASMARCH_HEADER_H_ 212 ./<ARCH>: ARCH_HEADER_H 213 214## Patches 215 216Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. 217 218Please prefix messages with: [kvm-unit-tests PATCH] 219 220You can add the following to .git/config to do this automatically for you: 221 222 [format] 223 subjectprefix = kvm-unit-tests PATCH 224 225Additionally it's helpful to have a common order of file types in patches. 226Our chosen order attempts to place the more declarative files before 227the code files. We also start with common code and finish with unit test 228code. git-diff's orderFile feature allows us to specify the order in a 229file. The orderFile we use is `scripts/git.difforder`; adding the config 230with `git config diff.orderFile scripts/git.difforder` enables it. 231 232We strive to follow the Linux kernels coding style so it's recommended 233to run the kernel's ./scripts/checkpatch.pl on new patches. 234 235Also run `make shellcheck` before submitting a patch which touches bash 236scripts. 237