xref: /kvm-unit-tests/README.md (revision d864b580863bc86c89f92936b115eb3303756f8a)
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:          general architecture neutral helper scripts for building and running tests
138    ./scripts/<ARCH>:   architecture dependent helper scripts for building and running tests
139    ./lib:              general architecture neutral services for the tests
140    ./lib/<ARCH>:       architecture dependent services for the tests
141    ./<ARCH>:           the sources of the tests and the created objects/images
142
143See ./ARCH/README for architecture specific documentation.
144
145## Style
146
147Currently there is a mix of indentation styles so any changes to
148existing files should be consistent with the existing style.  For new
149files:
150
151  - C: please use standard linux-with-tabs, see Linux kernel
152    doc Documentation/process/coding-style.rst
153  - Shell: use TABs for indentation
154
155Exceptions:
156
157  - While the kernel standard requires 80 columns, we allow up to 120.
158
159## Patches
160
161Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>.
162
163Please prefix messages with: [kvm-unit-tests PATCH]
164
165You can add the following to .git/config to do this automatically for you:
166
167    [format]
168        subjectprefix = kvm-unit-tests PATCH
169
170Additionally it's helpful to have a common order of file types in patches.
171Our chosen order attempts to place the more declarative files before
172the code files.  We also start with common code and finish with unit test
173code. git-diff's orderFile feature allows us to specify the order in a
174file.  The orderFile we use is `scripts/git.difforder`; adding the config
175with `git config diff.orderFile scripts/git.difforder` enables it.
176