Running in QEMU

QEMU provides a complete virtualized x86_64 environment with UEFI support, enabling rapid development and testing without physical hardware.

---

Quick Start

make run

This command builds everything and launches QEMU with the NØNOS desktop.

Run Modes

Mode	Command	Output	Use Case
Graphical	make run	Window with desktop	Normal development
Serial	make run-serial	Terminal only	Debugging boot issues
Debug	make debug	GDB server on :1234	Kernel debugging

---

Graphical Mode

make run

Opens a window displaying the NØNOS desktop environment.

Keyboard shortcuts:

Shortcut	Action
Ctrl+Alt+G	Release mouse from QEMU
Ctrl+Alt+F	Toggle fullscreen
Ctrl+A X	Force quit QEMU

---

Serial Mode

make run-serial

Redirects all output to your terminal. Essential for debugging boot failures:

NØNOS Bootloader v1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[OK] Ed25519 keys loaded
[OK] BLAKE3 self-test passed
[OK] Ed25519 self-test passed
[OK] Secure Boot: Disabled

Loading kernel...
[OK] Kernel loaded (221 KB)
[OK] BLAKE3 hash computed
[OK] Signature verified (Key 0)

Exiting boot services...
Jumping to kernel at 0x100000

NØNOS Kernel v1.0
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[OK] GDT initialized
[OK] IDT initialized
[OK] Memory: 512 MB detected
...

---

Debug Mode

make debug

Starts QEMU paused with GDB server listening on port 1234.

Connect with GDB:

# Terminal 2
gdb target/x86_64-nonos/debug/nonos-kernel \
    -ex 'target remote :1234' \
    -ex 'break kernel_main' \
    -ex 'continue'

Common GDB commands:

Command	Action
break kernel_main	Set breakpoint
continue	Resume execution
stepi	Single instruction step
info registers	Show CPU registers
x/16x $rsp	Examine stack

---

QEMU Configuration

The Makefile generates this QEMU invocation:

qemu-system-x86_64 \
    -m 512M \
    -cpu qemu64 \
    -machine q35 \
    -drive format=raw,file=fat:rw:target/esp \
    -drive if=pflash,format=raw,readonly=on,file=OVMF.fd \
    -serial mon:stdio \
    -vga std \
    -no-reboot

Parameter Reference

Parameter	Value	Purpose
-m	512M	Guest RAM allocation
-cpu	qemu64	CPU model emulation
-machine	q35	Modern PCIe chipset
-drive	fat:rw:target/esp	Mount ESP as FAT filesystem
-pflash	OVMF.fd	UEFI firmware
-vga	std	VGA graphics adapter
-serial	mon:stdio	Serial output to terminal
-no-reboot	—	Exit on triple fault

---

OVMF Firmware Locations

The Makefile auto-detects OVMF based on your platform:

Platform	Path
Debian/Ubuntu	/usr/share/OVMF/OVMF_CODE.fd
Fedora	/usr/share/edk2/ovmf/OVMF_CODE.fd
Arch Linux	/usr/share/edk2-ovmf/x64/OVMF_CODE.fd
macOS Intel	/usr/local/share/qemu/edk2-x86_64-code.fd
macOS ARM	/opt/homebrew/share/qemu/edk2-x86_64-code.fd

---

Hardware Acceleration

Linux (KVM)

QEMU uses KVM automatically when available:

# Verify KVM is loaded
lsmod | grep kvm

# Check permissions
ls -la /dev/kvm

If KVM isn't available, QEMU falls back to TCG (software emulation).

macOS (Hypervisor.framework)

Modern macOS systems provide hardware virtualization through Hypervisor.framework. QEMU uses it automatically.

Note: Apple Silicon Macs emulate x86_64 via Rosetta 2 + QEMU TCG, which is slower than native ARM virtualization.

Troubleshooting

Issue	Cause	Solution
"Could not initialize SDL"	Missing graphics libs	apt install libsdl2-2.0-0 or use make run-serial
"OVMF not found"	OVMF not installed	apt install ovmf or brew reinstall qemu
Boot hangs	Kernel panic during init	Use make run-serial to see error messages
Triple fault loop	Early boot crash	Use make debug + GDB to find crash point
Black screen	GPU not initialized	Check serial output; may need driver work
Mouse not captured	QEMU focus issue	Click window, then Ctrl+Alt+G to toggle

---

Advanced Configuration

Custom RAM Size

QEMU_MEMORY=1024M make run

Enable Networking

qemu-system-x86_64 \
    ... \
    -netdev user,id=net0 \
    -device e1000,netdev=net0

Record Boot Trace

qemu-system-x86_64 \
    ... \
    -d in_asm,cpu_reset \
    -D trace.log

---

What's Next

• Creating Bootable Media — Build USB installer

• Booting on Hardware — Test on real hardware