mail archive of the barebox mailing list
 help / color / mirror / Atom feed
From: Ahmad Fatoum <a.fatoum@pengutronix.de>
To: barebox@lists.infradead.org
Cc: Ahmad Fatoum <a.fatoum@pengutronix.de>
Subject: [PATCH 5/5] Documentation: board: emulated: rewrite to use MAKEALL/pytest directly
Date: Thu, 22 Aug 2024 13:57:30 +0200	[thread overview]
Message-ID: <20240822115730.1184500-5-a.fatoum@pengutronix.de> (raw)
In-Reply-To: <20240822115730.1184500-1-a.fatoum@pengutronix.de>

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@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@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@multi_v7_defconfig --no-tuxmake --test
+  # Run tests and pass a block device (here /dev/virtioblk0)
+  pytest --lg-env test/arm/virt@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




  parent reply	other threads:[~2024-08-22 11:58 UTC|newest]

Thread overview: 6+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2024-08-22 11:57 [PATCH 1/5] test: conftest.py: move top-level Ahmad Fatoum
2024-08-22 11:57 ` [PATCH 2/5] MAKEALL: return error code from do_build_target Ahmad Fatoum
2024-08-22 11:57 ` [PATCH 3/5] MAKEALL: don't build all configs wen defconfigs given Ahmad Fatoum
2024-08-22 11:57 ` [PATCH 4/5] MAKEALL: add support for running pytest after build Ahmad Fatoum
2024-08-22 11:57 ` Ahmad Fatoum [this message]
2024-08-23  8:04 ` [PATCH 1/5] test: conftest.py: move top-level Sascha Hauer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20240822115730.1184500-5-a.fatoum@pengutronix.de \
    --to=a.fatoum@pengutronix.de \
    --cc=barebox@lists.infradead.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox