QEMU q35 Boot Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The QEMU q35 boot architecture provides a specialized environment for testing Linux kernel regressions within the gokrazy ecosystem. It utilizes a Linux 7.0 amd64 kernel specifically configured to preserve the UDP GSO regression found in tailscale/tailscale#19777. This architecture allows the Tailscale natlab/vmtest suite to verify mitigation behaviors on a host that simulates a buggy kernel environment.
Sources: README.md:3-6, empty.go:7-11
The system targets the QEMU q35 machine type. It includes necessary drivers for virtualized environments, specifically focusing on PCI bus support, VirtIO storage, and Intel emulated networking.
Sources: README.md:12-16, config.addendum.txt:108-113
Kernel Build and Image Generation
The build process transforms standard Linux 7.0 source into a bootable vmlinuz image. The automation script handles dependency retrieval, configuration merging, and compilation.
Build Workflow
The build script follows a linear progression to ensure the resulting image contains both standard defaults and project-specific requirements.
The workflow ensures the config.addendum.txt overrides or supplements the default x86_64 kernel configuration.
Sources: build-buggy-linux-7_0.bash:6-26
Configuration Components
The kernel configuration includes specific subsystems required for gokrazy and Tailscale operations.
| Category | Configuration Options | Purpose |
|---|---|---|
| File System | CONFIG_SQUASHFS | Support for the gokrazy root file system. |
| Networking | CONFIG_WIREGUARD, CONFIG_TUN | Support for Tailscale VPN and tunneling. |
| Diagnostics | CONFIG_IKCONFIG_PROC | Enables access to kernel config via /proc/config.gz. |
| Congestion Control | CONFIG_TCP_CONG_BBR | Sets BBR as the default congestion control. |
Sources: config.addendum.txt:11-14, config.addendum.txt:75-81, config.addendum.txt:140-142
Runtime Boot Parameters
The bootloader passes specific arguments to the kernel via cmdline.txt. These parameters define the root device location, the initialization path, and error handling behavior.
The command line string is: root=/dev/sda2 ro init=/gokrazy/init panic=10 oops=panic.
Sources: cmdline.txt:1
Hardware and Driver Interface
The architecture prioritizes VirtIO and Intel igb drivers to facilitate high-performance networking and storage within QEMU.
Virtualization Drivers
The configuration enables the full VirtIO stack to interact with QEMU's emulated hardware efficiently. This includes:
CONFIG_VIRTIO_PCI: PCI transport for VirtIO devices.CONFIG_VIRTIO_BLK: Virtual block devices for storage.CONFIG_VIRTIO_NET: Virtualized network interface.CONFIG_HW_RANDOM_VIRTIO: Hardware entropy from the host.
Sources: config.addendum.txt:98-106
Intel igb Diagnostic Path
The Intel igb driver is critical for the UDP GSO regression test. The vmtest image checks the igb interface for specific flags:
tx-udp-segmentationtx-gso-partial
The kernel must advertise these capabilities to trigger the mitigation logic being tested.
Sources: README.md:16-19, config.addendum.txt:109-111
Network Stack Architecture
The kernel integrates complex networking features required for modern container and VPN workloads, including nftables and BPF support.
This diagram represents the flow of network data through the configured kernel modules.
Sources: config.addendum.txt:7-9, config.addendum.txt:24-60, config.addendum.txt:108-111
Summary
The QEMU q35 Boot Architecture for this project serves as a target-specific kernel environment. It combines a Linux 7.0 base with a custom configuration addendum to support gokrazy's init system and Tailscale's testing requirements. By intentionally preserving specific network bugs and providing drivers for q35 emulated hardware, it enables automated validation of network stack mitigations.
Sources: README.md:3-6, empty.go:7-11, build-buggy-linux-7_0.bash:26