Expand USB/NVMe boot docs with EEPROM reference and boot order table

2026-05-19 23:23:26 -04:00
parent 9492cdd324
commit 03f517dc24
3 changed files with 89 additions and 31 deletions
@@ -17,33 +17,72 @@ sudo apt install gcc-aarch64-linux-gnu build-essential flex bison libssl-dev bc

 ## Build Modes

-| Command | Description | Time |
-|---------|-------------|------|
-| `./build/build.sh` | Full build with PREEMPT_RT kernel | 30-45 min |
-| `./build/build.sh --skip-kernel` | Quick build, stock kernel | 10-15 min |
-| `./build/build.sh --target usb` | Build for USB SSD boot | 30-45 min |
-| `./build/build.sh --target nvme` | Build for NVMe HAT (NVMe driver included) | +1 min |
-| `./build/build.sh --kernel-only` | Only build RT kernel | 10-15 min |
+| Build Flag | Target | Use Case | Time |
+|---|---|---|---|
+| (none) | SD Card (default) | Development / testing | 30-45 min |
+| `--skip-kernel` | SD Card (stock kernel) | Quick iteration | 10-15 min |
+| `--target usb` | USB 3.0 SSD | Portable, shares USB with audio | 30-45 min |
+| `--target nvme` | NVMe HAT | **Production** — PCIe, no bus contention | 30-45 min |
+| `--kernel-only` | Kernel only | Custom RT kernel builds | 10-15 min |

 ## Flashing

-### SD Card
+### Linux
+
 ```bash
+# SD Card:
 sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/mmcblk0 bs=4M status=progress conv=fsync
-```

-### USB SSD
-```bash
+# USB SSD:
 sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/sda bs=4M status=progress conv=fsync
-# Then on Pi: sudo rpi-eeprom-config --edit → BOOT_ORDER=0xf41
+
+# NVMe HAT:
+sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/nvme0n1 bs=4M status=progress conv=fsync
 ```

-### NVMe HAT
+### macOS
+
 ```bash
-sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/nvme0n1 bs=4M status=progress conv=fsync
-# Then on Pi: sudo rpi-eeprom-config --edit → BOOT_ORDER=0xf614
+xz -d build/out/rpi-audio-mixer-*.img.xz
+diskutil list
+diskutil unmountDisk /dev/diskX
+sudo dd if=build/out/rpi-audio-mixer-*.img of=/dev/rdiskX bs=4m status=progress
+diskutil eject /dev/diskX
 ```

