# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nonos.systems/building-nonos-os/running-in-qemu.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.