SouveraineOS/saf/device/README.md

# PAF — Pixel 3 (blueline) architecture

The living spine for the phone, reached from the SAF index as **device**. It
began in the pmOS project, moved to Pixel3Arch in July, was copied to
SouveraineOS on 2026-07-24, and became `saf/device/` on 2026-08-18 when the
SAF moved up to the umbrella and took the whole spine with it. Device code
remains in `../../Pixel3Arch/`.

**Update the relevant layer in place.** Dated captures are evidence, not a
second spine. Git holds the old arrangements: SouveraineOS `72aaa53` is the
July import; Pixel3Arch `9b1afd1` is the last full in-repo PAF snapshot.

## Start here — "I want to work on my phone"

The six things you need before any of the layer docs below matter.

**Where it is.** `10.10.20.234` over WiFi (stable since 2026-07-20; the MAC is
pinned, so it does not drift the way this doc used to claim). `172.16.42.1`
over USB, which is the fallback when WiFi is wedged.

    ssh -i ~/.ssh/ani casey@10.10.20.234

**What it runs.** Souveraine OS — Arch Linux ARM, systemd, pacman, bash. Our
own kernel (`uname -r` → `7.1.1-sdm845-g<hash>`; the hash is ground truth for
what is actually booted). Slot A is ours, slot B is LineageOS and is the
fallback — never touch it. `casey` has passwordless sudo.

**Where things get built.** Never here, and never on the laptop:
ArchDev, `casey@10.10.20.123`, same key. The phone has 3.5 GB of RAM and is the
daily driver; the laptop is for device ops only. This holds for `cargo test`
and `cargo clippy` too, not just release builds.

**How it updates.** `sudo pacman -Syu`. Everything we build ships as a signed
package — kernel included. Reaching for fastboot because a kernel changed is a
regression, not a fallback; see `../../START-HERE.md` and
`../../Pixel3Arch/CLAUDE.md` for the few real reasons to flash. COLD boots only
(a warm reboot poisons TZ/remoteproc), and reboots are Casey's, at the device.

**When it will not answer.** Two failures look identical (ping works, ssh
hangs) and both are routing, not the phone:
- *USB:* networkd matches `Name=usb*`, so a stale down `usb0` and the live
  `usb1` both hold 172.16.42.1 and replies leave by the dead one.
  `sudo ip addr flush dev usb0`, and on the laptop
  `sudo ip neigh del 172.16.42.1 dev <iface>` if the MAC looks wrong.
- *WiFi:* ath10k_snoc wedges with auth timeouts — reload the module, then
  `systemctl restart wpa_supplicant`.

**Work that started on the phone.** This is the one with no tooling, so it is
the one that bites. Things get hacked on-device and then live only there —
`~/stevia-pkg` was four pkgrels deep before any of it came back. To find it:

    ssh -i ~/.ssh/ani casey@10.10.20.234 'ls -lt ~ | head -20'
    pacman -Qm                 # foreign packages — built here, owned by nobody upstream
    pacman -Qo /usr/bin/<x>    # "No package owns" = it was hand-copied

Finishing it means three steps, in order, and the middle one is the one that
gets skipped: **merge it back** into `../../Pixel3Arch/pkgs/<name>/` (the repo
copy may have moved too — diff both ways, they can both claim the same pkgrel),
**build it on ArchDev** (`CARCH=aarch64 makepkg -f --ignorearch --nodeps`;
`../../Pixel3Arch/pkgs/stevia` is the worked cross example), then **install the
built package** rather than the on-device one. A thing that only exists on the
phone is one reflash from gone, and `../../Pixel3Arch/rootfs-overlay/` only
reaches a device at provision time — which is TASK-27's whole subject.

---

- **[platform.md](platform.md)** — hardware map, live partition layout,
  reaching the phone, boot chain, recovery.
- **[build.md](build.md)** — gitea → ArchDev → deploy pipeline, and the
  gotchas that have each cost a session.
- **[display.md](display.md)** — panel/DSI stack, the warm-cycle doctrine,
  SWIRE bias rails. SOLVED; read before touching the panel driver.
- **[touch.md](touch.md)** — FTS driver, reset polarity truth, GPI-DMA
  telemetry, the tap-to-wake/SLPI handoff goal.
- **[slpi.md](slpi.md)** — sensor island: the five-fix bring-up chain and
  the `sar.cc:27` wall. Arch status header + pmOS-era record.
- **[audio.md](audio.md)** — WCD9340/SLIMbus audio: working HiFi speaker and
  microphone profiles, working two-way calls, and the lifecycle archaeology.
