[PATCH 5/5] Documentation: board: emulated: rewrite to use MAKEALL/pytest directly

[Ahmad Fatoum]

I added test/emulate.pl for my own use, but it didn't catch on. The CI
uses MAKEALL and lots of functionality has been migrated into pytest
proper, e.g. test/emulate.pl --emulate is now pytest --interactive.

Everything that's described in the docs is now supported though by
MAKEALL/pytest, so let's rewrite the documentation to use them.

There's still some features remaining that only emulate.pl supports,
once these are present in MAKEALL/pytest, we can drop it too.

Signed-off-by: Ahmad Fatoum <a.fatoum at pengutronix.de>
---
 Documentation/boards/emulated.rst | 85 +++++++++++++++++--------------
 1 file changed, 47 insertions(+), 38 deletions(-)

diff --git a/Documentation/boards/emulated.rst b/Documentation/boards/emulated.rst
index a67533613ec5..99c55d2051c2 100644
--- a/Documentation/boards/emulated.rst
+++ b/Documentation/boards/emulated.rst
@@ -20,56 +20,65 @@ fix up the virtio mmio regions into the device tree and barebox will
 discover the devices automatically, analogously to what it does with
 VirtIO over PCI.
 
-test/emulate.pl
----------------
+labgrid
+-------
 
-The ``emulate.pl`` script shipped with barebox can be used to easily
-start VMs. It reads a number of YAML files in ``test/$ARCH``, which
-describe some virtualized targets that barebox is known to run on.
-
-Controlled by command line options, these targets are built with
-tuxmake if available and loaded into the emulator for either interactive
-use or for automated testing with Labgrid ``QEMUDriver``.
-
-.. _tuxmake: https://pypi.org/project/tuxmake/
-.. _Labgrid: https://labgrid.org
-
-Install dependencies for interactive use::
-
-  cpan YAML::XS # or use e.g. libyaml-libyaml-perl on Debian
-  pip3 install tuxmake # optional
+Labgrid is used to run the barebox test suite, both on real and emulated
+hardware. A number of YAML files located in ``test/$ARCH`` describe some
+of the virtualized targets that barebox is known to run on.
 
 Example usage::
 
-  # Switch to barebox source directory
-  cd barebox
+  # Run x86 VM runnig the EFI payload from efi_defconfig
+  pytest --lg-env test/x86/efi_defconfig.yaml --interactive
 
-  # emulate x86 VM runnig the EFI payload from efi_defconfig
-  ARCH=x86 ./test/emulate.pl efi_defconfig
+  # Run the test suite against the same
+  pytest --lg-env test/x86/efi_defconfig.yaml
 
-  # build all MIPS targets known to emulate.pl and exit
-  ARCH=mips ./test/emulate.pl --no-emulate
+The above assumes that barebox has already been built for the
+configuration and that labgrid is available. If barebox has been
+built out-of-tree, the build directory must be pointed at by
+``LG_BUILDDIR``, ``KBUILD_OUTPUT`` or a ``build`` symlink.
 
-The script can also be used with a precompiled barebox tree::
+Additional QEMU command-line options can be added by specifying
+them after the ``--qemu`` option::
 
-  # Switch to build directory
-  export KBUILD_OUTPUT=build
+  # appends -device ? to the command line. Add --dry-run to see the final result
+  pytest --lg-env test/riscv/rv64i_defconfig.yaml --interactive --qemu -device '?'
 
-  # run a barebox image built outside tuxmake on an ARM virt machine
-  ARCH=arm ./test/emulate.pl virt at multi_v7_defconfig --no-tuxmake
+Some of the QEMU options that are used more often also have explicit
+support in the test runner, so paravirtualized devices can be added
+more easily::
 
-  # run tests instead of starting emulator interactively
-  ARCH=arm ./test/emulate.pl virt at multi_v7_defconfig --no-tuxmake --test
+  # Run tests and pass a block device (here /dev/virtioblk0)
+  pytest --lg-env test/arm/virt at multi_v8_defconfig.yaml --blk=rootfs.ext4
 
-``emulate.pl`` also has some knowledge on paravirtualized devices::
+For a complete listing of possible options run ``pytest --help``.
 
-  # Run target and pass a block device (here /dev/virtioblk0)
-  ARCH=riscv ./test/emulate.pl --blk=rootfs.ext4 rv64i_defconfig
+MAKEALL
+-------
 
-Needed command line options can be passed directly to the
-emulator/``pytest`` as well by placing them behind ``--``::
+The ``MAKEALL`` script is a wrapper around ``make`` to more easily build
+multiple configurations. It also accepts YAML Labgrid environment files
+as arguments, which will cause it to build and then run the tests::
 
-  # appends -device ? to the command line. Add -n to see the final result
-  ARCH=riscv ./test/emulate.pl rv64i_defconfig -- -device ?
+  ./MAKEALL test/mips/qemu-maltael_defconfig.yaml
 
-For a complete listing of options run ``./test/emulate.pl -h``.
+This expects ``CROSS_COMPILE`` (or ``CROSS_COMPILE_mips``) to have been
+set beforehand to point at an appropriate toolchain prefix.
+
+The barebox-ci container provides an easy way to run ``MAKEALL`` against
+all configurations supported by barebox, even if the host system
+lacks the appropriate toolchains::
+
+  # Run MAKEALL and possibly pytest in the container
+  alias MAKEALL="scripts/container.sh ./MAKEALL"
+
+  # Build a single configuration
+  MAKEALL test/mips/qemu-maltael_defconfig.yaml
+
+  # Build all configurations for an architecture, no test
+  MAKEALL -a riscv
+
+  # Build all mips platforms that can be tested
+  MAKEALL test/mips/*.yaml
-- 
2.39.2