Debian Codegraph @

vmtest/README.rst

raw
1 drgn VM Testing
2 ===============
3
4 drgn has a significant amount of code (both core and in helpers) which is
5 dependent on the Linux kernel version. This code is tested on multiple Linux
6 kernel versions in a virtual machine. These tests can be run on all supported
7 kernels with ``python3 setup.py test -K``. This requires QEMU and zstd to be
8 installed.
9
10 Tests can also be run on specific kernels with ``-k``. This takes a
11 comma-separated list of kernels which are wildcard patterns (e.g., ``5.6.*``)
12 matching a kernel release hosted on GitHub (see below).
13
14 Architecture
15 ------------
16
17 The goal of vmtest is to run tests in the same userspace environment as the
18 host, but with a different kernel. The host runs the virtual machine with `QEMU
19 <https://www.qemu.org/>`_ (see the `vmtest.vm <vm.py>`_ module).
20
21 The guest mounts the host's root filesystem as its own root filesystem via
22 `VirtFS <https://www.linux-kvm.org/page/VirtFS>`_. It is mounted read-only for
23 safety. To support modifications, the guest uses `OverlayFS
24 <https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt>`_ to
25 overlay a read-write tmpfs over the VirtFS root. It also mounts the kernel
26 modules and vmlinux via VirtFS.
27
28 The guest runs an init shell script which sets up the system and filesystem
29 hierarchy, runs a command, and returns the exit status via `virtio-serial
30 <https://fedoraproject.org/wiki/Features/VirtioSerial>`_.
31
32 This infrastructure is all generic. The drgn-specific parts are:
33
34 1. The kernel builds. These are configured with a minimal configuration
35 including everything required to run drgn and the Linux kernel helper tests.
36 Each build is packaged as a tarball containing ``vmlinux``, ``vmlinuz``, and
37 kernel modules. These packages are built by the `vmtest.kbuild <kbuild.py>`_
38 module. They are hosted in a `GitHub release
39 <https://github.com/osandov/drgn/releases/tag/vmtest-assets>`_ which is
40 managed via the GitHub API by the `vmtest.manage <manage.py>`_ CLI. New
41 kernel releases are built and uploaded by a `GitHub Actions workflow
42 <../.github/workflows/vmtest-build.yml>`_. The packages are downloaded by
43 the `vmtest.download <download.py>`_ module.
44 2. A `kernel module <../tests/linux_kernel/kmod>`_ for testing drgn
45 functionality that cannot be tested through userspace APIs.
46 3. The test command itself. This is just some ``setup.py`` glue to build the
47 test kernel module and run the VM with the proper invocation of the Python
48 `unittest command line interface
49 <https://docs.python.org/3/library/unittest.html#test-discovery>`_.
50
51 The ``vmtest.vm`` and ``vmtest.download`` modules also have CLIs for testing
52 purposes. These are subject to change.