drgn/vmtest
Omar Sandoval a000eed8f4 vmtest: kbuild: add scripts/check-local-export to module build files
Linux kernel commit 31cb50b5590f ("kbuild: check static EXPORT_SYMBOL*
by script instead of modpost") (in v5.19-rc1) added this script to the
build process, and the latest vmtest kernel build failed without it.

Signed-off-by: Omar Sandoval <osandov@osandov.com>
2022-06-06 02:08:23 -07:00
..
__init__.py Rewrite virtual machine testing setup 2020-04-02 17:35:24 -07:00
asynciosubprocess.py Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
download.py Fix some more flake8 errors 2022-05-17 15:23:42 -07:00
enter_kdump.py vmtest: only disable SMP for the capture kernel when not using KVM acceleration 2022-01-11 17:28:17 -08:00
githubapi.py Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
kbuild.py vmtest: kbuild: add scripts/check-local-export to module build files 2022-06-06 02:08:23 -07:00
manage.py vmtest: manage: add option to not build anything 2022-05-12 13:25:14 -07:00
onoatimehack.c Update copyright headers to Meta 2021-11-21 15:59:44 -08:00
README.rst tests: add framework for test kernel module 2022-05-16 14:27:35 -07:00
vm.py vmtest: only disable SMP for the capture kernel when not using KVM acceleration 2022-01-11 17:28:17 -08:00

drgn VM Testing
===============

drgn has a significant amount of code (both core and in helpers) which is
dependent on the Linux kernel version. This code is tested on multiple Linux
kernel versions in a virtual machine. These tests can be run on all supported
kernels with ``python3 setup.py test -K``. This requires QEMU, BusyBox, and
zstd to be installed.

Tests can also be run on specific kernels with ``-k``. This takes a
comma-separated list of kernels which are wildcard patterns (e.g., ``5.6.*``)
matching a kernel release hosted on GitHub (see below).

Architecture
------------

The goal of vmtest is to run tests in the same userspace environment as the
host, but with a different kernel. The host runs the virtual machine with `QEMU
<https://www.qemu.org/>`_ (see the `vmtest.vm <vm.py>`_ module).

The guest mounts the host's root filesystem as its own root filesystem via
`VirtFS <https://www.linux-kvm.org/page/VirtFS>`_. It is mounted read-only for
safety. To support modifications, the guest uses `OverlayFS
<https://www.kernel.org/doc/Documentation/filesystems/overlayfs.txt>`_ to
overlay a read-write tmpfs over the VirtFS root. It also mounts the kernel
modules and vmlinux via VirtFS.

The guest runs a `BusyBox <https://www.busybox.net/>`_ shell script as init
which sets up the system and filesystem hierarchy, runs a command, and returns
the exit status via `virtio-serial
<https://fedoraproject.org/wiki/Features/VirtioSerial>`_.

This infrastructure is all generic. The drgn-specific parts are:

1. The kernel builds. These are configured with a minimal configuration
   including everything required to run drgn and the Linux kernel helper tests.
   Each build is packaged as a tarball containing ``vmlinux``, ``vmlinuz``, and
   kernel modules. These packages are built by the `vmtest.kbuild <kbuild.py>`_
   module. They are hosted in a `GitHub release
   <https://github.com/osandov/drgn/releases/tag/vmtest-assets>`_ which is
   managed via the GitHub API by the `vmtest.manage <manage.py>`_ CLI. New
   kernel releases are built and uploaded by a `GitHub Actions workflow
   <../.github/workflows/vmtest-build.yml>`_. The packages are downloaded by
   the `vmtest.download <download.py>`_ module.
2. A `kernel module <../tests/linux_kernel/kmod>`_ for testing drgn
   functionality that cannot be tested through userspace APIs.
3. The test command itself. This is just some ``setup.py`` glue to build the
   test kernel module and run the VM with the proper invocation of the Python
   `unittest command line interface
   <https://docs.python.org/3/library/unittest.html#test-discovery>`_.

The ``vmtest.vm`` and ``vmtest.download`` modules also have CLIs for testing
purposes. These are subject to change.