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, arm64, riscv32, and riscv64 tests can 69also be run using kvmtool. 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 100This is only supported with QEMU; kvmtool cannot run the tests under UEFI. 101 102# Tests configuration file 103 104The test case may need specific runtime configurations, for 105example, extra QEMU parameters and time to execute limited, the 106runner script reads those information from a configuration file found 107at ./ARCH/unittests.cfg. 108 109The configuration file also contain the groups (if any) each test belong 110to. So that a given group can be executed by specifying its name in the 111runner's -g option. 112 113# Unit test inputs 114 115Unit tests use QEMU's '-append args...' parameter for command line 116inputs, i.e. all args will be available as argv strings in main(). 117Additionally a file of the form 118 119 KEY=VAL 120 KEY2=VAL 121 ... 122 123may be passed with '-initrd file' to become the unit test's environ, 124which can then be accessed in the usual ways, e.g. VAL = getenv("KEY"). 125Any key=val strings can be passed, but some have reserved meanings in 126the framework. The list of reserved environment variables is below 127 128 QEMU_ACCEL either kvm, hvf or tcg 129 QEMU_VERSION_STRING string of the form `qemu -h | head -1` 130 KERNEL_VERSION_STRING string of the form `uname -r` 131 132Additionally these self-explanatory variables are reserved 133 134 QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, 135 KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION 136 137# Guarding unsafe tests 138 139Some tests are not safe to run by default, as they may crash the 140host. kvm-unit-tests provides two ways to handle tests like those. 141 142 1) Adding 'nodefault' to the groups field for the unit test in the 143 unittests.cfg file. When a unit test is in the nodefault group 144 it is only run when invoked 145 146 a) independently, `ARCH-run ARCH/test` 147 148 b) by specifying any other non-nodefault group it is in, 149 groups = nodefault mygroup : `./run_tests.sh -g mygroup` 150 151 c) by specifying all tests should be run, `./run_tests.sh -a` 152 153 2) Making the test conditional on errata in the code, 154 ``` 155 if (ERRATA(abcdef012345)) { 156 do_unsafe_test(); 157 } 158 ``` 159 160 With the errata condition the unsafe unit test is only run 161 when 162 163 a) the ERRATA_abcdef012345 environment variable is provided and 'y' 164 165 b) the ERRATA_FORCE environment variable is provided and 'y' 166 167 c) by specifying all tests should be run, `./run_tests.sh -a` 168 (The -a switch ensures the ERRATA_FORCE is provided and set 169 to 'y'.) 170 171The ./errata.txt file provides a mapping of the commits needed by errata 172conditionals to their respective minimum kernel versions. By default, 173when the user does not provide an environ, then an environ generated 174from the ./errata.txt file and the host's kernel version is provided to 175all unit tests. 176 177# Contributing 178 179## Directory structure 180 181 .: configure script, top-level Makefile, and run_tests.sh 182 ./scripts: general architecture neutral helper scripts for building and running tests 183 ./scripts/<ARCH>: architecture dependent helper scripts for building and running tests 184 ./lib: general architecture neutral services for the tests 185 ./lib/<ARCH>: architecture dependent services for the tests 186 ./<ARCH>: the sources of the tests and the created objects/images 187 188See ./ARCH/README for architecture specific documentation. 189 190## Style 191 192Currently there is a mix of indentation styles so any changes to 193existing files should be consistent with the existing style. For new 194files: 195 196 - C: please use standard linux-with-tabs, see Linux kernel 197 doc Documentation/process/coding-style.rst 198 - Shell: use TABs for indentation 199 200Exceptions: 201 202 - While the kernel standard requires 80 columns, we allow up to 120. 203 204Header guards: 205 206Please try to adhere to the following patterns when adding 207"#ifndef <...> #define <...>" header guards: 208 ./lib: _HEADER_H_ 209 ./lib/<ARCH>: _ARCH_HEADER_H_ 210 ./lib/<ARCH>/asm: _ASMARCH_HEADER_H_ 211 ./<ARCH>: ARCH_HEADER_H 212 213## Patches 214 215Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. 216 217Please prefix messages with: [kvm-unit-tests PATCH] 218 219You can add the following to .git/config to do this automatically for you: 220 221 [format] 222 subjectprefix = kvm-unit-tests PATCH 223 224Additionally it's helpful to have a common order of file types in patches. 225Our chosen order attempts to place the more declarative files before 226the code files. We also start with common code and finish with unit test 227code. git-diff's orderFile feature allows us to specify the order in a 228file. The orderFile we use is `scripts/git.difforder`; adding the config 229with `git config diff.orderFile scripts/git.difforder` enables it. 230 231We strive to follow the Linux kernels coding style so it's recommended 232to run the kernel's ./scripts/checkpatch.pl on new patches. 233 234Also run `make shellcheck` before submitting a patch which touches bash 235scripts. 236