punktfunk/design/windows-dualsense-scoping.md

Windows host — virtual DualSense scoping

Status: SHIPPED — M0 feasibility gate PASSED (2026-06-21), M1–M4 landed. Driver: packaging/windows/drivers/pf-dualsense/ (README there); host backend crates/punktfunk-host/src/inject/dualsense_windows.rs + shared contract inject/dualsense_proto.rs. Commits aa159df (Rust UMDF driver + shm channel), 4a73102 (host backend), fde438a/6db3525 (SwDeviceCreate per-session devnode), b0c8233 (pure-user-mode DS4/Xbox 360, ViGEm dropped). This doc is trimmed to design rationale + open items; implementation detail lives in the code and the driver README.

Why UMDF2, and why a real virtual DualSense (the WHY)

Apollo's backlog "DS4 ViGEm target on Windows" is the wrong target for actual DualSense. ViGEmBus emulates only Xbox 360 (XUSB) and DualShock 4 — never a DualSense. Because this is a host-side virtual pad, the DualSense-defining features (adaptive triggers, the fine haptic actuators, DS5 identity) only work end-to-end if the game sees a real DualSense and therefore drives them. A DS4 virtual pad makes the game take its DS4 code path and never emit those commands, so the client's adaptive-trigger rendering is never exercised. ViGEm DS4 structurally cannot deliver adaptive triggers — that ceiling is the whole reason not to copy Apollo here (and Apollo itself does DualSense only on Linux via inputtino; its Windows path is ViGEm XUSB/DS4_REPORT_EX only — zero virtual-HID/DualSense code to vendor).

The right path is the Windows analog of the Linux host's /dev/uhid device: present a real virtual DualSense HID device (Sony VID 054C / PID 0CE6, the inputtino PS5 report descriptor we already ship) so the game/Steam/GameInput bind it as genuine.

Mechanism = a UMDF2 (user-mode) HID minidriver, created/torn-down per session via SwDeviceCreate, as a lower filter under the OS pass-through driver mshidumdf.sys. This is the same driver tier as SudoVDA (UMDF, not kernel), so the existing vendor → sign → Inno-installer machinery applies almost unchanged. Two corrections drove this conclusion over the 2026-06-20 draft:

• VHF (Virtual HID Framework) supports a HID source driver only in kernel mode — it is not the mechanism for a user-mode virtual pad. The user-mode mechanism is a UMDF2 HID minidriver built from the vhidmini2 sample. So the earlier "KMDF, a higher bar than SudoVDA" framing was wrong: it is the same UMDF tier.
• UMDF 2.0 is NOT COM-based (COM/IDriverEntry/IWDFDriver are legacy UMDF 1.x). UMDF 2.0 uses the same C-style WDF object model as KMDF — a DriverEntry symbol + C function pointers, no vtable. This is precisely why a Rust FFI implementation is even conceivable.

Everything except the host backend was already platform-agnostic and DualSense-complete (protocol planes 0xCC/0xCA/0xCD, the HidOutput feedback abstraction, pad-type negotiation, clients, the C-ABI). The DualSense HID contract (the 232-byte DUALSENSE_RDESC, serialize_state for input report 0x01, parse_ds_output for output report 0x02, the 0x05/0x09/0x20 feature blobs, USB framing no-CRC) was already pure transport-independent Rust — so the report bytes are identical to Linux and only the device-framing layer is new.

Why Rust ("Option R") despite zero precedent

The user's strong preference was a self-authored Rust driver, accepted as pioneering risk. microsoft/windows-drivers-rs officially targets UMDF and ships a real (but bare-stub) UMDF sample; because UMDF 2.0 is the C function-pointer model, the FFI maps cleanly. The honest gap going in: the whole HID-minidriver layer (WdfFdoInitSetFilter, the manual inverted-call queue, IOCTL_UMDF_HID_* dispatch, HID_XFER_PACKET) was hand-written unsafe FFI with no safe wrappers, and every other shipping virtual-HID controller driver (vhidmini2, HIDMaestro, DsHidMini) is C — so symbol coverage for the UMDF target was unproven. The de-risk plan was a C vhidmini2 shim fallback (keeping all DualSense logic in the Rust host either way), with forking HIDMaestro as the last resort (rejected for real use because HIDMaestro omits adaptive triggers — it cannot prove the one thing that makes a virtual DualSense worth building).

Outcome: Option R confirmed. The M0 spike answered both the build-symbol question and the on-glass gate with a Rust driver — no C shim needed. The DualSense logic stays in Rust where it already lived.

M0 feasibility gate — PASSED (2026-06-21), and the three bugs

The blocking gate (RTX box 192.168.1.173; the dev VM is headless/WARP and cannot validate game-facing HID recognition) asked two questions no prior art settled:

1. Recognition — is a virtual 054C:0CE6 UMDF2 device accepted as a genuine DualSense by Windows.Gaming.Input / GameInput / Steam? YES — Steam recognized it and drove its DualSense-specific LEDs.
2. Adaptive-trigger fidelity — does the game's output report 0x02 (the adaptive-trigger block) actually reach the driver's WriteReport/SetOutputReport callback? YES — captured two Steam-Input output reports (validFlag1=0x14 = LIGHTBAR|PLAYER_INDICATOR). Adaptive-trigger bytes ride the same 0x02 path.

Three M0 bugs — reference for any future UMDF-in-Rust work:

1. PE FORCE_INTEGRITY blocks self-signed load. wdk-build's /INTEGRITYCHECK sets the PE FORCE_INTEGRITY bit, which demands a Microsoft-trusted signature to load. Fix: clear bit 0x80 at offset PE+0x5e post-build and re-sign. This was the load wall (earlier "Secure Boot blocks self-signed UMDF" conclusions were wrong).
2. Timer ExecutionLevel must be InheritFromParent, not zeroed. A mem::zeroed WDF_TIMER_CONFIG gives ExecutionLevel 0, which the framework rejects.
3. Queue NumberOfPresentedRequests must be u32::MAX, not 0. A zeroed parallel-queue config caps in-flight requests at 0 → EvtIoDeviceControl never fires.

Milestones

#	Milestone	State	Commit(s)
M0	Feasibility spike (Rust UMDF build + on-glass recognition + 0x02 callback)	✅ SHIPPED	driver aa159df
M1	Extract transport-independent contract into inject/dualsense_proto.rs (DUALSENSE_RDESC, serialize_state, parse_ds_output, feature blobs; calibration trimmed 42→41)	✅ SHIPPED	4a73102
M2	UMDF2 HID minidriver + INF + signed .cat (authored in Rust)	✅ SHIPPED	aa159df
M3	Rust host bridge inject/dualsense_windows.rs (DualSenseWindowsManager over Global\pfds-shm-<idx>; SwDeviceCreate per-session devnode)	✅ SHIPPED	4a73102, fde438a, 6db3525
M4	Un-gate the PadBackend::DualSense seam + GamepadPref::DualSense resolution on Windows; ViGEm dropped (pure user-mode DS4/Xbox 360 too)	✅ SHIPPED	b0c8233

A SwDeviceCreate gotcha surfaced during M3 and is worth keeping: two E_INVALIDARG causes were found — (1) an underscore in the enumerator name (pf_dualsense → must be punktfunk), and (2) passing the completion callback was rejected; the INF lists both root\pf_dualsense (devgen) and pf_dualsense (SwDevice) and the host falls back to an out-of-band devnode when per-session create fails.

Decision matrix (condensed)

Option	Adaptive triggers / DS5 identity	Effort	When it's right
A. UMDF2 virtual DualSense (shipped)	✅ full	medium — UMDF, same tier as SudoVDA	the goal — matches the Linux host
B. ViGEm DS4	❌ never (DS4 ceiling)	small	quick PS-pad, no adaptive triggers — rejected, ViGEm removed
C. Hybrid	A for DS5, Xbox 360 fallback	A + small	belt-and-suspenders (Xbox 360/XInput still covers most games)
D. Defer	—	—	would have applied only if the M0 0x02 gate had failed

Xbox 360 (XInput) covers most Windows games regardless; Xbox One/Series fold into it on Windows.

Risk register (condensed)

Risk	Status
Output 0x02 never reaches the driver write callback (fatal to value prop)	resolved — M0 measured it directly, YES
054C:0CE6 not accepted as a real DualSense	resolved — Steam recognizes it
Rust UMDF pioneering risk (no safe WDF/HID wrappers; symbol coverage)	resolved — Rust driver shipped, no C shim
SwDeviceCreate device lifetime tied to host process handle	accepted — hold HSWDEVICE for the session (matches Linux UHID fd semantics)
windows-drivers-rs transient toolchain breaks (LLVM-22 bindgen, Disc. #591)	low — pin LLVM 21.1.2
EV cert + Partner Center attestation lead time / friction	open (see below)

Open items

1. Public-distribution signing — EV cert + Microsoft attestation. The fleet/self-signed recipe (bundled .cer → machine Root + TrustedPublisher via certutil -addstore -f, then pnputil /add-driver /install, cloned from install-sudovda.ps1) works for dev/internal boxes only — Microsoft is explicit it "should never be followed for any driver package distributed outside your organization." For arms-length public users the minimal correct path is Microsoft attestation signing via Partner Center (it re-signs the .cat with a Microsoft cert → silent PnP install, no publisher prompt, no Root-store import). A bare Authenticode/OV/EV signature is not sufficient: it installs but with the blocking "would you like to install this device software?" prompt (setupapi 0x800b0109 / 0xe0000242). Attestation needs a registered Windows Hardware Developer Program (Partner Center) account and an EV code-signing cert (FIPS hardware token, ~USD 250–560/yr, 1–7 day vetting) to register and to sign the submission CAB. UMDF is exempt from kernel-mode load enforcement so the .dll loads unsigned, but installation still needs a trusted catalog. The EV key is non-exportable → CAB signing + submission is a manual offline step, not a CI secret; vendor the Microsoft-resigned .cat like SudoVDA's. (Azure Trusted Signing cannot substitute — it signs only user-mode PE//INTEGRITYCHECK/SmartScreen, not the driver .cat.) Blocks public release; dev/fleet self-signed works today.

2. GameInput API detection reads VID/PID as 0x0000. The GameInput path does not pick up the 054C:0CE6 identity (reads 0x0000); may require the KMDF USB-emulating bus driver rather than the root-enumerated UMDF HID device. Tracked in design/windows-dualsense-game-detection.md.

3. HidHide integration — unclear value on a usually-headless host; only relevant when a physical pad is also attached. Decide whether to bundle/integrate at all.

4. Minimum-OS / UMDFVERSION targeting decision — which UmdfLibraryVersion / WDK to target for the widest Win10/11 install base, consistent with punktfunk's existing host support matrix.

5. Single multi-driver CAB — can one Partner Center submission carry both SudoVDA and the DualSense driver? Multi-driver CABs are supported in general; unverified for this account.

6. DsHidMini end-user signing tier — self-signed vs attestation in its WixSharp MSI, useful as a second public-distribution data point.