README.md 4.93 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
# Unit test inputs

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

61
62
63
    KEY=VAL
    KEY2=VAL
    ...
64

65
66
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").
67
Any key=val strings can be passed, but some have reserved meanings in
68
the framework.  The list of reserved environment variables is below
69

70
71
72
    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`
73
74
75

Additionally these self-explanatory variables are reserved

76
77
    QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL,
    KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION
78

79
80
81
82
83
84
# 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
85
    unittests.cfg file.  When a unit test is in the nodefault group
86
87
    it is only run when invoked

88
89
90
91
92
93
     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`
94
95

 2) Making the test conditional on errata in the code,
96
    ```
97
98
99
    if (ERRATA(abcdef012345)) {
        do_unsafe_test();
    }
100
    ```
101
102
103
104

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

105
106
107
108
109
    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`
110
111
112
       (The -a switch ensures the ERRATA_FORCE is provided and set
        to 'y'.)

113
114
The ./errata.txt file provides a mapping of the commits needed by errata
conditionals to their respective minimum kernel versions.  By default,
115
when the user does not provide an environ, then an environ generated
116
from the ./errata.txt file and the host's kernel version is provided to
117
118
all unit tests.

119
120
121
122
# Contributing

## Directory structure

123
124
125
126
127
    .:                  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
128

129
See ./ARCH/README for architecture specific documentation.
130
131
132
133

## Style

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

137
138
  - C: please use standard linux-with-tabs, see Linux kernel
    doc Documentation/process/coding-style.rst
139
140
  - Shell: use TABs for indentation

141
142
143
144
Exceptions:

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

145
146
147
148
149
150
151
152
153
154
155
## 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
156
157
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
158
the code files.  We also start with common code and finish with unit test
Andrew Jones's avatar
Andrew Jones committed
159
code. git-diff's orderFile feature allows us to specify the order in a
160
file.  The orderFile we use is `scripts/git.difforder`; adding the config
Andrew Jones's avatar
Andrew Jones committed
161
with `git config diff.orderFile scripts/git.difforder` enables it.