punktfunk/design/steam-deck-passthrough-plan.md

Plan: production-ready Steam Deck pass-through (client) + shippable virtual Deck on any Linux host

Status (2026-06-29): BUILT — code-complete, all CI checks green on Linux (build · clippy -D warnings · fmt · ~270 tests), adversarially reviewed; NOT yet on-glass validated, NOT pushed. Implemented in one pass:

• usbip/vhci_hcd transport (crates/punktfunk-host/src/inject/linux/steam_usbip.rs) presenting a real interface-2 USB Deck, with in-process vhci attach (sysfs OP_REQ_IMPORT handshake) and a bounded usbip-CLI fallback. Backed by a vendored, libusb-free trim of the usbip crate (crates/punktfunk-host/vendor/usbip-sim/, MIT, see its NOTICE).
• Selection ladder raw_gadget (SteamOS) → usbip (vhci_hcd, universal) → UHID (steam_controller.rs::open_transport); PUNKTFUNK_STEAM_USBIP=0/1, PUNKTFUNK_USBIP_ATTACH=inproc|cli.
• Shared Deck device contract (captured descriptors + 0x83/0xAE feature_reply + a Steam-accepted serial) consolidated into steam_proto.rs; the gadget now reuses it.
• Client leave-shortcuts: keyboard Ctrl+Alt+Shift+D + controller hold the escape chord (L1+R1+Start+Select) ≥1.5 s → disconnect (short press still leaves fullscreen). Steam/QAM are NOT in the chord. Linux client only for now (windows/apple/android mirror is future work).

