contrib/bpf-vmtest-tool/README - gcc.git - Git at Google

 BPF vmtest Tool
 ===============
 https://gcc.gnu.org/wiki/BPFRunTimeTests

 This directory contains a Python script for running BPF programs or shell commands
 under a live Linux kernel using QEMU virtual machines.


 USAGE
 =====

 Before using the tool, you must set the directory where vmtest will look for
 kernels and store kernel artifacts. You can do this in two ways:

 1. Set the VMTEST_DIR environment variable
 2. Use the --vmtest-dir flag with each command

 Note: This is required to use the tool.


 Available Options
 -----------------

     usage: main.py [-h] [-v DEBUG|INFO|WARNING|ERROR] [--vmtest-dir DIR] {bpf,vmtest,kernel} ...

     BPF vmtest tool

     positional arguments:
       {bpf,vmtest,kernel}   Available commands
         bpf                 BPF program management
         vmtest              Run VM tests
         kernel              Kernel management

     options:
       -h, --help            show this help message and exit
       -v DEBUG|INFO|WARNING|ERROR, --log-level DEBUG|INFO|WARNING|ERROR
                             Log level
       --vmtest-dir DIR      Directory for vmtest artifacts (or set VMTEST_DIR env variable)

 COMMANDS
 ========

 kernel subcommand
 -----------------

 Manage kernel builds for use in virtual machines. You must build a
 kernel before using it.

 Build a kernel:

     python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" kernel build 6.15

     The tool downloads and builds the specified kernel version from
     https://www.kernel.org/pub/linux/kernel and stores the build artifacts in
     $VMTEST_DIR/kernels/linux-6.15-x86_64. Specifically, it stores bpftool,
     libbpf.a, bzImage-6.15-x86_64, and vmlinux.h, which are used when compiling
     BPF programs instead of relying on the host system.

 List available kernels:

     python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" kernel list

 Remove kernels:

     python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" kernel remove 6.15-x86_64

 Note: If the architecture is omitted, the host architecture is assumed. For
 example, 6.15 is treated as 6.15-x86_64 on an x86_64 system.


 vmtest subcommand
 -----------------

 Run BPF programs and commands inside a QEMU virtual machine with a live kernel.

 Options:

   -k VERSION, --kernel VERSION
       Kernel version to boot in the VM. Must be a kernel previously built using
       the "kernel build" subcommand. The kernel version should match the format
       used during build (e.g., 6.15-x86_64 or just 6.15 for host architecture).

       Required: Yes

   -r PATH, --rootfs PATH
       Path to a root filesystem directory to mount in the VM.
       If not specified, the host's root filesystem (/) is mounted by default.

       Required: No
       Default: / (host root filesystem)

       See "Creating a Custom Rootfs" section below for how to build a rootfs from
       a container image.

   --bpf-src PATH
       BPF C source file to compile and load. Mutually exclusive with --bpf-obj.

   --bpf-obj PATH
       Pre-compiled BPF object to load. Mutually exclusive with --bpf-src.

   -c COMMAND, --command COMMAND
       Shell command to run in VM.

 At least one of --bpf-src, --bpf-obj, or --command is required.


 Examples:

   Run a shell command inside a live kernel VM:

     python main.py vmtest -k 6.15 -c "uname -a"

   Load and run a BPF source file with custom rootfs:

     python main.py vmtest -k 6.15 --bpf-src fail.c -r $HOME/rootfs/debian-rootfs

     The tool compiles the source file using BPF_CC with BPF_CFLAGS and the
     kernel-specific vmlinux.h, then generates a skeleton from the compiled BPF
     object using bpftool and compiles it with a generated loader to produce
     the final userspace binary.

   Load a precompiled BPF object file:

     python main.py vmtest -k 6.15 --bpf-obj fail.bpf.o

     The tool follows the same steps to generate the final userspace binary, except
     it skips the BPF object compilation step.


 Creating a Custom Rootfs:

   You can build a rootfs from a container image using this script:

     #!/usr/bin/env bash
     set -euo pipefail

     ROOT="$HOME/rootfs"
     IMAGE_NAME="debian-bookworm-rootfs"
     CTR_NAME="debian-rootfs-ctr"

     cat <<'EOF' | podman build -t "$IMAGE_NAME" -
     FROM debian:bookworm
     RUN apt-get update && \
         apt-get install -y --no-install-recommends \
             libelf1 \
             qemu-guest-agent \
             && \
         apt-get clean && \
         rm -rf /var/lib/apt/lists/*
     EOF

     CTR_ID=$(podman create --name "$CTR_NAME" "$IMAGE_NAME")
     podman export -o "$ROOT/deb.tar" "$CTR_ID"
     tar -xf "$ROOT/deb.tar" -C "$ROOT/debian-rootfs"
     podman rm "$CTR_NAME"
     echo "Debian rootfs ready at: $ROOT/debian-rootfs"

   After running this script, use the rootfs with:

     python main.py vmtest -k 6.15 -r $HOME/rootfs/debian-rootfs -c "uname -a"


 bpf subcommand
 --------------

 Compile BPF source code to bytecode using kernel-specific headers.

 Options:

   compile
       Compile a BPF C source file to a BPF object file.

   -k VERSION, --kernel VERSION
       Kernel version to use for compilation. The tool will use the vmlinux.h
       header from this kernel for the compilation.

       Required: Yes

   -o OUTPUT, --output OUTPUT
       Output path for the compiled BPF object file.

       Required: Yes

 Example:

     python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" bpf compile \
         invalid-memory-access.c -k 6.15 -o /tmp/invalid-memory-access.bpf.o

 The compilation stage can be modified using the BPF_CFLAGS environment variable
 (default: -c)

  Example :

     BPF_CFLAGS="-O2 -E" python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" \
         bpf compile invalid-memory-access.c -k 6.15 -o /tmp/invalid-memory-access.bpf.o

 LIMITATIONS
 ===========

 - Only x86_64 architecture is currently supported


 DEPENDENCIES
 ============

 - Python >= 3.9
 - vmtest >= v0.18.0 (https://github.com/danobi/vmtest)
   - QEMU
   - qemu-guest-agent (on guest filesystem)

 For compiling kernels:
 - pahole
 - See https://docs.kernel.org/process/changes.html#current-minimal-requirements

 For compiling and loading BPF programs:
 - libbpf
 - gcc-bpf-unknown-none (https://gcc.gnu.org/wiki/BPFBackEnd#Where_to_find_GCC_BPF)


 BUILD FLAGS
 ===========

 You can customize compiler settings using environment variables:

 - BPF_CC:          Compiler for the BPF program (default: bpf-unknown-none-gcc)
 - BPF_CFLAGS:      Extra flags for BPF program compilation (default: "-O2 -Wall -Werror -c")
 - BPF_INCLUDES:    Include paths for BPF (default: "-I/usr/local/include -I/usr/include")
 - VMTEST_CC:       Compiler for the user-space loader (default: gcc)
 - VMTEST_CFLAGS:   Flags for compiling the loader (default: "-g -Wall -Werror")
 - VMTEST_LDFLAGS:  Linker flags for the loader (default: "-lelf -lz")

 Example usage:

     BPF_CFLAGS="-O3 -g" BPF_CC="/bpf-gcc-build/gcc/xgcc" \
         python main.py vmtest -k 6.15 --bpf-src fail.c


 DEVELOPMENT
 ===========

 Development dependencies are specified in pyproject.toml and can be installed
 using any suitable Python virtual environment manager.

 To run the test suite:

     python3 -m pytest
	BPF vmtest Tool
	===============
	https://gcc.gnu.org/wiki/BPFRunTimeTests

	This directory contains a Python script for running BPF programs or shell commands
	under a live Linux kernel using QEMU virtual machines.


	USAGE
	=====

	Before using the tool, you must set the directory where vmtest will look for
	kernels and store kernel artifacts. You can do this in two ways:

	1. Set the VMTEST_DIR environment variable
	2. Use the --vmtest-dir flag with each command

	Note: This is required to use the tool.


	Available Options
	-----------------

	usage: main.py [-h] [-v DEBUG\|INFO\|WARNING\|ERROR] [--vmtest-dir DIR] {bpf,vmtest,kernel} ...

	BPF vmtest tool

	positional arguments:
	{bpf,vmtest,kernel} Available commands
	bpf BPF program management
	vmtest Run VM tests
	kernel Kernel management

	options:
	-h, --help show this help message and exit
	-v DEBUG\|INFO\|WARNING\|ERROR, --log-level DEBUG\|INFO\|WARNING\|ERROR
	Log level
	--vmtest-dir DIR Directory for vmtest artifacts (or set VMTEST_DIR env variable)

	COMMANDS
	========

	kernel subcommand
	-----------------

	Manage kernel builds for use in virtual machines. You must build a
	kernel before using it.

	Build a kernel:

	python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" kernel build 6.15

	The tool downloads and builds the specified kernel version from
	https://www.kernel.org/pub/linux/kernel and stores the build artifacts in
	$VMTEST_DIR/kernels/linux-6.15-x86_64. Specifically, it stores bpftool,
	libbpf.a, bzImage-6.15-x86_64, and vmlinux.h, which are used when compiling
	BPF programs instead of relying on the host system.

	List available kernels:

	python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" kernel list

	Remove kernels:

	python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" kernel remove 6.15-x86_64

	Note: If the architecture is omitted, the host architecture is assumed. For
	example, 6.15 is treated as 6.15-x86_64 on an x86_64 system.


	vmtest subcommand
	-----------------

	Run BPF programs and commands inside a QEMU virtual machine with a live kernel.

	Options:

	-k VERSION, --kernel VERSION
	Kernel version to boot in the VM. Must be a kernel previously built using
	the "kernel build" subcommand. The kernel version should match the format
	used during build (e.g., 6.15-x86_64 or just 6.15 for host architecture).

	Required: Yes

	-r PATH, --rootfs PATH
	Path to a root filesystem directory to mount in the VM.
	If not specified, the host's root filesystem (/) is mounted by default.

	Required: No
	Default: / (host root filesystem)

	See "Creating a Custom Rootfs" section below for how to build a rootfs from
	a container image.

	--bpf-src PATH
	BPF C source file to compile and load. Mutually exclusive with --bpf-obj.

	--bpf-obj PATH
	Pre-compiled BPF object to load. Mutually exclusive with --bpf-src.

	-c COMMAND, --command COMMAND
	Shell command to run in VM.

	At least one of --bpf-src, --bpf-obj, or --command is required.



	Examples:

	Run a shell command inside a live kernel VM:

	python main.py vmtest -k 6.15 -c "uname -a"

	Load and run a BPF source file with custom rootfs:

	python main.py vmtest -k 6.15 --bpf-src fail.c -r $HOME/rootfs/debian-rootfs

	The tool compiles the source file using BPF_CC with BPF_CFLAGS and the
	kernel-specific vmlinux.h, then generates a skeleton from the compiled BPF
	object using bpftool and compiles it with a generated loader to produce
	the final userspace binary.

	Load a precompiled BPF object file:

	python main.py vmtest -k 6.15 --bpf-obj fail.bpf.o

	The tool follows the same steps to generate the final userspace binary, except
	it skips the BPF object compilation step.



	Creating a Custom Rootfs:

	You can build a rootfs from a container image using this script:

	#!/usr/bin/env bash
	set -euo pipefail

	ROOT="$HOME/rootfs"
	IMAGE_NAME="debian-bookworm-rootfs"
	CTR_NAME="debian-rootfs-ctr"

	cat <<'EOF' \| podman build -t "$IMAGE_NAME" -
	FROM debian:bookworm
	RUN apt-get update && \
	apt-get install -y --no-install-recommends \
	libelf1 \
	qemu-guest-agent \
	&& \
	apt-get clean && \
	rm -rf /var/lib/apt/lists/*
	EOF

	CTR_ID=$(podman create --name "$CTR_NAME" "$IMAGE_NAME")
	podman export -o "$ROOT/deb.tar" "$CTR_ID"
	tar -xf "$ROOT/deb.tar" -C "$ROOT/debian-rootfs"
	podman rm "$CTR_NAME"
	echo "Debian rootfs ready at: $ROOT/debian-rootfs"

	After running this script, use the rootfs with:

	python main.py vmtest -k 6.15 -r $HOME/rootfs/debian-rootfs -c "uname -a"


	bpf subcommand
	--------------

	Compile BPF source code to bytecode using kernel-specific headers.

	Options:

	compile
	Compile a BPF C source file to a BPF object file.

	-k VERSION, --kernel VERSION
	Kernel version to use for compilation. The tool will use the vmlinux.h
	header from this kernel for the compilation.

	Required: Yes

	-o OUTPUT, --output OUTPUT
	Output path for the compiled BPF object file.

	Required: Yes

	Example:

	python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" bpf compile \
	invalid-memory-access.c -k 6.15 -o /tmp/invalid-memory-access.bpf.o

	The compilation stage can be modified using the BPF_CFLAGS environment variable
	(default: -c)

	Example :

	BPF_CFLAGS="-O2 -E" python main.py --vmtest-dir="/home/user/.bpf-vmtest-tool" \
	bpf compile invalid-memory-access.c -k 6.15 -o /tmp/invalid-memory-access.bpf.o

	LIMITATIONS
	===========

	- Only x86_64 architecture is currently supported


	DEPENDENCIES
	============

	- Python >= 3.9
	- vmtest >= v0.18.0 (https://github.com/danobi/vmtest)
	- QEMU
	- qemu-guest-agent (on guest filesystem)

	For compiling kernels:
	- pahole
	- See https://docs.kernel.org/process/changes.html#current-minimal-requirements

	For compiling and loading BPF programs:
	- libbpf
	- gcc-bpf-unknown-none (https://gcc.gnu.org/wiki/BPFBackEnd#Where_to_find_GCC_BPF)


	BUILD FLAGS
	===========

	You can customize compiler settings using environment variables:

	- BPF_CC: Compiler for the BPF program (default: bpf-unknown-none-gcc)
	- BPF_CFLAGS: Extra flags for BPF program compilation (default: "-O2 -Wall -Werror -c")
	- BPF_INCLUDES: Include paths for BPF (default: "-I/usr/local/include -I/usr/include")
	- VMTEST_CC: Compiler for the user-space loader (default: gcc)
	- VMTEST_CFLAGS: Flags for compiling the loader (default: "-g -Wall -Werror")
	- VMTEST_LDFLAGS: Linker flags for the loader (default: "-lelf -lz")

	Example usage:

	BPF_CFLAGS="-O3 -g" BPF_CC="/bpf-gcc-build/gcc/xgcc" \
	python main.py vmtest -k 6.15 --bpf-src fail.c


	DEVELOPMENT
	===========

	Development dependencies are specified in pyproject.toml and can be installed
	using any suitable Python virtual environment manager.

	To run the test suite:

	python3 -m pytest