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:
@@ -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> {}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user