enricobuehler
c8e19396e4
Port the proven raw_gadget virtual Deck to a Rust host gamepad backend, the SteamOS-only transport that gets Steam Input to actually promote the Deck. - inject/linux/steam_gadget.rs (new): SteamDeckGadget — a userspace raw_gadget emulator of the real 3-interface USB Deck (mouse=0/keyboard=1/controller=2, 28DE:1205) on a dummy_hcd loopback UDC, descriptors captured from a physical Deck, answering every control transfer incl. the HID feature reports. Driven by the same steam_proto::serialize_deck_state as the UHID pad; rumble feedback via parse_steam_output. The raw_gadget UAPI is funneled through 4 documented ioctl wrappers (the crate denies undocumented unsafe). - inject/linux/steam_controller.rs: the manager pad is now a DeckTransport enum (Uhid | Gadget); ensure() prefers the gadget when PUNKTFUNK_STEAM_GADGET=1 (best-effort modprobe dummy_hcd+raw_gadget), gracefully falling back to the universal UHID SteamDeckPad. write/pump/heartbeat dispatch through the enum. Validated on a real Deck via a static musl harness that #[path]-includes the module: enumerates, hid-steam binds + reads our serial + creates the Steam Deck + Motion Sensors evdevs — identical to the C PoC. Caught a real portability bug: raw_gadget's no-arg ioctls (RUN/CONFIGURE/EP0_STALL) reject a non-zero `value` with EINVAL, and on musl an omitted ioctl vararg is a garbage register — so they must pass an explicit 0. Opt-in (default off) while the Steam GetControllerInfo feature contract is hardened (to stop the gamepad-evdev churn). Workspace clippy/fmt/test green. Not pushed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
80 lines
5.0 KiB
Markdown
80 lines
5.0 KiB
Markdown
# Virtual Steam Deck via USB gadget — true Steam Input recognition
|
|
|
|
**Proven on a real Steam Deck (SteamOS 3.8.11), 2026-06-29.** A `raw_gadget` userspace emulator of a
|
|
real 3-interface USB Steam Deck (`28DE:1205`) — mouse = interface 0, keyboard = 1, **controller =
|
|
interface 2** — bound to a `dummy_hcd` loopback UDC, so the host's own Steam sees a genuine
|
|
interface-2 Deck and **promotes it through Steam Input** (XInput pad emission, glyphs, bindings).
|
|
|
|
## Why this exists (the interface-2 wall)
|
|
|
|
A virtual Deck created via **UHID** (the `inject/proto/steam_proto.rs` / `steam_controller.rs` path)
|
|
binds the kernel `hid-steam` driver, but **Steam Input will not manage it**: Steam filters the Deck's
|
|
controller to USB **interface 2**, and a UHID device has no USB interface number (`Interface: -1` in
|
|
Steam's `controller.txt`), so Steam enumerates it but never promotes it. A single-interface DualSense
|
|
is accepted at `-1` (no ambiguity), but the multi-interface Deck specifically needs interface 2. See
|
|
`design/steam-controller-deck-support.md` §11.
|
|
|
|
A real multi-interface USB device with the controller on interface 2 requires a **USB gadget**.
|
|
SteamOS ships every piece (`CONFIG_USB_DUMMY_HCD=m`, `CONFIG_USB_RAW_GADGET=m`,
|
|
`CONFIG_USB_CONFIGFS_F_HID=y`), so this runs on a Deck with no module-building.
|
|
|
|
## What's here
|
|
|
|
- **`deck_raw_gadget.c`** — the working emulator. Presents the 3-interface Deck with descriptors
|
|
captured verbatim from a physical Deck (incl. the real 38-byte controller report descriptor), and
|
|
— crucially — answers **every** control transfer, including the HID feature reports (`f_hid` can't,
|
|
so it produced a "zombie controller" in Steam). Streams the 64-byte state report on the interface-2
|
|
interrupt-IN endpoint. Build static (the Deck has no compiler):
|
|
```sh
|
|
gcc -O2 -static -pthread -o deck_raw_gadget deck_raw_gadget.c
|
|
```
|
|
Run as root with `dummy_hcd` + `raw_gadget` loaded: `./deck_raw_gadget [seconds]`.
|
|
- **`configfs_gadget_up.sh` / `_down.sh`** — the simpler **configfs `f_hid`** variant. It proves the
|
|
structure (interface 2 → `hid-steam` binds → Steam *opens* it + *reserves an XInput slot*) but
|
|
`f_hid` cannot serve HID feature reports, so Steam can't read controller details and drops it as a
|
|
zombie. Kept as the minimal reproducer of the interface-2 result.
|
|
|
|
## Result (raw_gadget, live)
|
|
|
|
```
|
|
hid-steam ... Steam Controller 'PFDECK000' connected
|
|
input: Steam Deck / Steam Deck Motion Sensors (kernel gamepad + IMU evdevs)
|
|
controller.txt: Interface: 2 ... device opened for index 14 ... reserving XInput slot 1
|
|
input: Microsoft X-Box 360 pad 1 (Steam Input's XInput output — promoted)
|
|
```
|
|
Stable (1 connect, 0 disconnects), no zombie. The kernel `"Steam Deck"` evdev is then grabbed by
|
|
Steam Input, which exposes its own X-Box 360 pad — exactly a real Deck's behaviour.
|
|
|
|
## Key implementation gotchas (all real, all cost time)
|
|
|
|
- `struct usb_endpoint_descriptor` (ch9.h) is **9 bytes** (audio `bRefresh`/`bSynchAddress`); the wire
|
|
descriptor needs **7** — use a packed 7-byte struct in the config blob or the kernel mis-parses it.
|
|
- raw_gadget EP0: a **no-data OUT** control (`SET_CONFIGURATION`, `SET_INTERFACE`, `SET_IDLE`,
|
|
`SET_PROTOCOL`) is completed with a zero-length **`EP0_READ`**, not `EP0_WRITE` (using write →
|
|
`EBUSY`/`can't set config error -110`). IN controls (`GET_*`) use `EP0_WRITE`.
|
|
- Don't start the input streamer until after `SET_CONFIGURATION` is fully acked, or its blocking
|
|
`EP_WRITE` starves the control path.
|
|
- `dummy_hcd` + `raw_gadget` must both be loaded and `/dev/raw-gadget` present before launch.
|
|
|
|
## Host backend (shipped, opt-in)
|
|
|
|
The C PoC's transport is ported to a Rust host gamepad backend:
|
|
`crates/punktfunk-host/src/inject/linux/steam_gadget.rs` (`SteamDeckGadget`), driven by the same
|
|
`steam_proto` serializer as the UHID `SteamDeckPad`. The Steam-Deck manager
|
|
(`inject/linux/steam_controller.rs`) now selects per-pad between **UHID** (default, universal) and the
|
|
**USB gadget** (`PUNKTFUNK_STEAM_GADGET=1`, SteamOS-only — best-effort `modprobe dummy_hcd raw_gadget`,
|
|
graceful fallback to UHID if `/dev/raw-gadget` is unusable).
|
|
|
|
The Rust transport is **validated on the Deck** (a static musl test binary that `#[path]`-includes the
|
|
real module): it enumerates the 3-interface Deck, hid-steam binds it + reads our serial + creates the
|
|
`Steam Deck` + `Motion Sensors` evdevs — identical to the C PoC. A real USB-stack bug it caught: on
|
|
musl, `ioctl(fd, RUN)` with no third arg passes a garbage `value`, and raw_gadget's `RUN`/`CONFIGURE`/
|
|
`EP0_STALL` reject a non-zero `value` with `EINVAL` — so the no-arg ioctls must pass an explicit `0`.
|
|
|
|
## Remaining
|
|
|
|
- **Harden the feature contract** so Steam stops re-probing + the gamepad evdev stops churning (serve
|
|
Steam's full `GetControllerInfo` attribute set, captured from a physical Deck) — then a clean live
|
|
input-flow check + defaulting the gadget on for SteamOS hosts.
|
|
- A `punktfunk-host` build for SteamOS to exercise the integrated path end-to-end with a live client.
|