# Building the Bootloader

***

### Overview

```
┌─────────────────────────────────────────────────────────────────┐
│                    BOOTLOADER ARCHITECTURE                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                    BOOTX64.EFI (300 KB)                 │   │
│   ├─────────────────────────────────────────────────────────┤   │
│   │                                                         │   │
│   │   ┌──────────────┐   ┌──────────────┐   ┌────────────┐  │   │
│   │   │   Ed25519    │   │    BLAKE3    │   │  Groth16   │  │   │
│   │   │  Verifier    │   │   Hasher     │   │  Verifier  │  │   │
│   │   └──────────────┘   └──────────────┘   └────────────┘  │   │
│   │                                                         │   │
│   │   ┌──────────────┐   ┌──────────────┐   ┌────────────┐  │   │
│   │   │  Public Key  │   │    UEFI      │   │   Memory   │  │   │
│   │   │   Storage    │   │  Services    │   │    Map     │  │   │
│   │   └──────────────┘   └──────────────┘   └────────────┘  │   │
│   │                                                         │   │
│   └─────────────────────────────────────────────────────────┘   │
│                              │                                  │
│                              ▼                                  │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                    VERIFICATION FLOW                    │   │
│   │                                                         │   │
│   │   Load kernel.bin ──▶ BLAKE3 hash ──▶ Ed25519 verify    │   │
│   │                                              │          │   │
│   │                                              ▼          │   │
│   │                               ┌─────────────────────┐   │   │
│   │                               │ Jump to kernel_main │   │   │
│   │                               │     at 0x100000     │   │   │
│   │                               └─────────────────────┘   │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

***

### Build Command

```bash
make bootloader
```

### Build Target

| Property | Value                                               |
| -------- | --------------------------------------------------- |
| Target   | `x86_64-unknown-uefi`                               |
| Format   | PE32+ executable                                    |
| Size     | \~300 KB                                            |
| Output   | `target/x86_64-unknown-uefi/release/nonos_boot.efi` |

***

### Bootloader Responsibilities

#### `Cryptographic Verification`

1. **Load kernel** from ESP partition (`EFI/nonos/kernel.bin`)
2. **Compute BLAKE3 hash** of kernel binary
3. **Verify Ed25519 signature** against embedded public keys
4. **Optional**: Verify Groth16 ZK proof for attestation

#### `Hardware Initialization`

* PCI bus enumeration
* GPU/framebuffer detection
* ACPI table discovery
* Memory map collection
* Hardware RNG seeding

***

#### Boot Information Structure

The bootloader passes critical information to the kernel:

```rust
BootInfo {
    framebuffer: FramebufferInfo,
    memory_map: &[MemoryDescriptor],
    acpi_rsdp: *const u8,
    hardware_entropy: [u8; 64],
    boot_services_exited: bool,
}
```

***

### Embedded Public Keys

Production public keys are compiled into the bootloader:

```
nonos-boot/src/crypto/sig.rs
```

The bootloader supports multiple trusted keys:

| Key   | Purpose                |
| ----- | ---------------------- |
| Key 0 | Primary production key |
| Key 1 | Backup production key  |
| Key 2 | Recovery key           |

A kernel is accepted if its signature verifies against **any** trusted key.

***

### Build Output Structure

```
target/
├── x86_64-unknown-uefi/release/
│   ├── nonos_boot.efi          # Raw UEFI binary
│   └── nonos_boot.pdb          # Debug symbols (92 KB)
│
└── esp/EFI/
    └── Boot/BOOTX64.EFI        # Deployed bootloader
```

***

### Secure Boot Integration

The bootloader can operate in two modes:

| Mode        | Secure Boot | Description                         |
| ----------- | ----------- | ----------------------------------- |
| Development | Disabled    | Uses dev signing key                |
| Production  | Enabled     | Requires enrolled NØNOS certificate |

To enroll NØNOS for Secure Boot, see Booting on Hardware.

***

### Testing Standalone

Test the bootloader independently:

```bash
# Build bootloader only
make bootloader

# Run in QEMU (will fail at kernel verification - expected)
qemu-system-x86_64 \
    -machine q35 \
    -bios /usr/share/OVMF/OVMF_CODE.fd \
    -drive format=raw,file=fat:rw:target/esp \
    -serial stdio
```

***

### Troubleshooting

| Issue                        | Solution                                         |
| ---------------------------- | ------------------------------------------------ |
| `not a valid PE image`       | Verify `--target x86_64-unknown-uefi`            |
| UEFI boot fails              | Check OVMF path: `ls /usr/share/OVMF/`           |
| Signature verification fails | Rebuild both bootloader and kernel with same key |
| Black screen                 | Try different display output or serial mode      |

***