qemu-test: add test for device_add
[qemu-test.git] / README
1 Build
2 -----
3
4 qemu-test will build a Linux kernel and initramfs based on busybox.  The
5 initramfs will pull in your local glibc.
6
7 Since the initrd and kernel are git submodules, you need to first fetch the
8 submodules:
9
10     $ git submodule update --init
11
12 If you have a local kernel tree, you may want to use that instead of
13 git.kernel.org.  To do this:
14
15     $ git submodule init
16     $ # update .gitmodules to point to your local tree
17     $ git submodule update
18
19 After updating submodules, to build the initrd and kernel, do:
20
21     $ make
22
23 Once the modules are built, you can issue a *make clean* to clean up the working
24 directory.  *make clean* will not remove the final kernel/initramfs.
25
26 Running Tests
27 -------------
28
29 To run a new test, execute:
30
31     $ ./qemu-test ~/build/qemu/x86_64-softmmu/qemu-system-x86_64 \
32                   tests/no-vga-pci-allocation.sh
33
34 The first argument is the QEMU executable to use.  The second is the test shell
35 script.
36
37 If you get an error about QEMU_SRC not being set, you'll need to set the
38 QEMU_SRC environment variable to point to your qemu.git tree.  It should be at
39 least qemu-1.0.
40
41 Writing New Tests
42 -----------------
43
44 Each test is a single shell script.  If the environmental variable QEMU_TEST is
45 set, then the shell script is being used to launch qemu.  If it is not set, then
46 the shell script is running in the guest and can be used to run guest code.
47
48 In both cases, failure is indicated by exiting with a non-zero exit status.
49
50 When running in the host, the following commands are avaiable:
51
52 - qmp  -- execute a qmp command.  'qmp human-monitor-command' can be used to
53           execute HMP commands.
54
55 - qemu -- a light wrapper around the user supplied qemu executable.
56
57 The qemu wrapper tracks standard output from the test and implements a timeout.
58 If no new text appears on stdout after 10 seconds, the guest is assumed to be
59 hung.  Please write your tests accordingly.
60
61 The wrapper also constantly interacts with QMP attempting to detect when QEMU
62 itself is locked up.
63
64 Submitting Tests
65 ----------------
66
67 Send new tests to qemu-devel@nongnu.org
68
69 Tips on Writing New Tests
70 -------------------------
71
72 - Tests should fail and pass as quickly as possible
73 - Running a test should test one piece of functionality.  If you want to test
74   multiple scenarios in one test file, consider using $RANDOM to choose which
75   scenario is run.