README.md 5.54 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
    .:                  configure script, top-level Makefile, and run_tests.sh
137 138
    ./scripts:          general architecture neutral helper scripts for building and running tests
    ./scripts/<ARCH>:   architecture dependent helper scripts for building and running tests
139 140 141
    ./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
142

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

## Style

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

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

155 156 157 158
Exceptions:

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

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