Debugging Guide

This guide covers debugging techniques and tools for Redox OS development, including GDB debugging, QEMU options, and network analysis.

GDB Debugging

Kernel Debugging

Debug the Redox kernel using GDB with QEMU’s remote debugging protocol.

Start QEMU with GDB support

In one terminal, start QEMU with GDB enabled:

make qemu gdb=yes

This starts QEMU with the flags -d cpu_reset -s -S, which:

Logs CPU resets
Opens a GDB server on port 1234
Waits for GDB to connect before starting

Connect GDB

In another terminal, connect GDB to the kernel:

make gdb

This runs:

rust-gdb recipes/core/kernel/target/<TARGET>/build/kernel.sym \
  --eval-command="target remote :1234"

Debug

Use standard GDB commands to debug:

# Set a breakpoint
break kernel::main

# Continue execution
continue

# Step through code
step
next

# Examine variables
print variable_name

# View backtrace
backtrace

Non-blocking GDB mode: Use gdb=nonblock to allow attaching GDB without blocking QEMU startup:

make qemu gdb=nonblock

Userspace Debugging

Use gdbserver when possible! The userspace debugging target stops the entire VM, not just the application. Only use this when:

The application runs early during boot before the network stack starts
You need to debug the interaction between the application and kernel

GDB Direct (Not Recommended)
GDB with gdbserver (Recommended)

Set the application file

export GDB_APP_FILE=path/to/application/binary

Start QEMU with GDB

make qemu gdb=yes

Connect userspace GDB

make gdb-userspace

This runs:

rust-gdb $GDB_APP_FILE \
  --eval-command="add-symbol-file recipes/core/kernel/target/<TARGET>/build/kernel.sym" \
  --eval-command="target remote :1234"

When the network stack is available, use gdbserver running inside Redox:

Start Redox with network

make qemu net=redir

Port 64126 is forwarded for gdbserver.

Run application with gdbserver in Redox

Inside the Redox VM:

gdbserver :64126 /path/to/application

Connect from host

On your host system:

rust-gdb /path/to/application/binary
(gdb) target remote :64126

Advanced GDB Debugging

Debug with gdbgui (Interactive Web Interface)

Enable debug symbols and use gdbgui for a web-based debugging interface:

Build with debug symbols

REPO_DEBUG=1 make cr.recipe rebuild

Verify debug symbols:

file binary-path  # Should output "debug_info, not stripped"

Start QEMU with GDB

make qemu kvm=no QEMU_SMP=1 gdb=yes

Launch gdbgui

make debug.recipe-name DEBUG_BIN=binary-name

Open http://localhost:5000/dashboard in your browser.

This is experimental and may not work if ARCH differs from the host architecture.

Multi-arch Debugging

For debugging architectures different from your host:

export RUST_GDB=gdb-multiarch
make gdb

This is set automatically in the Makefile:

export RUST_GDB=gdb-multiarch

QEMU Debugging Options

Serial Output and Debugging Console

Serial Console (Default)
Debug Console Only
Serial with Logfile

By default, serial output is enabled:

make qemu

This uses:

-chardev stdio,id=debug,signal=off,mux=on
-serial chardev:debug
-mon chardev=debug

Disable serial and use debug console:

make qemu serial=no

This uses:

-chardev stdio,id=debug
-device isa-debugcon,iobase=0x402,chardev=debug

Log serial output to a file:

make qemu qemu_serial_logfile=serial.log

Graphics and Display Options

make qemu gpu=no

CPU and Performance Options

KVM Acceleration
CPU Configuration
IOMMU

Enable KVM for faster execution (default on matching host arch):

make qemu kvm=yes

Disable KVM:

make qemu kvm=no

On Linux with matching architecture, this uses -enable-kvm -cpu host. On macOS with ARM, this uses -accel hvf -cpu max.

Adjust CPU cores and memory:

# Set SMP cores (default varies by arch)
make qemu QEMU_SMP=8

# Set memory in MB (default varies by arch)
make qemu QEMU_MEM=4096

# Combine both
make qemu QEMU_SMP=8 QEMU_MEM=4096

Enable IOMMU for testing:

make qemu iommu=yes

Disk and Storage Options

make qemu disk=nvme

Network Debugging

Network Packet Capture
Port Forwarding
Network Adapters
Bridge Networking

By default, network traffic is captured to a pcap file:

make qemu

This creates build/<arch>/<config>/network.pcap.View with Wireshark:

make wireshark

Or directly:

wireshark build/<arch>/<config>/network.pcap

Enable port forwarding for network services:

make qemu net=redir

Forwarded ports:

8022 → 22 (SSH)
8080 → 80 (HTTP)
8081 → 8081 (HTTP alt)
8082 → 8082 (HTTP alt)
8083 → 8083 (HTTP alt)
64126 → 64126 (gdbserver)

Choose different network adapters:

# Intel e1000 (default)
make qemu net=default

# RTL8139
make qemu net=rtl8139

# VirtIO network
make qemu net=virtio

# USB network
make qemu net=usb-net

# No network
make qemu net=no

Use a network bridge (requires setup on host):

make qemu bridge=br0

Logging and Error Collection

Capture All Output

Capture both stdout and stderr to a log file:

make qemu 2>&1 | tee redox-debug.log

Build System Logging

Enable verbose logging during builds:

# Verbose cookbook output
COOKBOOK_VERBOSE=true make r.recipe-name

# Build with debug symbols
REPO_DEBUG=1 make cr.recipe-name

# Combine both
COOKBOOK_VERBOSE=true REPO_DEBUG=1 make cr.recipe-name 2>&1 | tee build.log

