Wednesday, October 30, 2024

Comprehensive Guide to Linux Kernel Selftests

The Linux kernel includes a powerful suite of self-tests found under the `tools/testing/selftests/` directory. These self-tests provide a framework for developers to verify specific code paths within the kernel, ensuring the robustness and reliability of individual components. This guide covers how to set up, run, and customize these tests to suit different testing needs.

Overview of Kernel Self-Tests

Kernel self-tests serve as essential tools for validating new code additions or changes to the Linux kernel. They can be run post-kernel build, installation, and boot to validate that code changes do not introduce regressions or unexpected behavior. One critical feature within these self-tests is the hot-plug testing, which allows developers to simulate and verify the dynamic plugging and unplugging of CPUs and memory.

Hot-Plug Tests: Limited and Full Modes

Hot-plug testing, by nature, can be complex due to dependencies on hardware readiness for CPU and memory offlining. To mitigate potential system hangs during these tests, the kernel provides:

Limited Mode: CPU hot-plug is tested on a single CPU, and memory hot-plug is restricted to 2% of available hot-plug-capable memory.

Full Mode: This extensive test mode performs hot-plug actions across all hot-plug capable CPUs and 10% of the memory. This mode can be useful for systems where comprehensive validation of hot-plug readiness is required.

Building and Running Self-Tests

$ make -C tools/testing/selftests

$ make -C tools/testing/selftests run_tests

Alternatively, to both build and run in a single command, use:

$ make kselftest

Note: Some tests, particularly those requiring hardware access, may need root privileges.


Running Specific Self-Tests

Kernel self-tests offer flexibility for targeting specific components or subsystems. To run only the tests related to a specific subsystem, use the `TARGETS` variable:

For example, to run only `ptrace` tests:

$ make -C tools/testing/selftests TARGETS=ptrace run_tests

$ make TARGETS="size timers" kselftest

Refer to the `Makefile` located at `tools/testing/selftests/Makefile` for a complete list of possible test targets.


Running Full Range Hot-Plug Self-Tests

For systems requiring full-scale hot-plug testing, the following commands build and execute the tests across all hot-plug-capable resources.


$ make -C tools/testing/selftests hotplug

$ make -C tools/testing/selftests run_hotplug


 Installing Kernel Self-Tests

To simplify running self-tests on other systems, the `kselftest_install.sh` script allows installation to a default or user-specified location.

Default Installation

$ cd tools/testing/selftests

$ ./kselftest_install.sh

Custom Installation Location

Specify an installation directory for easier management and accessibility:

$ cd tools/testing/selftests

$ ./kselftest_install.sh <install_dir>

Running Installed Self-Tests

After installing, run the installed tests using the provided `run_kselftest.sh` script, which executes all self-tests in the specified installation directory.

$ cd kselftest

$ ./run_kselftest.sh

---------------------------------------

Testing BPF (Berkeley Packet Filter) and fprobe features within Linux kernel self-tests involves several additional steps because these tests require specific kernel configurations and privileges to ensure proper operation. Here’s a breakdown of the steps required:

Enable Required Kernel Configurations

To run BPF and fprobe self-tests, ensure the kernel has the necessary configurations enabled. These settings are often found in the kernel's `.config` file before building the kernel.

CASE 1 : For BPF Self-Tests

Enable the following configurations:

- `CONFIG_BPF`: Enable BPF support

- `CONFIG_BPF_SYSCALL`: Enable BPF syscall interface

- `CONFIG_BPF_JIT`: Enable BPF Just-In-Time (JIT) compiler

- `CONFIG_HAVE_EBPF_JIT`: Enable extended BPF JIT support

- `CONFIG_DEBUG_INFO_BTF`: Enable BPF Type Format (BTF), which is often required for BPF self-tests

- `CONFIG_NET`: Enable networking stack if testing network-related BPF functionality

If running BPF tracing , make sure the following options are also enabled:

- `CONFIG_TRACING`: Enable kernel tracing

- `CONFIG_FUNCTION_TRACER`: Enable function tracing (for eBPF tracing features)

- `CONFIG_BPF_EVENTS`: Enable BPF events for tracing

CASE2: For fprobe Self-Tests

fprobe relies on certain configurations, particularly in the tracing subsystem:

- `CONFIG_KPROBES`: Enable kernel probes

- `CONFIG_FPROBE`: Enable fprobe functionality, which is typically under kernel debugging and tracing options

- `CONFIG_KPROBE_EVENTS`: Enable kprobe events (needed for fprobe usage and testing)

Use `make menuconfig` or `make nconfig` in your kernel source directory to enable these options interactively.

--------------------------------------------

Recompile and Boot into the Custom Kernel

After setting the configurations, recompile the kernel to include the BPF and fprobe functionality, then reboot into this kernel.

$ make -j$(nproc) && make modules_install && make install

$ reboot

Install Required User-Space Utilities

Some BPF and fprobe tests may require user-space tools for BPF program management or tracing. Ensure these tools are installed:

  1. bpftool: Used to inspect and manage BPF programs and maps.
  2. iproute: Provides tools like `tc` for attaching BPF programs to network traffic.

 

 Run BPF and fprobe Self-Tests : Navigate to the `tools/testing/selftests/` directory in your kernel source and specify the `TARGETS` for BPF and fprobe:


Running BPF Tests  

$ make -C tools/testing/selftests TARGETS=bpf run_tests

BPF self-tests are designed to cover various aspects, such as BPF JIT, network socket filters, and tracing. Some BPF tests may require root privileges, so consider running with `sudo` if you encounter permission errors.

Running fprobe Tests

$ make -C tools/testing/selftests TARGETS=fprobe run_tests

The fprobe tests are generally under the tracing or ftrace section. Since fprobe works closely with kprobes and tracing functionalities, you may see additional output related to probe events.

Troubleshooting Common Issues

Missing Kernel Configurations: If tests fail with messages about unsupported configurations, recheck that all necessary kernel options are enabled.

Permission Issues: Some BPF programs and fprobes require privileged access. Run the tests with `sudo` if needed.

BTF (BPF Type Format) Requirements: Some BPF tests require BTF data, which may need to be enabled explicitly in `.config` (`CONFIG_DEBUG_INFO_BTF`).

By following these steps, you should be able to run BPF and fprobe tests as part of the Linux kernel self-tests, verifying their functionality and stability within your custom-built kernel.


Reference:
https://www.kernel.org/doc/Documentation/kselftest.txt

No comments:

Post a Comment