README.md 5.42 KB
Newer Older
1
2
3
4
5
6
7
8
# Welcome to kvm-unit-tests

See http://www.linux-kvm.org/page/KVM-unit-tests for a high-level
description of this project, as well as running tests and adding
tests HOWTOs.

# Building the tests

9
This directory contains sources for a KVM test suite.
10
11
12
13
14
15

To create the test images do:

    ./configure
    make

16
in this directory.  Test images are created in ./ARCH/\*.flat
17

18
19
NOTE: GCC cross-compiler is required for [build on macOS](README.macOS.md).

20
21
## Standalone tests

22
The tests can be built as standalone.  To create and use standalone tests do:
23
24
25
26
27
28
29

    ./configure
    make standalone
    (send tests/some-test somewhere)
    (go to somewhere)
    ./some-test

30
`make install` will install all tests in PREFIX/share/kvm-unit-tests/tests,
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
each as a standalone test.


# Running the tests

Then use the runner script to detect the correct invocation and
invoke the test:

    ./x86-run ./x86/msr.flat
or:

    ./run_tests.sh

to run them all.

46
47
By default the runner script searches for a suitable QEMU binary in the system.
To select a specific QEMU binary though, specify the QEMU=path/to/binary
48
49
50
51
environment variable:

    QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat

52
To select an accelerator, for example "kvm", "hvf" or "tcg", specify the
53
ACCEL=name environment variable:
54
55
56

    ACCEL=kvm ./x86-run ./x86/msr.flat

57
58
59
60
61
62
63
64
65
66
67
# Tests configuration file

The test case may need specific runtime configurations, for
example, extra QEMU parameters and time to execute limited, the
runner script reads those information from a configuration file found
at ./ARCH/unittests.cfg.

The configuration file also contain the groups (if any) each test belong
to.  So that a given group can be executed by specifying its name in the
runner's -g option.

68
69
# Unit test inputs

70
Unit tests use QEMU's '-append args...' parameter for command line
71
72
73
inputs, i.e. all args will be available as argv strings in main().
Additionally a file of the form

74
75
76
    KEY=VAL
    KEY2=VAL
    ...
77

78
79
may be passed with '-initrd file' to become the unit test's environ,
which can then be accessed in the usual ways, e.g. VAL = getenv("KEY").
80
Any key=val strings can be passed, but some have reserved meanings in
81
the framework.  The list of reserved environment variables is below
82

83
    QEMU_ACCEL                   either kvm, hvf or tcg
84
85
    QEMU_VERSION_STRING          string of the form `qemu -h | head -1`
    KERNEL_VERSION_STRING        string of the form `uname -r`
86
87
88

Additionally these self-explanatory variables are reserved

89
90
    QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL,
    KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION
91

92
93
94
95
96
97
# Guarding unsafe tests

Some tests are not safe to run by default, as they may crash the
host. kvm-unit-tests provides two ways to handle tests like those.

 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
100
    it is only run when invoked

101
102
103
104
105
106
     a) independently, `ARCH-run ARCH/test`

     b) by specifying any other non-nodefault group it is in,
        groups = nodefault,mygroup : `./run_tests.sh -g mygroup`

     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
111
112
    if (ERRATA(abcdef012345)) {
        do_unsafe_test();
    }
113
    ```
114
115
116
117

    With the errata condition the unsafe unit test is only run
    when

118
119
120
121
122
    a) the ERRATA_abcdef012345 environment variable is provided and 'y'

    b) the ERRATA_FORCE environment variable is provided and 'y'

    c) by specifying all tests should be run, `./run_tests.sh -a`
123
124
125
       (The -a switch ensures the ERRATA_FORCE is provided and set
        to 'y'.)

126
127
The ./errata.txt file provides a mapping of the commits needed by errata
conditionals to their respective minimum kernel versions.  By default,
128
when the user does not provide an environ, then an environ generated
129
from the ./errata.txt file and the host's kernel version is provided to
130
131
all unit tests.

132
133
134
135
# Contributing

## Directory structure

136
137
138
139
140
    .:                  configure script, top-level Makefile, and run_tests.sh
    ./scripts:          helper scripts for building and running tests
    ./lib:              general architecture neutral services for the tests
    ./lib/<ARCH>:       architecture dependent services for the tests
    ./<ARCH>:           the sources of the tests and the created objects/images
141

142
See ./ARCH/README for architecture specific documentation.
143
144
145
146

## Style

Currently there is a mix of indentation styles so any changes to
147
existing files should be consistent with the existing style.  For new
148
149
files:

150
151
  - C: please use standard linux-with-tabs, see Linux kernel
    doc Documentation/process/coding-style.rst
152
153
  - Shell: use TABs for indentation

154
155
156
157
Exceptions:

  - While the kernel standard requires 80 columns, we allow up to 120.

158
159
160
161
162
163
164
165
166
167
168
## Patches

Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>.

Please prefix messages with: [kvm-unit-tests PATCH]

You can add the following to .git/config to do this automatically for you:

    [format]
        subjectprefix = kvm-unit-tests PATCH

Andrew Jones's avatar
Andrew Jones committed
169
170
Additionally it's helpful to have a common order of file types in patches.
Our chosen order attempts to place the more declarative files before
171
the code files.  We also start with common code and finish with unit test
Andrew Jones's avatar
Andrew Jones committed
172
code. git-diff's orderFile feature allows us to specify the order in a
173
file.  The orderFile we use is `scripts/git.difforder`; adding the config
Andrew Jones's avatar
Andrew Jones committed
174
with `git config diff.orderFile scripts/git.difforder` enables it.