unom/punktfunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 13 Wiki Activity

feat(host/windows): seal the host↔driver channels (frame + gamepad, proto v2)

Browse Source 
Frame ring (pf-vdisplay) and both gamepad SHM channels move off named Global\
objects (openable by any sibling LocalService) to UNNAMED sections/events whose
handles the host DuplicateHandles into the driver's verified WUDFHost with least
access — frame delivery over the SYSTEM+admins-only IOCTL_SET_FRAME_CHANNEL,
pads over a 32-byte named bootstrap mailbox (pid + handle value only, DoS-bounded;
HID minidrivers have no control device). Driver-validated pad_index kills
cross-pad redirects; v1↔v2 mixes fail closed with diagnosis logs on both sides.
Sibling-LocalService denial proven empirically (design/idd-push-security.md,
design/gamepad-channel-sealing.md).

Driver-side raw ops now live behind pf-umdf-util (checked shm accessors, the
forbid(unsafe_code) ChannelClient state machine, WDF request tokens) — the pad
drivers' logic is 100% safe Rust; whole drivers workspace clippy-gated in CI.

driver install --gamepad now sweeps SWD\punktfunk phantom devnodes: a re-created
SwDevice REVIVES the old devnode with its previously-bound driver (never
re-ranks), so an upgrade otherwise leaves the old driver serving — or, across
the v1→v2 fence, a dead pad (found live on the RTX box).

