PlayStation: bypass HidSharp overlapped I/O on Windows via direct WriteFile

Field reports against the USB transport showed lightbar updating once and
then freezing. Root cause: HidSharp's HidStream opens its handle with
FILE_FLAG_OVERLAPPED and runs an asynchronous WriteFile + GetOverlappedResult
dance. The PlayStation HID minidriver returns failure on the second and
subsequent overlapped writes, which HidSharp surfaces as IOException — the
queue's catch handler then suspends the queue.

Reintroduced HidRawWriter (synchronous Win32 WriteFile on a separate kernel
handle, BOOL return — never throws). On Windows, both DS4 and DS5 queues
prefer the raw writer; on non-Windows the queues fall back to HidStream.Write
since HidSharp's macOS/Linux paths don't share the overlapped Windows code.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: logicallysynced

RGB.NET.Devices.PlayStation/DualSense/DualSenseUpdateQueue.cs

@@ -65,6 +65,7 @@ internal sealed class DualSenseUpdateQueue : UpdateQueue
     #region Properties & Fields
 
     private readonly HidStream _stream;
+    private readonly HidRawWriter? _rawWriter;
     private readonly PlayStationTransport _transport;
     private readonly byte[] _buffer;
     private readonly string _devicePath;
@@ -77,10 +78,11 @@ internal sealed class DualSenseUpdateQueue : UpdateQueue
 
     #region Constructors
 
-    public DualSenseUpdateQueue(IDeviceUpdateTrigger trigger, HidStream stream, PlayStationTransport transport, string devicePath)
+    public DualSenseUpdateQueue(IDeviceUpdateTrigger trigger, HidStream stream, HidRawWriter? rawWriter, PlayStationTransport transport, string devicePath)
         : base(trigger)
     {
         _stream = stream;
+        _rawWriter = rawWriter;
         _transport = transport;
         _devicePath = devicePath ?? string.Empty;
         _buffer = new byte[transport == PlayStationTransport.Bluetooth ? 78 : 63];
@@ -132,21 +134,39 @@ protected override bool Update(ReadOnlySpan<(object key, Color color)> dataSet)
         // the lightbar at black instead of leaving uninitialised state.
         if (!gotLightbar) lightbar = new Color(0, 0, 0);
 
+        bool ok;
+        lock (_writeLock)
+        {
+            Array.Clear(_buffer, 0, _buffer.Length);
+            BuildReport(lightbar, playerLedBits);
+            ok = WriteBuffer();
+        }
+
+        if (!ok)
+        {
+            Trace.WriteLine("[RGB.NET.PlayStation] DualSense write failed, suspending queue.");
+            _disposed = true;
+            return false;
+        }
+        _firstReport = false;
+        return true;
+    }
+
+    // See DualShock4UpdateQueue.WriteBuffer for the rationale behind preferring
+    // HidRawWriter over HidStream.Write on Windows.
+    private bool WriteBuffer()
+    {
+        if (_rawWriter != null)
+            return _rawWriter.TryWrite(_buffer);
+
         try
         {
-            lock (_writeLock)
-            {
-                Array.Clear(_buffer, 0, _buffer.Length);
-                BuildReport(lightbar, playerLedBits);
-                _stream.Write(_buffer);
-            }
-            _firstReport = false;
+            _stream.Write(_buffer);
             return true;
         }
         catch (Exception ex)
         {
-            Trace.WriteLine($"[RGB.NET.PlayStation] DualSense write failed, suspending queue: {ex.Message}");
-            _disposed = true;
+            Trace.WriteLine($"[RGB.NET.PlayStation] DualSense stream write threw: {ex.Message}");
             return false;
         }
     }
@@ -246,18 +266,13 @@ public void Shutdown(bool sendOffFrame = true)
         if (_disposed) return;
         _disposed = true;
         if (!sendOffFrame) return;
-        try
-        {
-            lock (_writeLock)
-            {
-                Array.Clear(_buffer, 0, _buffer.Length);
-                BuildReport(new Color(0, 0, 0), 0);
-                _stream.Write(_buffer);
-            }
-        }
-        catch
+        // Best-effort — WriteBuffer returns false silently if the handle has
+        // already been invalidated.
+        lock (_writeLock)
         {
-            // Best-effort.
+            Array.Clear(_buffer, 0, _buffer.Length);
+            BuildReport(new Color(0, 0, 0), 0);
+            WriteBuffer();
         }
     }
 

RGB.NET.Devices.PlayStation/DualShock4/DualShock4UpdateQueue.cs

@@ -34,6 +34,7 @@ internal sealed class DualShock4UpdateQueue : UpdateQueue
     #region Properties & Fields
 
     private readonly HidStream _stream;
