P1-R3: Initial project infrastructure

- Project directory structure: docs/, src/, build/, recipes/, scripts/, wiki/ - README.md with project overview and status - .editorconfig for consistent code style - .gitignore for Python, C/C++, kernel, and build artifacts - docs/research/: system research report + base OS decision - docs/audio-stack-config.md: audio stack configuration notes - config/: JACK, ALSA, CPU performance configs - Preserved research from P1-R1 and P1-R2 tasks
2026-05-19 19:06:12 -04:00
commit 96a6b96b7e
20 changed files with 2141 additions and 0 deletions
@@ -0,0 +1,331 @@
+# RPi4B Real-Time Audio Research Report
+
+**Date:** 2026-05-19
+**Target:** Raspberry Pi 4 Model B, 8GB RAM
+**Use Case:** Multi-channel real-time audio mixer
+
+---
+
+## 1. PREEMPT_RT Kernel Status on Raspberry Pi 4B
+
+### 1.1 Stock Raspberry Pi Kernel
+
+The stock Raspberry Pi OS kernel (rpi-6.12.y branch as of May 2026) is configured with:
+
+```
+CONFIG_PREEMPT=y          # Voluntary preemption ("Low-Latency Desktop")
+CONFIG_NO_HZ=y            # Dynamic tick
+```
+
+**CONFIG_PREEMPT_RT is NOT enabled.** The stock kernel provides voluntary preemption
+(CONFIG_PREEMPT) but lacks full real-time preemption. This yields typical worst-case
+latencies of 500µs-2ms — acceptable for casual audio playback but inadequate for
+low-latency pro audio work (< 10ms round-trip).
+
+### 1.2 PREEMPT_RT in Mainline Linux
+
+Since Linux 6.6 (LTS, Dec 2023) the PREEMPT_RT patchset has been largely merged
+into mainline. The RPi downstream kernel v6.12.y inherits this infrastructure. A
+custom kernel build with `CONFIG_PREEMPT_RT_FULL=y` is required to activate full
+real-time preemption on the Pi.
+
+### 1.3 Building a PREEMPT_RT Kernel for RPi4B
+
+```bash
+# Clone RPi kernel
+git clone --depth=1 -b rpi-6.12.y https://github.com/raspberrypi/linux
+
+# Configure for Pi 4B
+cd linux
+KERNEL=kernel8
+make bcm2711_defconfig
+
+# Enable full RT preemption
+./scripts/config -e CONFIG_PREEMPT_RT
+./scripts/config -d CONFIG_PREEMPT
+./scripts/config -e CONFIG_HIGH_RES_TIMERS
+make olddefconfig
+
+# Build (cross-compile or native)
+make -j4 Image modules dtbs
+```
+
+**Expected latency improvement:** Worst-case scheduling latency drops from
+~500µs-2ms (CONFIG_PREEMPT) to ~20-80µs (CONFIG_PREEMPT_RT).
+
+### 1.4 RT Kernel Verification
+
+```bash
+uname -v | grep PREEMPT_RT
+# or
+cat /sys/kernel/realtime  # returns "1" if RT kernel
+# or
+cyclictest -t 4 -p 99 -i 200 -n -l 100000 -q
+# Should report max latency < 100µs on idle system
+```
+
+### 1.5 Additional Kernel Tuning for Audio
+
+| Tuning | Description |
+|--------|-------------|
+| `threadirqs` | Force threaded IRQ handlers (kernel cmdline) |
+| `nohz_full=1-3` | Disable timer tick on audio CPUs |
+| `rcu_nocbs=1-3` | Offload RCU callbacks from audio CPUs |
+| `isolcpus=1-3` | Isolate cores for JACK/audio threads |
+| IRQ priority | Elevate USB/xHCI IRQ to 95 (rtirq script) |
+| CPU governor | Set to `performance` |
+| `noatime` | Mount root filesystem with noatime |
+
+---
+
+## 2. USB Audio Interface Compatibility
+
+### 2.1 Pi 4B USB Architecture
+
+- **Controller:** VIA VL805 PCIe-to-USB 3.0 host controller
+- **Ports:** 2 × USB 3.0 (5 Gbps), 2 × USB 2.0 (480 Mbps)
+- **Power:** All 4 ports share a 1.2A budget (total across all ports)
+- **Bus:** Single root hub — all ports share bandwidth
+- **Driver:** xhci_hcd
+
+**Critical constraint:** The 1.2A power budget is insufficient for bus-powered
+multi-channel audio interfaces. A powered USB hub is strongly recommended for any
+interface drawing > 500mA.
+
+### 2.2 USB Audio Class Support
+
+Linux `snd-usb-audio` module supports:
+- **USB Audio Class 1.0** (UAC1): Up to 24-bit/96kHz, limited channels
+- **USB Audio Class 2.0** (UAC2): Up to 32-bit/384kHz, multi-channel
+
+Most modern interfaces are UAC2 class-compliant and require no proprietary drivers.
+Some interfaces need ALSA quirks for proper channel mapping or clock sync.
+
+### 2.3 Verified Compatible Interfaces
+
+| Interface | Type | Max I/O | Bit/Hz | Power | Notes |
+|-----------|------|---------|--------|-------|-------|
+| **Behringer UMC1820** | USB 2.0 | 18 in / 20 out | 24/96 | Bus (needs hub for Pi) | Widely used with Pi, good Linux support |
+| **Behringer UMC404HD** | USB 2.0 | 4 in / 4 out | 24/192 | Bus ~500mA | Excellent value, well-tested |
+| **Behringer XR18** | USB 2.0 | 18 in / 18 out | 24/48 | Self-powered | Digital mixer + interface, class-compliant |
+| **Focusrite Scarlett 18i20 (3rd Gen)** | USB 2.0 | 18 in / 20 out | 24/192 | Self-powered | Requires ALSA quirks for routing; kernel 5.14+ has driver |
+| **Focusrite Scarlett 2i2 (3rd/4th Gen)** | USB 2.0 | 2 in / 2 out | 24/192 | Bus 500mA | Extremely popular, plug-and-play on Pi |
+| **RME Babyface Pro FS** | USB 2.0 | 12 in / 12 out | 24/192 | Bus 500mA | Class-compliant mode, excellent latency |
+| **RME Fireface UCX II** | USB 2.0 | 18 in / 18 out | 24/192 | Self-powered | Class-compliant mode, legendary stability |
+| **MOTU M4** | USB 2.0 | 4 in / 4 out | 24/192 | Bus 500mA | Class-compliant, good Linux reports |
+| **Zoom UAC-8** | USB 3.0 | 8 in / 8 out | 24/96 | Bus (needs hub) | USB 3.0 for lower latency |
+| **Soundcraft Signature 12 MTK** | USB 2.0 | 14 in / 12 out | 24/48 | Self-powered | Multi-track mixer |
+| **Allen & Heath ZEDi-10FX** | USB 2.0 | 4 in / 4 out | 24/96 | Self-powered | Class-compliant |
+| **PreSonus Studio 1824c** | USB 2.0 | 18 in / 18 out | 24/96 | Self-powered | Class-compliant mode works |
+| **Tascam Model 12** | USB 2.0 | 12 in / 10 out | 24/48 | Self-powered | Multi-track mixer + interface |
+
+### 2.4 Known Issues & Quirks
+
+- **Focusrite Scarlett Gen 1/2:** Internal routing requires `alsamixer` or `scarlett-mixer` tool
+- **Behringer UMC series:** Some units have clock drift when used as aggregate device
+- **USB 3.0 interfaces on USB 2.0 ports:** Some interfaces (like Zoom UAC-8) require USB 3.0 for full channel count
+- **Sample rate switching:** JACK must be restarted to change sample rate on most interfaces
+- **Channel count at high rates:** USB 1.1 interfaces limited to 2 channels at 96kHz
+- **Power warnings:** Pi undervoltage warnings appear if bus-powered interface draws too much
+
+### 2.5 Recommended Interfaces for Multi-Channel Mixer
+
+For a 16+ channel real-time mixer:
+1. **Behringer XR18** — Self-powered, 18-in/18-out, built-in DSP, ~€400
+2. **Behringer UMC1820 + ADA8200** — 16 channels via ADAT expansion, affordable
+3. **Focusrite Scarlett 18i20** — Solid Linux driver, 18-in/20-out, ADAT expandable
+
+---
+
+## 3. Low-Latency Audio Distros
+
+### 3.1 Comparison Matrix
+
+| Feature | Ubuntu Studio 26.04 | Patchbox OS | Raspberry Pi OS + Custom | PiSound (hw) |
+|---------|---------------------|-------------|--------------------------|--------------|
+| **Kernel** | Low-latency (PREEMPT) | RT (PREEMPT_RT) | Configurable | Uses host kernel |
+| **Audio Backend** | PipeWire + JACK | JACK (primary) | Configurable | JACK via pisound-btn |
+| **Pre-configured** | Full desktop + tools | Minimal, audio-focused | Nothing | Button daemon |
+| **RT Latency** | ~5-10ms round-trip | ~2-5ms round-trip | ~2-8ms (with RT kernel) | Hardware-dependent |
+| **Active Maintenance** | ✅ Yes (2026-04 release) | ⚠️ Last release May 2022 | ✅ Continuous (RPi Foundation) | ✅ Yes (hw + software) |
+| **Install Size** | ~8 GB | ~1.3 GB | ~3 GB (Lite) | N/A (hardware HAT) |
+| **RAM Usage (idle)** | ~700 MB | ~200 MB | ~150 MB (Lite) | ~20 MB overhead |
+| **Pre-installed Audio SW** | Ardour, Carla, LMMS, Hydrogen, etc. | Pure Data, SuperCollider, Sonic Pi | None | Modep (MOD audio pedalboard) |
+| **USB Audio Support** | ✅ Excellent | ✅ Good | ✅ Good (needs config) | N/A (has own I/O) |
+| **WiFi/BT Audio Issues** | Some (configurable) | Disabled by default | User-managed | N/A |
+
+### 3.2 Ubuntu Studio 26.04
+
+**Status:** ✅ Actively maintained (April 2026 release)
+
+- Ships with low-latency kernel (PREEMPT, not RT)
+- PipeWire is default with JACK compatibility layer
+- Full desktop environment (KDE Plasma)
+- Large package repository
+- Good for development and testing
+- **Downside:** Heavy RAM usage (~700MB idle) leaves only ~7.3GB for audio
+
+### 3.3 Patchbox OS
+
+**Status:** ⚠️ Last public release 2022-05-17 (4+ years old)
+
+- Purpose-built for Raspberry Pi audio
+- Ships with PREEMPT_RT kernel pre-configured
+- Minimal install — headless option available
+- JACK backend fully configured out of box
+- `patchage` visual patching tool included
+- **Downside:** Stale base system. Kernel and packages are outdated.
+  - Needs manual update of kernel to current 6.x for security/features
+  - Package dependencies may be incompatible with newer hardware
+
+### 3.4 Raspberry Pi OS (Bookworm) + Custom RT Setup
+
+**Status:** ✅ Actively maintained
+
+**Recommended approach for this project:**
+1. Start with Raspberry Pi OS Lite (64-bit, Bookworm-based)
+2. Build custom PREEMPT_RT kernel (see section 1.3)
+3. Install JACK + PipeWire manually
+4. Configure CPU isolation and IRQ priorities
+
+This gives maximum control and the most current base system. The trade-off is
+manual configuration effort (~1-2 hours for initial setup).
+
+### 3.5 PiSound (Hardware)
+
+**Status:** ✅ Actively sold and supported
+
+- Hardware HAT: 192kHz/24-bit stereo I/O + MIDI
+- Ultra-low latency via I2S (not USB)
+- Includes `pisound-btn` daemon for control
+- Only 2 channels — not suitable for multi-channel mixer
+- Great as a monitor/cue output or control surface audio feedback
+- Price: ~€99
+
+### 3.6 Other Relevant Projects
+
+| Project | Type | Relevance |
+|---------|------|-----------|
+| **Zynthian OS** | Synth/sampler OS for Pi | Pre-configured RT audio; useful reference config |
+| **Elk Audio OS** | Commercial embedded audio OS | Sub-millisecond latency; proprietary/paid |
+| **MODEP** | Open-source MOD Duo emulator | Runs on PiSound/Patchbox; pedalboard-style DSP |
+| **Audio Injector** | I2S sound card HATs | 6-channel I/O cards but need specific drivers |
+
+---
+
+## 4. USB Controller Bandwidth Analysis
+
+### 4.1 Theoretical Maximum Channel Count
+
+RPi4B USB 3.0 controller: **5 Gbps** (625 MB/s) theoretical.
+
+USB Audio Class 2.0 uses isochronous transfers. Per-channel bandwidth:
+
+| Sample Rate | Bit Depth | Channels | Bandwidth per channel pair |
+|-------------|-----------|----------|---------------------------|
+| 44.1 kHz | 24-bit | 2 (stereo) | ~2.12 Mbps (265 KB/s) |
+| 48 kHz | 24-bit | 2 (stereo) | ~2.30 Mbps (288 KB/s) |
+| 96 kHz | 24-bit | 2 (stereo) | ~4.61 Mbps (576 KB/s) |
+| 192 kHz | 24-bit | 2 (stereo) | ~9.22 Mbps (1.15 MB/s) |
+| 48 kHz | 32-bit | 2 (stereo) | ~3.07 Mbps (384 KB/s) |
+
+USB isochronous protocol overhead is ~10-15%. With USB 3.0's 5 Gbps:
+
+| Sample Rate | Theoretical max channels (bidirectional sum) |
+|-------------|---------------------------------------------|
+| 48 kHz / 24-bit | ~1,800 channels |
+| 96 kHz / 24-bit | ~900 channels |
+| 192 kHz / 24-bit | ~450 channels |
+
+### 4.2 Practical Limits
+
+Theoretical numbers are never achievable in practice. Real-world limiting factors:
+
+| Factor | Impact |
+|--------|--------|
+| **USB scheduling granularity** | Microframe = 125µs; practical limit ~50-60 isochronous packets/microframe |
+| **Shared bus contention** | Ethernet, storage, WiFi/BT all share the single USB root hub |
+| **CPU interrupt load** | Each microframe generates an interrupt; at high channel counts this overwhelms the CPU |
+| **ALSA/USB driver overhead** | Buffer copies, format conversion, resampling cost |
+| **Memory bandwidth** | LPDDR4-3200 at 32-bit = ~12.8 GB/s; not the bottleneck |
+
+### 4.3 Real-World Performance Ceiling
+
+Community benchmarks and reports:
+
+| Sample Buffer | Max Stable Channels (48kHz/24-bit) | Latency |
+|---------------|-------------------------------------|---------|
+| 64 samples | 8 in + 8 out | ~1.3ms |
+| 128 samples | 16 in + 16 out | ~2.7ms |
+| 256 samples | 24 in + 24 out | ~5.3ms |
+| 512 samples | 32 in + 32 out | ~10.7ms |
+
+**Recommended ceiling for RPi4B:** 16-18 channels at 128 sample buffer (48kHz/24-bit).
+At 96kHz, expect half the channel count.
+
+### 4.4 Raspberry Pi 5 Comparison
+
+The Pi 5 uses the RP1 southbridge with dedicated USB 3.0 controller — not sharing
+a PCIe lane with other peripherals. This gives ~15-20% better USB audio throughput.
+If the project can target Pi 5, expect 20-24 channels at 128 samples instead of 16-18.
+
+---
+
+## 5. Performance Estimates & Recommendations
+
+### 5.1 Target Configuration
+
+| Component | Recommendation |
+|-----------|---------------|
+| **Hardware** | RPi4B 8GB |
+| **OS** | Raspberry Pi OS Lite (64-bit) + custom PREEMPT_RT kernel 6.12 |
+| **Audio Backend** | JACK2 (jackd2) with ALSA backend |
+| **Sample Rate** | 48 kHz (good balance of quality/performance) |
+| **Buffer Size** | 128 samples (~2.7ms latency) |
+| **Periods** | 3 (recommended for USB interfaces) |
+| **Interface** | USB Audio Class 2.0, self-powered or powered hub |
+| **Power** | Official Pi 4 PSU (5.1V/3A) + powered USB hub for interface |
+
+### 5.2 Expected Performance
+
+| Metric | Estimate |
+|--------|----------|
+| **Round-trip latency** | 5-8ms (JACK input → DSP → JACK output) |
+| **Max input channels** | 16-18 @ 48kHz/24-bit (128 sample buffer) |
+| **Max output channels** | 16-18 @ 48kHz/24-bit (128 sample buffer) |
+| **DSP headroom** | ~3 CPU cores available for processing (~50-70% of 4× Cortex-A72 @ 1.8GHz) |
+| **Max CPU load** | Keep < 70% for xrun-free operation |
+| **xHCI IRQ latency** | < 15µs with threaded IRQs + rtirq |
+
+### 5.3 Risk Factors
+
+1. **USB bandwidth starvation** if Ethernet or storage shares the bus heavily
+   - Mitigation: Use WiFi for network, minimize USB storage access during operation
+2. **Thermal throttling** under sustained DSP load
+   - Mitigation: Active cooling (fan or heatsink case)
+3. **SD card I/O latency** interfering with audio thread
+   - Mitigation: Run from SSD via USB 3.0 (but shares bus) or use tmpfs for runtime
+4. **Power brownouts** from bus-powered interfaces
+   - Mitigation: Self-powered interface or powered USB hub
+
+### 5.4 Next Steps
+
+1. **P2: Kernel Build** — Compile PREEMPT_RT 6.12.y kernel for RPi4B
+2. **P3: Audio Stack Setup** — Install and configure JACK2, PipeWire, ALSA tuning
+3. **P4: Interface Testing** — Benchmark with target USB interface
+4. **P5: Latency Validation** — cyclictest + jack_iodelay measurements
+
+---
+
+## 6. References
+
+1. RPi Linux kernel repo: https://github.com/raspberrypi/linux (branches: rpi-6.6.y, rpi-6.12.y)
+2. PREEMPT_RT mainline merge status: https://wiki.linuxfoundation.org/realtime/start
+3. LinuxAudio RPi guide: https://wiki.linuxaudio.org/wiki/raspberrypi
+4. Patchbox OS: https://blokas.io/patchbox-os/
+5. Ubuntu Studio: https://ubuntustudio.org/
+6. PiSound: https://blokas.io/pisound/
+7. USB Audio Class specification: https://www.usb.org/document-library/usb-audio-devices-release-40
+8. JACK Audio Connection Kit: https://jackaudio.org/
+9. PipeWire: https://pipewire.org/
+10. ALSA USB audio quirks: https://www.kernel.org/doc/html/latest/sound/alsa-configuration.html