new file mode 100644
@@ -0,0 +1,90 @@
+=============================================================================
+ACPI/SMBIOS PYTESTS USING BIOSBITS
+=============================================================================
+
+Biosbits is a software written by Josh Triplett that can be downloaded by
+visiting https://biosbits.org/. The github codebase can be found here:
+https://github.com/biosbits/bits/tree/master. 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.
+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).
+This directory contains tests written in python that exercizes the QEMU
+bios components using biosbits and reports test failures.
+Under the directory tests/avocado/, acpi-bits.py is a QEMU avocado test that
+drives all this.
+
+A brief description of the various test files follows.
+
+Under tests/avocado/ as the root we have:
+
+├── acpi-bits
+│ ├── bits-config
+│ │ └── bits-cfg.txt
+│ ├── bits-tests
+│ │ ├── smbios.py
+│ │ ├── smilatency.py
+│ │ ├── testacpi.py
+│ │ └── testcpuid.py
+│ └── README
+├── acpi-bits.py
+
+tests/avocado:
+ - acpi-bits.py: This is the main python avocado test script that generates a
+ biosbits iso. It then spawns a QEMU VM with it, collects the logs and reports
+ test failures. This is the script one would be interested in if they wanted
+ to add or change some component of the log parsing, add a new command line to
+ how QEMU is spawned etc. Test writers typically would not need to modify
+ this script unless they wanted to enhance or change the log parsing for
+ their tests. Following environment variables are used in this test:
+ - V=1 : This enables verbose mode for the test. It dumps the entire log
+ from bios bits and also more details in case failure happens. It is
+ useful for debugging the test failures or tests themselves.
+
+tests/avocado/acpi-bits:
+ - README: This text file.
+
+tests/avocado/acpi-bits/bits-config:
+ This location contains biosbits config files that determine how the software
+ runs the tests.
+ - bits-config.txt: this is the biosbits config file that determines what tests
+ or actions are performed by bits. The description of the config options are
+ provided in the file itself.
+
+tests/avocado/acpi-bits/bits-tests:
+ This directory contains biosbits python based tests that are run from within
+ the biosbits environment in the spawned VM. New additions of test cases can
+ be made in the appropriate test file. For example, new acpi tests can go
+ into testacpi.py and one would call testsuite.add_test() to register the new
+ test so that it gets executed as a part of the ACPI tests.
+ It might be occasionally necessary to disable some subtests or add a new
+ test that belongs to a test suite not already present in this directory. To
+ do this, please extract the bits source from the zip file mentioned above.
+ Copy the test suite/script that needs modification (addition of new tests
+ or disabling them) from boot/python location of the extracted directory
+ into this directory.
+
+ step (a): copy unmodified test script to this directory.
+ step (b): update meson.build and add this file to the list.
+ Commit (a) and (b) together in the same commit.
+
+ step (c): perform modifications to the test.
+ Commit (c) in a separate commit.
+
+ 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
+ appropriate changes have taken effect.
+
+
+Author: Ani Sinha <ani@anisinha.ca>
+
+References:
+(a) https://blog.linuxplumbersconf.org/2011/ocw/system/presentations/867/original/bits.pdf
+(b) https://www.youtube.com/watch?v=36QIepyUuhg
Add a README file that describes the purpose of the various test files and gives guidance to developers on where and how to make changes. Cc: Daniel P. BerrangÃ" <berrange@redhat.com> Cc: Paolo Bonzini <pbonzini@redhat.com> Cc: Maydell Peter <peter.maydell@linaro.org> Cc: John Snow <jsnow@redhat.com> Cc: Thomas Huth <thuth@redhat.com> Signed-off-by: Ani Sinha <ani@anisinha.ca> --- tests/avocado/acpi-bits/README | 90 ++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 tests/avocado/acpi-bits/README