enricobuehler
77f0a25d18
The field report that started this work was an Xbox controller that no game could see on a Windows host for two weeks. Root cause was that our Xbox pad reaches no Windows input API a modern title uses. This is the fix, and it is two registry values. Windows promotes Xbox pads with `xinputhid`, whose INF is an explicit hardware-id ALLOW-LIST — its own comment says "we can not use a Compatability ID for the loading of this driver, and so rely on individual hardware IDs". A software-enumerated devnode can never match those ids, so we write what the matching install sections would have written. `045E:0B13`, the PID this identity already claimed, is on that allow-list twice, so the identity choice turned out to be exactly right. 🛑 THE PAIRING IS THE WHOLE FINDING, AND THE TWO VALUES GO IN DIFFERENT KEYS. `UpperFilters` is a `.HW` AddReg (hardware key); `DevicePropertyFlags` is a DDInstall AddReg (software key). A live A/B on .173: removing `DevicePropertyFlags` alone reverts EVERYTHING — no `IG_00`, no XUSB interface, no XInput, no WGI entry — while `UpperFilters` alone is completely inert. `1` = `BusDevice`, which Microsoft glosses as "a focused bus filter driver for the IG_ problem". It is not a description of the device, it is the switch. An earlier session installed the filter WITHOUT it, measured a device that produced nothing, and recorded "never ship it". The filter was never broken; it had never been switched on. That conclusion is now retracted. ⚠️ The Xbox line gets its OWN DDInstall section, `pfGamepadXbox`. All five identities previously shared `pfGamepad`, so an AddReg there would have handed a DualSense, DualShock 4, Edge and Steam Deck to Microsoft's Xbox translator. The regression check below exists for exactly that. MEASURED ON .173 (Win11 26200), INF-SHIPPED — no hand-written registry values: * `UpperFilters=xinputhid` lands on the hardware key and `DevicePropertyFlags=1` on the software key, applied by the INF at install. * The HID child gains the `IG_00` token: `HID\PUNKTFUNK&IG_00\...`. * An XUSB interface appears: `\\?\hid#punktfunk&ig_00#...#{ec87f1e3-...}`. * classic XInput reads it live — packets ADVANCING, `buttons=0x1000` (the devtest's A), and the stick sweeping. XInput had NEVER seen this backend before. * `XInputSetState` rumble round-trips: `rumble from game: pad=0 low=65535 high=32767`. * REGRESSION CHECK PASSED: with the DualSense identity up, its devnode has an EMPTY `UpperFilters` and no `DevicePropertyFlags`. The PlayStation pads are untouched. WGI `Gamepad` lists the pad but reads `ts=0`. That is NOT ours: a real Xbox Elite Series 2, promoted by Microsoft's own driver on the same box, reads `ts=0` in WGI at the very moment classic XInput is reading live data from it (`buttons=0x1000 LY=-32768`). Our pad is behaviourally indistinguishable from real hardware here; the row is a property of the non-interactive session. NOT VERIFIED * On-glass in a console session. Everything above ran over ssh, which is what makes the WGI row unreadable; the real-Elite control is what settles it, not a clean WGI reading. * GameInput — no binding in the `windows` crate, still unmeasured for this backend. * `PUNKTFUNK_XBOX_BACKEND` still defaults to XUSB. This changes what the HID backend CAN do; it does not change which backend is chosen. That is WP-E and it is a separate decision. * Trigger-actuator enable bits, still conjecture — `XINPUT_VIBRATION` has two members and cannot exercise them.
pf-gamepad — the virtual-gamepad UMDF2 HID minidriver
Renamed from pf-dualsense (2026-07-28). One driver has always served four identities — DualSense, DualShock 4, DualSense Edge and Steam Deck — so the old name read as if the other three lived somewhere else. Only the PACKAGE identity moved (crate, INF, CAT, DLL, UMDF service); the four hardware ids (
pf_dualsense,pf_dualshock4,pf_dualsenseedge,pf_steamdeck) are deliberately unchanged — they bind every devnode the host creates and every installed system.driver install --gamepadretires the pre-rename store package so the two can't both claim them.
A self-authored Rust UMDF2 HID minidriver that presents a virtual Sony DualSense
(VID 054C / PID 0CE6) to Windows, so games drive adaptive triggers / lightbar / rumble —
capabilities ViGEm structurally cannot deliver. It's how the punktfunk Windows host gives a client's
DualSense a near-native feel with no external gamepad dependencies (no ViGEmBus).
Shipping: the driver is one member of the in-tree driver workspace
(packaging/windows/drivers/), built from source in CI, and bundled +
pnputil-installed by the Windows host installer. The host feeds it over a shared
memory channel from crates/punktfunk-host/src/inject/windows/dualsense_windows.rs. The same UMDF driver also
serves the DualShock 4 identity per a device_type byte the host stamps.
This README captures the driver-authoring lore — the bugs and the signing recipe that make a self-signed UMDF HID driver actually load. The authoritative build/sign/package flow (CI + Inno Setup) lives in the Windows host packaging README.
Build workspace
This crate builds as a member of the packaging/windows/drivers/ workspace, which
uses the published crates.io wdk/wdk-sys/wdk-build (0.4/0.5) — not the old dev-box
windows-drivers-rs path-deps. It's a separate cargo workspace from the main tree because driver
crates are cdylibs built with the WDK toolchain on Windows only; it path-deps the shared ABI crate
crates/pf-driver-proto.
Build / sign / install recipe (the one that actually loads)
Prereqs on the Windows box: WDK 26100, LLVM (the current default; bindgen 0.72 builds on clang
22), Rust MSVC. Built as a member of the packaging/windows/drivers/ workspace (plain cargo build, no
cargo-make). A self-signed CodeSigning cert in CurrentUser\My + LocalMachine\Root +
TrustedPublisher.
Every build needs:
$env:LIBCLANG_PATH = 'C:\Program Files\LLVM\bin'
$env:Version_Number = '10.0.26100.0' # else wdk-build picks 10.0.28000.0 (no km/crt) and bindgen fails
The shipping flow is build-gamepad-drivers.ps1 (one level up): workspace cargo build --release
plus the sign steps below, staged for the installer. The original manual dev-box recipe, kept as
lore (paths reflect that era's cargo-make layout):
cargo make # -> target\debug\pf_gamepad_package\ (.inf/.cat/.dll)
# *** CRITICAL: clear the PE FORCE_INTEGRITY bit ***
# windows-drivers-rs links the DLL with /INTEGRITYCHECK, which forces a CI-trusted page-hash
# signature a self-signed cert cannot satisfy (CodeIntegrity 3004 "hash not found" /
# 3089 VerificationError 7). SudoVDA.dll (third-party VDD prior art, not used by punktfunk) has
# this bit OFF. Clear bit 0x80 at PE-header offset +0x5e:
$f = 'target\debug\pf_gamepad_package\pf_gamepad.dll'
$b = [IO.File]::ReadAllBytes($f); $pe = [BitConverter]::ToInt32($b,0x3c); $off = $pe + 0x5e
$dc = [BitConverter]::ToUInt16($b,$off); $bb = [BitConverter]::GetBytes([uint16]($dc -band 0xFF7F))
$b[$off]=$bb[0]; $b[$off+1]=$bb[1]; [IO.File]::WriteAllBytes($f,$b)
signtool sign /fd SHA256 /sha1 <cert-thumbprint> $f
Remove-Item target\debug\pf_gamepad_package\pf_gamepad.cat
Inf2Cat /driver:target\debug\pf_gamepad_package /os:10_x64
signtool sign /fd SHA256 /sha1 <cert-thumbprint> target\debug\pf_gamepad_package\pf_gamepad.cat
pnputil /add-driver target\debug\pf_gamepad_package\pf_gamepad.inf /install
devgen /add /hardwareid "root\pf_dualsense" # creates the (transient, SWD) device node
devgen (under Windows Kits\10\Tools\<ver>\x64\) is only for manual testing — the shipping
install is punktfunk-host.exe driver install --gamepad, and the host SwDeviceCreate's the device
per session (no persistent devnode). SWD devgen devices clear on reboot. TODO: drop the post-build
PE patch by stopping wdk-build emitting /INTEGRITYCHECK.
The three bugs that made it work (porting a WDK C sample to Rust)
WDF_*_CONFIG_INIT / WDF_OBJECT_ATTRIBUTES_INIT macros set non-zero defaults — mem::zeroed()
silently breaks them:
- FORCE_INTEGRITY (above) — the load wall.
- Timer
ExecutionLevel— zeroed = Invalid →WdfTimerCreate0xC0200209. SetExecutionLevel/SynchronizationScope = InheritFromParent+AutomaticSerialization = TRUE(the working vhidmini2 shape). - Queue
Settings.Parallel.NumberOfPresentedRequests— zeroed = 0 → a parallel queue presents zero requests →EvtIoDeviceControlnever fires → no HID handshake → ~5 s timeout →CM_PROB_FAILED_START. Set tou32::MAX.
Notes
- Multi-pad works via
UmdfHostProcessSharing=ProcessSharingDisabled— each pad gets its own WUDFHost (so the per-instance statics don't collide), and the driver reads its pad index from the device Location (WdfDeviceAllocAndQueryProperty) to poll its own*-boot-<index>bootstrap mailbox (the DATA section itself is unnamed — the sealed pad channel, punktfunk-planning:gamepad-channel-sealing.md— and itspad_indexis validated against this index on attach). - Port of the WDK
vhidmini2UMDF2 sample; the DualSense identity + 273-byte descriptor + feature blobs0x05/0x09/0x20come fromcrates/punktfunk-host/src/inject/proto/dualsense_proto.rs.