xref: /kvm-unit-tests/README.md (revision f3f338619e4938c2509f5c691adc1f331b07c203)
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