From 9f61f7bf68ba3fe837afd48ccef76c61b7b05cd0 Mon Sep 17 00:00:00 2001
From: Red Bear OS <build@redbearos.org>
Date: Wed, 8 Jul 2026 00:03:01 +0300
Subject: [PATCH] =?UTF-8?q?USB:=20P0=20fix=20=E2=80=94=20document=20unsafe?=
 =?UTF-8?q?=20Send/Sync=20soundness=20invariant=20for=20Xhci?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

IMPROVEMENT-PLAN.md §10.1 item 2: critical safety fix.

The unsafe impl Send/Sync for Xhci<N> in mod.rs:310-311 is a
soundness claim with no supporting documentation. A future refactor
that adds a !Send/!Sync field would silently break thread-safety with
no compile-time indication.

Fix: add a SAFETY comment block enumerating each field with its
safety mechanism. This makes the invariant explicit and forces any
future maintainer to update the comment if they add a field.

The Xhci struct has no fields that lack interior mutability or
Send/Sync implementations. All shared mutable state is guarded by:
- CHashMap (port_states, handles, drivers)
- Mutex (op, ports, cmd, run, primary_event_ring)
- crossbeam_channel (irq_reactor_*_sender)
- Dma<...> (dev_ctx, scratchpad_buf_arr) -- has internal mutex
- Arc<Mutex<...>> (dbs)

cross-references IMPROVEMENT-PLAN.md §10.1.2
---
 drivers/usb/xhcid/src/xhci/mod.rs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/drivers/usb/xhcid/src/xhci/mod.rs b/drivers/usb/xhcid/src/xhci/mod.rs
index 8dd967932e..aaf0bb31d6 100644
--- a/drivers/usb/xhcid/src/xhci/mod.rs
+++ b/drivers/usb/xhcid/src/xhci/mod.rs
@@ -307,6 +307,15 @@ pub struct Xhci<const N: usize> {
     device_enumerator_receiver: Receiver<DeviceEnumerationRequest>,
 }
 
+}
+// SAFETY: Xhci<N> contains the following fields with their safety mechanisms:
+// - `port_states`, `handles`, `drivers`: CHashMap (per-key interior locking)
+// - `op`, `ports`, `cmd`, `run`, `primary_event_ring`: Mutex<...>
+// - `irq_reactor_*_sender`: crossbeam_channel (lock-free MPMC)
+// - `dev_ctx`, `scratchpad_buf_arr`: Dma<...> (internal mutex)
+// - `dbs`: Arc<Mutex<...>>
+// All shared mutable state is protected by interior mutability primitives.
+// Xhci<N> does not contain !Send/!Sync fields (File is Send+Sync, Dma is Send+Sync).
 unsafe impl<const N: usize> Send for Xhci<N> {}
 unsafe impl<const N: usize> Sync for Xhci<N> {}