USB: P0 fix — document unsafe Send/Sync soundness invariant for Xhci

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
This commit is contained in:
Red Bear OS
2026-07-08 00:03:01 +03:00
parent f646e42e55
commit 9f61f7bf68
+9
View File
@@ -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> {}