Architecture-Specific Debugging

x86_64
i586
aarch64
riscv64gc

Default configuration:

make qemu ARCH=x86_64 QEMU_SMP=4 QEMU_MEM=2048

Debug exit codes (for redoxer):

make qemu redoxer=yes

Uses -device isa-debug-exit (exit code: 51 = success, 53 = failure).

32-bit x86 debugging:

make qemu ARCH=i586 QEMU_SMP=1 QEMU_MEM=1024

VGA is supported on i586.

ARM64 debugging:

make qemu ARCH=aarch64 gpu=ramfb

For Raspberry Pi 3B+ emulation:

make qemu ARCH=aarch64 BOARD=raspi3bp

Semihosting is enabled for redoxer on aarch64:

-semihosting-config enable=on,target=native,userspace=on

RISC-V debugging:

make qemu ARCH=riscv64gc QEMU_SMP=4 QEMU_MEM=2048

RISC-V uses ACPI-off mode by default:

QEMU_MACHINE=virt,acpi=off

Common Debugging Scenarios

Debugging Boot Issues

Use serial console

make qemu serial=yes qemu_serial_logfile=boot.log

Check bootloader

For UEFI boot issues, verify firmware path:

# x86_64
ls /usr/share/OVMF/OVMF_CODE.fd

# aarch64
ls /usr/share/AAVMF/AAVMF_CODE.fd

# riscv64gc
ls /usr/share/qemu-efi-riscv64/RISCV_VIRT_CODE.fd

Try different boot methods

# Try legacy BIOS (x86_64)
make qemu uefi=no

# Try live ISO
make qemu live=yes

Debugging Network Issues

Enable packet capture

make qemu net=default

This creates build/network.pcap.

Analyze with Wireshark

make wireshark

Test connectivity

Use port forwarding to test services:

make qemu net=redir

# From host
ssh -p 8022 user@localhost
curl http://localhost:8080

Debugging Driver Issues

Build driver with debug symbols

REPO_DEBUG=1 make cr.driver-name

Update initfs

See How to update initfs.

Run with serial logging

make qemu serial=yes qemu_serial_logfile=driver-debug.log

Debug with GDB

make qemu gdb=yes
# In another terminal
make gdb

Debugging Filesystem Issues

Mount the filesystem

make mount

Inspect at build/<arch>/<config>/filesystem/.

Check disk image

# Check image integrity
file build/<arch>/<config>/harddrive.img

Unmount when done

make unmount

Performance Profiling

QEMU Performance Options

# Maximize performance
make qemu kvm=yes QEMU_SMP=8 QEMU_MEM=4096 disk=virtio net=virtio

# Profile mode (slower but more accurate)
make qemu kvm=no QEMU_SMP=1

Benchmarking

Run benchmarks on Redox:

# Build with benchmarks included
make all CONFIG_NAME=tests

# Run the system
make qemu CONFIG_NAME=tests

The tests.toml configuration includes:

redox-tests package
benchmarks package

Troubleshooting

GDB Won't Connect

Check QEMU is waiting

Ensure you see the GDB server message:

waiting for gdb connection on port 1234

Verify port availability

netstat -an | grep 1234

Try manual connection

gdb-multiarch
(gdb) target remote :1234

Serial Output Not Showing

Try serial=yes explicitly
Check if output is going to a logfile
Verify QEMU version compatibility

QEMU Performance Issues

Enable KVM: make qemu kvm=yes
Reduce SMP: make qemu QEMU_SMP=1
Use lighter GPU: make qemu gpu=no
Disable audio: make qemu audio=no

Additional Resources

Developer FAQ

Common debugging questions

Build System Reference

Complete build system documentation

Testing Guide

Learn how to test your changes

Kernel Documentation

Kernel API documentation

Get Started

Build System

Architecture

Components

Development

Hardware

GDB Debugging

Kernel Debugging

Userspace Debugging

Advanced GDB Debugging

QEMU Debugging Options

Serial Output and Debugging Console

Graphics and Display Options

CPU and Performance Options

Disk and Storage Options

Network Debugging

Logging and Error Collection

Capture All Output

Build System Logging

Architecture-Specific Debugging

Common Debugging Scenarios

Performance Profiling

QEMU Performance Options

Benchmarking

Troubleshooting

Additional Resources

Developer FAQ

Build System Reference

Testing Guide

Kernel Documentation

Build docs developers (and LLMs) love

Get Started

Build System

Architecture

Components

Development

Hardware

​GDB Debugging

​Kernel Debugging

​Userspace Debugging

​Advanced GDB Debugging

​QEMU Debugging Options

​Serial Output and Debugging Console

​Graphics and Display Options

​CPU and Performance Options

​Disk and Storage Options

​Network Debugging

​Logging and Error Collection

​Capture All Output

​Build System Logging

​Architecture-Specific Debugging

​Common Debugging Scenarios

​Performance Profiling

​QEMU Performance Options

​Benchmarking

​Troubleshooting

​Additional Resources

Developer FAQ

Build System Reference

Testing Guide

Kernel Documentation

Build docs developers (and LLMs) love

GDB Debugging

Kernel Debugging

Userspace Debugging

Advanced GDB Debugging

QEMU Debugging Options

Serial Output and Debugging Console

Graphics and Display Options

CPU and Performance Options

Disk and Storage Options

Network Debugging

Logging and Error Collection

Capture All Output

Build System Logging

Architecture-Specific Debugging

Common Debugging Scenarios

Performance Profiling

QEMU Performance Options

Benchmarking

Troubleshooting

Additional Resources