target/ppc: Fix slbia TLB invalidation gap
[qemu.git] / docs / devel / testing.rst
1 ===============
2 Testing in QEMU
3 ===============
4
5 This document describes the testing infrastructure in QEMU.
6
7 Testing with "make check"
8 =========================
9
10 The "make check" testing family includes most of the C based tests in QEMU. For
11 a quick help, run ``make check-help`` from the source tree.
12
13 The usual way to run these tests is:
14
15 .. code::
16
17   make check
18
19 which includes QAPI schema tests, unit tests, QTests and some iotests.
20 Different sub-types of "make check" tests will be explained below.
21
22 Before running tests, it is best to build QEMU programs first. Some tests
23 expect the executables to exist and will fail with obscure messages if they
24 cannot find them.
25
26 Unit tests
27 ----------
28
29 Unit tests, which can be invoked with ``make check-unit``, are simple C tests
30 that typically link to individual QEMU object files and exercise them by
31 calling exported functions.
32
33 If you are writing new code in QEMU, consider adding a unit test, especially
34 for utility modules that are relatively stateless or have few dependencies. To
35 add a new unit test:
36
37 1. Create a new source file. For example, ``tests/foo-test.c``.
38
39 2. Write the test. Normally you would include the header file which exports
40    the module API, then verify the interface behaves as expected from your
41    test. The test code should be organized with the glib testing framework.
42    Copying and modifying an existing test is usually a good idea.
43
44 3. Add the test to ``tests/Makefile.include``. First, name the unit test
45    program and add it to ``$(check-unit-y)``; then add a rule to build the
46    executable.  For example:
47
48 .. code::
49
50   check-unit-y += tests/foo-test$(EXESUF)
51   tests/foo-test$(EXESUF): tests/foo-test.o $(test-util-obj-y)
52   ...
53
54 Since unit tests don't require environment variables, the simplest way to debug
55 a unit test failure is often directly invoking it or even running it under
56 ``gdb``. However there can still be differences in behavior between ``make``
57 invocations and your manual run, due to ``$MALLOC_PERTURB_`` environment
58 variable (which affects memory reclamation and catches invalid pointers better)
59 and gtester options. If necessary, you can run
60
61 .. code::
62
63   make check-unit V=1
64
65 and copy the actual command line which executes the unit test, then run
66 it from the command line.
67
68 QTest
69 -----
70
71 QTest is a device emulation testing framework.  It can be very useful to test
72 device models; it could also control certain aspects of QEMU (such as virtual
73 clock stepping), with a special purpose "qtest" protocol.  Refer to the
74 documentation in ``qtest.c`` for more details of the protocol.
75
76 QTest cases can be executed with
77
78 .. code::
79
80    make check-qtest
81
82 The QTest library is implemented by ``tests/qtest/libqtest.c`` and the API is
83 defined in ``tests/qtest/libqtest.h``.
84
85 Consider adding a new QTest case when you are introducing a new virtual
86 hardware, or extending one if you are adding functionalities to an existing
87 virtual device.
88
89 On top of libqtest, a higher level library, ``libqos``, was created to
90 encapsulate common tasks of device drivers, such as memory management and
91 communicating with system buses or devices. Many virtual device tests use
92 libqos instead of directly calling into libqtest.
93
94 Steps to add a new QTest case are:
95
96 1. Create a new source file for the test. (More than one file can be added as
97    necessary.) For example, ``tests/qtest/foo-test.c``.
98
99 2. Write the test code with the glib and libqtest/libqos API. See also existing
100    tests and the library headers for reference.
101
102 3. Register the new test in ``tests/qtest/Makefile.include``. Add the test
103    executable name to an appropriate ``check-qtest-*-y`` variable. For example:
104
105    ``check-qtest-generic-y = tests/qtest/foo-test$(EXESUF)``
106
107 4. Add object dependencies of the executable in the Makefile, including the
108    test source file(s) and other interesting objects. For example:
109
110    ``tests/qtest/foo-test$(EXESUF): tests/qtest/foo-test.o $(libqos-obj-y)``
111
112 Debugging a QTest failure is slightly harder than the unit test because the
113 tests look up QEMU program names in the environment variables, such as
114 ``QTEST_QEMU_BINARY`` and ``QTEST_QEMU_IMG``, and also because it is not easy
115 to attach gdb to the QEMU process spawned from the test. But manual invoking
116 and using gdb on the test is still simple to do: find out the actual command
117 from the output of
118
119 .. code::
120
121   make check-qtest V=1
122
123 which you can run manually.
124
125 QAPI schema tests
126 -----------------
127
128 The QAPI schema tests validate the QAPI parser used by QMP, by feeding
129 predefined input to the parser and comparing the result with the reference
130 output.
131
132 The input/output data is managed under the ``tests/qapi-schema`` directory.
133 Each test case includes four files that have a common base name:
134
135   * ``${casename}.json`` - the file contains the JSON input for feeding the
136     parser
137   * ``${casename}.out`` - the file contains the expected stdout from the parser
138   * ``${casename}.err`` - the file contains the expected stderr from the parser
139   * ``${casename}.exit`` - the expected error code
140
141 Consider adding a new QAPI schema test when you are making a change on the QAPI
142 parser (either fixing a bug or extending/modifying the syntax). To do this:
143
144 1. Add four files for the new case as explained above. For example:
145
146   ``$EDITOR tests/qapi-schema/foo.{json,out,err,exit}``.
147
148 2. Add the new test in ``tests/Makefile.include``. For example:
149
150   ``qapi-schema += foo.json``
151
152 check-block
153 -----------
154
155 ``make check-block`` runs a subset of the block layer iotests (the tests that
156 are in the "auto" group in ``tests/qemu-iotests/group``).
157 See the "QEMU iotests" section below for more information.
158
159 GCC gcov support
160 ----------------
161
162 ``gcov`` is a GCC tool to analyze the testing coverage by
163 instrumenting the tested code. To use it, configure QEMU with
164 ``--enable-gcov`` option and build. Then run ``make check`` as usual.
165
166 If you want to gather coverage information on a single test the ``make
167 clean-coverage`` target can be used to delete any existing coverage
168 information before running a single test.
169
170 You can generate a HTML coverage report by executing ``make
171 coverage-report`` which will create
172 ./reports/coverage/coverage-report.html. If you want to create it
173 elsewhere simply execute ``make /foo/bar/baz/coverage-report.html``.
174
175 Further analysis can be conducted by running the ``gcov`` command
176 directly on the various .gcda output files. Please read the ``gcov``
177 documentation for more information.
178
179 QEMU iotests
180 ============
181
182 QEMU iotests, under the directory ``tests/qemu-iotests``, is the testing
183 framework widely used to test block layer related features. It is higher level
184 than "make check" tests and 99% of the code is written in bash or Python
185 scripts.  The testing success criteria is golden output comparison, and the
186 test files are named with numbers.
187
188 To run iotests, make sure QEMU is built successfully, then switch to the
189 ``tests/qemu-iotests`` directory under the build directory, and run ``./check``
190 with desired arguments from there.
191
192 By default, "raw" format and "file" protocol is used; all tests will be
193 executed, except the unsupported ones. You can override the format and protocol
194 with arguments:
195
196 .. code::
197
198   # test with qcow2 format
199   ./check -qcow2
200   # or test a different protocol
201   ./check -nbd
202
203 It's also possible to list test numbers explicitly:
204
205 .. code::
206
207   # run selected cases with qcow2 format
208   ./check -qcow2 001 030 153
209
210 Cache mode can be selected with the "-c" option, which may help reveal bugs
211 that are specific to certain cache mode.
212
213 More options are supported by the ``./check`` script, run ``./check -h`` for
214 help.
215
216 Writing a new test case
217 -----------------------
218
219 Consider writing a tests case when you are making any changes to the block
220 layer. An iotest case is usually the choice for that. There are already many
221 test cases, so it is possible that extending one of them may achieve the goal
222 and save the boilerplate to create one.  (Unfortunately, there isn't a 100%
223 reliable way to find a related one out of hundreds of tests.  One approach is
224 using ``git grep``.)
225
226 Usually an iotest case consists of two files. One is an executable that
227 produces output to stdout and stderr, the other is the expected reference
228 output. They are given the same number in file names. E.g. Test script ``055``
229 and reference output ``055.out``.
230
231 In rare cases, when outputs differ between cache mode ``none`` and others, a
232 ``.out.nocache`` file is added. In other cases, when outputs differ between
233 image formats, more than one ``.out`` files are created ending with the
234 respective format names, e.g. ``178.out.qcow2`` and ``178.out.raw``.
235
236 There isn't a hard rule about how to write a test script, but a new test is
237 usually a (copy and) modification of an existing case.  There are a few
238 commonly used ways to create a test:
239
240 * A Bash script. It will make use of several environmental variables related
241   to the testing procedure, and could source a group of ``common.*`` libraries
242   for some common helper routines.
243
244 * A Python unittest script. Import ``iotests`` and create a subclass of
245   ``iotests.QMPTestCase``, then call ``iotests.main`` method. The downside of
246   this approach is that the output is too scarce, and the script is considered
247   harder to debug.
248
249 * A simple Python script without using unittest module. This could also import
250   ``iotests`` for launching QEMU and utilities etc, but it doesn't inherit
251   from ``iotests.QMPTestCase`` therefore doesn't use the Python unittest
252   execution. This is a combination of 1 and 2.
253
254 Pick the language per your preference since both Bash and Python have
255 comparable library support for invoking and interacting with QEMU programs. If
256 you opt for Python, it is strongly recommended to write Python 3 compatible
257 code.
258
259 Both Python and Bash frameworks in iotests provide helpers to manage test
260 images. They can be used to create and clean up images under the test
261 directory. If no I/O or any protocol specific feature is needed, it is often
262 more convenient to use the pseudo block driver, ``null-co://``, as the test
263 image, which doesn't require image creation or cleaning up. Avoid system-wide
264 devices or files whenever possible, such as ``/dev/null`` or ``/dev/zero``.
265 Otherwise, image locking implications have to be considered.  For example,
266 another application on the host may have locked the file, possibly leading to a
267 test failure.  If using such devices are explicitly desired, consider adding
268 ``locking=off`` option to disable image locking.
269
270 .. _docker-ref:
271
272 Docker based tests
273 ==================
274
275 Introduction
276 ------------
277
278 The Docker testing framework in QEMU utilizes public Docker images to build and
279 test QEMU in predefined and widely accessible Linux environments.  This makes
280 it possible to expand the test coverage across distros, toolchain flavors and
281 library versions.
282
283 Prerequisites
284 -------------
285
286 Install "docker" with the system package manager and start the Docker service
287 on your development machine, then make sure you have the privilege to run
288 Docker commands. Typically it means setting up passwordless ``sudo docker``
289 command or login as root. For example:
290
291 .. code::
292
293   $ sudo yum install docker
294   $ # or `apt-get install docker` for Ubuntu, etc.
295   $ sudo systemctl start docker
296   $ sudo docker ps
297
298 The last command should print an empty table, to verify the system is ready.
299
300 An alternative method to set up permissions is by adding the current user to
301 "docker" group and making the docker daemon socket file (by default
302 ``/var/run/docker.sock``) accessible to the group:
303
304 .. code::
305
306   $ sudo groupadd docker
307   $ sudo usermod $USER -a -G docker
308   $ sudo chown :docker /var/run/docker.sock
309
310 Note that any one of above configurations makes it possible for the user to
311 exploit the whole host with Docker bind mounting or other privileged
312 operations.  So only do it on development machines.
313
314 Quickstart
315 ----------
316
317 From source tree, type ``make docker`` to see the help. Testing can be started
318 without configuring or building QEMU (``configure`` and ``make`` are done in
319 the container, with parameters defined by the make target):
320
321 .. code::
322
323   make docker-test-build@min-glib
324
325 This will create a container instance using the ``min-glib`` image (the image
326 is downloaded and initialized automatically), in which the ``test-build`` job
327 is executed.
328
329 Images
330 ------
331
332 Along with many other images, the ``min-glib`` image is defined in a Dockerfile
333 in ``tests/docker/dockerfiles/``, called ``min-glib.docker``. ``make docker``
334 command will list all the available images.
335
336 To add a new image, simply create a new ``.docker`` file under the
337 ``tests/docker/dockerfiles/`` directory.
338
339 A ``.pre`` script can be added beside the ``.docker`` file, which will be
340 executed before building the image under the build context directory. This is
341 mainly used to do necessary host side setup. One such setup is ``binfmt_misc``,
342 for example, to make qemu-user powered cross build containers work.
343
344 Tests
345 -----
346
347 Different tests are added to cover various configurations to build and test
348 QEMU.  Docker tests are the executables under ``tests/docker`` named
349 ``test-*``. They are typically shell scripts and are built on top of a shell
350 library, ``tests/docker/common.rc``, which provides helpers to find the QEMU
351 source and build it.
352
353 The full list of tests is printed in the ``make docker`` help.
354
355 Tools
356 -----
357
358 There are executables that are created to run in a specific Docker environment.
359 This makes it easy to write scripts that have heavy or special dependencies,
360 but are still very easy to use.
361
362 Currently the only tool is ``travis``, which mimics the Travis-CI tests in a
363 container. It runs in the ``travis`` image:
364
365 .. code::
366
367   make docker-travis@travis
368
369 Debugging a Docker test failure
370 -------------------------------
371
372 When CI tasks, maintainers or yourself report a Docker test failure, follow the
373 below steps to debug it:
374
375 1. Locally reproduce the failure with the reported command line. E.g. run
376    ``make docker-test-mingw@fedora J=8``.
377 2. Add "V=1" to the command line, try again, to see the verbose output.
378 3. Further add "DEBUG=1" to the command line. This will pause in a shell prompt
379    in the container right before testing starts. You could either manually
380    build QEMU and run tests from there, or press Ctrl-D to let the Docker
381    testing continue.
382 4. If you press Ctrl-D, the same building and testing procedure will begin, and
383    will hopefully run into the error again. After that, you will be dropped to
384    the prompt for debug.
385
386 Options
387 -------
388
389 Various options can be used to affect how Docker tests are done. The full
390 list is in the ``make docker`` help text. The frequently used ones are:
391
392 * ``V=1``: the same as in top level ``make``. It will be propagated to the
393   container and enable verbose output.
394 * ``J=$N``: the number of parallel tasks in make commands in the container,
395   similar to the ``-j $N`` option in top level ``make``. (The ``-j`` option in
396   top level ``make`` will not be propagated into the container.)
397 * ``DEBUG=1``: enables debug. See the previous "Debugging a Docker test
398   failure" section.
399
400 VM testing
401 ==========
402
403 This test suite contains scripts that bootstrap various guest images that have
404 necessary packages to build QEMU. The basic usage is documented in ``Makefile``
405 help which is displayed with ``make vm-help``.
406
407 Quickstart
408 ----------
409
410 Run ``make vm-help`` to list available make targets. Invoke a specific make
411 command to run build test in an image. For example, ``make vm-build-freebsd``
412 will build the source tree in the FreeBSD image. The command can be executed
413 from either the source tree or the build dir; if the former, ``./configure`` is
414 not needed. The command will then generate the test image in ``./tests/vm/``
415 under the working directory.
416
417 Note: images created by the scripts accept a well-known RSA key pair for SSH
418 access, so they SHOULD NOT be exposed to external interfaces if you are
419 concerned about attackers taking control of the guest and potentially
420 exploiting a QEMU security bug to compromise the host.
421
422 QEMU binaries
423 -------------
424
425 By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
426 isn't one, or if it is older than 2.10, the test won't work. In this case,
427 provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``.
428
429 Likewise the path to qemu-img can be set in QEMU_IMG environment variable.
430
431 Make jobs
432 ---------
433
434 The ``-j$X`` option in the make command line is not propagated into the VM,
435 specify ``J=$X`` to control the make jobs in the guest.
436
437 Debugging
438 ---------
439
440 Add ``DEBUG=1`` and/or ``V=1`` to the make command to allow interactive
441 debugging and verbose output. If this is not enough, see the next section.
442 ``V=1`` will be propagated down into the make jobs in the guest.
443
444 Manual invocation
445 -----------------
446
447 Each guest script is an executable script with the same command line options.
448 For example to work with the netbsd guest, use ``$QEMU_SRC/tests/vm/netbsd``:
449
450 .. code::
451
452     $ cd $QEMU_SRC/tests/vm
453
454     # To bootstrap the image
455     $ ./netbsd --build-image --image /var/tmp/netbsd.img
456     <...>
457
458     # To run an arbitrary command in guest (the output will not be echoed unless
459     # --debug is added)
460     $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a
461
462     # To build QEMU in guest
463     $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC
464
465     # To get to an interactive shell
466     $ ./netbsd --interactive --image /var/tmp/netbsd.img sh
467
468 Adding new guests
469 -----------------
470
471 Please look at existing guest scripts for how to add new guests.
472
473 Most importantly, create a subclass of BaseVM and implement ``build_image()``
474 method and define ``BUILD_SCRIPT``, then finally call ``basevm.main()`` from
475 the script's ``main()``.
476
477 * Usually in ``build_image()``, a template image is downloaded from a
478   predefined URL. ``BaseVM._download_with_cache()`` takes care of the cache and
479   the checksum, so consider using it.
480
481 * Once the image is downloaded, users, SSH server and QEMU build deps should
482   be set up:
483
484   - Root password set to ``BaseVM.ROOT_PASS``
485   - User ``BaseVM.GUEST_USER`` is created, and password set to
486     ``BaseVM.GUEST_PASS``
487   - SSH service is enabled and started on boot,
488     ``$QEMU_SRC/tests/keys/id_rsa.pub`` is added to ssh's ``authorized_keys``
489     file of both root and the normal user
490   - DHCP client service is enabled and started on boot, so that it can
491     automatically configure the virtio-net-pci NIC and communicate with QEMU
492     user net (10.0.2.2)
493   - Necessary packages are installed to untar the source tarball and build
494     QEMU
495
496 * Write a proper ``BUILD_SCRIPT`` template, which should be a shell script that
497   untars a raw virtio-blk block device, which is the tarball data blob of the
498   QEMU source tree, then configure/build it. Running "make check" is also
499   recommended.
500
501 Image fuzzer testing
502 ====================
503
504 An image fuzzer was added to exercise format drivers. Currently only qcow2 is
505 supported. To start the fuzzer, run
506
507 .. code::
508
509   tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
510
511 Alternatively, some command different from "qemu-img info" can be tested, by
512 changing the ``-c`` option.
513
514 Acceptance tests using the Avocado Framework
515 ============================================
516
517 The ``tests/acceptance`` directory hosts functional tests, also known
518 as acceptance level tests.  They're usually higher level tests, and
519 may interact with external resources and with various guest operating
520 systems.
521
522 These tests are written using the Avocado Testing Framework (which must
523 be installed separately) in conjunction with a the ``avocado_qemu.Test``
524 class, implemented at ``tests/acceptance/avocado_qemu``.
525
526 Tests based on ``avocado_qemu.Test`` can easily:
527
528  * Customize the command line arguments given to the convenience
529    ``self.vm`` attribute (a QEMUMachine instance)
530
531  * Interact with the QEMU monitor, send QMP commands and check
532    their results
533
534  * Interact with the guest OS, using the convenience console device
535    (which may be useful to assert the effectiveness and correctness of
536    command line arguments or QMP commands)
537
538  * Interact with external data files that accompany the test itself
539    (see ``self.get_data()``)
540
541  * Download (and cache) remote data files, such as firmware and kernel
542    images
543
544  * Have access to a library of guest OS images (by means of the
545    ``avocado.utils.vmimage`` library)
546
547  * Make use of various other test related utilities available at the
548    test class itself and at the utility library:
549
550    - http://avocado-framework.readthedocs.io/en/latest/api/test/avocado.html#avocado.Test
551    - http://avocado-framework.readthedocs.io/en/latest/api/utils/avocado.utils.html
552
553 Running tests
554 -------------
555
556 You can run the acceptance tests simply by executing:
557
558 .. code::
559
560   make check-acceptance
561
562 This involves the automatic creation of Python virtual environment
563 within the build tree (at ``tests/venv``) which will have all the
564 right dependencies, and will save tests results also within the
565 build tree (at ``tests/results``).
566
567 Note: the build environment must be using a Python 3 stack, and have
568 the ``venv`` and ``pip`` packages installed.  If necessary, make sure
569 ``configure`` is called with ``--python=`` and that those modules are
570 available.  On Debian and Ubuntu based systems, depending on the
571 specific version, they may be on packages named ``python3-venv`` and
572 ``python3-pip``.
573
574 The scripts installed inside the virtual environment may be used
575 without an "activation".  For instance, the Avocado test runner
576 may be invoked by running:
577
578  .. code::
579
580   tests/venv/bin/avocado run $OPTION1 $OPTION2 tests/acceptance/
581
582 Manual Installation
583 -------------------
584
585 To manually install Avocado and its dependencies, run:
586
587 .. code::
588
589   pip install --user avocado-framework
590
591 Alternatively, follow the instructions on this link:
592
593   http://avocado-framework.readthedocs.io/en/latest/GetStartedGuide.html#installing-avocado
594
595 Overview
596 --------
597
598 The ``tests/acceptance/avocado_qemu`` directory provides the
599 ``avocado_qemu`` Python module, containing the ``avocado_qemu.Test``
600 class.  Here's a simple usage example:
601
602 .. code::
603
604   from avocado_qemu import Test
605
606
607   class Version(Test):
608       """
609       :avocado: tags=quick
610       """
611       def test_qmp_human_info_version(self):
612           self.vm.launch()
613           res = self.vm.command('human-monitor-command',
614                                 command_line='info version')
615           self.assertRegexpMatches(res, r'^(\d+\.\d+\.\d)')
616
617 To execute your test, run:
618
619 .. code::
620
621   avocado run version.py
622
623 Tests may be classified according to a convention by using docstring
624 directives such as ``:avocado: tags=TAG1,TAG2``.  To run all tests
625 in the current directory, tagged as "quick", run:
626
627 .. code::
628
629   avocado run -t quick .
630
631 The ``avocado_qemu.Test`` base test class
632 -----------------------------------------
633
634 The ``avocado_qemu.Test`` class has a number of characteristics that
635 are worth being mentioned right away.
636
637 First of all, it attempts to give each test a ready to use QEMUMachine
638 instance, available at ``self.vm``.  Because many tests will tweak the
639 QEMU command line, launching the QEMUMachine (by using ``self.vm.launch()``)
640 is left to the test writer.
641
642 The base test class has also support for tests with more than one
643 QEMUMachine. The way to get machines is through the ``self.get_vm()``
644 method which will return a QEMUMachine instance. The ``self.get_vm()``
645 method accepts arguments that will be passed to the QEMUMachine creation
646 and also an optional `name` attribute so you can identify a specific
647 machine and get it more than once through the tests methods. A simple
648 and hypothetical example follows:
649
650 .. code::
651
652   from avocado_qemu import Test
653
654
655   class MultipleMachines(Test):
656       """
657       :avocado: enable
658       """
659       def test_multiple_machines(self):
660           first_machine = self.get_vm()
661           second_machine = self.get_vm()
662           self.get_vm(name='third_machine').launch()
663
664           first_machine.launch()
665           second_machine.launch()
666
667           first_res = first_machine.command(
668               'human-monitor-command',
669               command_line='info version')
670
671           second_res = second_machine.command(
672               'human-monitor-command',
673               command_line='info version')
674
675           third_res = self.get_vm(name='third_machine').command(
676               'human-monitor-command',
677               command_line='info version')
678
679           self.assertEquals(first_res, second_res, third_res)
680
681 At test "tear down", ``avocado_qemu.Test`` handles all the QEMUMachines
682 shutdown.
683
684 QEMUMachine
685 ~~~~~~~~~~~
686
687 The QEMUMachine API is already widely used in the Python iotests,
688 device-crash-test and other Python scripts.  It's a wrapper around the
689 execution of a QEMU binary, giving its users:
690
691  * the ability to set command line arguments to be given to the QEMU
692    binary
693
694  * a ready to use QMP connection and interface, which can be used to
695    send commands and inspect its results, as well as asynchronous
696    events
697
698  * convenience methods to set commonly used command line arguments in
699    a more succinct and intuitive way
700
701 QEMU binary selection
702 ~~~~~~~~~~~~~~~~~~~~~
703
704 The QEMU binary used for the ``self.vm`` QEMUMachine instance will
705 primarily depend on the value of the ``qemu_bin`` parameter.  If it's
706 not explicitly set, its default value will be the result of a dynamic
707 probe in the same source tree.  A suitable binary will be one that
708 targets the architecture matching host machine.
709
710 Based on this description, test writers will usually rely on one of
711 the following approaches:
712
713 1) Set ``qemu_bin``, and use the given binary
714
715 2) Do not set ``qemu_bin``, and use a QEMU binary named like
716    "${arch}-softmmu/qemu-system-${arch}", either in the current
717    working directory, or in the current source tree.
718
719 The resulting ``qemu_bin`` value will be preserved in the
720 ``avocado_qemu.Test`` as an attribute with the same name.
721
722 Attribute reference
723 -------------------
724
725 Besides the attributes and methods that are part of the base
726 ``avocado.Test`` class, the following attributes are available on any
727 ``avocado_qemu.Test`` instance.
728
729 vm
730 ~~
731
732 A QEMUMachine instance, initially configured according to the given
733 ``qemu_bin`` parameter.
734
735 arch
736 ~~~~
737
738 The architecture can be used on different levels of the stack, e.g. by
739 the framework or by the test itself.  At the framework level, it will
740 currently influence the selection of a QEMU binary (when one is not
741 explicitly given).
742
743 Tests are also free to use this attribute value, for their own needs.
744 A test may, for instance, use the same value when selecting the
745 architecture of a kernel or disk image to boot a VM with.
746
747 The ``arch`` attribute will be set to the test parameter of the same
748 name.  If one is not given explicitly, it will either be set to
749 ``None``, or, if the test is tagged with one (and only one)
750 ``:avocado: tags=arch:VALUE`` tag, it will be set to ``VALUE``.
751
752 machine
753 ~~~~~~~
754
755 The machine type that will be set to all QEMUMachine instances created
756 by the test.
757
758 The ``machine`` attribute will be set to the test parameter of the same
759 name.  If one is not given explicitly, it will either be set to
760 ``None``, or, if the test is tagged with one (and only one)
761 ``:avocado: tags=machine:VALUE`` tag, it will be set to ``VALUE``.
762
763 qemu_bin
764 ~~~~~~~~
765
766 The preserved value of the ``qemu_bin`` parameter or the result of the
767 dynamic probe for a QEMU binary in the current working directory or
768 source tree.
769
770 Parameter reference
771 -------------------
772
773 To understand how Avocado parameters are accessed by tests, and how
774 they can be passed to tests, please refer to::
775
776   http://avocado-framework.readthedocs.io/en/latest/WritingTests.html#accessing-test-parameters
777
778 Parameter values can be easily seen in the log files, and will look
779 like the following:
780
781 .. code::
782
783   PARAMS (key=qemu_bin, path=*, default=x86_64-softmmu/qemu-system-x86_64) => 'x86_64-softmmu/qemu-system-x86_64
784
785 arch
786 ~~~~
787
788 The architecture that will influence the selection of a QEMU binary
789 (when one is not explicitly given).
790
791 Tests are also free to use this parameter value, for their own needs.
792 A test may, for instance, use the same value when selecting the
793 architecture of a kernel or disk image to boot a VM with.
794
795 This parameter has a direct relation with the ``arch`` attribute.  If
796 not given, it will default to None.
797
798 machine
799 ~~~~~~~
800
801 The machine type that will be set to all QEMUMachine instances created
802 by the test.
803
804
805 qemu_bin
806 ~~~~~~~~
807
808 The exact QEMU binary to be used on QEMUMachine.
809
810 Uninstalling Avocado
811 --------------------
812
813 If you've followed the manual installation instructions above, you can
814 easily uninstall Avocado.  Start by listing the packages you have
815 installed::
816
817   pip list --user
818
819 And remove any package you want with::
820
821   pip uninstall <package_name>
822
823 If you've used ``make check-acceptance``, the Python virtual environment where
824 Avocado is installed will be cleaned up as part of ``make check-clean``.
825
826 Testing with "make check-tcg"
827 =============================
828
829 The check-tcg tests are intended for simple smoke tests of both
830 linux-user and softmmu TCG functionality. However to build test
831 programs for guest targets you need to have cross compilers available.
832 If your distribution supports cross compilers you can do something as
833 simple as::
834
835   apt install gcc-aarch64-linux-gnu
836
837 The configure script will automatically pick up their presence.
838 Sometimes compilers have slightly odd names so the availability of
839 them can be prompted by passing in the appropriate configure option
840 for the architecture in question, for example::
841
842   $(configure) --cross-cc-aarch64=aarch64-cc
843
844 There is also a ``--cross-cc-flags-ARCH`` flag in case additional
845 compiler flags are needed to build for a given target.
846
847 If you have the ability to run containers as the user you can also
848 take advantage of the build systems "Docker" support. It will then use
849 containers to build any test case for an enabled guest where there is
850 no system compiler available. See :ref: `_docker-ref` for details.
851
852 Running subset of tests
853 -----------------------
854
855 You can build the tests for one architecture::
856
857   make build-tcg-tests-$TARGET
858
859 And run with::
860
861   make run-tcg-tests-$TARGET
862
863 Adding ``V=1`` to the invocation will show the details of how to
864 invoke QEMU for the test which is useful for debugging tests.
865
866 TCG test dependencies
867 ---------------------
868
869 The TCG tests are deliberately very light on dependencies and are
870 either totally bare with minimal gcc lib support (for softmmu tests)
871 or just glibc (for linux-user tests). This is because getting a cross
872 compiler to work with additional libraries can be challenging.
873
874 Other TCG Tests
875 ---------------
876
877 There are a number of out-of-tree test suites that are used for more
878 extensive testing of processor features.
879
880 KVM Unit Tests
881 ~~~~~~~~~~~~~~
882
883 The KVM unit tests are designed to run as a Guest OS under KVM but
884 there is no reason why they can't exercise the TCG as well. It
885 provides a minimal OS kernel with hooks for enabling the MMU as well
886 as reporting test results via a special device::
887
888   https://git.kernel.org/pub/scm/virt/kvm/kvm-unit-tests.git
889
890 Linux Test Project
891 ~~~~~~~~~~~~~~~~~~
892
893 The LTP is focused on exercising the syscall interface of a Linux
894 kernel. It checks that syscalls behave as documented and strives to
895 exercise as many corner cases as possible. It is a useful test suite
896 to run to exercise QEMU's linux-user code::
897
898   https://linux-test-project.github.io/