| 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. |