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 21To create and use standalone tests do: 22 23 ./configure 24 make standalone 25 (send tests/some-test somewhere) 26 (go to somewhere) 27 ./some-test 28 29'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests, 30each as a standalone test. 31 32 33# Running the tests 34 35Then use the runner script to detect the correct invocation and 36invoke the test: 37 38 ./x86-run ./x86/msr.flat 39or: 40 41 ./run_tests.sh 42 43to run them all. 44 45To select a specific qemu binary, specify the QEMU=<path> 46environment variable: 47 48 QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat 49 50# Unit test inputs 51 52Unit tests use QEMU's '-append <args...>' parameter for command line 53inputs, i.e. all args will be available as argv strings in main(). 54Additionally a file of the form 55 56KEY=VAL 57KEY2=VAL 58... 59 60may be passed with '-initrd <file>' to become the unit test's environ, 61which can then be accessed in the usual ways, e.g. VAL = getenv("KEY") 62Any key=val strings can be passed, but some have reserved meanings in 63the framework. The list of reserved environment variables is below 64 65 QEMU_ACCEL ... either kvm or tcg 66 QEMU_VERSION_STRING ... string of the form `qemu -h | head -1` 67 KERNEL_VERSION_STRING ... string of the form `uname -r` 68 69Additionally these self-explanatory variables are reserved 70 71 QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL, 72 KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION 73 74# Contributing 75 76## Directory structure 77 78 .: configure script, top-level Makefile, and run_tests.sh 79 ./scripts: helper scripts for building and running tests 80 ./lib: general architecture neutral services for the tests 81 ./lib/<ARCH>: architecture dependent services for the tests 82 ./<ARCH>: the sources of the tests and the created objects/images 83 84See <ARCH>/README for architecture specific documentation. 85 86## Style 87 88Currently there is a mix of indentation styles so any changes to 89existing files should be consistent with the existing style. For new 90files: 91 92 - C: please use standard linux-with-tabs 93 - Shell: use TABs for indentation 94 95## Patches 96 97Patches are welcome at the KVM mailing list <kvm@vger.kernel.org>. 98 99Please prefix messages with: [kvm-unit-tests PATCH] 100 101You can add the following to .git/config to do this automatically for you: 102 103 [format] 104 subjectprefix = kvm-unit-tests PATCH 105 106Additionally it's helpful to have a common order of file types in patches. 107Our chosen order attempts to place the more declarative files before 108the code files. We also start with common code and finish with unit test 109code. git-diff's orderFile feature allows us to specify the order in a 110file. The orderFile we use is `scripts/git.difforder`. Adding the config 111with `git config diff.orderFile scripts/git.difforder` enables it. 112