Files

T

enricobuehler f9fe496dbc feat(drivers/pf-gamepad): declare the rumble output report, and the Xbox pad gets rumble at all

`XBOX_RDESC` declared no OUTPUT item — zero `0x91` bytes. hidclass routes an output report only if
the descriptor declares one, so `on_output_report` never fired, `publish_output` never wrote the
out-ring, and `parse_xbox_output` in `inject/windows/xbox_windows.rs` was unreachable code. The
entire host-side rumble plane was already built, wired and tested, and was simply never fed. The
HID Xbox pad therefore had NO rumble whatsoever, not merely no trigger rumble.

This appends the PID-page `Set Effect Report` collection, report id `0x03`, 8 payload bytes, sized
to exactly the layout `parse_xbox_output` and `design/trigger-rumble-plane.md` §2.1 already
specify. It is declared AFTER the final Input item and re-states every global it uses, so the
16-byte input layout `xbox_proto`'s tests pin is untouched.

⚠️ PROVENANCE: hand-written, and it could not be otherwise. The Elite capture taken for WP-A
reports `OUTPUT items: 0` — Windows exposes no literal descriptor bytes and the reconstruction
carries no output collection for that pad — so there was nothing to copy. The comment says so and
asks for a Linux hidraw capture to replace it.

Also adds a compile-time assert pairing every descriptor with its HID-descriptor `wReportLength`.
Those are two copies of one length, edited in different places, and a mismatch fails SILENTLY:
hidclass asks for `wReportLength` bytes, parses whatever it got, and the pad either enumerates
truncated or not at all with nothing naming the cause. It now cannot build out of step. This
caught nothing today because I updated both by hand, but it is exactly the trap this descriptor
has already sprung twice in other forms.

MEASURED ON .173 (Win11 26200), with the pad promoted via the WP-B0 xinputhid bus-filter config:
  * `XInputSetState(0xFFFF, 0x8000)` produced, on the host side,
      `rumble from game: pad=0 low=65535 high=32767`
      `rumble from game: pad=0 low=0 high=0`
    i.e. XInputSetState -> xinputhid -> HID output report 0x03 -> on_output_report -> out-ring ->
    parse_xbox_output -> PadFeedback. First rumble this backend has ever delivered.
  * The round-trip values confirm the descriptor's `Logical Maximum (100)` percent domain is
    right: 0x8000 -> 50% -> 32767. A 0..255 domain would have produced different numbers.
  * This also answers `trigger-rumble-plane.md`'s WP0 gate — YES, Windows writes output reports
    to a synthesized 045E:0B13 — which was blocking the whole trigger plane.
  * classic XInput reads the pad fully: packets advancing, `buttons=0x1000` (the devtest's A), and
    `LX [-32768..31744]`, the complete sweep. LY/RX/RY frozen is correct; the devtest drives only
    LS-X and A.

VERIFIED
  * `cargo test -p pf-inject --lib xbox` 11/11 — the input layout is byte-identical, as intended.
  * `hid-descriptor-dump --rust-source ... --symbol XBOX_RDESC` decodes it clean: input report
    0x01 unchanged at 16 bytes and the same offsets, new output report 0x03 at 9 bytes on the
    wire, feature 0x85 unchanged, `structure: OK`.
  * Driver builds and signs on .173 with the WDK; the new const asserts compile, so all five
    descriptor/wReportLength pairs agree.
  * fmt clean on both tools; .173 fully reverted afterwards.

NOT VERIFIED
  * The enable-mask bit assignments for the two TRIGGER actuators. `XINPUT_VIBRATION` has only two
    members, so XInput can never drive them and this run could not exercise them. Still open, as
    trigger-rumble-plane.md WP0 says.
  * That this equals the real pad's output collection, byte for byte. Needs Linux hidraw.
  * Nothing about the INF is changed: `pf_gamepad.inx` still has no AddReg, so none of the
    promotion config ships. The rumble descriptor is inert until something drives it.

2026-08-09 20:07:34 +02:00

src

feat(drivers/pf-gamepad): declare the rumble output report, and the Xbox pad gets rumble at all

2026-08-09 20:07:34 +02:00

build.rs

fix(drivers): the pad channel asks the devnode who to trust, not the mailbox

2026-07-28 16:54:40 +02:00

Cargo.toml

fix(drivers): the pad channel asks the devnode who to trust, not the mailbox

2026-07-28 16:54:40 +02:00

pf_gamepad.inx

test(drivers): give the Xbox identity a root-enumerated id, and verify the whole thing on Windows

2026-08-09 16:54:00 +02:00

README.md

fix(drivers): the pad channel asks the devnode who to trust, not the mailbox

2026-07-28 16:54:40 +02:00

README.md

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 --gamepad retires 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 → WdfTimerCreate 0xC0200209. Set ExecutionLevel/SynchronizationScope = InheritFromParent + AutomaticSerialization = TRUE (the working vhidmini2 shape).
Queue Settings.Parallel.NumberOfPresentedRequests — zeroed = 0 → a parallel queue presents zero requests → EvtIoDeviceControl never fires → no HID handshake → ~5 s timeout → CM_PROB_FAILED_START. Set to u32::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 its pad_index is validated against this index on attach).
Port of the WDK vhidmini2 UMDF2 sample; the DualSense identity + 273-byte descriptor + feature blobs 0x05/0x09/0x20 come from crates/punktfunk-host/src/inject/proto/dualsense_proto.rs.