# Running in QEMU

***

## Quick Start

```bash
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

```bash
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

```bash
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

```bash
make debug
```

Starts QEMU paused with GDB server listening on port 1234.

Connect with GDB:

```bash
# 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:

```bash
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:

```bash
# 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

```bash
QEMU_MEMORY=1024M make run
```

#### Enable Networking

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

#### Record Boot Trace

```bash
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