scripts/qemu-trace-stap: Convert documentation to rST
[qemu/ar7.git] / docs / devel / testing.rst
blobab5be0c72992f1ce1e94ec261934be2a025c4e0f
1 ===============
2 Testing in QEMU
3 ===============
5 This document describes the testing infrastructure in QEMU.
7 Testing with "make check"
8 =========================
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.
13 The usual way to run these tests is:
15 .. code::
17   make check
19 which includes QAPI schema tests, unit tests, and QTests. Different sub-types
20 of "make check" tests will be explained below.
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.
26 Unit tests
27 ----------
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.
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:
37 1. Create a new source file. For example, ``tests/foo-test.c``.
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.
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:
48 .. code::
50   check-unit-y += tests/foo-test$(EXESUF)
51   tests/foo-test$(EXESUF): tests/foo-test.o $(test-util-obj-y)
52   ...
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
61 .. code::
63   make check-unit V=1
65 and copy the actual command line which executes the unit test, then run
66 it from the command line.
68 QTest
69 -----
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.
76 QTest cases can be executed with
78 .. code::
80    make check-qtest
82 The QTest library is implemented by ``tests/libqtest.c`` and the API is defined
83 in ``tests/libqtest.h``.
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.
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.
94 Steps to add a new QTest case are:
96 1. Create a new source file for the test. (More than one file can be added as
97    necessary.) For example, ``tests/test-foo-device.c``.
99 2. Write the test code with the glib and libqtest/libqos API. See also existing
100    tests and the library headers for reference.
102 3. Register the new test in ``tests/Makefile.include``. Add the test executable
103    name to an appropriate ``check-qtest-*-y`` variable. For example:
105    ``check-qtest-generic-y = tests/test-foo-device$(EXESUF)``
107 4. Add object dependencies of the executable in the Makefile, including the
108    test source file(s) and other interesting objects. For example:
110    ``tests/test-foo-device$(EXESUF): tests/test-foo-device.o $(libqos-obj-y)``
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
119 .. code::
121   make check-qtest V=1
123 which you can run manually.
125 QAPI schema tests
126 -----------------
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.
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:
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
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:
144 1. Add four files for the new case as explained above. For example:
146   ``$EDITOR tests/qapi-schema/foo.{json,out,err,exit}``.
148 2. Add the new test in ``tests/Makefile.include``. For example:
150   ``qapi-schema += foo.json``
152 check-block
153 -----------
155 ``make check-block`` is a legacy command to invoke block layer iotests and is
156 rarely used. See "QEMU iotests" section below for more information.
158 GCC gcov support
159 ----------------
161 ``gcov`` is a GCC tool to analyze the testing coverage by
162 instrumenting the tested code. To use it, configure QEMU with
163 ``--enable-gcov`` option and build. Then run ``make check`` as usual.
165 If you want to gather coverage information on a single test the ``make
166 clean-coverage`` target can be used to delete any existing coverage
167 information before running a single test.
169 You can generate a HTML coverage report by executing ``make
170 coverage-report`` which will create
171 ./reports/coverage/coverage-report.html. If you want to create it
172 elsewhere simply execute ``make /foo/bar/baz/coverage-report.html``.
174 Further analysis can be conducted by running the ``gcov`` command
175 directly on the various .gcda output files. Please read the ``gcov``
176 documentation for more information.
178 QEMU iotests
179 ============
181 QEMU iotests, under the directory ``tests/qemu-iotests``, is the testing
182 framework widely used to test block layer related features. It is higher level
183 than "make check" tests and 99% of the code is written in bash or Python
184 scripts.  The testing success criteria is golden output comparison, and the
185 test files are named with numbers.
187 To run iotests, make sure QEMU is built successfully, then switch to the
188 ``tests/qemu-iotests`` directory under the build directory, and run ``./check``
189 with desired arguments from there.
191 By default, "raw" format and "file" protocol is used; all tests will be
192 executed, except the unsupported ones. You can override the format and protocol
193 with arguments:
195 .. code::
197   # test with qcow2 format
198   ./check -qcow2
199   # or test a different protocol
200   ./check -nbd
202 It's also possible to list test numbers explicitly:
204 .. code::
206   # run selected cases with qcow2 format
207   ./check -qcow2 001 030 153
209 Cache mode can be selected with the "-c" option, which may help reveal bugs
210 that are specific to certain cache mode.
212 More options are supported by the ``./check`` script, run ``./check -h`` for
213 help.
215 Writing a new test case
216 -----------------------
218 Consider writing a tests case when you are making any changes to the block
219 layer. An iotest case is usually the choice for that. There are already many
220 test cases, so it is possible that extending one of them may achieve the goal
221 and save the boilerplate to create one.  (Unfortunately, there isn't a 100%
222 reliable way to find a related one out of hundreds of tests.  One approach is
223 using ``git grep``.)
225 Usually an iotest case consists of two files. One is an executable that
226 produces output to stdout and stderr, the other is the expected reference
227 output. They are given the same number in file names. E.g. Test script ``055``
228 and reference output ``055.out``.
230 In rare cases, when outputs differ between cache mode ``none`` and others, a
231 ``.out.nocache`` file is added. In other cases, when outputs differ between
232 image formats, more than one ``.out`` files are created ending with the
233 respective format names, e.g. ``178.out.qcow2`` and ``178.out.raw``.
235 There isn't a hard rule about how to write a test script, but a new test is
236 usually a (copy and) modification of an existing case.  There are a few
237 commonly used ways to create a test:
239 * A Bash script. It will make use of several environmental variables related
240   to the testing procedure, and could source a group of ``common.*`` libraries
241   for some common helper routines.
243 * A Python unittest script. Import ``iotests`` and create a subclass of
244   ``iotests.QMPTestCase``, then call ``iotests.main`` method. The downside of
245   this approach is that the output is too scarce, and the script is considered
246   harder to debug.
248 * A simple Python script without using unittest module. This could also import
249   ``iotests`` for launching QEMU and utilities etc, but it doesn't inherit
250   from ``iotests.QMPTestCase`` therefore doesn't use the Python unittest
251   execution. This is a combination of 1 and 2.
253 Pick the language per your preference since both Bash and Python have
254 comparable library support for invoking and interacting with QEMU programs. If
255 you opt for Python, it is strongly recommended to write Python 3 compatible
256 code.
258 Both Python and Bash frameworks in iotests provide helpers to manage test
259 images. They can be used to create and clean up images under the test
260 directory. If no I/O or any protocol specific feature is needed, it is often
261 more convenient to use the pseudo block driver, ``null-co://``, as the test
262 image, which doesn't require image creation or cleaning up. Avoid system-wide
263 devices or files whenever possible, such as ``/dev/null`` or ``/dev/zero``.
264 Otherwise, image locking implications have to be considered.  For example,
265 another application on the host may have locked the file, possibly leading to a
266 test failure.  If using such devices are explicitly desired, consider adding
267 ``locking=off`` option to disable image locking.
269 .. _docker-ref:
271 Docker based tests
272 ==================
274 Introduction
275 ------------
277 The Docker testing framework in QEMU utilizes public Docker images to build and
278 test QEMU in predefined and widely accessible Linux environments.  This makes
279 it possible to expand the test coverage across distros, toolchain flavors and
280 library versions.
282 Prerequisites
283 -------------
285 Install "docker" with the system package manager and start the Docker service
286 on your development machine, then make sure you have the privilege to run
287 Docker commands. Typically it means setting up passwordless ``sudo docker``
288 command or login as root. For example:
290 .. code::
292   $ sudo yum install docker
293   $ # or `apt-get install docker` for Ubuntu, etc.
294   $ sudo systemctl start docker
295   $ sudo docker ps
297 The last command should print an empty table, to verify the system is ready.
299 An alternative method to set up permissions is by adding the current user to
300 "docker" group and making the docker daemon socket file (by default
301 ``/var/run/docker.sock``) accessible to the group:
303 .. code::
305   $ sudo groupadd docker
306   $ sudo usermod $USER -a -G docker
307   $ sudo chown :docker /var/run/docker.sock
309 Note that any one of above configurations makes it possible for the user to
310 exploit the whole host with Docker bind mounting or other privileged
311 operations.  So only do it on development machines.
313 Quickstart
314 ----------
316 From source tree, type ``make docker`` to see the help. Testing can be started
317 without configuring or building QEMU (``configure`` and ``make`` are done in
318 the container, with parameters defined by the make target):
320 .. code::
322   make docker-test-build@min-glib
324 This will create a container instance using the ``min-glib`` image (the image
325 is downloaded and initialized automatically), in which the ``test-build`` job
326 is executed.
328 Images
329 ------
331 Along with many other images, the ``min-glib`` image is defined in a Dockerfile
332 in ``tests/docker/dockerfiles/``, called ``min-glib.docker``. ``make docker``
333 command will list all the available images.
335 To add a new image, simply create a new ``.docker`` file under the
336 ``tests/docker/dockerfiles/`` directory.
338 A ``.pre`` script can be added beside the ``.docker`` file, which will be
339 executed before building the image under the build context directory. This is
340 mainly used to do necessary host side setup. One such setup is ``binfmt_misc``,
341 for example, to make qemu-user powered cross build containers work.
343 Tests
344 -----
346 Different tests are added to cover various configurations to build and test
347 QEMU.  Docker tests are the executables under ``tests/docker`` named
348 ``test-*``. They are typically shell scripts and are built on top of a shell
349 library, ``tests/docker/common.rc``, which provides helpers to find the QEMU
350 source and build it.
352 The full list of tests is printed in the ``make docker`` help.
354 Tools
355 -----
357 There are executables that are created to run in a specific Docker environment.
358 This makes it easy to write scripts that have heavy or special dependencies,
359 but are still very easy to use.
361 Currently the only tool is ``travis``, which mimics the Travis-CI tests in a
362 container. It runs in the ``travis`` image:
364 .. code::
366   make docker-travis@travis
368 Debugging a Docker test failure
369 -------------------------------
371 When CI tasks, maintainers or yourself report a Docker test failure, follow the
372 below steps to debug it:
374 1. Locally reproduce the failure with the reported command line. E.g. run
375    ``make docker-test-mingw@fedora J=8``.
376 2. Add "V=1" to the command line, try again, to see the verbose output.
377 3. Further add "DEBUG=1" to the command line. This will pause in a shell prompt
378    in the container right before testing starts. You could either manually
379    build QEMU and run tests from there, or press Ctrl-D to let the Docker
380    testing continue.
381 4. If you press Ctrl-D, the same building and testing procedure will begin, and
382    will hopefully run into the error again. After that, you will be dropped to
383    the prompt for debug.
385 Options
386 -------
388 Various options can be used to affect how Docker tests are done. The full
389 list is in the ``make docker`` help text. The frequently used ones are:
391 * ``V=1``: the same as in top level ``make``. It will be propagated to the
392   container and enable verbose output.
393 * ``J=$N``: the number of parallel tasks in make commands in the container,
394   similar to the ``-j $N`` option in top level ``make``. (The ``-j`` option in
395   top level ``make`` will not be propagated into the container.)
396 * ``DEBUG=1``: enables debug. See the previous "Debugging a Docker test
397   failure" section.
399 VM testing
400 ==========
402 This test suite contains scripts that bootstrap various guest images that have
403 necessary packages to build QEMU. The basic usage is documented in ``Makefile``
404 help which is displayed with ``make vm-help``.
406 Quickstart
407 ----------
409 Run ``make vm-help`` to list available make targets. Invoke a specific make
410 command to run build test in an image. For example, ``make vm-build-freebsd``
411 will build the source tree in the FreeBSD image. The command can be executed
412 from either the source tree or the build dir; if the former, ``./configure`` is
413 not needed. The command will then generate the test image in ``./tests/vm/``
414 under the working directory.
416 Note: images created by the scripts accept a well-known RSA key pair for SSH
417 access, so they SHOULD NOT be exposed to external interfaces if you are
418 concerned about attackers taking control of the guest and potentially
419 exploiting a QEMU security bug to compromise the host.
421 QEMU binaries
422 -------------
424 By default, qemu-system-x86_64 is searched in $PATH to run the guest. If there
425 isn't one, or if it is older than 2.10, the test won't work. In this case,
426 provide the QEMU binary in env var: ``QEMU=/path/to/qemu-2.10+``.
428 Likewise the path to qemu-img can be set in QEMU_IMG environment variable.
430 Make jobs
431 ---------
433 The ``-j$X`` option in the make command line is not propagated into the VM,
434 specify ``J=$X`` to control the make jobs in the guest.
436 Debugging
437 ---------
439 Add ``DEBUG=1`` and/or ``V=1`` to the make command to allow interactive
440 debugging and verbose output. If this is not enough, see the next section.
441 ``V=1`` will be propagated down into the make jobs in the guest.
443 Manual invocation
444 -----------------
446 Each guest script is an executable script with the same command line options.
447 For example to work with the netbsd guest, use ``$QEMU_SRC/tests/vm/netbsd``:
449 .. code::
451     $ cd $QEMU_SRC/tests/vm
453     # To bootstrap the image
454     $ ./netbsd --build-image --image /var/tmp/netbsd.img
455     <...>
457     # To run an arbitrary command in guest (the output will not be echoed unless
458     # --debug is added)
459     $ ./netbsd --debug --image /var/tmp/netbsd.img uname -a
461     # To build QEMU in guest
462     $ ./netbsd --debug --image /var/tmp/netbsd.img --build-qemu $QEMU_SRC
464     # To get to an interactive shell
465     $ ./netbsd --interactive --image /var/tmp/netbsd.img sh
467 Adding new guests
468 -----------------
470 Please look at existing guest scripts for how to add new guests.
472 Most importantly, create a subclass of BaseVM and implement ``build_image()``
473 method and define ``BUILD_SCRIPT``, then finally call ``basevm.main()`` from
474 the script's ``main()``.
476 * Usually in ``build_image()``, a template image is downloaded from a
477   predefined URL. ``BaseVM._download_with_cache()`` takes care of the cache and
478   the checksum, so consider using it.
480 * Once the image is downloaded, users, SSH server and QEMU build deps should
481   be set up:
483   - Root password set to ``BaseVM.ROOT_PASS``
484   - User ``BaseVM.GUEST_USER`` is created, and password set to
485     ``BaseVM.GUEST_PASS``
486   - SSH service is enabled and started on boot,
487     ``$QEMU_SRC/tests/keys/id_rsa.pub`` is added to ssh's ``authorized_keys``
488     file of both root and the normal user
489   - DHCP client service is enabled and started on boot, so that it can
490     automatically configure the virtio-net-pci NIC and communicate with QEMU
491     user net (10.0.2.2)
492   - Necessary packages are installed to untar the source tarball and build
493     QEMU
495 * Write a proper ``BUILD_SCRIPT`` template, which should be a shell script that
496   untars a raw virtio-blk block device, which is the tarball data blob of the
497   QEMU source tree, then configure/build it. Running "make check" is also
498   recommended.
500 Image fuzzer testing
501 ====================
503 An image fuzzer was added to exercise format drivers. Currently only qcow2 is
504 supported. To start the fuzzer, run
506 .. code::
508   tests/image-fuzzer/runner.py -c '[["qemu-img", "info", "$test_img"]]' /tmp/test qcow2
510 Alternatively, some command different from "qemu-img info" can be tested, by
511 changing the ``-c`` option.
513 Acceptance tests using the Avocado Framework
514 ============================================
516 The ``tests/acceptance`` directory hosts functional tests, also known
517 as acceptance level tests.  They're usually higher level tests, and
518 may interact with external resources and with various guest operating
519 systems.
521 These tests are written using the Avocado Testing Framework (which must
522 be installed separately) in conjunction with a the ``avocado_qemu.Test``
523 class, implemented at ``tests/acceptance/avocado_qemu``.
525 Tests based on ``avocado_qemu.Test`` can easily:
527  * Customize the command line arguments given to the convenience
528    ``self.vm`` attribute (a QEMUMachine instance)
530  * Interact with the QEMU monitor, send QMP commands and check
531    their results
533  * Interact with the guest OS, using the convenience console device
534    (which may be useful to assert the effectiveness and correctness of
535    command line arguments or QMP commands)
537  * Interact with external data files that accompany the test itself
538    (see ``self.get_data()``)
540  * Download (and cache) remote data files, such as firmware and kernel
541    images
543  * Have access to a library of guest OS images (by means of the
544    ``avocado.utils.vmimage`` library)
546  * Make use of various other test related utilities available at the
547    test class itself and at the utility library:
549    - http://avocado-framework.readthedocs.io/en/latest/api/test/avocado.html#avocado.Test
550    - http://avocado-framework.readthedocs.io/en/latest/api/utils/avocado.utils.html
552 Running tests
553 -------------
555 You can run the acceptance tests simply by executing:
557 .. code::
559   make check-acceptance
561 This involves the automatic creation of Python virtual environment
562 within the build tree (at ``tests/venv``) which will have all the
563 right dependencies, and will save tests results also within the
564 build tree (at ``tests/results``).
566 Note: the build environment must be using a Python 3 stack, and have
567 the ``venv`` and ``pip`` packages installed.  If necessary, make sure
568 ``configure`` is called with ``--python=`` and that those modules are
569 available.  On Debian and Ubuntu based systems, depending on the
570 specific version, they may be on packages named ``python3-venv`` and
571 ``python3-pip``.
573 The scripts installed inside the virtual environment may be used
574 without an "activation".  For instance, the Avocado test runner
575 may be invoked by running:
577  .. code::
579   tests/venv/bin/avocado run $OPTION1 $OPTION2 tests/acceptance/
581 Manual Installation
582 -------------------
584 To manually install Avocado and its dependencies, run:
586 .. code::
588   pip install --user avocado-framework
590 Alternatively, follow the instructions on this link:
592   http://avocado-framework.readthedocs.io/en/latest/GetStartedGuide.html#installing-avocado
594 Overview
595 --------
597 The ``tests/acceptance/avocado_qemu`` directory provides the
598 ``avocado_qemu`` Python module, containing the ``avocado_qemu.Test``
599 class.  Here's a simple usage example:
601 .. code::
603   from avocado_qemu import Test
606   class Version(Test):
607       """
608       :avocado: tags=quick
609       """
610       def test_qmp_human_info_version(self):
611           self.vm.launch()
612           res = self.vm.command('human-monitor-command',
613                                 command_line='info version')
614           self.assertRegexpMatches(res, r'^(\d+\.\d+\.\d)')
616 To execute your test, run:
618 .. code::
620   avocado run version.py
622 Tests may be classified according to a convention by using docstring
623 directives such as ``:avocado: tags=TAG1,TAG2``.  To run all tests
624 in the current directory, tagged as "quick", run:
626 .. code::
628   avocado run -t quick .
630 The ``avocado_qemu.Test`` base test class
631 -----------------------------------------
633 The ``avocado_qemu.Test`` class has a number of characteristics that
634 are worth being mentioned right away.
636 First of all, it attempts to give each test a ready to use QEMUMachine
637 instance, available at ``self.vm``.  Because many tests will tweak the
638 QEMU command line, launching the QEMUMachine (by using ``self.vm.launch()``)
639 is left to the test writer.
641 The base test class has also support for tests with more than one
642 QEMUMachine. The way to get machines is through the ``self.get_vm()``
643 method which will return a QEMUMachine instance. The ``self.get_vm()``
644 method accepts arguments that will be passed to the QEMUMachine creation
645 and also an optional `name` attribute so you can identify a specific
646 machine and get it more than once through the tests methods. A simple
647 and hypothetical example follows:
649 .. code::
651   from avocado_qemu import Test
654   class MultipleMachines(Test):
655       """
656       :avocado: enable
657       """
658       def test_multiple_machines(self):
659           first_machine = self.get_vm()
660           second_machine = self.get_vm()
661           self.get_vm(name='third_machine').launch()
663           first_machine.launch()
664           second_machine.launch()
666           first_res = first_machine.command(
667               'human-monitor-command',
668               command_line='info version')
670           second_res = second_machine.command(
671               'human-monitor-command',
672               command_line='info version')
674           third_res = self.get_vm(name='third_machine').command(
675               'human-monitor-command',
676               command_line='info version')
678           self.assertEquals(first_res, second_res, third_res)
680 At test "tear down", ``avocado_qemu.Test`` handles all the QEMUMachines
681 shutdown.
683 QEMUMachine
684 ~~~~~~~~~~~
686 The QEMUMachine API is already widely used in the Python iotests,
687 device-crash-test and other Python scripts.  It's a wrapper around the
688 execution of a QEMU binary, giving its users:
690  * the ability to set command line arguments to be given to the QEMU
691    binary
693  * a ready to use QMP connection and interface, which can be used to
694    send commands and inspect its results, as well as asynchronous
695    events
697  * convenience methods to set commonly used command line arguments in
698    a more succinct and intuitive way
700 QEMU binary selection
701 ~~~~~~~~~~~~~~~~~~~~~
703 The QEMU binary used for the ``self.vm`` QEMUMachine instance will
704 primarily depend on the value of the ``qemu_bin`` parameter.  If it's
705 not explicitly set, its default value will be the result of a dynamic
706 probe in the same source tree.  A suitable binary will be one that
707 targets the architecture matching host machine.
709 Based on this description, test writers will usually rely on one of
710 the following approaches:
712 1) Set ``qemu_bin``, and use the given binary
714 2) Do not set ``qemu_bin``, and use a QEMU binary named like
715    "${arch}-softmmu/qemu-system-${arch}", either in the current
716    working directory, or in the current source tree.
718 The resulting ``qemu_bin`` value will be preserved in the
719 ``avocado_qemu.Test`` as an attribute with the same name.
721 Attribute reference
722 -------------------
724 Besides the attributes and methods that are part of the base
725 ``avocado.Test`` class, the following attributes are available on any
726 ``avocado_qemu.Test`` instance.
731 A QEMUMachine instance, initially configured according to the given
732 ``qemu_bin`` parameter.
734 arch
735 ~~~~
737 The architecture can be used on different levels of the stack, e.g. by
738 the framework or by the test itself.  At the framework level, it will
739 currently influence the selection of a QEMU binary (when one is not
740 explicitly given).
742 Tests are also free to use this attribute value, for their own needs.
743 A test may, for instance, use the same value when selecting the
744 architecture of a kernel or disk image to boot a VM with.
746 The ``arch`` attribute will be set to the test parameter of the same
747 name.  If one is not given explicitly, it will either be set to
748 ``None``, or, if the test is tagged with one (and only one)
749 ``:avocado: tags=arch:VALUE`` tag, it will be set to ``VALUE``.
751 machine
752 ~~~~~~~
754 The machine type that will be set to all QEMUMachine instances created
755 by the test.
757 The ``machine`` attribute will be set to the test parameter of the same
758 name.  If one is not given explicitly, it will either be set to
759 ``None``, or, if the test is tagged with one (and only one)
760 ``:avocado: tags=machine:VALUE`` tag, it will be set to ``VALUE``.
762 qemu_bin
763 ~~~~~~~~
765 The preserved value of the ``qemu_bin`` parameter or the result of the
766 dynamic probe for a QEMU binary in the current working directory or
767 source tree.
769 Parameter reference
770 -------------------
772 To understand how Avocado parameters are accessed by tests, and how
773 they can be passed to tests, please refer to::
775   http://avocado-framework.readthedocs.io/en/latest/WritingTests.html#accessing-test-parameters
777 Parameter values can be easily seen in the log files, and will look
778 like the following:
780 .. code::
782   PARAMS (key=qemu_bin, path=*, default=x86_64-softmmu/qemu-system-x86_64) => 'x86_64-softmmu/qemu-system-x86_64
784 arch
785 ~~~~
787 The architecture that will influence the selection of a QEMU binary
788 (when one is not explicitly given).
790 Tests are also free to use this parameter value, for their own needs.
791 A test may, for instance, use the same value when selecting the
792 architecture of a kernel or disk image to boot a VM with.
794 This parameter has a direct relation with the ``arch`` attribute.  If
795 not given, it will default to None.
797 machine
798 ~~~~~~~
800 The machine type that will be set to all QEMUMachine instances created
801 by the test.
804 qemu_bin
805 ~~~~~~~~
807 The exact QEMU binary to be used on QEMUMachine.
809 Uninstalling Avocado
810 --------------------
812 If you've followed the manual installation instructions above, you can
813 easily uninstall Avocado.  Start by listing the packages you have
814 installed::
816   pip list --user
818 And remove any package you want with::
820   pip uninstall <package_name>
822 If you've used ``make check-acceptance``, the Python virtual environment where
823 Avocado is installed will be cleaned up as part of ``make check-clean``.
825 Testing with "make check-tcg"
826 =============================
828 The check-tcg tests are intended for simple smoke tests of both
829 linux-user and softmmu TCG functionality. However to build test
830 programs for guest targets you need to have cross compilers available.
831 If your distribution supports cross compilers you can do something as
832 simple as::
834   apt install gcc-aarch64-linux-gnu
836 The configure script will automatically pick up their presence.
837 Sometimes compilers have slightly odd names so the availability of
838 them can be prompted by passing in the appropriate configure option
839 for the architecture in question, for example::
841   $(configure) --cross-cc-aarch64=aarch64-cc
843 There is also a ``--cross-cc-flags-ARCH`` flag in case additional
844 compiler flags are needed to build for a given target.
846 If you have the ability to run containers as the user you can also
847 take advantage of the build systems "Docker" support. It will then use
848 containers to build any test case for an enabled guest where there is
849 no system compiler available. See :ref: `_docker-ref` for details.
851 Running subset of tests
852 -----------------------
854 You can build the tests for one architecture::
856   make build-tcg-tests-$TARGET
858 And run with::
860   make run-tcg-tests-$TARGET
862 Adding ``V=1`` to the invocation will show the details of how to
863 invoke QEMU for the test which is useful for debugging tests.
865 TCG test dependencies
866 ---------------------
868 The TCG tests are deliberately very light on dependencies and are
869 either totally bare with minimal gcc lib support (for softmmu tests)
870 or just glibc (for linux-user tests). This is because getting a cross
871 compiler to work with additional libraries can be challenging.
873 Other TCG Tests
874 ---------------
876 There are a number of out-of-tree test suites that are used for more
877 extensive testing of processor features.
879 KVM Unit Tests
880 ~~~~~~~~~~~~~~
882 The KVM unit tests are designed to run as a Guest OS under KVM but
883 there is no reason why they can't exercise the TCG as well. It
884 provides a minimal OS kernel with hooks for enabling the MMU as well
885 as reporting test results via a special device::
887   https://git.kernel.org/pub/scm/virt/kvm/kvm-unit-tests.git
889 Linux Test Project
890 ~~~~~~~~~~~~~~~~~~
892 The LTP is focused on exercising the syscall interface of a Linux
893 kernel. It checks that syscalls behave as documented and strives to
894 exercise as many corner cases as possible. It is a useful test suite
895 to run to exercise QEMU's linux-user code::
897   https://linux-test-project.github.io/