On-glass validated on the RTX 4090 box: frame path 7007 frames p50 2.06 ms
cross-machine; DualSense + XUSB "sealed pad channel mapped"/proto=2 attach via
both the test harness and a real streaming session; phantom-sweep repro.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Enrico Bühler
2026-07-03 12:08:56 +00:00
parent a3e1ea2b44
commit 95a08e99c3
37 changed files with 2985 additions and 1174 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packaging/windows/drivers/pf-vdisplay/src/frame_transport.rs
+196 -132
View File
@@ -1,32 +1,30 @@
//! STEP 6 — IDD-push frame publisher (DRIVER side).
//! STEP 6 — IDD-push frame publisher (DRIVER side), attached over the **sealed channel**.
//!
//! The restricted WUDFHost token canNOT create named kernel objects (proven on the RTX box: it can't
//! even write a world-writable file), so — exactly like the gamepad UMDF drivers
//! (`crates/punktfunk-host/src/inject/dualsense_windows.rs`: *"the host creates the section, privileged,
//! with a permissive SDDL so the WUDFHost can open it; the driver maps it"*) — the **host** creates the
//! shared header + frame-ready event + ring of keyed-mutex textures, and the driver only **OPENS** them.
//! The driver writes its actual render-adapter LUID + a status code back into the host-created header (our
//! only driver-visibility channel: UMDF hides OutputDebugString in ETW and the token can't write files),
//! then copies each acquired swap-chain surface into the next ring slot and signals the host.
//! The restricted WUDFHost token canNOT create named kernel objects — and since the frame channel
//! carries whole-desktop pixels, the objects are not merely host-created but **unnamed**: nothing to
//! enumerate, open by name, or pre-create ("squat"). The **host** creates the shared header +
//! frame-ready event + ring of keyed-mutex textures with no names, duplicates the handles INTO this
//! WUDFHost process (`DuplicateHandle` — SYSTEM can, we can't reciprocate, which is why the host is the
//! broker), and delivers the handle VALUES over `IOCTL_SET_FRAME_CHANNEL` ([`crate::control`] stashes
//! them per monitor as a [`FrameChannel`]). The swap-chain worker picks the stash up and attaches with
//! [`FramePublisher::from_channel`]. Only the two endpoint processes ever hold a handle to any frame
//! object — see `design/idd-push-security.md`.
//!
//! Host counterpart: `crates/punktfunk-host/src/capture/idd_push.rs`. The shared `SharedHeader` layout,
//! the [`FrameToken`] packing, the `Global\` object-name scheme, the `MAGIC`/`RING_LEN` and the
//! `DRV_STATUS_*` codes are NOT hand-duplicated here: both sides `use pf_driver_proto::frame::*`, which
//! OWNS the contract (with `const` size asserts so any drift is a compile error).
//! The driver writes its actual render-adapter LUID + a status code back into the host-created header
//! (our only driver-visibility channel: UMDF hides OutputDebugString in ETW and the token can't write
//! files), then copies each acquired swap-chain surface into the next ring slot and signals the host.
//!
//! Ported from the proven oracle (`packaging/windows/vdisplay-driver/pf-vdisplay/src/frame_transport.rs`).
//! Differences from the oracle:
//! * the layout/consts/names/token come from `pf_driver_proto::frame` instead of being re-declared;
//! * `dbglog!` replaces `log::info!`;
//! * the optional fixed-name `Global\pfvd-dbg` `DebugBlock` bring-up channel is SKIPPED (not on the data
//! path). FOLLOW-UP: if the host bring-up diagnostics are needed again, port the oracle's `DebugBlock`
//! here too (it is owned by `idd_push.rs`, not the proto).
//! Host counterpart: `crates/punktfunk-host/src/capture/windows/idd_push.rs`. The shared `SharedHeader`
//! layout, the [`FrameToken`] packing, the `MAGIC`/`RING_LEN`, the `DRV_STATUS_*` codes and the
//! channel-delivery struct are NOT hand-duplicated here: both sides `use pf_driver_proto::{control,
//! frame}`, which OWNS the contract (with `const` size asserts so any drift is a compile error).
use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
use pf_driver_proto::control::SetFrameChannelRequest;
use pf_driver_proto::frame::{
DRV_STATUS_NO_DEVICE1, DRV_STATUS_OPENED, DRV_STATUS_TEX_FAIL, FrameToken, MAGIC, RING_LEN,
SharedHeader, event_name, header_name, texture_name,
SharedHeader,
};
use windows::Win32::Foundation::{CloseHandle, HANDLE};
use windows::Win32::Graphics::Direct3D11::{
@@ -34,28 +32,95 @@ use windows::Win32::Graphics::Direct3D11::{
};
use windows::Win32::Graphics::Dxgi::IDXGIKeyedMutex;
use windows::Win32::System::Memory::{
FILE_MAP_ALL_ACCESS, MEMORY_MAPPED_VIEW_ADDRESS, MapViewOfFile, OpenFileMappingW,
UnmapViewOfFile,
FILE_MAP_READ, FILE_MAP_WRITE, MEMORY_MAPPED_VIEW_ADDRESS, MapViewOfFile, UnmapViewOfFile,
};
use windows::Win32::System::Threading::{OpenEventW, SYNCHRONIZATION_ACCESS_RIGHTS, SetEvent};
use windows::core::{HSTRING, Interface};
use windows::Win32::System::Threading::SetEvent;
use windows::core::Interface;
/// `DXGI_SHARED_RESOURCE_READ | _WRITE` — passed to `OpenSharedResourceByName` (matches the host's
/// `CreateSharedHandle` access). Kept local: it is a `OpenSharedResourceByName` arg, not part of the
/// proto contract. (Same value the host uses in `idd_push.rs`.)
const DXGI_SHARED_RESOURCE_RW: u32 = 0x8000_0000 | 0x1;
/// SYNCHRONIZE | EVENT_MODIFY_STATE — the driver does not wait on the event, only SIGNALS it.
const EVENT_ACCESS: u32 = 0x0010_0000 | 0x0002;
/// `WAIT_TIMEOUT` as an HRESULT — `AcquireSync` returns this when the slot is held by the consumer.
const WAIT_TIMEOUT_HRESULT: i32 = 0x0000_0102;
/// One monitor's sealed-channel bootstrap: the handle VALUES the host duplicated into THIS process
/// (`IOCTL_SET_FRAME_CHANNEL`). Owning a `FrameChannel` means owning those handles — exactly one of
/// {the monitor stash ([`crate::monitor`]), a [`FramePublisher`] under construction} holds it at any
/// time, and `Drop` closes every entry not consumed, so a replaced/unmatched/failed delivery can never
/// leak entries in the WUDFHost handle table. A `0` field means "taken" (or never valid) and is skipped.
pub struct FrameChannel {
/// The ring generation these textures belong to (checked against the header at attach).
generation: u32,
ring_len: u32,
header: u64,
event: u64,
textures: [u64; RING_LEN as usize],
}
impl FrameChannel {
/// Validate + adopt the handle values from the host's IOCTL. `None` on a malformed request (bad
/// `ring_len`, zero handles) — the caller completes with `STATUS_INVALID_PARAMETER` and nothing is
/// adopted (a zero value is never treated as a handle).
pub fn from_request(req: &SetFrameChannelRequest) -> Option<Self> {
if req.ring_len == 0 || req.ring_len > RING_LEN {
return None;
}
if req.header_handle == 0
|| req.event_handle == 0
|| req.texture_handles[..req.ring_len as usize].contains(&0)
{
return None;
}
Some(Self {
generation: req.generation,
ring_len: req.ring_len,
header: req.header_handle,
event: req.event_handle,
textures: req.texture_handles,
})
}
/// Move a handle value out of the channel: the caller now owns it; `Drop` skips the zeroed slot.
fn take(v: &mut u64) -> HANDLE {
HANDLE(core::mem::take(v) as usize as *mut core::ffi::c_void)
}
/// Disarm without closing anything — for the adopt-on-success-only contract: a delivery rejected
/// with an error completion was never adopted, and the HOST reaps its remote duplicates on that
/// error, so closing here too would double-close (see `crate::control::set_frame_channel`).
pub fn into_unowned(mut self) {
self.header = 0;
self.event = 0;
self.textures = [0; RING_LEN as usize];
}
}
impl Drop for FrameChannel {
fn drop(&mut self) {
for v in [&mut self.header, &mut self.event]
.into_iter()
.chain(self.textures.iter_mut())
{
if *v != 0 {
let h = Self::take(v);
// SAFETY: `h` is a live handle the host duplicated into this process for us to own; it
// was not consumed (non-zero), so this is its sole close.
unsafe {
let _ = CloseHandle(h);
}
}
}
}
}
// NB: `FrameChannel` is plain integers, so it is auto-`Send` — it crosses from the control-plane
// dispatch thread (stash) to the swap-chain worker (attach) with `MONITOR_MODES` serializing the
// hand-off; no manual impl needed (handle values are process-global tokens, not thread-affine).
struct Slot {
tex: ID3D11Texture2D,
mutex: IDXGIKeyedMutex,
}
/// Publishes acquired swap-chain surfaces into the HOST-created ring. Owned by the swap-chain processor
/// thread; attached lazily once the host has created the shared objects.
/// thread; attached lazily once the host's channel delivery lands in the monitor stash.
pub struct FramePublisher {
context: ID3D11DeviceContext,
map: HANDLE,
@@ -70,7 +135,8 @@ pub struct FramePublisher {
ring_format: u32,
/// The ring generation this publisher attached to. The host BUMPS the header generation when it
/// recreates the ring at a new format mid-session (the display's HDR mode flipped) — [`Self::is_stale`]
/// detects that so `run_core` re-attaches to the new-format textures instead of dropping every frame.
/// detects that so `run_core` re-attaches to the new ring (whose channel the host re-delivers)
/// instead of dropping every frame.
generation: u32,
/// Set when a surface is dropped for a descriptor mismatch (a game mode-set the display), cleared on a
/// matched publish — throttles the drop log to once per mismatch episode (game-capture bug GB1).
@@ -81,102 +147,99 @@ pub struct FramePublisher {
unsafe impl Send for FramePublisher {}
impl FramePublisher {
/// Try ONCE to attach to the host-created shared objects. Returns `Err` cheaply if the host hasn't
/// created/published them yet — the drain loop retries periodically, so a non-IDD-push session just
/// keeps draining with no stall. All early-return paths clean up the handles/mapping they opened
/// explicitly (raw-handle style, no RAII — matches the rest of this driver).
pub fn try_open(
target_id: u32,
/// Attach to the host ring from a delivered [`FrameChannel`]. Consumes the channel: on ANY failure
/// every handle is closed (taken ones explicitly, the rest by the channel's `Drop`) and the host
/// re-delivers on the next recreate — there is nothing to poll, so failure is terminal for THIS
/// delivery (the host's `wait_for_attach` sees the status code and fails the session open). All
/// early-return paths clean up explicitly (raw-handle style, no RAII — matches the rest of this
/// driver).
pub fn from_channel(
mut channel: FrameChannel,
render_luid_low: u32,
render_luid_high: i32,
device: &ID3D11Device,
context: &ID3D11DeviceContext,
) -> windows::core::Result<Self> {
// 1. Open the host-created header (RW). Err if the host hasn't created it yet.
// SAFETY: a plain Win32 call; the name HSTRING is valid for the call (`?` returns on failure).
let map = unsafe {
OpenFileMappingW(
FILE_MAP_ALL_ACCESS.0,
false,
&HSTRING::from(header_name(target_id)),
)?
};
// SAFETY: `map` is the just-opened file mapping; mapping size_of::<SharedHeader>() bytes of it
// (the host created the mapping at >= that size). The null `view.Value` is checked below.
let ring_len = channel.ring_len;
// 1. Map the header from the duplicated section handle (ours from here on).
let map = FrameChannel::take(&mut channel.header);
// SAFETY: `map` is the live section handle the host duplicated into this process; mapping
// size_of::<SharedHeader>() bytes of it (the host created the mapping at >= that size). The null
// `view.Value` is checked below.
let view = unsafe {
// Read/write only — the host now duplicates the header handle with least access
// (`SECTION_MAP_READ | SECTION_MAP_WRITE`), so `FILE_MAP_ALL_ACCESS` would exceed the
// granted rights and fail. We read the layout + write status/publish-token fields; RW covers it.
MapViewOfFile(
map,
FILE_MAP_ALL_ACCESS,
FILE_MAP_READ | FILE_MAP_WRITE,
0,
0,
core::mem::size_of::<SharedHeader>(),
)
};
if view.Value.is_null() {
// SAFETY: `map` is the just-opened mapping handle, closed once here on the error path.
let err = windows::core::Error::from_win32();
// SAFETY: `map` is the taken section handle, closed once here on the error path (the rest of
// `channel` closes via its Drop).
unsafe {
let _ = CloseHandle(map);
}
return Err(windows::core::Error::from_win32());
return Err(err);
}
let header = view.Value.cast::<SharedHeader>();
// 2. Report our render adapter to the host immediately (lets it detect a mismatch).
// SAFETY: `header` points to the mapped, non-null host header (>= size_of::<SharedHeader>() bytes);
// these scalar writes are within it. The host opened the section with a permissive SDDL for us.
// SAFETY: `header` points to the mapped, non-null host header (>= size_of::<SharedHeader>()
// bytes); these scalar writes are within it.
unsafe {
(*header).driver_render_luid_low = render_luid_low;
(*header).driver_render_luid_high = render_luid_high;
}
// 3. The host sets magic==MAGIC only once the ring textures exist. Not ready → retry later.
// SAFETY: `header` is the mapped host header; `magic` lives within it and is read atomically
// (Acquire) to pair with the host's Release store once the ring textures are published.
let magic = unsafe {
(*(core::ptr::addr_of!((*header).magic) as *const AtomicU32)).load(Ordering::Acquire)
// 3. The host stamps magic==MAGIC BEFORE delivering the channel, and this channel's generation
// must match the header's CURRENT generation — a mismatch means the host recreated the ring
// again before we attached (a fresh delivery is on its way); drop this stale one.
// SAFETY: `header` is the mapped host header; `magic`/`generation` live within it and are read
// atomically (Acquire) to pair with the host's Release publishes.
let (magic, header_gen) = unsafe {
(
(*(core::ptr::addr_of!((*header).magic) as *const AtomicU32))
.load(Ordering::Acquire),
(*(core::ptr::addr_of!((*header).generation) as *const AtomicU32))
.load(Ordering::Acquire),
)
};
if magic != MAGIC {
// SAFETY: `header`/`map` are the live mapped view + handle; unmapped + closed once on this path.
if magic != MAGIC || header_gen != channel.generation {
dbglog!(
"[pf-vd] frame-push(driver): dropping channel delivery (magic ok: {}, channel gen {} vs header gen {header_gen})",
magic == MAGIC,
channel.generation
);
// SAFETY: `header`/`map` are the live mapped view + taken handle; unmapped + closed once on
// this path.
unsafe {
let _ = UnmapViewOfFile(MEMORY_MAPPED_VIEW_ADDRESS {
Value: header.cast(),
});
let _ = CloseHandle(map);
}
return Err(windows::core::Error::from_win32());
// E_BOUNDS — stand-in for "stale delivery"; the caller only drops the attempt.
return Err(windows::core::HRESULT(0x8000_000Bu32 as i32).into());
}
// SAFETY: `header` is the mapped host header; these scalar fields live within it.
let (generation, ring_len) =
unsafe { ((*header).generation, (*header).ring_len.min(RING_LEN)) };
// 4. Open the event (SYNCHRONIZE | EVENT_MODIFY_STATE so we can SetEvent).
// SAFETY: a plain Win32 call; the name HSTRING is valid for the call.
let event = match unsafe {
OpenEventW(
SYNCHRONIZATION_ACCESS_RIGHTS(EVENT_ACCESS),
false,
&HSTRING::from(event_name(target_id)),
)
} {
Ok(e) => e,
Err(e) => {
// SAFETY: `header`/`map` are the live mapped view + handle; unmapped + closed once here.
unsafe {
let _ = UnmapViewOfFile(MEMORY_MAPPED_VIEW_ADDRESS {
Value: header.cast(),
});
let _ = CloseHandle(map);
}
return Err(e);
}
};
// 4. The frame-ready event (duplicated with the host handle's full access, so SetEvent works).
let event = FrameChannel::take(&mut channel.event);
// 5. Open device1 + the ring textures the host created (same render adapter required).
// 5. Open device1 + the ring textures from their duplicated shared handles (same render adapter
// required). Each NT handle is closed right after the open — the COM object holds its own
// reference, and the HOST keeps the resource alive with its own handle.
let device1: ID3D11Device1 = match device.cast() {
Ok(d) => d,
Err(e) => {
// SAFETY: `header` is the mapped host header (status write within it); `event`/`map` are the
// live handles, all released once on this error path.
// SAFETY: `header` is the mapped host header (status write within it); `event`/`map` are
// the taken live handles, all released once on this error path.
unsafe {
(*header).driver_status = DRV_STATUS_NO_DEVICE1;
let _ = CloseHandle(event);
@@ -189,45 +252,45 @@ impl FramePublisher {
}
};
let mut slots = Vec::new();
for k in 0..ring_len {
let name = HSTRING::from(texture_name(target_id, generation, k));
// SAFETY: `device1` is a live ID3D11Device1; the name HSTRING is valid for the call.
// Take each texture handle one at a time (NOT the whole array up front), so an error return
// mid-loop still lets `channel`'s Drop close every not-yet-taken handle.
for value in channel.textures.iter_mut().take(ring_len as usize) {
let tex_handle = FrameChannel::take(value);
// SAFETY: `device1` is a live ID3D11Device1; `tex_handle` is the duplicated shared NT handle
// for this ring texture.
let opened: windows::core::Result<ID3D11Texture2D> =
unsafe { device1.OpenSharedResourceByName(&name, DXGI_SHARED_RESOURCE_RW) };
match opened {
unsafe { device1.OpenSharedResource1(tex_handle) };
// SAFETY: `tex_handle` is ours (taken above) and no longer needed whether the open succeeded
// (the COM object holds the resource) or failed — close it exactly once here.
unsafe {
let _ = CloseHandle(tex_handle);
}
let failed = match opened {
Ok(tex) => match tex.cast::<IDXGIKeyedMutex>() {
Ok(mutex) => slots.push(Slot { tex, mutex }),
Err(e) => {
// SAFETY: `header` is the mapped host header (status writes within it); `event`/`map`
// are the live handles, all released once on this error path.
unsafe {
(*header).driver_status = DRV_STATUS_TEX_FAIL;
(*header).driver_status_detail = e.code().0 as u32;
let _ = CloseHandle(event);
let _ = UnmapViewOfFile(MEMORY_MAPPED_VIEW_ADDRESS {
Value: header.cast(),
});
let _ = CloseHandle(map);
}
return Err(e);
Ok(mutex) => {
slots.push(Slot { tex, mutex });
None
}
Err(e) => Some(e),
},
Err(e) => {
// Most likely a render-adapter mismatch (the host made the textures on a different
// GPU than the swap-chain renders on). Tell the host so it can report it.
// SAFETY: `header` is the mapped host header (status writes within it); `event`/`map`
// are the live handles, all released once on this error path.
unsafe {
(*header).driver_status = DRV_STATUS_TEX_FAIL;
(*header).driver_status_detail = e.code().0 as u32;
let _ = CloseHandle(event);
let _ = UnmapViewOfFile(MEMORY_MAPPED_VIEW_ADDRESS {
Value: header.cast(),
});
let _ = CloseHandle(map);
}
return Err(e);
// Most likely a render-adapter mismatch (the host made the textures on a different GPU
// than the swap-chain renders on). Tell the host so it can report it.
Err(e) => Some(e),
};
if let Some(e) = failed {
// SAFETY: `header` is the mapped host header (status writes within it); `event`/`map`
// are the taken live handles, all released once on this error path (the not-yet-taken
// texture handles close via `channel`'s Drop).
unsafe {
(*header).driver_status = DRV_STATUS_TEX_FAIL;
(*header).driver_status_detail = e.code().0 as u32;
let _ = CloseHandle(event);
let _ = UnmapViewOfFile(MEMORY_MAPPED_VIEW_ADDRESS {
Value: header.cast(),
});
let _ = CloseHandle(map);
}
return Err(e);
}
}
@@ -236,7 +299,7 @@ impl FramePublisher {
(*header).driver_status = DRV_STATUS_OPENED;
}
dbglog!(
"[pf-vd] frame-push(driver): attached to host ring gen {generation} ({ring_len} slots)"
"[pf-vd] frame-push(driver): attached to host ring gen {header_gen} ({ring_len} slots, sealed channel)"
);
Ok(Self {
context: context.clone(),
@@ -248,7 +311,7 @@ impl FramePublisher {
seq: 0,
// SAFETY: `header` is the mapped host header; `dxgi_format` lives within it.
ring_format: unsafe { (*header).dxgi_format },
generation,
generation: header_gen,
mismatch_logged: false,
})
}
@@ -261,8 +324,8 @@ impl FramePublisher {
}
/// True once the host has recreated the ring (bumped the header generation) — e.g. the display's HDR
/// mode flipped, so the ring format changed (FP16 ⇄ BGRA) and the texture names now carry a new
/// generation. `run_core` drops the publisher on this so it re-attaches to the new ring.
/// mode flipped, so the ring format changed (FP16 ⇄ BGRA) and a fresh channel delivery is coming.
/// `run_core` drops the publisher on this so it re-attaches to the new ring.
pub fn is_stale(&self) -> bool {
// SAFETY: `self.header` stays mapped for the publisher's lifetime; `generation` lives within it and
// is read atomically (Acquire) to pair with the host's Release bump on a mid-session ring recreate.
@@ -338,8 +401,8 @@ impl FramePublisher {
}
.pack();
self.latest_cell().store(latest, Ordering::Release);
// SAFETY: `self.event` is the live host-created frame-ready event we opened with
// EVENT_MODIFY_STATE; signalling it wakes the host consumer.
// SAFETY: `self.event` is the live host-created frame-ready event, duplicated into
// this process with the creator's access; signalling it wakes the host consumer.
unsafe {
let _ = SetEvent(self.event);
}
@@ -357,10 +420,11 @@ impl FramePublisher {
impl Drop for FramePublisher {
fn drop(&mut self) {
// Slots FIRST (release the shared textures + keyed mutexes), THEN unmap the header, THEN the
// handles.
// handles — nothing of the channel outlives the publisher (teardown invariant,
// `design/idd-push-security.md`).
self.slots.clear();
// SAFETY: drop runs once; `self.header` (if non-null) is the live mapped view and `self.event`/
// `self.map` are the live handles this publisher opened — each unmapped/closed exactly once here.
// `self.map` are the live handles this publisher owns — each unmapped/closed exactly once here.
unsafe {
if !self.header.is_null() {
let _ = UnmapViewOfFile(MEMORY_MAPPED_VIEW_ADDRESS {