Troubleshooting QEMU Boot Panics

Relevant source files

The following files were used as context for generating this wiki page:

• build-buggy-linux-7_0.bash
• config.addendum.txt
• README.md
• cmdline.txt
• empty.go

This gokrazy kernel package provides a Linux 7.0 amd64 kernel specifically for Tailscale natlab/vmtest environments. It intentionally includes a UDP GSO regression to test mitigation behaviors during guest execution.

Boot panics in this environment typically stem from missing drivers, incorrect root partition references, or specific kernel command line triggers. The kernel is bootable under QEMU q35 and depends on specific virtio and network driver configurations.

Sources: README.md:1-10, empty.go:5-7

Boot Parameter Analysis

The kernel command line dictates the behavior of the system during a failure. The project defines specific parameters to automate recovery and diagnostic actions when the kernel encounters a critical error.

Panic and Oops Configuration

The cmdline.txt file configures the kernel to panic immediately upon an "oops" (a non-fatal kernel error) and to reboot the system after a short delay.

• panic=10: The system waits 10 seconds before rebooting after a kernel panic occurs.
• oops=panic: Any kernel oops results in a full system panic.
• init=/gokrazy/init: The kernel executes the gokrazy init process.

Sources: cmdline.txt:1

The diagram shows how the kernel processes errors based on the command line parameters.
Sources: cmdline.txt:1

Required Drivers and Filesystem Support

Booting requires specific drivers to be compiled into the kernel via config.addendum.txt. Missing drivers for the root filesystem or the storage controller result in a "VFS: Unable to mount root fs" panic.

Storage and Filesystem Drivers

The system expects a Squashfs root filesystem located on the second partition of the primary storage device.

Configuration Option	Value	Purpose
CONFIG_SQUASHFS	y	Enables the root filesystem format.
CONFIG_VIRTIO_BLK	y	Required for QEMU block device access.
CONFIG_VIRTIO_PCI	y	Enables PCI-based virtio devices.

Sources: config.addendum.txt:10-13, config.addendum.txt:72-74, cmdline.txt:1

Network Driver Dependencies

The kernel includes specific drivers for Tailscale testing. If the guest igb interface fails to advertise tx-udp-segmentation or tx-gso-partial, certain mitigation tests will fail, though the system may still boot.

• CONFIG_IGB: Enables the Intel igb network driver.
• CONFIG_VIRTIO_NET: Enables the default virtio networking.

Sources: config.addendum.txt:81-86, README.md:10-15

Build Process Verification

If the kernel fails to boot after local modifications, you must verify the build pipeline. The build-buggy-linux-7_0.bash script automates the kernel compilation and packaging.

1. The script downloads the Linux 7.0 source tarball.
2. It applies the default configuration via make defconfig.
3. It appends custom options from config.addendum.txt to the .config file.
4. It compiles the bzImage and copies it to vmlinuz.

Sources: build-buggy-linux-7_0.bash:1-23

The sequence diagram illustrates the artifact generation flow for the kernel image.
Sources: build-buggy-linux-7_0.bash:16-23

Summary of Configuration for QEMU

To ensure a stable boot in QEMU q35, the following kernel configuration flags must be set to y to avoid device initialization panics:

• CONFIG_PCI=y and CONFIG_PCIEPORTBUS=y for bus communication.
• CONFIG_VIRTIO=y and CONFIG_VIRTIO_RING=y for virtualization support.
• CONFIG_FB=y and CONFIG_FRAMEBUFFER_CONSOLE=y for console output visibility.

Sources: config.addendum.txt:20-22, config.addendum.txt:72-78, config.addendum.txt:81-83