# Hardware Matrix

This document describes the fixture-backed hardware matrix so parser coverage stays tied
to realistic Raspberry Pi outputs instead of only hand-written unit strings.

## Supported Matrix

`pi-doctor` v1 supports diagnostics for:

- Raspberry Pi 3, 4, and 5
- Raspberry Pi Zero 2 W
- Compute Module variants that expose standard Raspberry Pi firmware and Linux interfaces
- 32-bit ARM and 64-bit ARM Linux userspaces
- Raspberry Pi OS Bookworm and the next supported release, Trixie
- Lite and Desktop images
- modern `rpicam-*` camera stacks and transitional `libcamera-*` camera stacks

Unsupported or partial-support hosts should still produce JSON, but `metadata.supported_os`
must explain why the target is outside the supported matrix.

## Fixture Set

- `fixtures/hardware-matrix/pi4-bookworm-lite-no-camera`
  - Pi 4
  - Lite-style image
  - no camera detected
- `fixtures/hardware-matrix/pi5-bookworm-desktop-camera`
  - Pi 5
  - desktop-style image
  - official camera attached
  - Bookworm externally managed Python
- `fixtures/hardware-matrix/pi5-stressed-lab-rig`
  - Pi 5
  - thermally constrained / undervoltage lab fixture
  - active and historical throttling bits present

## Capture Checklist

For each real hardware capture, collect:

- `/proc/device-tree/model`
- `/proc/cpuinfo`
- `/proc/sys/kernel/osrelease`
- `/etc/os-release`
- `/boot/firmware/config.txt` or `/boot/config.txt`
- `/sys/class/thermal/thermal_zone*/type`
- `/sys/class/thermal/thermal_zone*/temp`
- `vcgencmd get_throttled`
- `pinctrl`
- `rpicam-hello --list-cameras`
- `libcamera-hello --list-cameras` when available
- `python3 --version`
- `python3 -c "import sys; print(sys.executable)"`
- `python3 -c "import sys; print(int(sys.prefix != sys.base_prefix))"`
- `python3 -c "import sysconfig; print(sysconfig.get_path('stdlib'))"`
- `dpkg-query -W -f='${Status}' python3-picamera2`
- `dpkg-query -W -f='${Status}' python3-gpiozero`

## Validation Goals

- every parser reads at least one fixture-captured raw output
- report-building tests exercise both Pi 4 and Pi 5 layouts
- spacing-sensitive command output is covered by parser fixture tests
- no parser depends on a single exact spacing pattern without a matching test
- release binaries run natively on ARM hardware before publication
- parser fuzz and property tests cover malformed, truncated, and spacing-varied inputs
- `pi-doctor check` stays within the documented runtime and memory budget

## Hardware Validation Lab

Cross-target `cargo check` proves that code type-checks for ARM targets. It does
not prove the released ARM binary starts, probes real firmware interfaces, or
handles permissions on Raspberry Pi OS.

Release validation should run the built release binary on controlled hardware:

- Pi 3, Pi 4, Pi 5, Zero 2 W, and one Compute Module target
- at least one 32-bit ARM image and one 64-bit ARM image
- Bookworm Lite, Bookworm Desktop, and Trixie where supported
- one no-camera system, one working-camera system, and one intentionally faulty camera setup
- one system with `vcgencmd` missing or inaccessible
- one thermally constrained system or controlled thermal fixture

Self-hosted GitHub Actions runners can satisfy this when the runner labels make
the board, architecture, OS release, and image type explicit. A separate lab
runner is also acceptable if it records the release artifact digest and command
output in the release checklist.

The release-gating runner labels are:

- `self-hosted`, `linux`, `armv7`, `raspberry-pi-3`, `bookworm`, `no-camera`
- `self-hosted`, `linux`, `arm64`, `raspberry-pi-4`, `bookworm`, `no-camera`
- `self-hosted`, `linux`, `arm64`, `raspberry-pi-5`, `trixie`, `camera`
- `self-hosted`, `linux`, `armv7`, `raspberry-pi-zero-2-w`, `bookworm`,
  `no-camera`
- `self-hosted`, `linux`, `arm64`, `raspberry-pi-compute-module`,
  `bookworm`, `no-camera`
- `self-hosted`, `linux`, `arm64`, `raspberry-pi-5`, `bookworm`,
  `thermal-fixture`

Each native report must assert the expected Raspberry Pi identity, board-model
substring, architecture prefix, supported OS status, and any runner-specific
camera or thermal finding expectations. Schema-valid JSON alone is not enough
to pass hardware validation.

## Failure Modes To Keep Covered

- no camera
- camera cable or connector issue
- missing `vcgencmd`
- thermal zones with different names or missing permissions
- malformed and truncated command output
- unsupported distributions
- stale and conditional `config.txt` sections
- GPIO contention
- Pi 4 and Pi 5 `pinctrl` format differences

## Performance Budget

`pi-doctor check` should complete within five seconds on supported Raspberry Pi
hardware with default timeouts, and should keep peak memory below 64 MiB for the
CLI process. CI should fail performance regressions once native ARM runners are
available.