Decisions taken (the plan's open questions): vendor-trim the crate (no libusb) ✓; in-process attach primary + CLI fallback ✓; escalate the existing escape chord (long-hold) ✓; keep BOTH raw_gadget (SteamOS fast-path) and usbip (universal) behind the transport ladder ✓.

Remaining = §6 on-glass validation (Bazzite 192.168.1.41 + Deck 192.168.1.253): confirm the in-process usbip attach promotes the Deck in game mode (Steam + QAM reach the game-mode UI), the raw_gadget path still works on SteamOS (regression), and the leave-shortcuts fire. The dev box has no Steam + no root, so this could not be run here.

Companion doc: steam-controller-deck-support.md (the virtual-Deck design + §11 the interface-2 / gadget story). The virtual Steam Deck that Steam Input promotes is already built, hardware-validated, and default-on for SteamOS (raw_gadget/dummy_hcd, glass-confirmed in-game on a real Deck).

Goal

When a Steam Deck (or any Valve controller) is the client, streaming to a Linux host running Steam (SteamOS or Bazzite/generic), every Deck control — including the Steam logo button and the QAM "…" (quick-access) button — passes through and drives the host's game-mode UI, so it feels native. Plus a leave-shortcut (controller + keyboard) since Steam/QAM now pass through.

What's already true (do NOT rebuild — verified by investigation wf_f5e3528b-3ef)

The client capture is already correct, and the wire + host mapping already carry Steam + QAM:

• SDL3's HIDAPI Steam Deck driver exposes Steam → Button::Guide (joystick b5) and QAM "…" → Button::Misc1 (joystick b11→misc1 in SDL_gamepad_db.h:729; confirmed in SDL_gamepad.h: "Steam Controller QAM" = MISC1). Paddles → RightPaddle1/2,LeftPaddle1/2; trackpad clicks → Touchpad/Misc2.
• clients/linux/src/gamepad.rs:173-201 button_bit() already maps Guide → wire::BTN_GUIDE, Misc1 → wire::BTN_MISC1, all four paddles, touchpad.
• Wire buttons are u32 (crates/punktfunk-core/src/input.rs:54-86): BTN_GUIDE=0x0400 (bit 10), BTN_MISC1=0x0020_0000 (bit 21); free bits = 11, 22-31. Buttons ride as individual InputEvent (0xC8) events (code=bit, x=1/0); rich input (touchpad/gyro) on 0xCC.
• Host steam_proto::from_gamepad (crates/punktfunk-host/src/inject/proto/steam_proto.rs:179-233) already maps BTN_GUIDE → btn::STEAM (line 214) and BTN_MISC1 → btn::QAM (line 230). The btn module: STEAM = 1<<13, QAM = 1<<50.
• Caveat that matters: SDL only surfaces Steam/QAM when Steam Input is NOT grabbing the controller on the client (else Steam consumes them globally and hands the app its virtual Xbox pad, which lacks Steam/QAM). The fix is disable Steam Input for the client — already the Decky plugin's "Disable Steam Input" UX. SDL's HIDAPI Deck driver is on by default on Linux (SDL_HIDAPI_DEFAULT); SDL_JOYSTICK_HIDAPI_STEAMDECK=1 is already set in gamepad.rs:446-456.
• Only the Deck host backend carries QAM. The Xbox/xpad map (inject/linux/gamepad.rs:80-97) and DualSense (dualsense_proto.rs:214) map Guide→MODE/PS but drop BTN_MISC1 (QAM) — they have no slot for it. So QAM-to-game-mode requires the virtual Deck backend (gadget or usbip). This is expected and correct.

Net: for SteamOS hosts the whole feature already works today (client capture → gadget Deck → Steam Input). The remaining work is the non-SteamOS host (usbip) + the leave-shortcut + polish.

Architecture decision: usbip/vhci_hcd is the shippable universal transport

Presenting a real interface-2 USB Deck on a generic Linux host is the only gap. Decision matrix:

Mechanism	Ships?	Why
dummy_hcd + raw_gadget	SteamOS only	In-tree on SteamOS (used + validated). Not built on Bazzite/Fedora (CONFIG_USB_DUMMY_HCD/RAW_GADGET unset); building them needs kernel-devel and MOK-signing under Secure Boot → not shippable.
usbip + vhci_hcd	everywhere	In-tree + signed on SteamOS, Bazzite, and ~every distro (it's the standard usbip stack). Loads under Secure Boot, no module build, no MOK. A userspace usbip server emulates the Deck; vhci_hcd attaches it locally.

Both validated on hardware (2026-06-29):

• raw_gadget Deck on a real Steam Deck → Steam promotes it, glass-confirmed in-game.
• usbip Deck on Bazzite → usbip attach -r 127.0.0.1 -b 0-0-0 → vhci_hcd enumerates the 3-interface Deck, hid-steam binds it, reads the serial, makes the Steam Deck/Motion Sensors evdevs, stable (1 connect / 0 disconnect), and Steam logs Interface: 2 … opened for index … reserving XInput slot 1 + emits an X-Box pad. Identical recognition to the gadget.

The working PoC is checked in at packaging/linux/steam-deck-gadget/usbip-poc/ — the new session should build on it. It uses the usbip crate (jiegec/usbip v0.8.0): a custom UsbInterfaceHandler (get_class_specific_descriptor = the 9-byte HID descriptor; handle_urb = GET report-descriptor / HID GET_REPORT=feature_reply / SET_REPORT / interrupt-IN = the 64-byte Deck state), reusing the exact captured descriptors + feature contract from steam_gadget.rs.

Build steps (ordered)

1. Refactor steam_gadget.rs into shared Deck-logic + a transport trait

The descriptor set (mouse/kbd/controller report descriptors, the device/config assembly), the feature_reply (0x83 attributes + 0xAE serial), and serialize_deck_state are transport-agnostic and already proven. Extract them into a shared module (e.g. inject/proto/steam_proto.rs already holds serialize_deck_state/feature_reply-equivalents; consolidate the gadget's feature_reply + descriptors there or a new steam_device.rs). Define:

/// A virtual Deck transport: feed it the current 64-byte state, drain feedback.
trait DeckTransport {
    fn write_state(&mut self, st: &SteamState);
    fn service(&mut self) -> Option<(u16, u16)>; // rumble
}

Make the existing raw_gadget SteamDeckGadget implement it (it already has write_state/service).

2. Add the usbip transport (SteamDeckUsbip)

• Reuse the PoC's device definition + handler. Drive the interrupt-IN report from the shared SteamState (a Arc<Mutex<[u8;64]>> the handler reads), updated by write_state.
• Dependency decision: the usbip crate hard-depends on rusb→libusb1-sys (for its host mode, which we don't use; it also breaks musl). For a clean shippable host, vendor a trimmed copy of the crate (keep lib.rs, device.rs, interface.rs, endpoint.rs, setup.rs, usbip_protocol.rs, util.rs, consts.rs; drop host.rs/cdc.rs/hid.rs + the rusb/nusb deps) under e.g. crates/punktfunk-host/vendor/usbip-sim/, or accept the libusb dep if vendoring is too much churn. Recommendation: vendor-trim (no libusb at runtime).
• Runtime: the usbip server is tokio-based. Run it on a dedicated runtime/thread (the host already uses tokio behind the quic feature). Keep it off the per-frame video path (input only — fine).
• Local attach without the usbip CLI (preferred): don't shell out to usbip attach (avoids an external usbip-utils runtime dep). Implement the client side in-process: connect to our own server (or better, a socketpair/unix socket to avoid a TCP port), do the OP_REQ_IMPORT handshake, then write "<port> <sockfd> <devid> <speed>" to /sys/devices/platform/vhci_hcd.0/attach. (Acceptable fallback for v1: depend on the usbip CLI, which is widely packaged, and Command::new("usbip").args(["attach","-r","127.0.0.1","-b","0-0-0"]).)
• ensure_modules: modprobe vhci_hcd (best-effort) the way the gadget does dummy_hcd raw_gadget.

3. Transport selection (in inject/linux/steam_controller.rs ensure() + gadget_preferred)

Extend the existing DeckTransport enum (currently Uhid | Gadget) to Uhid | Gadget | Usbip and the selection ladder to: raw_gadget if /dev/raw-gadget usable (SteamOS) → else usbip if vhci_hcd loadable (Bazzite/generic) → else UHID/DualSense. gadget_preferred() currently keys on ID=steamos; generalize to "a recognized-by-Steam transport is available" (raw_gadget OR usbip). Keep the M6 conflict gate (degrade_steam_on_conflict in punktfunk1.rs) ahead of all this — a host with a physical Deck still degrades SteamDeck→DualSense, so two-Decks never happens in production.

4. Client leave-shortcut (clients/linux/src/)

Steam/QAM now pass through, so add an explicit disconnect:

• Keyboard: in ui_stream.rs:300-310 (next to the Ctrl+Alt+Shift+Q capture toggle) add Ctrl+Alt+Shift+D → stop.store(true, …) (the stop_h is already in scope), Propagation::Stop.
• Controller: in gamepad.rs (model on maybe_fire_escape at :354-362, ESCAPE_CHORD at :36) add a disconnect chord. Recommended: hold Start+Select+L1+R1 ≥ ~1.5 s (escalate the existing escape chord — short press leaves fullscreen, long-hold disconnects) OR a dedicated combo. Fire a disconnect_tx consumed in ui_stream.rs (parallel to the escape future) → set the session stop flag (session.rs:73,212-214). Do not use Steam/QAM in the chord (they're the marquee pass-through buttons). Mirror the same to the other clients (windows/apple/android) later.

5. Polish

• Serial format: Steam flagged PFDECK0000 as an "Invalid or missing unit serial number" and substituted 28de-1205-<hash> (benign, still promoted). Use a serial Steam accepts (a real Deck's is alphanumeric like FVZZ4200469B); derive a per-instance valid-looking serial. The 0xAE attr-1 reply + the 0x83 unit-id attrs (0x0a/0x04) should be consistent.
• Verify the Decky/client "Disable Steam Input" path actually frees the Deck controller for SDL on the client (so Steam/QAM reach SDL). This is the one runtime precondition for capture.

6. Validation (glass-to-glass)

• Bazzite host (bazzite@192.168.1.41): run the host with the usbip transport, connect the Linux client (a Deck or a machine with a Valve controller, Steam Input disabled), and confirm in game mode that the Steam button opens the Steam menu and the QAM "…" button opens Quick Access.
• SteamOS host (deck@192.168.1.253): confirm raw_gadget still selected + works (regression).
• Confirm the leave-shortcut works from both controller and keyboard while Steam/QAM pass through.

Key findings / gotchas (so they aren't rediscovered)

• usbip PoC portability: the glibc build needs GLIBC_2.34 (Bazzite has 2.42) + libusb (present or vendored) → a dev-box glibc binary runs on Bazzite. musl fails (libusb1-sys). The server runs as an unprivileged user (TCP 3240); only modprobe vhci_hcd + the attach need root. A systemd system service can't exec from /home (perms) — run the server as the user.
• raw_gadget gotchas (already solved, see steam-controller-deck-support.md §11): 7-vs-9-byte endpoint descriptor; no-data OUT controls acked via zero-length EP0_READ; no-arg ioctls must pass an explicit 0 (musl); libc::ioctl request is c_ulong/c_int per libc → as _.
• Feature contract is what stops the gamepad-evdev churn (Steam re-probing): serve the captured 0x83 GET_ATTRIBUTES blob + 0xAE serial (packaging/linux/steam-deck-gadget/get_deck_attrs.c captures them from a physical Deck via hidraw HIDIOCGFEATURE; usbmon truncates to 32B). This is already in steam_gadget.rs::feature_reply and the usbip PoC.
• Captured descriptors (verbatim from a physical Deck) live in steam_gadget.rs + the usbip PoC: mouse (65B), keyboard (39B), controller (38B, Usage Page 0xFFFF), endpoints 0x81/0x82/0x83, controller bCountryCode 33.

Hardware + recipes

• Deck (SteamOS) ssh deck@192.168.1.253 — has dummy_hcd+raw_gadget+vhci_hcd+usbip; a physical Deck controller (so it degrades to DualSense by the M6 gate — for raw_gadget testing there, de-authorize the physical Deck via /sys/bus/usb/devices/3-3/authorized). No gcc.
• Bazzite ssh bazzite@192.168.1.41 — vhci_hcd+usbip (signed, in-tree), no dummy_hcd; Secure Boot on; gcc+kernel-devel present; Steam runs. This is the usbip test bed.
• Both need passwordless sudo for driving (/etc/sudoers.d/zz-punktfunk-poc — remove when done). SSH via -o BatchMode=yes. No gcc on the Deck → build static/glibc on the dev box + scp.
• usbip quick test (Bazzite): sudo modprobe vhci_hcd; ./usbip-deck-poc pressa & ; sudo usbip attach -r 127.0.0.1 -b 0-0-0 then watch dmesg + ~/.local/share/Steam/logs/controller.txt for Interface: 2 … reserving XInput slot.

Open decisions for the new session

1. Vendor-trim the usbip crate (no libusb) vs. accept the rusb/libusb dep. Recommend trim.
2. In-process vhci attach (write the sysfs) vs. shell out to the usbip CLI. Recommend in-process for v1-ship (no external CLI dep); CLI is the quick path to a working build first.
3. Controller leave-chord: escalate the escape chord (long-hold) vs. a dedicated combo.
4. Whether to unify on usbip everywhere (it works on SteamOS too) and retire raw_gadget, vs. keep raw_gadget for SteamOS (already validated). Recommend keep both behind the trait — usbip is the universal fallback, raw_gadget the validated SteamOS fast-path.

Commit trail (this work, all on main, NOT pushed)

faea4f1…a33c7d3 (M0–M6) · b6b6f27 (raw_gadget Deck) · 9e5112b (feature contract) · b3bc313 (host backend) · 8c3188d (glass-confirmed + default-on SteamOS). The usbip PoC + this plan are the next commits.