diff --git a/docs/devel/acpi-bits.rst b/docs/devel/acpi-bits.rst index 9677b0098f..1ec394f5fb 100644 --- a/docs/devel/acpi-bits.rst +++ b/docs/devel/acpi-bits.rst @@ -1,26 +1,48 @@ ============================================================================= ACPI/SMBIOS avocado tests using biosbits ============================================================================= - +************ +Introduction +************ Biosbits is a software written by Josh Triplett that can be downloaded from https://biosbits.org/. The github codebase can be found -`here `__. It is a software that executes -the bios components such as acpi and smbios tables directly through acpica -bios interpreter (a freely available C based library written by Intel, +`here `__. It is a software that +executes the bios components such as acpi and smbios tables directly through +acpica bios interpreter (a freely available C based library written by Intel, downloadable from https://acpica.org/ and is included with biosbits) without an -operating system getting involved in between. +operating system getting involved in between. Bios-bits has python integration +with grub so actual routines that executes bios components can be written in +python instead of bash-ish (grub's native scripting language). There are several advantages to directly testing the bios in a real physical -machine or VM as opposed to indirectly discovering bios issues through the -operating system. For one thing, the OSes tend to hide bios problems from the -end user. The other is that we have more control of what we wanted to test -and how by directly using acpica interpreter on top of the bios on a running -system. More details on the inspiration for developing biosbits and its real -life uses can be found in [#a]_ and [#b]_. +machine or in a VM as opposed to indirectly discovering bios issues through the +operating system (the OS). Operating systems tend to bypass bios problems and +hide them from the end user. We have more control of what we wanted to test and +how by being as close to the bios on a running system as possible without a +complicated software component such as an operating system coming in between. +Another issue is that we cannot exercise bios components such as ACPI and +SMBIOS without being in the highest hardware privilege level, ring 0 for +example in case of x86. Since the OS executes from ring 0 whereas normal user +land software resides in unprivileged ring 3, operating system must be modified +in order to write our test routines that exercise and test the bios. This is +not possible in all cases. Lastly, test frameworks and routines are preferably +written using a high level scripting language such as python. OSes and +OS modules are generally written using low level languages such as C and +low level assembly machine language. Writing test routines in a low level +language makes things more cumbersome. These and other reasons makes using +bios-bits very attractive for testing bioses. More details on the inspiration +for developing biosbits and its real life uses can be found in [#a]_ and [#b]_. + For QEMU, we maintain a fork of bios bits in gitlab along with all the -dependent submodules here: https://gitlab.com/qemu-project/biosbits-bits +dependent submodules `here `__. This fork contains numerous fixes, a newer acpica and changes specific to running this avocado QEMU tests using bits. The author of this document -is the sole maintainer of the QEMU fork of bios bits repo. +is the sole maintainer of the QEMU fork of bios bits repository. For more +information, please see author's `FOSDEM talk on this bios-bits based test +framework `__. + +********************************* +Description of the test framework +********************************* Under the directory ``tests/avocado/``, ``acpi-bits.py`` is a QEMU avocado test that drives all this. @@ -120,8 +142,9 @@ Under ``tests/avocado/`` as the root we have: (b) Add a SPDX license header. (c) Perform modifications to the test. - Commits (a), (b) and (c) should go under separate commits so that the original - test script and the changes we have made are separated and clear. + Commits (a), (b) and (c) preferably should go under separate commits so that + the original test script and the changes we have made are separated and + clear. (a) and (b) can sometimes be combined into a single step. The test framework will then use your modified test script to run the test. No further changes would be needed. Please check the logs to make sure that @@ -141,4 +164,4 @@ References: ----------- .. [#a] https://blog.linuxplumbersconf.org/2011/ocw/system/presentations/867/original/bits.pdf .. [#b] https://www.youtube.com/watch?v=36QIepyUuhg - +.. [#c] https://fosdem.org/2024/schedule/event/fosdem-2024-2262-exercising-qemu-generated-acpi-smbios-tables-using-biosbits-from-within-a-guest-vm-/