docs: rework client/crate READMEs, add missing ones

Rework the client READMEs to be accurate and inviting to first-time visitors, and fill in the gaps where crates and tools had none. - Rewrite clients/{apple,android,decky} READMEs (features-first, trim dense internal narrative; drop the stale "one session at a time" / "renegotiation not implemented" section from the Apple README). - Add READMEs for clients/{linux,windows,probe}, which had none. - Add crate READMEs for punktfunk-host, punktfunk-core, pf-driver-proto. - Add brief READMEs for tools/{loss-harness,latency-probe}. - Fix packaging/README duplicate "Option B" heading (bootc -> Option C). - Fix docs-site/README stale docs/ -> design/ reference. - De-stale packaging/windows/drivers/pf-dualsense README (drop "M0 spike" / external-checkout framing; reflect in-tree workspace + shipped + installer-bundled + multi-pad), keeping the driver-authoring lore. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-01 19:31:06 +00:00
parent 7975a95cd6
commit d6596ff81b
14 changed files with 624 additions and 585 deletions
@@ -0,0 +1,16 @@
+# pf-driver-proto
+
+The shared **host ↔ driver binary contract** for punktfunk's Windows **pf-vdisplay** virtual display —
+the control IOCTLs and the IDD-push frame transport, defined exactly once.
+
+It's a path dependency of **both** the host workspace ([`crates/punktfunk-host`](../punktfunk-host))
+and the out-of-workspace driver workspace ([`packaging/windows/drivers/`](../../packaging/windows)),
+so it must resolve identically from either build graph. That's why it's deliberately self-contained:
+`no_std` (+ alloc), platform-neutral (GUID/LUID are plain integers each side converts to its own OS
+type), and free of `*.workspace = true` inheritance.
+
+Defining every wire struct here — with `const` size/offset asserts and `bytemuck` round-trips — turns
+host↔driver ABI drift into a **compile error** instead of a silent frame or IOCTL corruption.
+
+See the crate root ([`src/`](src/)) for the wire types; the Windows virtual-display design is in
+[`design/windows-virtual-display-rust-port.md`](../../design/windows-virtual-display-rust-port.md).
@@ -0,0 +1,61 @@
+# punktfunk-core
+
+The **shared protocol core** — the one place where punktfunk's transport, forward error correction,
+and crypto live. It's linked into the [host](../punktfunk-host/README.md) and every native client, so
+there's exactly one implementation of the wire format everywhere.
+
+Written in Rust with **no async on the per-frame path** (native threads only). It exposes both a
+normal Rust API and a **stable, versioned C ABI**, so the Swift and Kotlin clients — and any C
+embedder — link the same code as the Rust ones.
+
+## What's in here
+
+- **Transport & session** (`session.rs`, `transport/`, `packet.rs`) — the `punktfunk/1` data plane
+  over raw UDP: packetization, reassembly (with attacker-bounded limits), pacing, and socket tuning.
+- **FEC** (`fec/`) — the wall-breaker. Two codes:
+  - **GF(2⁸)** classic Reed–Solomon with the *Cauchy* generator matrix — byte-identical to the
+    `nanors` library Moonlight uses, so our parity is decodable by a stock Moonlight client.
+  - **GF(2¹⁶) Leopard-RS** (SIMD, O(n log n)) — up to 65535 shards/block, which removes the ~1 Gbps
+    FEC ceiling. `punktfunk/1` negotiates this one.
+- **Crypto** (`crypto.rs`) — AES-128-GCM session encryption with per-direction nonce salts and
+  sequence-as-AAD; SPAKE2 PIN pairing lives behind the `quic` feature.
+- **QUIC control plane** (`quic.rs`, `client.rs`, feature `quic`) — the Hello/Welcome/Start handshake,
+  cert pinning/TOFU, reverse audio, and the embeddable `NativeClient` connector. This is the **only**
+  place `tokio`/`quinn` are allowed; the feature is **off by default** so the core stays runtime-free.
+- **C ABI** (`abi.rs`) — the versioned surface (`punktfunk_abi_version()`, `PunktfunkConfig` carrying
+  its own `struct_size`) that generates [`include/punktfunk_core.h`](../../include/punktfunk_core.h)
+  via cbindgen at build time.
+
+## Build outputs
+
+The crate builds three ways at once (`crate-type = ["lib", "cdylib", "staticlib"]`):
+
+| Output | Used by |
+|--------|---------|
+| `lib` (rlib) | the host, probe, and tools link it as a normal Rust crate |
+| `cdylib` (`.so`/`.dylib`) | the Swift / Kotlin clients via the C ABI |
+| `staticlib` (`.a`) | the C test harness and static embedding |
+
+## Test
+
+```sh
+cargo test -p punktfunk-core                 # unit + proptest + loopback
+cargo run  -p loss-harness                   # FEC loss-resilience sweep (no network needed)
+bash crates/punktfunk-core/tests/c/run.sh    # standalone C-ABI link + round-trip proof
+```
+
+## Design invariants (do not regress)
+
+- **One core, linked everywhere** — protocol/FEC/crypto live only here, behind the stable C ABI.
+- **No async on the hot path** — the per-frame pipeline is native threads only; `quic` (tokio/quinn)
+  is control-plane only, feature-gated, off by default.
+- **Security hardening stays intact** — the reassembler bounds attacker-controlled fields before
+  allocating; AES-GCM keeps per-direction nonce salts + seq-as-AAD; the ABI checks `struct_size`.
+  Regression tests exist — keep them green.
+
+## Related
+
+- **[`punktfunk-host`](../punktfunk-host/README.md)** — the streaming host built on this core
+- **[Clients](../../clients/)** — the apps that link this core over the C ABI (or directly, in Rust)
+- **[`design/implementation-plan.md`](../../design/implementation-plan.md)** — why GF(2¹⁶) FEC, the
+  latency budget, and the architecture thesis
@@ -0,0 +1,90 @@
+# punktfunk-host
+
+The **streaming host** — the program you run on the machine whose desktop or games you want to
+stream. For each client that connects, it spins up a **virtual display sized to that device**,
+captures it on the GPU, encodes with hardware NVENC/VAAPI/AMF/QSV, and sends it out over a
+low-latency transport — no physical monitor, no letterboxing, no rearranging your real screens.
+
+It speaks two protocols from **one process**:
+
+- **GameStream** — so any [Moonlight](https://moonlight-stream.org/) / Artemis client works day one.
+- **`punktfunk/1`** — punktfunk's own faster protocol (QUIC control plane, GF(2¹⁶) FEC + AES-GCM data
+  plane) that the native clients use.
+
+Runs on **Linux** (the primary, most battle-tested path) and **Windows** (x64). The shared protocol,
+FEC, and crypto live in [`punktfunk-core`](../punktfunk-core/README.md); this crate is everything
+platform-facing around it.
+
+## What it does
+
+- **Per-client virtual displays at the exact WxH@Hz.** Linux uses per-compositor backends — **KWin**,
+  **gamescope**, **Mutter**, and **Sway/wlroots**; Windows uses its own all-Rust IddCx virtual display,
+  even on the secure desktop (UAC / lock screen).
+- **GPU zero-copy capture → encode.** dmabuf → CUDA/Vulkan → NVENC on Linux; DXGI/WGC → GPU encode on
+  Windows. Encoders auto-select by GPU vendor: **NVENC** (NVIDIA), **VAAPI** (Linux AMD/Intel),
+  **AMF/QSV** (Windows AMD/Intel), or software H.264 as a floor. HDR/10-bit and HEVC 4:4:4 supported.
+- **Input injection.** Mouse/keyboard (libei / gamescope EIS / wlr / Windows SendInput) and virtual
+  **gamepads** — Xbox 360/One, DualSense, DualShock 4 — with rumble and HID feedback back-channels.
+- **Audio both ways.** Opus audio host→client, plus a virtual microphone the client can talk into.
+- **Trust & discovery.** A persistent host identity, **SPAKE2 PIN pairing** (default) or TOFU, and
+  mDNS auto-advertisement so clients find the host without typing an IP.
+- **Management API + web console.** A REST API (`mgmt.rs`, OpenAPI at
+  [`api/openapi.json`](../../api/openapi.json)) drives status, paired devices, and on-demand pairing;
+  the browser UI is in [`web/`](../../web/README.md).
+
+## Run it
+
+`punktfunk-host serve` runs inside your desktop session. Bare `serve` is the **secure native-only
+default** (`punktfunk/1` + the management API); add `--gamestream` on a trusted LAN to also accept
+stock Moonlight clients.
+
+```sh
+# Linux, from the repo root (see the repo README "Running on this box" for the headless recipe):
+cargo run -rp punktfunk-host -- serve                 # native-only (secure default)
+cargo run -rp punktfunk-host -- serve --gamestream    # + Moonlight compatibility
+```
+
+Then pair from the web console (`https://<host-ip>:3000`) or the client app.
+
+Most people should install a **package** rather than run from source — see
+[`packaging/`](../../packaging/README.md) (apt · rpm/COPR/bootc · Arch/sysext · Windows installer) and
+the per-platform guides at **[docs.punktfunk.unom.io/docs/install](https://docs.punktfunk.unom.io/docs/install)**.
+
+### Subcommands
+
+| Command | Purpose |
+|---------|---------|
+| `serve` | The host (native `punktfunk/1` + mgmt API; `--gamestream` adds Moonlight). |
+| `punktfunk1-host` | Standalone native-protocol listener for testing/measurement (`--source virtual`, `--max-sessions`). |
+| `openapi` | Print the management-API OpenAPI spec (regenerates `api/openapi.json`). |
+| `library` | Inspect the multi-store game library. |
+| `service` · `driver` · `web` | Windows: SCM service, driver install, bundled web console. |
+| `*-test` / `*-selftest` / `*-probe` | Diagnostics (input, zero-copy, HDR, compositor, gamepads). |
+
+`--help` lists them all.
+
+## Layout
+
+```
+src/
+  main.rs            CLI + subcommand dispatch
+  config.rs · session_plan.rs · session_tuning.rs · pipeline.rs   session setup + the frame pipeline
+  vdisplay/          per-compositor virtual outputs (kwin · gamescope · mutter · wlroots)
+  capture/ · capture.rs    screen/dmabuf capture (+ Windows DXGI/WGC)
+  encode/ · encode.rs      per-GPU encoders (nvenc · vaapi · ffmpeg_win (AMF/QSV) · sw)
+  zerocopy/          dmabuf → CUDA → NVENC bridges (EGL/GL tiled, Vulkan LINEAR)
+  inject/ · inject.rs      input backends (libei · wlr · uinput gamepads · UHID DualSense/DS4)
+  audio/ · audio.rs        Opus out + virtual mic (PipeWire / WASAPI)
+  gamestream/        Moonlight compat: nvhttp · pairing · rtsp · control · stream · gamepad · apps
+  punktfunk1.rs      the native punktfunk/1 host (QUIC control + native-thread UDP data plane)
+  mgmt.rs · native_pairing.rs · stats_recorder.rs   management API, pairing, perf capture
+  hdr.rs · library.rs      HDR metadata; multi-store game library
+  linux/ · windows/  platform-confined backends
+```
+
+## Related
+
+- **[`punktfunk-core`](../punktfunk-core/README.md)** — the shared protocol · FEC · crypto core
+- **[Clients](../../clients/)** — the apps that connect (Apple · Linux · Windows · Android · probe)
+- **[Packaging](../../packaging/README.md)** & **[docs](https://docs.punktfunk.unom.io)** — install & operate
+- **[`design/`](../../design/README.md)** — architecture rationale and deep-dive plans