punktfunk/design/windows-dualsense-game-detection.md

Windows virtual DualSense — game detection handoff

Goal: get the host's virtual DualSense detected and usable in games (Cyberpunk's native PS5 path + others) on the Windows host. This doc is the portable handoff (the investigation lives here, not in any one agent's memory). Run the experiments on the Windows host (.173, repo at C:\Users\Public\punktfunk-native).

Status (2026-06-22)

• Input works. Client → host → virtual DualSense → games read input. Verified in Steam's controller test (buttons/sticks).
• The HID is a CORRECT, COMPLETE DualSense. An SDL3 probe reports our 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. So the report descriptor, feature reports, and identity are right; 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.)
• Rumble: host-side is proven working (driver captures the game's 0x02, parse_ds_output extracts the motors, host forwards 0xCA — log: rumble: forwarding to client (0xCA) low=16128 high=16128). The break is the client (macOS) not rendering 0xCA onto the physical pad. Separate task/agent.

Root cause — CONFIRMED (2026-06-22, run live on the interactive desktop, 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 (the decisive experiment — impossible over SSH, run live in the console session):

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, and ours carry no VID_054C&PID_0CE6. 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. See "Fix options".

Secondary driver gaps found (not the detection blocker, but fix while here):

• IOCTL_HID_GET_STRING (id 4, ioctl 0x000b0013) returns STATUS_NOT_IMPLEMENTED — a game polls it repeatedly (seen live in pfds-driver.log). Implement manufacturer / product / serial strings ("DualSense Wireless Controller", a serial). Native PS5 code can read the serial to tell USB from BT.
• DS_FEATURE_CALIBRATION is 42 bytes but the report descriptor declares feature 0x05 as 41 (0x95 0x28 = 40 data + 1 id). Trim to 41 (motion-only; SDL accepts it regardless).

Fix — implemented & validated at the identity layer (2026-06-22)

create_swdevice (inject/dualsense_windows.rs) now sets, via SW_DEVICE_CREATE_INFO struct fields (NOT pProperties — empirically a DEVPROPERTY write of these PnP-owned identity keys is 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; 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).

Remaining gap (NOT fixed by the above): GameInput VID/PID still reads 0. 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 (the rank-3, last resort). Pursue only if a target title uses GameInput AND the identity fix above doesn't satisfy it; 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.

Next steps

Deployed to .173 (2026-06-22): the host identity fix is live in the PunktfunkHost service (release rebuilt + restarted) and the driver fixes are installed + signed (oem74.inf, punktfunk-ds-test cert). The box is ready for the decisive on-glass test. A rollback copy of the prior driver is at C:\Users\Public\giprobe\driver-backup-oem74.

1. Decisive on-glass test (only the user can run): launch Cyberpunk 2077 with Steam Input OFF against a virtual DS5 carrying the new identity; check the in-game glyphs/prompt switch to DualSense. Cleanest single-pad test (frees the service's pad 0 so only the new-identity pad is present): sc stop PunktfunkHost → target\debug\punktfunk-host.exe dualsense-windows-test --index 0 --seconds 600 (new identity + live cycling Cross/stick), launch the game; then deploy the release + restart with scripts\windows\deploy-host.ps1.
2. Driver-side correctness — DONE & installed (2026-06-22). Rebuilt/resigned/reinstalled per the recipe below; validated live (hidstrings probe + pfds-driver.log):
   • IOCTL_HID_GET_STRING now implemented (was STATUS_NOT_IMPLEMENTED). Discovery: Windows polls this device's string slots with low-word ids 0x0E/0x0F/0x10 (lang 0x0409) cyclically — NOT the 0/1/2 HID_STRING_ID_* constants. The handler maps them (+ 0/1/2 as fallbacks): 0x0E→manufacturer "Sony Interactive Entertainment", 0x0F→product "DualSense Wireless Controller", 0x10→serial "35533AD6E774" (the 0x09 pairing-report MAC). Verified: HidD_GetManufacturer/Product/ SerialNumberString now return those three distinct strings.
   • DS_FEATURE_CALIBRATION trimmed 42 → 41 bytes (1 id + 40 data) to match the descriptor's feature 0x05 (0x95 0x28).
   • The repo source (packaging/windows/dualsense-driver/src/lib.rs) and the m0 build copy were diverged by formatting only; they are now back in sync (the repo file was copied to m0 before building).
3. If a GameInput-only title needs the real VID/PID → the rank-3 KMDF USB-emulating bus driver.

On-box experiment tooling (built 2026-06-22, C:\Users\Public\giprobe\)

• probe.cpp (+build.bat) — GameInput enumeration/fingerprint via LoadLibrary("GameInput.dll") + GameInputCreate/RegisterDeviceCallback (GDK header). Prints each device's vid/pid/usage/counts — this is what proved GameInput reads our pad as vid=0.
• swexp.cpp (+build-swexp.bat) — standalone SwDeviceCreate identity experiment: variations for pszzCompatibleIds (struct field) vs DEVPKEY_Device_CompatibleIds (pProperties — ignored), pszzHardwareIds USB ids, pContainerId. Create at a spare instance id, hold, inspect. Built with the VS18 MSVC toolchain via vcvars64.bat.
• WGI probe: Windows PowerShell 5.1 WinRT projection of RawGameController/Gamepad (pump the message loop; subscribe RawGameControllerAdded to kick enumeration).
• Parent-walk bus check: from the HID child, DEVPKEY_Device_Parent → that node's DEVPKEY_Device_CompatibleIds, match ^USB/^BTH — mirrors HIDAPI's hid_internal_detect_bus_type().
• NOTE: the agent shell's PowerShell tool chokes on inline @'…'@ here-strings feeding Add-Type (throws a spurious "Remove-Item on system path '/' is blocked"); write C#/scripts to a file and run them instead.

How to reproduce / iterate (on .173)

1. Spawn a live virtual DualSense to test against

C:\Users\Public\punktfunk-native\target\debug\punktfunk-host.exe dualsense-windows-test --seconds 60

Creates SWD\PUNKTFUNK\PF_PAD_0 (+ its HID child) and holds it, pushing a cycling input. Or just connect a client — the real session creates the identical device. (Build with the env CMAKE_POLICY_VERSION_MINIMUM=3.5.)

2. SDL3 detection oracle (already set up: C:\Users\Public\sdltest\SDL3.dll)

Confirms HID-level recognition (HIDAPI). Run while a device from step 1 is live. PowerShell + C# (note: PS 5.1's Add-Type is C# 5 — no interpolated strings, no inline out vars, no Marshal.PtrToStringUTF8; SDL3 bools are 1 byte → [return: MarshalAs(UnmanagedType.I1)]):

$cs = @'
using System; using System.Runtime.InteropServices; using System.Text;
public static class S {
  const string D = @"C:\Users\Public\sdltest\SDL3.dll";
  [DllImport(D)][return: MarshalAs(UnmanagedType.I1)] public static extern bool SDL_Init(uint f);
  [DllImport(D)] public static extern IntPtr SDL_GetJoysticks(out int c);
  [DllImport(D)] public static extern IntPtr SDL_GetJoystickNameForID(uint id);
  [DllImport(D)] public static extern ushort SDL_GetJoystickVendorForID(uint id);
  [DllImport(D)] public static extern ushort SDL_GetJoystickProductForID(uint id);
  [DllImport(D)][return: MarshalAs(UnmanagedType.I1)] public static extern bool SDL_IsGamepad(uint id);
  [DllImport(D)] public static extern IntPtr SDL_OpenGamepad(uint id);
  [DllImport(D)] public static extern int SDL_GetGamepadType(IntPtr g);
  static string U(IntPtr p){ if(p==IntPtr.Zero)return""; int n=0; while(Marshal.ReadByte(p,n)!=0)n++; byte[] b=new byte[n]; Marshal.Copy(p,b,0,n); return Encoding.UTF8.GetString(b); }
  public static string Run(){ if(!SDL_Init(0x2000))return"init fail"; System.Threading.Thread.Sleep(1500);
    int n=0; IntPtr a=SDL_GetJoysticks(out n); StringBuilder sb=new StringBuilder("joysticks: "+n+"\n");
    for(int i=0;i<n;i++){ uint id=(uint)Marshal.ReadInt32(a,i*4); bool ig=SDL_IsGamepad(id); int t=ig?SDL_GetGamepadType(SDL_OpenGamepad(id)):-1;
      sb.AppendLine("  '"+U(SDL_GetJoystickNameForID(id))+"' vid=0x"+SDL_GetJoystickVendorForID(id).ToString("x4")+" pid=0x"+SDL_GetJoystickProductForID(id).ToString("x4")+" isGamepad="+ig+" type="+t+" (PS5=6)"); }
    return sb.ToString(); }
}
'@
Add-Type -TypeDefinition $cs; [S]::Run()

Expected today: it lists our device with type=6 (PS5). That's the baseline "HID is correct".

Next experiments — MUST run ON THE INTERACTIVE DESKTOP, not over SSH

WGI / RawInput / GameInput enumeration returns empty from a headless SSH session (no window/message pump) — only HIDAPI works headless. So these must run in the logged-in desktop session (RDP in, or run locally) while a DualSense session is live:

1. Determine which API Cyberpunk uses and whether it sees the SWD device. Enumerate via, separately:
   • Windows.Gaming.Input (RawGameController.RawGameControllers, Gamepad.Gamepads),
   • RawInput (GetRawInputDeviceList → filter HID gamepad usage 01/05),
   • GameInput (GameInputCreate → EnumerateDevices) — GameInputRedistService is installed on .173. Compare which list our VID_054C&PID_0CE6 appears in. The one(s) it's missing from point at the API Cyberpunk uses.
2. If WGI/GameInput exclude it: make the SwDeviceCreate device enumerate more like a real USB device. SwDeviceCreate takes a pProperties (DEVPROPERTY[]) array — try setting bus-type / container-id / compatible-IDs so the newer APIs accept it. If that's insufficient, the heavyweight option is a USB-emulating bus driver (the way ViGEmBus presents a real-looking device) instead of SwDeviceCreate + UMDF-HID.
3. Rule out an XInput device taking priority (a leftover ViGEm pad, etc.).
4. Correctness (not the detection blocker): DS_FEATURE_CALIBRATION in the driver is 42 bytes but the report descriptor declares feature 0x05 as 41 (1 id + 40 data, 0x95 0x28). Trim to 41; wrong calibration only affects motion, and SDL accepts the device regardless.

On-box layout (.173, builds + tools)

• Host repo / build: C:\Users\Public\punktfunk-native → cargo build -p punktfunk-host (debug for dualsense-windows-test; --release --features nvenc is what the service runs). The build env is persisted Machine-scope (PUNKTFUNK_NVENC_LIB_DIR, LIBCLANG_PATH, CMAKE_POLICY_VERSION_MINIMUM) — see scripts\windows\. One-call rebuild+redeploy of the service: scripts\windows\deploy-host.ps1 (stop → build → restart, .bak rollback); web: scripts\windows\build-web.ps1. bun=C:\Users\Public\bun, node=C:\Users\Public\node-v22.11.0-win-x64.
• Host service: scheduled task / SCM PunktfunkHost runs …\target\release\punktfunk-host.exe service run → spawns serve (currently native-only, PUNKTFUNK_HOST_CMD=serve in C:\ProgramData\punktfunk\host.env). Restart: sc stop/start PunktfunkHost. Native port 9777, mgmt 47990. (NB: Sunshine/Apollo conflicts on the GameStream ports — keep it stopped, or run native-only.)
• UMDF driver build project: C:\Users\Public\m0\windows-drivers-rs\examples\pf-dualsense (pf_dualsense.inx + src\lib.rs live here; the canonical copies are in the repo under packaging/windows/dualsense-driver/ — keep them in sync). Rebuild + reinstall recipe (e.g. after the calibration fix), all from that dir, env LIBCLANG_PATH=C:\Program Files\LLVM\bin, Version_Number=10.0.26100.0:
  1. cargo make → target\debug\pf_dualsense_package\
  2. Clear the FORCE_INTEGRITY PE bit (wdk-build sets /INTEGRITYCHECK, which blocks self-signed load): clear bit 0x80 at PE_header_offset+0x5e of pf_dualsense.dll, then re-sign.
  3. signtool sign /fd SHA256 /sha1 6A52984E54376C45A1C236B1A2C8A746C5AB6131 pf_dualsense.dll
  4. Inf2Cat /driver:<pkg> /os:10_x64 → re-sign the .cat with the same thumbprint.
  5. pnputil /delete-driver <old oemNN.inf> /uninstall /force then pnputil /add-driver pf_dualsense.inf /install. (Self-signed cert is already trusted on .173; Secure Boot ON, HVCI off.)
• SDL oracle: C:\Users\Public\sdltest\SDL3.dll. Test device: punktfunk-host.exe dualsense-windows-test --seconds N creates one SWD\PUNKTFUNK\PF_PAD_0 and holds it.

Key code

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

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.
• HID descriptor + feature reports are DS5-accurate enough that SDL identifies it as PS5.
• Host-side rumble works end to end; the client (macOS) rendering of 0xCA is the open rumble bug.