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