Symbols & Debugging

Debug symbols, objdump usage, and kernel debugging for NØNOS.

---

Build Artifacts

Release Build

target/
├── x86_64-nonos/release/
│   └── nonos_kernel          # 221 KB, stripped
├── x86_64-unknown-uefi/release/
│   ├── nonos_boot.efi        # 300 KB, UEFI bootloader
│   └── nonos_boot.pdb        # 92 KB, debug symbols
└── esp/
    └── EFI/
        ├── Boot/BOOTX64.EFI  # Bootloader copy
        └── nonos/kernel.bin   # Kernel copy

---

Debug Build

make debug
# or
cargo build  # (without --release)

Debug builds include full symbols and are larger.

---

Using objdump

View Kernel Sections

objdump -h target/x86_64-nonos/release/nonos_kernel

Expected output:

Sections:
Idx Name          Size      VMA               LMA               File off  Algn
  0 .text         00012345  0000000000101000  0000000000101000  00001000  2**4
  1 .rodata       00004567  0000000000114000  0000000000114000  00014000  2**4
  2 .data         00001234  0000000000119000  0000000000119000  00019000  2**4
  3 .bss          00002000  000000000011b000  000000000011b000  0001a234  2**4
  4 .nonos.manifest 00000100  000000000011d000  000000000011d000  0001c234  2**4
  5 .nonos.sig    00000040  000000000011d100  000000000011d100  0001c334  2**3

Disassemble Entry Point

objdump -d target/x86_64-nonos/release/nonos_kernel | head -100

View Symbols

objdump -t target/x86_64-nonos/release/nonos_kernel | grep kernel_main

View All Symbols

nm target/x86_64-nonos/release/nonos_kernel

---

Key Symbols

Symbol	Description
kernel_main	Kernel entry point
__bss_start	BSS section start
__bss_end	BSS section end
__nonos_manifest_start	Manifest section start
__nonos_manifest_end	Manifest section end
__nonos_signature_start	Signature start (64 bytes)
__nonos_signature_end	Signature end
__stack_bottom	Stack bottom
__stack_top	Stack top

GDB Debugging

Start Debug Session

# Terminal 1: Start QEMU with GDB server
make debug

# Terminal 2: Connect GDB
gdb target/x86_64-nonos/debug/nonos_kernel \
    -ex 'target remote :1234'

---

Common GDB Commands

# Set breakpoint at kernel entry
break kernel_main

# Continue execution
continue

# Step one instruction
stepi

# Print registers
info registers

# Print memory
x/16x 0x100000

# Print backtrace
backtrace

# Print current instruction
x/i $rip

---

Debug Build with Symbols

For better debugging, use debug build:

# Build debug version
cargo build

# Kernel with symbols at:
# target/x86_64-nonos/debug/nonos_kernel

---

Serial Output

Enable Serial Debugging

make run-serial

Serial output appears in terminal. Useful for:

• Boot messages

• Kernel panics

• Debug print statements

---

Serial Port Configuration

Parameter	Value
Port	COM1 (0x3F8)
Baud	115200
Data bits	8
Parity	None
Stop bits	1

---

Kernel Panic Information

On panic, NØNOS prints:

• Panic message

• Source file and line

• Stack trace (if available)

• Register dump

Example:

KERNEL PANIC: index out of bounds
Location: src/memory/allocator.rs:142

Stack trace:
  0xffffffff80102345 allocator::allocate_frame
  0xffffffff80105678 memory::map_page
  0xffffffff80108901 kernel_main

Registers:
  RAX: 0x0000000000000000  RBX: 0xffffffff80200000
  RCX: 0x0000000000000100  RDX: 0x0000000000000000
  ...

---

Inspecting the Manifest

# Extract manifest section
objcopy -O binary \
    --only-section=.nonos.manifest \
    target/x86_64-nonos/release/nonos_kernel \
    manifest.bin

# View manifest
xxd manifest.bin

---

Inspecting the Signature

# Extract signature section
objcopy -O binary \
    --only-section=.nonos.sig \
    target/x86_64-nonos/release/nonos_kernel \
    signature.bin

# View signature (64 bytes)
xxd signature.bin

---

Verifying Kernel Hash

# Compute BLAKE3 hash of kernel
b3sum target/x86_64-nonos/release/nonos_kernel

# Or with Python
python3 -c "
import hashlib
# Note: Use blake3 library for actual BLAKE3
with open('target/x86_64-nonos/release/nonos_kernel', 'rb') as f:
    print(hashlib.sha256(f.read()).hexdigest())
"

---

Memory Debugging

View Page Tables

In GDB:

# Print CR3 (page table base)
print/x $cr3

# Examine PML4
x/8gx ($cr3 & ~0xfff)

Check Memory Mapping

# Check if address is mapped
x/1x 0xffffffff80100000

---

Performance Profiling

Boot Timing

Serial output includes timing:

[0.000] Bootloader start
[0.123] Kernel loaded
[0.456] Memory initialized
[1.234] Drivers initialized
[2.345] Desktop ready

Instruction Counting

In QEMU:

qemu-system-x86_64 ... -d in_asm -D trace.log

---

Common Issues

No Symbols in Release Build

Release builds strip symbols. Use debug build:

cargo build  # Without --release

GDB Won't Connect

1. Ensure QEMU started with -s -S

2. Check port 1234 is free

3. Try localhost:1234 instead of :1234

Kernel Doesn't Boot

1. Use serial mode: make run-serial

2. Check for panic messages

3. Verify signature with objdump