+    private readonly HidRawWriter? _rawWriter;
     private readonly PlayStationTransport _transport;
     private readonly byte[] _buffer;
     private readonly string _devicePath;
@@ -44,10 +45,11 @@ internal sealed class DualShock4UpdateQueue : UpdateQueue
 
     #region Constructors
 
-    public DualShock4UpdateQueue(IDeviceUpdateTrigger trigger, HidStream stream, PlayStationTransport transport, string devicePath)
+    public DualShock4UpdateQueue(IDeviceUpdateTrigger trigger, HidStream stream, HidRawWriter? rawWriter, PlayStationTransport transport, string devicePath)
         : base(trigger)
     {
         _stream = stream;
+        _rawWriter = rawWriter;
         _transport = transport;
         _devicePath = devicePath ?? string.Empty;
         _buffer = new byte[transport == PlayStationTransport.Bluetooth ? 78 : 32];
@@ -76,26 +78,46 @@ protected override bool Update(ReadOnlySpan<(object key, Color color)> dataSet)
         // colour we see — RGB.NET commits the painted colour for that LED each tick.
         Color color = dataSet[0].color;
 
-        try
+        bool ok;
+        lock (_writeLock)
         {
-            lock (_writeLock)
-            {
-                Array.Clear(_buffer, 0, _buffer.Length);
-                BuildReport(color);
-                _stream.Write(_buffer);
-            }
-            return true;
+            Array.Clear(_buffer, 0, _buffer.Length);
+            BuildReport(color);
+            ok = WriteBuffer();
         }
-        catch (Exception ex)
+
+        if (!ok)
         {
             // Device went away mid-write or another tool grabbed exclusive access.
             // Suspend the queue so the next 30Hz tick short-circuits at the
             // `if (_disposed)` gate. The provider's hot-plug Reconcile will
             // RemoveDevice us shortly.
-            Trace.WriteLine($"[RGB.NET.PlayStation] DualShock4 write failed, suspending queue: {ex.Message}");
+            Trace.WriteLine("[RGB.NET.PlayStation] DualShock4 write failed, suspending queue.");
             _disposed = true;
             return false;
         }
+        return true;
+    }
+
+    // On Windows, prefer HidRawWriter (synchronous Win32 WriteFile) — HidSharp's
+    // overlapped HidStream.Write fails on the second and subsequent USB writes
+    // against the PlayStation HID minidriver. On non-Windows or if HidRawWriter
+    // failed to open, fall back to HidStream.Write.
+    private bool WriteBuffer()
+    {
+        if (_rawWriter != null)
+            return _rawWriter.TryWrite(_buffer);
+
+        try
+        {
+            _stream.Write(_buffer);
+            return true;
+        }
+        catch (Exception ex)
+        {
+            Trace.WriteLine($"[RGB.NET.PlayStation] DualShock4 stream write threw: {ex.Message}");
+            return false;
+        }
     }
 
     private void BuildReport(Color color)
@@ -169,19 +191,14 @@ public void Shutdown(bool sendOffFrame = true)
         // last colour after we tear down. The controller's firmware restores
         // the OS-driven indicator (e.g. player number) shortly after we stop
         // sending reports anyway, but explicit black avoids the visible "stuck
-        // on last colour" beat between shutdown and firmware reset.
-        try
-        {
-            lock (_writeLock)
-            {
-                Array.Clear(_buffer, 0, _buffer.Length);
-                BuildReport(new Color(0, 0, 0));
-                _stream.Write(_buffer);
-            }
-        }
-        catch
+        // on last colour" beat between shutdown and firmware reset. Best-effort —
+        // WriteBuffer returns false silently if the handle has already been
+        // invalidated.
+        lock (_writeLock)
         {
-            // Best-effort — handle may already have been invalidated.
+            Array.Clear(_buffer, 0, _buffer.Length);
+            BuildReport(new Color(0, 0, 0));
+            WriteBuffer();
         }
     }
 

RGB.NET.Devices.PlayStation/Generic/HidRawWriter.cs

