README.md 5.34 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

## Standalone tests

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

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

28
`make install` will install all tests in PREFIX/share/kvm-unit-tests/tests,
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
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.

44
45
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
46
47
48
49
environment variable:

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

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

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

55
56
57
58
59
60
61
62
63
64
65
# 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.

66
67
# Unit test inputs

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

72
73
74
    KEY=VAL
    KEY2=VAL
    ...
75

76
77
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").
78
Any key=val strings can be passed, but some have reserved meanings in
79
the framework.  The list of reserved environment variables is below
80

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

Additionally these self-explanatory variables are reserved

87
88
    QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL,
    KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION
89

90
91
92
93
94
95
# 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
96
    unittests.cfg file.  When a unit test is in the nodefault group
97
98
    it is only run when invoked

99
100
101
102
103
104
     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`
105
106

 2) Making the test conditional on errata in the code,
107
    ```
108
109
110
    if (ERRATA(abcdef012345)) {
        do_unsafe_test();
    }
111
    ```
112
113
114
115

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

116
117
118
119
120
    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`
121
122
123
       (The -a switch ensures the ERRATA_FORCE is provided and set
        to 'y'.)

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

130
131
132
133
# Contributing

## Directory structure

134
135
136
137
138
    .:                  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
139

140
See ./ARCH/README for architecture specific documentation.
141
142
143
144

## Style

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

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

152
153
154
155
Exceptions:

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

156
157
158
159
160
161
162
163
164
165
166
## 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
167
168
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
169
the code files.  We also start with common code and finish with unit test
Andrew Jones's avatar
Andrew Jones committed
170
code. git-diff's orderFile feature allows us to specify the order in a
171
file.  The orderFile we use is `scripts/git.difforder`; adding the config
Andrew Jones's avatar
Andrew Jones committed
172
with `git config diff.orderFile scripts/git.difforder` enables it.