https://linux-kvm.org/api.php?action=feedcontributions&user=Ldoktor&feedformat=atomKVM - User contributions [en]2024-03-29T15:45:06ZUser contributionsMediaWiki 1.39.5https://linux-kvm.org/index.php?title=KVM-unit-tests&diff=173808KVM-unit-tests2017-02-24T05:54:28Z<p>Ldoktor: Add a note about running kvm-unit-test inside Avocado</p>
<hr />
<div><includeonly><br />
== [http://www.linux-kvm.org/page/KVM-unit-tests KVM unit tests] ==<br />
</includeonly><br />
<noinclude><br />
= kvm-unit-tests =<br />
<br />
<br />
The source code can be found on kernel.org's git server:<br />
* [https://git.kernel.org/cgit/virt/kvm/kvm-unit-tests.git https://git.kernel.org/cgit/virt/kvm/kvm-unit-tests.git]<br />
* git://git.kernel.org/pub/scm/virt/kvm/kvm-unit-tests.git<br />
</noinclude><br />
<br />
= Introduction =<br />
<br />
kvm-unit-tests is a project as old as KVM. As its name suggests, it's purpose is to provide [http://en.wikipedia.org/wiki/Unit_testing unit tests] for KVM. The unit tests are tiny guest operating systems that generally execute only tens of lines of C and assembler test code in order to obtain its PASS/FAIL result. Unit tests provide KVM and virt hardware functional testing by targeting the features through minimal implementations of their use per the hardware specification. The simplicity of unit tests make them easy to verify they are correct, easy to maintain, and easy to use in timing measurements. Unit tests are also often used for quick and dirty bug reproducers. The reproducers may then be kept as regression tests. It's strongly encouraged that patches implementing new KVM features are submitted with accompanying unit tests.<br />
<br />
While a single unit test is focused on a single feature, all unit tests share the minimal system initialization and setup code. There are also several functions made shareable across all unit tests, comprising a unit test API. The setup code and API implementation are briefly described in the next section, [[KVM-unit-tests#Framework|"Framework"]]. We then describe testdevs in the [[KVM-unit-tests#Testdevs|"Testdevs"]] section, which are extensions to KVM's userspace that provide special support for unit tests. Section [[KVM-unit-tests#API|"API"]] lists the subsystems, e.g. MMU, SMP, that the API covers, along with a few descriptions of what the API supports. It specifically avoids listing any actual function declarations though, as those may change (use the source Luke!). The [[KVM-unit-tests#Running tests|"Running tests"]] section gives all the details necessary to build and run tests, and section [[KVM-unit-tests#Adding a test|"Adding a test"]] provides an example of adding a test. Finally section [[KVM-unit-tests#Contributing|"Contributing"]] explains where and how to submit patches.<br />
<includeonly><br />
[http://www.linux-kvm.org/page/KVM-unit-tests More...]<br />
</includeonly><br />
<noinclude><br />
= Framework =<br />
<br />
The kvm-unit-tests framework supports multiple architectures; currently i386, x86_64, armv7 (arm), armv8 (arm64), ppc64, and ppc64le. The framework makes sharing code between similar architectures, e.g. arm and arm64, easier by adopting Linux's configured asm symlink. With the asm symlink each architecture gets its own copy of the headers, but then may opt to share the same code.<br />
<br />
The framework has the following components:<br />
; Test building support<br />
: Test building is done through makefiles and some supporting bash scripts.<br />
; Shared code for test setup and API<br />
: Test setup code includes, for example, early system init, MMU enablement, and UART init. The API provides some common libc functions, e.g. strcpy, atol, malloc, printf, as well as some low-level helper functions commonly seen in kernel code, e.g. irq_enable/disable(), barrier(), and some kvm-unit-tests specific API for, e.g., installing exception handlers and reporting test success/failure.<br />
; Test running support<br />
: Test running is provided with a few bash scripts, using a unit tests configuration file as input. Generally tests are run from within the source root directory using the supporting scripts, but tests may optionally be built as standalone tests as well. More information about the standalone building and running is in the section [[KVM-unit-tests#Running tests|"Running tests"]].<br />
<br />
= Testdevs =<br />
<br />
Like all guests, a kvm-unit-test unit test (a mini guest) is run not only with KVM, but also with KVM's userspace. It's useful for unit tests to be able to open a test specific communication channel to KVM's userspace, allowing it to send commands for host-controlled behaviors or external-to-the-guest invoked events. In particular this channel is useful for initiating an exit, i.e. to quit the unit test. Testdevs fill these roles. The following are testdevs currently in QEMU<br />
<br />
; isa-debug-exit<br />
: x86 device that opens an I/O port. When the I/O port is written it induces an exit, using the value written to form the exit code. Note, the exit code written is modified with "<tt>(''code'' << 1) | 1</tt>". Thus, a unit test exiting with zero for success induces an exit from QEMU with 1.<br />
<br />
; pc-testdev<br />
: x86 device that opens several I/O ports, where each port provides an interface to a helper function for the unit tests. One such function is interrupt injection.<br />
<br />
; pci-testdev<br />
: A PCI "device" that when read and written helps test PCI accesses.<br />
<br />
; testdev<br />
: An architecture neutral testdev that takes its commands in postfix notation over a serial channel. Unit tests add an additional serial channel to their unit test guest config (the first being for test output), and then bind this device to it. kvm-unit-tests has minimal support for virtio in order to allow the additional serial channel to be an instance of virtio-serial. Currently testdev only supports the command "<tt>''code''q</tt>", which works exactly like the isa-debug-exit testdev.<br />
<br />
= API =<br />
<br />
There are three API categories in kvm-unit-tests 1) libc, 2) functions typical of kernel code, and 3) kvm-unit-tests specific. Very little libc has been implemented, but some of the most commonly used functions, such as strcpy, memset, malloc, printf, assert, exit, and others are available. To give an overview of (2), it's best to break them down by subsytem<br />
<br />
; Device discovery<br />
: ACPI - minimal table search support. Currently x86-only.<br />
: Device tree - libfdt and a device tree library wrapping libfdt to accommodate the use of device trees conforming to the Linux documentation. For example there is a function that gets the "bootargs" from /chosen, which are then fed into the unit test's main function's inputs (argc, argv) by the setup code before the unit test starts.<br />
<br />
; Vectors<br />
: Functions to install exception handlers. On ARM a default register-dumping handler is installed during system init before the unit test starts.<br />
<br />
; Memory<br />
: Functions for memory allocation. Free memory is prepared for allocation during system init before the unit test starts.<br />
: Functions for MMU enable/disable, TLB flushing, PTE setting, etc.<br />
<br />
; SMP<br />
: Functions to boot secondaries, iterate online cpus, etc.<br />
: Barriers, spinlocks, atomic ops, cpumasks, etc.<br />
<br />
; I/O<br />
: Output messages to the UART. The UART is initialized during system init before the unit test starts.<br />
: Functions to read/write MMIO<br />
: Functions to read/write I/O ports (x86-only)<br />
: Functions for accessing PCI devices (Currently x86-only)<br />
<br />
; Power management<br />
: PSCI (ARM-only)<br />
: RTAS (PowerPC-only)<br />
<br />
; Interrupt controller<br />
: Functions to enable/disable, send IPIs, etc.<br />
: Functions to enable/disable IRQs<br />
<br />
; Virtio<br />
: Buffer sending support (Currently virtio-mmio only)<br />
<br />
; Misc<br />
: Special register accessors<br />
: Switch to user mode support<br />
: Linux's asm-offsets generation, which can be used for structures that need to be accessed from assembly.<br />
<br />
Note, many of the names for the functions implementing the above are kvm-unit-tests specific, making them also part of the kvm-unit-tests specific API. However, at least for ARM, any function that implements something for which the Linux kernel already has a function, then we use the same name (and exact same type signature, if possible). The kvm-unit-tests specific API also includes some testing specific functions, such as report() and report_summary(). The report* functions should be used to report PASS/FAIL results of the tests, and the overall test result summary.<br />
<br />
= Running tests =<br />
<br />
<br>Here are a few examples of building and running tests<br />
:: Run all tests on the current host<br />
<pre><br />
$ git clone git://git.kernel.org/pub/scm/virt/kvm/kvm-unit-tests.git<br />
$ cd kvm-unit-tests/<br />
$ ./configure<br />
$ make<br />
$ ./run_tests.sh<br />
</pre><br />
<br />
:: Cross-compile and run with a specific QEMU<br />
<pre><br />
$ ./configure --arch=arm64 --cross-prefix=aarch64-linux-gnu-<br />
$ make<br />
$ export QEMU=/path/to/qemu-system-aarch64<br />
$ ./run_tests.sh<br />
</pre><br />
<br />
:: Run a single test, passing additional QEMU command line options<br />
<pre><br />
$ ./arm-run arm/selftest.flat -smp 4 -append smp<br />
</pre><br />
<br />
Note1: run_tests.sh runs each test in $TEST_DIR/unittests.cfg (TEST_DIR, along with some other variables, is defined in config.mak after running configure)<br><br />
Note2: When a unit test is run separately, all output goes to stdout. When unit tests are run through run_tests.sh, all output is redirected to a file named 'test.log'.<br />
<br />
:: Building and running standalone tests<br />
<pre><br />
$ make standalone<br />
$ tests/hypercall # example run of a standalone test<br />
</pre><br />
<br />
Tests may be installed with 'make install', which copies the standalone version of each test to /usr/local/share/kvm-unit-tests/<br />
<br />
= Running tests via Avocado =<br />
<br />
To simplify things one can use [https://github.com/avocado-framework/avocado/blob/master/contrib/testsuites/run-kvm-unit-test.sh https://github.com/avocado-framework/avocado/blob/master/contrib/testsuites/run-kvm-unit-test.sh] script to run kvm-unit-tests. Simply [http://avocado-framework.readthedocs.io/en/latest/GetStartedGuide.html install Avocado], download the script and use `sh run-kvm-unit-test.sh -h` to see the options. By default it downloads the latest kvm-unit-test and runs all available tests:<br />
<br />
<pre><br />
$ sh contrib/testsuites/run-kvm-unit-test.sh <br />
JOB ID : 216c5cf937b07befd9d2bc1dd496714fce280f22<br />
JOB LOG : /home/medic/avocado/job-results/job-2017-02-23T16.49-216c5cf/job.log<br />
(01/42) access: PASS (4.46 s)<br />
(02/42) apic: FAIL (4.42 s)<br />
(03/42) apic-split: FAIL (4.41 s)<br />
...<br />
(41/42) vmx: FAIL (1.64 s)<br />
(42/42) xsave: PASS (1.28 s)<br />
RESULTS : PASS 33 | ERROR 0 | FAIL 9 | SKIP 0 | WARN 0 | INTERRUPT 0<br />
TESTS TIME : 114.34 s<br />
JOB HTML : /home/medic/avocado/job-results/job-2017-02-23T16.49-216c5cf/html/results.html<br />
</pre><br />
<br />
The main benefit in using Avocado is to get persistent results along with sysinfo collection and the possibility to re-run the job (or only FAILed cases) or see the difference between two jobs.<br />
<br />
= Adding a test =<br />
<br />
1. Create the new unit test's main code file<br />
<pre><br />
$ cat > arm/new-unit-test.c<br />
#include <libcflat.h><br />
<br />
int main(int ac, char **av)<br />
{<br />
report("hello!", true);<br />
return report_summary();<br />
}<br />
</pre><br />
<br />
2. Add a line like the following to the appropriate config/ .mak file<br><br />
<pre><br />
$(TEST_DIR)/new-unit-test.elf: $(cstart.o) $(TEST_DIR)/new-unit-test.o<br />
</pre><br />
And also add <tt>$(TEST_DIR)/new-unit-test.flat</tt> to the tests-common makefile variable. Note, the tests-common variable identifies tests shared between similar architectures, e.g. i386 and x86_64 or arm and arm64. Use the tests makefile variable of a specific architecture's makefile to build the test specifically for that architecture.<br />
<br />
3. You can now build and run the test<br />
<pre><br />
$ make<br />
$ arm/run arm/new-unit-test.flat <br />
</pre><br />
<br />
= Contributing =<br />
<br />
To contribute new tests and enhancements and fixes to the framework, please submit patches to the KVM mailing list with the additional tag 'kvm-unit-tests' in the subject, i.e. [kvm-unit-tests PATCH]<br />
<br />
[[Category:Docs]][[Category:Testing]][[Category:HowTo]]<br />
</noinclude></div>Ldoktorhttps://linux-kvm.org/index.php?title=KVM-Autotest/TODO&diff=2329KVM-Autotest/TODO2009-06-08T08:43:53Z<p>Ldoktor: </p>
<hr />
<div>= KVM-Autotest To-Do list =<br />
<br />
== Framework ==<br />
<br />
* <s>Verify MD5 sum of ISO image before starting a VM</s> [Michael] [DONE]<br />
* <s>Enable multiple user controlled port redirections (with -redir)</s> [Michael] [DONE]<br />
* <s>Implement functions to translate VM ports and addresses (e.g. VM.get_port(), VM.get_address())</s> [Michael] [DONE]<br />
* Support TAP networking with a user specified MAC address for each NIC [Michael]<br />
* <s>Add <tt>display</tt> parameter to enable user control of the QEMU display method (VNC/SDL/nographic)</s> [Michael] [DONE]<br />
* Implement VM.clone() -- to be used by tests that need to add new VMs by themselves [Michael]<br />
* kickstart installation support<br />
* kvm-autotest auto resolve qemu-kvm backtraces<br />
* <s>Make sure ppm_utils.image_crop() handles bad input properly</s> [Michael] [DONE]<br />
* Enable tests to modify a VM's params (while it's down) [Michael]<br />
* Make tests shorter by using small utility functions that fail a test and display a failure message [Michael]<br />
* <s>Improve the stepmaker data naming system (e.g. name PPM files according to their MD5 sums)</s> [Michael] [DONE]<br />
* Redirect guest monitor to serial and capture guest error messages written to console. Log the errors and also scan for specific problems (e.g. oops)<br />
* Support an "expected to fail" param (at least in our html report)<br />
* Log a gdb-backtrace for tests (executables) which generate a core dump file.<br />
* Enable "guest-load" for a VMs before/while tests are running (e.g. migration of a VM, while a movie is playing on it) [Michael]<br />
* Add support for kvm-trace.<br />
* Fail upon indentation/white-space problems in the configuration file<br />
* Add a way to shutdown the VMs when the whole job completes (compared to doing nothing or shutting-down after every test) [Michael]<br />
* <s>Implement <tt>include</tt> functionality in the config file parser</s> [Michael] [DONE]<br />
* <s>Implement kvm_spawn.get_command_status_output() to make sending SSH commands easier</s> [Michael] [DONE]<br />
* Config file parser: enable selective modification of parameters based on regular expressions, e.g. mem.* ?= 256 [Michael]<br />
* Support running user specified pre-job, post-job, pre-test and post-test scripts [Michael]<br />
* <s>Make Step Editor accept a filename command line argument</s> [Michael] [DONE]<br />
* <s>When running step files, detect frozen (stuck) guests even in the presence of a blinking cursor</s> [Michael] [DONE]<br />
* Support running tests in parallel with multiple queues for each host [Michael]<br />
* Automatically convert PPM images in debug dirs to PNG format to save space [Michael]<br />
* Automatically assign a UUID to a VM (use the '-uuid' QEMU parameter). Once assigned, should be used in all dependent tests. [jasowang]<br />
* Automatically assign a MAC address to a NIC. Once assigned, should be used in all dependent tests. [jasowang]<br />
* <s>Allow run_bg to track a child process's stdin and stderr even after the parent process has exited; achieved by merging run_bg with kvm_spawn</s> [Michael] [DONE]<br />
<br />
<br />
== Tests ==<br />
<br />
* Find out how to use Autotest's netperf test with guests [jasowang]<br />
* If needed, write a netperf/iperf test [jasowang]<br />
* Write a time drift test (pic/apic/pm_timer)<br />
* Write a test which adds VMs until one of them becomes unresponsive, and records the maximum number of VMs successfully started. [jasowang]<br />
* cpu hotplug [Glauber]<br />
* pci net hot plug [Glauber]<br />
* pci block hot plug [Glauber]<br />
* <s>s3 hibernation</s> [Gleb] [DONE]<br />
* tap networking [jasowang]<br />
* pxe boot * net types [jasowang]<br />
* qcow1, qcow2, vmdk, vhd<br />
* qcow2 internal snapshots<br />
* <s>Run autotest tests inside Linux guest</s> [Michael] [ALREADY DONE]<br />
* Further migration [jasowang]<br />
* Multiple nics [jasowang]<br />
* multiple disks<br />
* ksm [jasowang, jzupka, ldoktor]<br />
* -vga stg, nographics<br />
* kvm unit-tests<br />
* Add unattended guest installations (using kickstart or answer-files) [jasowang]<br />
* kvm_install -- keep src and build directories under <kvm_autotest_root> instead of under kvm_runtest_2.<br />
* Stable tsc test - http://people.redhat.com/mingo/time-warp-test/MINI-HOWTO<br />
* Guest installation with pv-block device/driver (for both windows and Linux)<br />
* savevm test [jasowang]<br />
* Guests with large page support [jzupka, ldoktor]<br />
* Verify SMBIOS/DMI data (UUID, for example)<br />
* Disk serial number (for IDE, SCSI, VirtIO drives)<br />
<br />
<br />
== Misc ==<br />
<br />
* Goal -- get accepted into upstream autotest<br />
* Add docstrings to all functions that still lack them, including the ones in stepmaker.py, stepeditor.py and kvm_tests.py [Michael]<br />
* Add module headers and docstrings [Michael]<br />
* Document the setupssh.iso and setuptelnet.iso creation procedures in the wiki<br />
* Rename all Windows ISOs currently used to their official MSDN names<br />
* <s>Move Windows-setup iso images into the windows directory.</s> [DONE]<br />
* Share all the stepmaker data somehow so other people can debug stepfiles<br />
* Fill the sections "Working with step files" and "Step file creation tips" in the wiki [Michael]<br />
* Document the kvm_install test in the "Tests" section of the wiki<br />
<br />
<br />
== Bugs ==<br />
<br />
* <s>Step Maker/Step Editor: fix the GDK MemoryError problem (do not pass gtk.gdk.pixbuf_new_from_data() a 0x0 pixmap even if a ppm file contains one)</s> [DONE]</div>Ldoktor