@@ -0,0 +1,141 @@
+using System;
+using System.IO;
+using System.Runtime.InteropServices;
+using Microsoft.Win32.SafeHandles;
+
+namespace RGB.NET.Devices.PlayStation;
+
+// Direct Win32 WriteFile wrapper for HID output reports — Windows only.
+//
+// On Windows, HidSharp's HidStream opens its underlying handle with
+// FILE_FLAG_OVERLAPPED and runs an asynchronous WriteFile + GetOverlappedResult
+// dance internally. Field reports against the PlayStation USB minidriver
+// indicate that overlapped path can return non-ERROR_IO_PENDING failure on the
+// second and subsequent writes, which HidSharp surfaces as IOException — and
+// our queue's catch handler turns the exception into a queue suspension. End
+// result: lightbar updates once, then freezes.
+//
+// To sidestep the overlapped I/O path entirely we open OUR OWN kernel handle
+// alongside HidSharp's, with shared read/write access and dwFlagsAndAttributes
+// = 0 (synchronous I/O, no overlapped). WriteFile then returns BOOL — false on
+// failure surfaces as a return value, no exception. HidSharp keeps the handle
+// it opens during TryOpen (still useful for detecting exclusive-access
+// conflicts via DS4Windows / reWASD at open time). Two handles per controller
+// is fine — Sony HID gamepads accept shared writes by default on Windows.
+//
+// The class is intentionally minimal: open with shared read/write access,
+// write a buffer, dispose. No reads, no overlapped I/O, no internal locking
+// (the caller's UpdateQueue already serialises via its own write lock).
+//
+// Windows-only at runtime — the kernel32 P/Invokes will throw
+// DllNotFoundException on Linux/macOS. Construction is gated on
+// OperatingSystem.IsWindows() inside the provider; the class itself is not
+// platform-attributed to keep call sites readable across the assembly.
+internal sealed class HidRawWriter : IDisposable
+{
+    #region Win32
+
+    [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
+    private static extern SafeFileHandle CreateFileW(
+        string lpFileName,
+        uint dwDesiredAccess,
+        uint dwShareMode,
+        IntPtr lpSecurityAttributes,
+        uint dwCreationDisposition,
+        uint dwFlagsAndAttributes,
+        IntPtr hTemplateFile);
+
+    [DllImport("kernel32.dll", SetLastError = true)]
+    [return: MarshalAs(UnmanagedType.Bool)]
+    private static extern bool WriteFile(
+        SafeFileHandle hFile,
+        byte[] lpBuffer,
+        uint nNumberOfBytesToWrite,
+        out uint lpNumberOfBytesWritten,
+        IntPtr lpOverlapped);
+
+    private const uint GENERIC_WRITE = 0x40000000;
+    private const uint FILE_SHARE_READ = 0x00000001;
+    private const uint FILE_SHARE_WRITE = 0x00000002;
+    private const uint OPEN_EXISTING = 3;
+
+    #endregion
+
+    #region Properties & Fields
+
+    private readonly SafeFileHandle _handle;
+    private volatile bool _closed;
+
+    #endregion
+
+    #region Constructors
+
+    public HidRawWriter(string devicePath)
+    {
+        if (string.IsNullOrEmpty(devicePath))
+            throw new ArgumentException("Device path is required.", nameof(devicePath));
+
+        // Shared read/write so we coexist with HidSharp's handle and any other
+        // app (Steam Input, game native lighting, etc.) that may also be
+        // opening the device. dwFlagsAndAttributes = 0 → synchronous I/O. We
+        // don't need overlapped — writes are small (78 bytes max) and our
+        // caller is already on a dedicated trigger thread.
+        _handle = CreateFileW(
+            devicePath,
+            GENERIC_WRITE,
+            FILE_SHARE_READ | FILE_SHARE_WRITE,
+            IntPtr.Zero,
+            OPEN_EXISTING,
+            0,
+            IntPtr.Zero);
+
+        if (_handle == null || _handle.IsInvalid)
+        {
+            int err = Marshal.GetLastWin32Error();
+            throw new IOException($"CreateFile failed for HID device ({devicePath}). Win32 error: {err}");
+        }
+    }
+
+    #endregion
+
+    #region Methods
+
+    /// <summary>
+    /// True on successful write, false on any failure (handle invalid, device
+    /// gone, partial write, etc.). Never throws — that's the whole point.
+    /// Caller checks the return value and decides whether to log, retry, or
+    /// self-suspend the queue.
+    ///
+    /// The first byte of <paramref name="buffer"/> must be the HID report ID,
+    /// matching the convention HidStream.Write uses.
+    /// </summary>
+    public bool TryWrite(byte[] buffer)
+    {
+        if (_closed) return false;
+        if (buffer == null || buffer.Length == 0) return false;
+
+        try
+        {
+            if (_handle == null || _handle.IsClosed || _handle.IsInvalid)
+                return false;
+
+            return WriteFile(_handle, buffer, (uint)buffer.Length, out _, IntPtr.Zero);
+        }
+        catch
+        {
+            // P/Invoke marshalling could conceivably fault on a pathological
+            // handle state; swallow and report failure rather than escape the
+            // contract.
+            return false;
+        }
+    }
+
+    public void Dispose()
+    {
+        if (_closed) return;
+        _closed = true;
+        try { _handle?.Dispose(); } catch { /* best effort */ }
+    }
+
+    #endregion
+}