+### Windows
+
+Use [Raspberry Pi Imager](https://www.raspberrypi.com/software/) or [balenaEtcher](https://www.balena.io/etcher/).
+
+## Configuring EEPROM Boot Order
+
+The RPi4B boots from SD card by default. To boot from USB or NVMe, configure the EEPROM once:
+
+```bash
+# Check current
+sudo rpi-eeprom-config
+
+# Edit
+sudo rpi-eeprom-config --edit
+```
+
+| Boot Order | Sequence |
+|---|---|
+| `BOOT_ORDER=0xf41` | USB → SD → Restart |
+| `BOOT_ORDER=0xf614` | NVMe → USB → SD → Restart |
+
+### First-Boot Bootstrap
+
+Without a working SD card, flash RPiOS Lite to a temporary SD, boot, configure EEPROM, then switch to your USB/NVMe drive.
+
+### Boot Device Codes
+
+- `0x0` = SD Card (SDIO)
+- `0x1` = USB Mass Storage
+- `0x2` = NVMe (PCIe)
+- `0x6` = Network (PXE)
+- `0xf` = Stop/Restart
+
 ## First Boot

 The setup wizard runs automatically and configures:
@@ -52,4 +91,4 @@ The setup wizard runs automatically and configures:
 3. Hostname
 4. API key
 5. JACK buffer/latency
-6. **EEPROM boot order** (USB/NVMe option)
+6. EEPROM boot order (USB/NVMe option)
@@ -3,7 +3,7 @@
 ## Raspberry Pi

 | Model | Status |
-|-------|--------|
+|---|---|
 | Pi 4B (8GB) | ✅ Primary target |
 | Pi 4B (4GB) | ✅ Supported |
 | Pi 5 | ⚠️ Untested |
@@ -11,25 +11,31 @@

 ## Storage / Boot Media

-| Media | Target | Bus | Recommendation |
-|-------|--------|-----|----------------|
-| A2 SD Card | `--target sd` | SDIO | Dev/testing |
+| Media | Build Flag | Bus | Recommendation |
+|---|---|---|---|
+| A2 SD Card | `--target sd` (default) | SDIO | Dev/testing |
 | USB 3.0 SSD | `--target usb` | USB 3.0 | Portable use |
 | NVMe SSD + HAT | `--target nvme` | PCIe | **Production** |

 ### NVMe HATs

 | HAT | Size | Price |
-|-----|------|-------|
+|---|---|---|
 | Official RPi NVMe Base | 2230/2242 | ~€15 |
 | Pimoroni NVMe Base | 2230/2242 | ~€15 |
 | Geekworm X1001 | 2230 | ~€12 |
 | Geekworm X1002 | 2242/2280 | ~€15 |

+### USB SSD Considerations
+
+- Shares the USB 3.0 bus with audio interface — test for xruns under load
+- Self-powered USB 3.0 enclosure recommended
+- Run at 48kHz/128-frame buffer minimum
+
 ## USB Audio Interfaces

 | Interface | I/O | Status |
-|-----------|-----|--------|
+|---|---|---|
 | Behringer UMC1820 | 18/20 | ✅ Verified |
 | Behringer UMC404HD | 4/4 | ✅ Verified |
 | Focusrite Scarlett 18i20 (3rd Gen) | 18/20 | ✅ Verified |
@@ -41,7 +47,7 @@
 ## Displays

 | Display | Connection | Status |
-|---------|-----------|--------|
+|---|---|---|
 | Official RPi 7" Touch | DSI | ✅ Verified |
 | Waveshare 5" HDMI | HDMI + USB touch | ✅ Verified |
 | Waveshare 7" HDMI | HDMI + USB touch | ✅ Verified |
@@ -53,3 +59,18 @@ All USB class-compliant MIDI controllers work. Tested with:
 - FaderFox UC4
 - Arturia BeatStep Pro
 - Korg nanoKONTROL2
+
+## EEPROM Boot Config (Quick Reference)
+
+```bash
+# SD boot (default)
+BOOT_ORDER=0xf41  # SD → USB → Restart
+
+# USB SSD boot
+BOOT_ORDER=0xf41  # USB → SD → Restart
+
+# NVMe HAT boot
+BOOT_ORDER=0xf614 # NVMe → USB → SD → Restart
+```
+
+See the [[Build-Instructions]] wiki page for detailed setup steps.
@@ -22,12 +22,10 @@

 ## Boot Options

-The same image supports three boot targets:
+The same image supports three boot targets. See [[Build-Instructions]] for flash commands and EEPROM configuration.

-| Media | Build Flag | Recommendation |
-|-------|-----------|----------------|
-| SD Card | `--target sd` (default) | Development/testing |
-| USB SSD | `--target usb` | Portable, but shares USB bus with audio |
-| NVMe HAT | `--target nvme` | **Production** — PCIe, no bus contention |
-
-See [[Build-Instructions]] for full build and flash guide.
+| Media | Build Flag | Performance | Reliability |
+|---|---|---|---|
+| SD Card | `--target sd` (default) | Good — SDIO bus, some latency variation | Moderate — limited write endurance |
+| USB SSD | `--target usb` | Good — shares USB with audio interface | Medium — test for xruns |
+| NVMe HAT | `--target nvme` | **Best** — PCIe 2.0 x1 dedicated bus | **Best** — no bus contention |