xref: /kvm-unit-tests/README.md (revision 97b5f9553a48a15296462dc4c6170200b0dd70b8) 
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
18## Standalone tests
19
20The tests can be built as standalone.  To create and use standalone tests do:
21
22    ./configure
23    make standalone
24    (send tests/some-test somewhere)
25    (go to somewhere)
26    ./some-test
27
28`make install` will install all tests in PREFIX/share/kvm-unit-tests/tests,
29each as a standalone test.
30
31
32# Running the tests
33
34Then use the runner script to detect the correct invocation and
35invoke the test:
36
37    ./x86-run ./x86/msr.flat
38or:
39
40    ./run_tests.sh
41
42to run them all.
43
44By default the runner script searches for a suitable QEMU binary in the system.
45To select a specific QEMU binary though, specify the QEMU=path/to/binary
46environment variable:
47
48    QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat
49
50To select an accelerator, for example "kvm" or "tcg", specify the
51ACCEL=name environment variable:
52
53    ACCEL=kvm ./x86-run ./x86/msr.flat
54
55# Tests configuration file
56
57The test case may need specific runtime configurations, for
58example, extra QEMU parameters and time to execute limited, the
59runner script reads those information from a configuration file found
60at ./ARCH/unittests.cfg.
61
62The configuration file also contain the groups (if any) each test belong
63to.  So that a given group can be executed by specifying its name in the
64runner's -g option.
65
66# Unit test inputs
67
68Unit tests use QEMU's '-append args...' parameter for command line
69inputs, i.e. all args will be available as argv strings in main().
70Additionally a file of the form
71
72    KEY=VAL
73    KEY2=VAL
74    ...
75
76may be passed with '-initrd file' to become the unit test's environ,
77which can then be accessed in the usual ways, e.g. VAL = getenv("KEY").
78Any key=val strings can be passed, but some have reserved meanings in
79the framework.  The list of reserved environment variables is below
80
81    QEMU_ACCEL                   either kvm or tcg
82    QEMU_VERSION_STRING          string of the form `qemu -h | head -1`
83    KERNEL_VERSION_STRING        string of the form `uname -r`
84
85Additionally these self-explanatory variables are reserved
86
87    QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL,
88    KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION
89
90# Guarding unsafe tests
91
92Some tests are not safe to run by default, as they may crash the
93host. kvm-unit-tests provides two ways to handle tests like those.
94
95 1) Adding 'nodefault' to the groups field for the unit test in the
96    unittests.cfg file.  When a unit test is in the nodefault group
97    it is only run when invoked
98
99     a) independently, `ARCH-run ARCH/test`
100
101     b) by specifying any other non-nodefault group it is in,
102        groups = nodefault,mygroup : `./run_tests.sh -g mygroup`
103
104     c) by specifying all tests should be run, `./run_tests.sh -a`
105
106 2) Making the test conditional on errata in the code,
107    ```
108    if (ERRATA(abcdef012345)) {
109        do_unsafe_test();
110    }
111    ```
112
113    With the errata condition the unsafe unit test is only run
114    when
115
116    a) the ERRATA_abcdef012345 environment variable is provided and 'y'
117
118    b) the ERRATA_FORCE environment variable is provided and 'y'
119
120    c) by specifying all tests should be run, `./run_tests.sh -a`
121       (The -a switch ensures the ERRATA_FORCE is provided and set
122        to 'y'.)
123
124The ./errata.txt file provides a mapping of the commits needed by errata
125conditionals to their respective minimum kernel versions.  By default,
126when the user does not provide an environ, then an environ generated
127from the ./errata.txt file and the host's kernel version is provided to
128all unit tests.
129
130# Contributing
131
132## Directory structure
133
134    .:                  configure script, top-level Makefile, and run_tests.sh
135    ./scripts:          helper scripts for building and running tests
136    ./lib:              general architecture neutral services for the tests
137    ./lib/<ARCH>:       architecture dependent services for the tests
138    ./<ARCH>:           the sources of the tests and the created objects/images
139
140See ./ARCH/README for architecture specific documentation.
141
142## Style
143
144Currently there is a mix of indentation styles so any changes to
145existing files should be consistent with the existing style.  For new
146files:
147
148  - C: please use standard linux-with-tabs, see Linux kernel
149    doc Documentation/process/coding-style.rst
150  - Shell: use TABs for indentation
151
152Exceptions:
153
154  - While the kernel standard requires 80 columns, we allow up to 120.
155
156## Patches
157
158Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>.
159
160Please prefix messages with: [kvm-unit-tests PATCH]
161
162You can add the following to .git/config to do this automatically for you:
163
164    [format]
165        subjectprefix = kvm-unit-tests PATCH
166
167Additionally it's helpful to have a common order of file types in patches.
168Our chosen order attempts to place the more declarative files before
169the code files.  We also start with common code and finish with unit test
170code. git-diff's orderFile feature allows us to specify the order in a
171file.  The orderFile we use is `scripts/git.difforder`; adding the config
172with `git config diff.orderFile scripts/git.difforder` enables it.
173