# Windows virtual DualSense — game detection handoff

> **Status:** Identity fix SHIPPED (commits `6db3525`, `aa159df`, `4a73102`) —
> `crates/punktfunk-host/src/inject/windows/dualsense_windows.rs` (`create_swdevice`). This doc is trimmed
> to the root-cause analysis, the SwDeviceCreate identity rationale, the GameInput fallback design, and the
> still-open on-glass Cyberpunk verification. The implementation walkthrough, probe tooling, and the
> (now-fixed) secondary driver gaps are cut — the shipped code is the source of truth.

Goal: get the host's virtual DualSense **detected and usable in games** (Cyberpunk's native PS5 path +
others) on the Windows host. Run the decisive experiments **on the interactive desktop of the Windows host**
(`.173`) — not over SSH.

## Where it works / where it doesn't

- **Input works.** Client → host → virtual DualSense → games read input (verified in Steam's controller
  test).
- **The HID is a CORRECT, COMPLETE DualSense.** SDL3 reports the live device as
  `name='DualSense Wireless Controller' vid=0x054C pid=0x0CE6 isGamepad=True gamepadType=PS5`. SDL = HIDAPI =
  what Steam (and many games) build on → that's why Steam works. This is **not** a descriptor/feature-report
  problem.
- **Cyberpunk's native DualSense path does NOT detect it at all** (Steam Input was off — Cyberpunk was
  reading the raw HID). This is the problem the identity fix targets; on-glass confirmation is still open.

## Root cause — the PnP identity, not the HID descriptor (CONFIRMED, run live in console session 3)

The break is the device's **PnP identity / device-interface path**, not the HID descriptor or feature
reports. `hidclass` derives the HID child's path token and its `HID\VID_054C&PID_0CE6` hardware-ids from the
**parent bus device's hardware-id**. Our parent is the software (SWD) devnode `SWD\PUNKTFUNK\PF_PAD_0` whose
hardware-id is `pf_dualsense` (no VID/PID), so hidclass emits only the *VendorID+usage* fallback and **no
PID**. Measured on this box (one virtual pad live + one real 8BitDo present):

HID-child hardware-ids (`DEVPKEY_Device_HardwareIds`, CompatibleIds empty):
`HID\pf_dualsense` · `HID\VID_054C&UP:0001_U:0005` · `HID_DEVICE_SYSTEM_GAME` · `HID_DEVICE_UP:0001_U:0005`
· `HID_DEVICE` — **note the absent `HID\VID_054C&PID_0CE6`.** `HIDD_ATTRIBUTES` itself is correct (VID 054C
/ PID 0CE6), which is why attribute-readers work.

Device-interface paths (from `HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{4d1e55b2-…}`):

| Device | HID interface path |
| --- | --- |
| **Ours (virtual)** | `\\?\HID#punktfunk#1&ca418da&0&0000#{…}` — **no `VID_/PID_` token** |
| Real DualShock 4 (USB, registry remnant) | `\\?\HID#VID_054C&PID_05C4&REV_0100#…` |
| Real DualSense (BT, registry remnant) | `\\?\HID#{00001124-…}_VID&0002054c_PID&0ce6#…` |

**Cross-API enumeration matrix (the decisive experiment — impossible over SSH, run live in the console):**

| API | Sees our virtual DS5? | Identity reported | Reads from |
| --- | --- | --- | --- |
| SDL3 / HIDAPI | ✅ | 054C:0CE6, type=PS5 | `HIDD_ATTRIBUTES` → Steam works |
| RawInput | ✅ | 054C:0CE6 | `HIDD_ATTRIBUTES` |
| WGI `RawGameController` | ✅ | 054C:0CE6 | `HIDD_ATTRIBUTES` |
| WGI `Gamepad` | ❌ empty | — | (empty for *all* pads on this box — no Xbox-profile pad; not DS-specific) |
| **MS GameInput** | ✅ enumerates it | **vid=0x0000 pid=0x0000** | **PnP path / hardware-ids** |
| Cyberpunk native PS5 | ❌ | — | needs the DS5 VID/PID identity |

The GameInput result is the clincher: it **does** enumerate our pad — descriptor fingerprint matches exactly
(15 buttons, 6 axes, 1 hat, usage Game Pad 0x05) — but reports **vid/pid = 0**, while it reads the real
8BitDo's `vid=0x3434` correctly. So GameInput (and, by the same logic, a native PS5 path) takes VID/PID from
the **PnP device path / hardware-ids, NOT from `HIDD_ATTRIBUTES`**. Everything that reads attributes directly
(SDL / RawInput / WGI-raw) is fine; everything that keys off the device *identity/path* (GameInput, native
DualSense detection) sees a generic, unidentified gamepad → no PS5 path.

**⇒ The fix must put `VID_054C&PID_0CE6` into the device-interface path and the `HID\VID&PID` hardware-ids**
(give the device a real-USB-like PnP identity), not merely correct `HIDD_ATTRIBUTES`.

## The fix — SwDeviceCreate identity (shipped)

`create_swdevice` sets the identity via **`SW_DEVICE_CREATE_INFO` struct fields** (NOT `pProperties` — a
`DEVPROPERTY` write of these PnP-owned identity keys is empirically *ignored*; the create-time struct fields
are the supported lever, confirmed on `.173`):

- **`pszzCompatibleIds`** = `USB\VID_054C&PID_0CE6`, `USB\Class_03&SubClass_00&Prot_00`, `USB\Class_03`
  (Windows appends `SWD\Generic`). HIDAPI/SDL/libScePad walk HID-child → `CM_Get_Parent` → this parent's
  CompatibleIds and string-match `"USB"` → **`bus_type` now resolves to USB** (was UNKNOWN).
