docs/devel/acpi-bits.rst

   1 =============================================================================
   2 ACPI/SMBIOS avocado tests using biosbits
   3 =============================================================================
   4 ************
   5 Introduction
   6 ************
   7 Biosbits is a software written by Josh Triplett that can be downloaded
   8 from https://biosbits.org/. The github codebase can be found
   9 `here <https://github.com/biosbits/bits/tree/master>`__. It is a software that
  10 executes the bios components such as acpi and smbios tables directly through
  11 acpica bios interpreter (a freely available C based library written by Intel,
  12 downloadable from https://acpica.org/ and is included with biosbits) without an
  13 operating system getting involved in between. Bios-bits has python integration
  14 with grub so actual routines that executes bios components can be written in
  15 python instead of bash-ish (grub's native scripting language).
  16 There are several advantages to directly testing the bios in a real physical
  17 machine or in a VM as opposed to indirectly discovering bios issues through the
  18 operating system (the OS). Operating systems tend to bypass bios problems and
  19 hide them from the end user. We have more control of what we wanted to test and
  20 how by being as close to the bios on a running system as possible without a
  21 complicated software component such as an operating system coming in between.
  22 Another issue is that we cannot exercise bios components such as ACPI and
  23 SMBIOS without being in the highest hardware privilege level, ring 0 for
  24 example in case of x86. Since the OS executes from ring 0 whereas normal user
  25 land software resides in unprivileged ring 3, operating system must be modified
  26 in order to write our test routines that exercise and test the bios. This is
  27 not possible in all cases. Lastly, test frameworks and routines are preferably
  28 written using a high level scripting language such as python. OSes and
  29 OS modules are generally written using low level languages such as C and
  30 low level assembly machine language. Writing test routines in a low level
  31 language makes things more cumbersome. These and other reasons makes using
  32 bios-bits very attractive for testing bioses. More details on the inspiration
  33 for developing biosbits and its real life uses can be found in [#a]_ and [#b]_.
  34
  35 For QEMU, we maintain a fork of bios bits in gitlab along with all the
  36 dependent submodules `here <https://gitlab.com/qemu-project/biosbits-bits>`__.
  37 This fork contains numerous fixes, a newer acpica and changes specific to
  38 running this avocado QEMU tests using bits. The author of this document
  39 is the sole maintainer of the QEMU fork of bios bits repository. For more
  40 information, please see author's `FOSDEM talk on this bios-bits based test
  41 framework <https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/>`__.
  42
  43 *********************************
  44 Description of the test framework
  45 *********************************
  46
  47 Under the directory ``tests/avocado/``, ``acpi-bits.py`` is a QEMU avocado
  48 test that drives all this.
  49
  50 A brief description of the various test files follows.
  51
  52 Under ``tests/avocado/`` as the root we have:
  53
  54 ::
  55
  56    ├── acpi-bits
  57    │ ├── bits-config
  58    │ │ └── bits-cfg.txt
  59    │ ├── bits-tests
  60    │   ├── smbios.py2
  61    │   ├── testacpi.py2
  62    │   └── testcpuid.py2
  63    ├── acpi-bits.py
  64
  65 * ``tests/avocado``:
  66
  67    ``acpi-bits.py``:
  68    This is the main python avocado test script that generates a
  69    biosbits iso. It then spawns a QEMU VM with it, collects the log and reports
  70    test failures. This is the script one would be interested in if they wanted
  71    to add or change some component of the log parsing, add a new command line
  72    to alter how QEMU is spawned etc. Test writers typically would not need to
  73    modify this script unless they wanted to enhance or change the log parsing
  74    for their tests. In order to enable debugging, you can set **V=1**
  75    environment variable. This enables verbose mode for the test and also dumps
  76    the entire log from bios bits and more information in case failure happens.
  77    You can also set **BITS_DEBUG=1** to turn on debug mode. It will enable
  78    verbose logs and also retain the temporary work directory the test used for
  79    you to inspect and run the specific commands manually.
  80
  81    In order to run this test, please perform the following steps from the QEMU
  82    build directory:
  83    ::
  84
  85      $ make check-venv (needed only the first time to create the venv)
  86      $ ./pyvenv/bin/avocado run -t acpi tests/avocado
  87
  88    The above will run all acpi avocado tests including this one.
  89    In order to run the individual tests, perform the following:
  90    ::
  91
  92      $ ./pyvenv/bin/avocado run tests/avocado/acpi-bits.py --tap -
  93
  94    The above will produce output in tap format. You can omit "--tap -" in the
  95    end and it will produce output like the following:
  96    ::
  97
  98       $ ./pyvenv/bin/avocado run tests/avocado/acpi-bits.py
  99       Fetching asset from tests/avocado/acpi-bits.py:AcpiBitsTest.test_acpi_smbios_bits
 100       JOB ID     : eab225724da7b64c012c65705dc2fa14ab1defef
 101       JOB LOG    : /home/anisinha/avocado/job-results/job-2022-10-10T17.58-eab2257/job.log
 102       (1/1) tests/avocado/acpi-bits.py:AcpiBitsTest.test_acpi_smbios_bits: PASS (33.09 s)
 103       RESULTS    : PASS 1 | ERROR 0 | FAIL 0 | SKIP 0 | WARN 0 | INTERRUPT 0 | CANCEL 0
 104       JOB TIME   : 39.22 s
 105
 106    You can inspect the log file for more information about the run or in order
 107    to diagnoze issues. If you pass V=1 in the environment, more diagnostic logs
 108    would be found in the test log.
 109
 110 * ``tests/avocado/acpi-bits/bits-config``:
 111
 112    This location contains biosbits configuration files that determine how the
 113    software runs the tests.
 114
 115    ``bits-config.txt``:
 116    This is the biosbits config file that determines what tests
 117    or actions are performed by bits. The description of the config options are
 118    provided in the file itself.
 119
 120 * ``tests/avocado/acpi-bits/bits-tests``:
 121
 122    This directory contains biosbits python based tests that are run from within
 123    the biosbits environment in the spawned VM. New additions of test cases can
 124    be made in the appropriate test file. For example, new acpi tests can go
 125    into testacpi.py2 and one would call testsuite.add_test() to register the new
 126    test so that it gets executed as a part of the ACPI tests.
 127    It might be occasionally necessary to disable some subtests or add a new
 128    test that belongs to a test suite not already present in this directory. To
 129    do this, please clone the bits source from
 130    https://gitlab.com/qemu-project/biosbits-bits/-/tree/qemu-bits.
 131    Note that this is the "qemu-bits" branch and not the "bits" branch of the
 132    repository. "qemu-bits" is the branch where we have made all the QEMU
 133    specific enhancements and we must use the source from this branch only.
 134    Copy the test suite/script that needs modification (addition of new tests
 135    or disabling them) from python directory into this directory. For
 136    example, in order to change cpuid related tests, copy the following
 137    file into this directory and rename it with .py2 extension:
 138    https://gitlab.com/qemu-project/biosbits-bits/-/blob/qemu-bits/python/testcpuid.py
 139    Then make your additions and changes here. Therefore, the steps are:
 140
 141        (a) Copy unmodified test script to this directory from bits source.
 142        (b) Add a SPDX license header.
 143        (c) Perform modifications to the test.
 144
 145    Commits (a), (b) and (c) preferably should go under separate commits so that
 146    the original test script and the changes we have made are separated and
 147    clear. (a) and (b) can sometimes be combined into a single step.
 148
 149    The test framework will then use your modified test script to run the test.
 150    No further changes would be needed. Please check the logs to make sure that
 151    appropriate changes have taken effect.
 152
 153    The tests have an extension .py2 in order to indicate that:
 154
 155    (a) They are python2.7 based scripts and not python 3 scripts.
 156    (b) They are run from within the bios bits VM and is not subjected to QEMU
 157        build/test python script maintenance and dependency resolutions.
 158    (c) They need not be loaded by avocado framework when running tests.
 159
 160
 161 Author: Ani Sinha <anisinha@redhat.com>
 162
 163 References:
 164 -----------
 165 .. [#a] https://blog.linuxplumbersconf.org/2011/ocw/system/presentations/867/original/bits.pdf
 166 .. [#b] https://www.youtube.com/watch?v=36QIepyUuhg
 167 .. [#c] https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/