- **[edge-sense.md](edge-sense.md)** — Active Edge force path, calibration,
  sessiond gating, and the remaining doze gap.
- **[modem.md](modem.md)** — WORKING on Arch. Status header + the full
  52-wall research record (modemsmem root cause).
- **[evidence/](evidence/)** — dated capture/research docs the spine cites:
  audio handoffs under `evidence/audio/`, power handoffs under
  `evidence/power/`, plus modem/QCRIL/TZ archaeology and pmOS-era snapshots.
  Read-only history; amend the living layer doc instead.

Related: `../../START-HERE.md` for triage, `../../docs/tasks/` for live work, and
`../../Pixel3Arch/` for kernel, packages, overlays, and device tooling.

## Status at a glance (reconciled 2026-08-07)

| Layer | State |
|---|---|
| Boot chain (our kernel + pmOS-chain ramdisk → Arch_root) | 🟢 stable; qbootctl closes the A/B lockout |
| Display (SW43408 panel, DPMS off/on wake) | 🟠 Warm-cycle baseline remains the only working architecture, but current `g56b0a053bef8` glass testing shows a green flash at boot/wake and occasional stale visible frame; no DSI/DPU error was logged — see display.md |
| Touch (FTS, multi-touch + gestures) | 🟠 Daytime touch and gesture detection work on current glass. DT2W can half-wake on the first double-tap (prepare immediately followed by unprepare); a second tap wakes — see touch.md |
| Modem / RF (LTE data) | 🟢 WORKING on Arch — mmcli connected, LTE, Fido, clat up (verified live 2026-07-10) |
| WiFi (ath10k_snoc) | 🟢 True unplugged cold boot verified 2026-07-11: no `rejected:90`, associates, gets DHCP, and reaches gateway + Internet. `failed to install key … -110` still occurs during association/roam but did not break connectivity; `cryptmode=1` remains a fallback only if it does. |
| Bluetooth (bluetoothd) | 🟢 WORKING 2026-07-10: controller was invisible because WCN3990 ships no BD address (kernel leaves hci0 unconfigured) — blueline-bt-bdaddr.service sets a persisted one; live scan verified |
| USB device / KVM | 🟠 Full GUD + HID + NCM + smoo composite builds on ArchDev with transactional rollback and a sessiond-owned power-sheet verb. Not installed on glass yet: the phone still runs usb-signaller 0.3.1-3 and has no smoo package — see `../../USB/README.md` and TASK-62. |
| SLPI sensor island | 🟢 `sar.cc` fatal is gone (regression, not a real limit) — `iio-sensor-proxy` runs always-on via `blueline-sensors-enable.service` (After=blueline-hexagonrpcd-sdsp), no more on-demand start/stop. Proximity (TMD2725) and accelerometer both live — see slpi.md |
| Tap-to-wake | 🟠 AP-side gesture mode detects DBLTAP and delivers wake, but the current screen-toggle path can half-wake on the first tap. DT2W now gates on proximity — `blueline-screen-toggle on` checks `ProximityNear` over D-Bus and suppresses the wake if blocked (phone in pocket). The SLPI gesture-nanoapp path is unblocked by the sar.cc fix but not required for AP-side DT2W. |
| Audio | 🟢 WORKING. PipeWire/WirePlumber exposes the HiFi speaker and microphone; Casey uses the mic for STT. The Voice Call profile carries real two-way calls, with earpiece/speaker switching handled by `blueline-callaudio-hook` — see audio.md. |
| Active Edge (squeeze) | 🟢 WORKING 2026-07-28 — force detected (2502-2990 deflection) after the rail became a DT gpio-hog; producer packaged, enabled, and gated through sessiond's pocket veto. No detection while the AP sleeps — see edge-sense.md |
| Fingerprint (FPC1020) | 🟠 driver written and building 2026-08-01 — `drivers/input/misc/fpc1020.c` on branch `fingerprint-fpc1020`, reset gpio7 / IRQ gpio121 verified against this unit's DTBO, reports `KEY_WAKEUP`. **Never run on the device.** Electrical half only; capture/matching are a TrustZone app we do not load — see TASK-44 |
| Camera | 🟠 Front IMX355 streams real frames. Rear IMX363 DT exists but remains unbuilt — see TASK-46. |
| NFC / haptics | ⚪ Open — see TASK-45 and the live task index. |

**One-line state:** daily-driver Arch on slot A with LTE, WiFi, Bluetooth,
speaker/microphone/call audio, daytime touch, Active Edge, always-on sensors,
and a working front camera. Android (LOS) remains intact on slot B.