- **`pszzHardwareIds`** = `pf_dualsense` **first** (so the INF still binds our UMDF driver), then
  `USB\VID_054C&PID_0CE6&REV_0100`, `USB\VID_054C&PID_0CE6`. hidclass then derives the real-DS5 child ids
  **`HID\VID_054C&PID_0CE6[&REV_0100]`** (previously only `HID\VID_054C&UP:0001_U:0005`).
- **`pContainerId`** = a deterministic per-pad GUID `{50464453-0000-0000-0000-00000000000<idx>}` ("PFDS")
  — avoids the null-sentinel-ContainerId `xinput1_4` slot-skip bug, and groups the pad's devnodes.

**Validated live** (real shipping path, `dualsense-windows-test --index 1` alongside the running service's
pad 0): INF still binds (`Service=MsHidUmdf`), parent CompatibleIds/HardwareIds + per-pad ContainerId set,
the HID child gains `HID\VID_054C&PID_0CE6`, and the HIDAPI parent-walk reports **bus_type=USB**. SDL /
RawInput / WGI `RawGameController` identity stays correct (054C:0CE6).

**Why this may still not satisfy GameInput / a native PS5 path:** GameInput parses VID/PID from the HID
child's **instance path** (`HID\punktfunk\1&…`), which carries no `VID_…&PID_…` token; neither CompatibleIds
nor HardwareIds change the instance path. Only a real USB-bus instance path (`HID\VID_054C&PID_0CE6\…`) does —
i.e. a **ViGEm-style KMDF USB-emulating bus driver** (see fallback below). Prior art (HIDMaestro) shows pure
user-mode pads ARE accepted by WGI/GameInput, so other parity (descriptor / strings / mapping) may matter
more than a genuine USB bus.

## GameInput fallback design (rank-3, only if needed)

If a target title uses **GameInput** AND the shipped identity fix above doesn't satisfy it, the last-resort
option is a **rank-3 KMDF USB-emulating bus driver** (the way ViGEmBus presents a real-looking device)
instead of SwDeviceCreate + UMDF-HID — it produces a genuine `HID\VID_054C&PID_0CE6\…` instance path, the one
thing GameInput keys off. Pursue this only if required by a target title; it is heavier than the user-mode
path and HIDMaestro suggests user-mode pads can be made acceptable to GameInput without it.

## On-glass Cyberpunk verification procedure (open — only the user can run it)

Must run on the interactive desktop (RDP in or run locally) — WGI / RawInput / GameInput enumeration returns
**empty from a headless SSH session** (no window/message pump); only HIDAPI works headless.

1. Free the service's pad 0 so only the new-identity pad is present:
   `sc stop PunktfunkHost`
2. Spawn a single virtual DS5 carrying the new identity (cycles Cross/stick so input is visible):
   `target\debug\punktfunk-host.exe dualsense-windows-test --index 0 --seconds 600`
3. Launch **Cyberpunk 2077 with Steam Input OFF** (so the game reads the raw HID). Check the in-game
   glyphs/prompt **switch to DualSense**.
4. Restore the service afterward: redeploy the release + restart with `scripts\windows\deploy-host.ps1`.

## Key code

| What | File |
| --- | --- |
| Host backend (`create_swdevice`, the `Global\pfds-shm-<idx>` section, write_state/service/pump) | `crates/punktfunk-host/src/inject/windows/dualsense_windows.rs` |
| UMDF driver (HID descriptor, feature reports, `on_output_report`) | `packaging/windows/drivers/pf-dualsense/src/lib.rs` |
| Shared report codec (`serialize_state` input, `parse_ds_output` feedback) | `crates/punktfunk-host/src/inject/proto/dualsense_proto.rs` |
| Pad seam (`PadBackend`, `pump` → rumble `0xCA` / hidout `0xCD`) | `crates/punktfunk-host/src/punktfunk1.rs` |

## Open items

1. **Decisive on-glass Cyberpunk test — pending execution.** Launch Cyberpunk 2077 with Steam Input OFF
   against a virtual DS5 carrying the new identity; verify the in-game glyphs switch to DualSense (procedure
   above).
2. **GameInput rank-3 KMDF USB-emulating bus-driver fallback — optional.** Only if a GameInput-only title
   needs the real VID/PID and the shipped SwDeviceCreate identity fix doesn't satisfy it.

## Facts proven (don't re-litigate)

- `SwDeviceCreate` requirements: enumerator must have **no underscore** (`punktfunk`); the completion
  **callback is mandatory** (NULL → E_INVALIDARG). Per-session device works; auto-removed on disconnect.
- The identity keys must be set via the **`SW_DEVICE_CREATE_INFO` struct fields**, not `pProperties` — a
  `DEVPROPERTY` write of the PnP-owned identity keys is ignored.
- HID descriptor + feature reports are DS5-accurate enough that **SDL identifies it as PS5**.
- The `IOCTL_HID_GET_STRING` and `DS_FEATURE_CALIBRATION` (42 → 41 bytes) driver gaps were fixed + shipped;
  the driver answers `HidD_GetManufacturer/Product/SerialNumberString` with distinct strings. (Detail in
  `packaging/windows/drivers/pf-dualsense/src/lib.rs`.)
- Host-side rumble works end to end (driver captures the game's `0x02`, `parse_ds_output` extracts the
  motors, host forwards `0xCA`); the client (macOS) rendering of `0xCA` onto the physical pad is a separate
  open bug, not part of game detection.