Commit f3cb1762 authored by Wainer dos Santos Moschetta's avatar Wainer dos Santos Moschetta Committed by Paolo Bonzini
Browse files

README: Fix markdown formatting



There are formatting issues that prevent README.md
from being rendered correctly in a browser. This
patch fixes the following categories of issues:

- blocks which aren't indented correctly;
- texts wrapped in <> which need escape, or
  be replaced with another thing.

Also some inline commands are marked with ``.
Signed-off-by: default avatarWainer dos Santos Moschetta <wainersm@redhat.com>
Reviewed-by: Andrew Jones's avatarAndrew Jones <drjones@redhat.com>
Signed-off-by: default avatarPaolo Bonzini <pbonzini@redhat.com>
parent e5fb3067
......@@ -6,19 +6,18 @@ tests HOWTOs.
# Building the tests
This directory contains sources for a kvm test suite.
This directory contains sources for a KVM test suite.
To create the test images do:
./configure
make
in this directory. Test images are created in ./<ARCH>/*.flat
in this directory. Test images are created in ./ARCH/\*.flat
## Standalone tests
The tests can be built as standalone
To create and use standalone tests do:
The tests can be built as standalone. To create and use standalone tests do:
./configure
make standalone
......@@ -26,7 +25,7 @@ To create and use standalone tests do:
(go to somewhere)
./some-test
'make install' will install all tests in PREFIX/share/kvm-unit-tests/tests,
`make install` will install all tests in PREFIX/share/kvm-unit-tests/tests,
each as a standalone test.
......@@ -42,39 +41,40 @@ or:
to run them all.
To select a specific qemu binary, specify the QEMU=<path>
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
environment variable:
QEMU=/tmp/qemu/x86_64-softmmu/qemu-system-x86_64 ./x86-run ./x86/msr.flat
To select an accelerator, for example "kvm" or "tcg", specify the
ACCEL=<name> environment variable:
ACCEL=name environment variable:
ACCEL=kvm ./x86-run ./x86/msr.flat
# Unit test inputs
Unit tests use QEMU's '-append <args...>' parameter for command line
Unit tests use QEMU's '-append args...' parameter for command line
inputs, i.e. all args will be available as argv strings in main().
Additionally a file of the form
KEY=VAL
KEY2=VAL
...
KEY=VAL
KEY2=VAL
...
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")
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").
Any key=val strings can be passed, but some have reserved meanings in
the framework. The list of reserved environment variables is below
the framework. The list of reserved environment variables is below
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`
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`
Additionally these self-explanatory variables are reserved
QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL,
KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION
QEMU_MAJOR, QEMU_MINOR, QEMU_MICRO, KERNEL_VERSION, KERNEL_PATCHLEVEL,
KERNEL_SUBLEVEL, KERNEL_EXTRAVERSION
# Guarding unsafe tests
......@@ -82,50 +82,56 @@ 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
unittests.cfg file. When a unit test is in the nodefault group
unittests.cfg file. When a unit test is in the nodefault group
it is only run when invoked
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
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`
2) Making the test conditional on errata in the code,
```
if (ERRATA(abcdef012345)) {
do_unsafe_test();
}
```
With the errata condition the unsafe unit test is only run
when
a) the ERRATA_abcdef012345 environ variable is provided and 'y'
b) the ERRATA_FORCE environ variable is provided and 'y'
c) by specifying all tests should be run, ./run_tests.sh -a
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`
(The -a switch ensures the ERRATA_FORCE is provided and set
to 'y'.)
The errata.txt file provides a mapping of the commits needed by errata
conditionals to their respective minimum kernel versions. By default,
The ./errata.txt file provides a mapping of the commits needed by errata
conditionals to their respective minimum kernel versions. By default,
when the user does not provide an environ, then an environ generated
from the errata.txt file and the host's kernel version is provided to
from the ./errata.txt file and the host's kernel version is provided to
all unit tests.
# Contributing
## Directory structure
.: 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
.: 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
See <ARCH>/README for architecture specific documentation.
See ./ARCH/README for architecture specific documentation.
## Style
Currently there is a mix of indentation styles so any changes to
existing files should be consistent with the existing style. For new
existing files should be consistent with the existing style. For new
files:
- C: please use standard linux-with-tabs, see Linux kernel
......@@ -149,7 +155,7 @@ You can add the following to .git/config to do this automatically for you:
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
the code files. We also start with common code and finish with unit test
the code files. We also start with common code and finish with unit test
code. git-diff's orderFile feature allows us to specify the order in a
file. The orderFile we use is `scripts/git.difforder`. Adding the config
file. The orderFile we use is `scripts/git.difforder`; adding the config
with `git config diff.orderFile scripts/git.difforder` enables it.
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment