Allow updating single fields of InterrupterRegisterSet (#142)

It is necessary to be able to update ERDP without confusing the controller (in QEMU, at least).

The description of ERSTBA which is on page 428 of xHCI specification 1.2 says:

> Writing this register sets the Event Ring State Machine:EREP Advancement to the Start state.

Thus, writing to any register in an interrupter register set in the old API made an event ring reset.

Author: Demindiro

src/registers/mod.rs

@@ -5,8 +5,6 @@ use accessor::Mapper;
 
 pub use capability::Capability;
 pub use operational::{Operational, PortRegisterSet};
-#[allow(deprecated)]
-pub use runtime::InterruptRegisterSet;
 pub use runtime::InterrupterRegisterSet;
 pub use runtime::Runtime;
 
@@ -32,8 +30,7 @@ where
     /// Runtime Registers
     pub runtime: Runtime<M>,
     /// Interrupter Register Set Array
-    // TODO rename to interrupter_register_set
-    pub interrupt_register_set: array::ReadWrite<InterrupterRegisterSet, M>,
+    pub interrupter_register_set: InterrupterRegisterSet<M>,
 }
 impl<M> Registers<M>
 where
@@ -83,7 +80,7 @@ where
             Operational::new(mmio_base, capability.caplength.read_volatile(), &mapper);
         let port_register_set = PortRegisterSet::new(mmio_base, &capability, mapper.clone());
         let runtime = Runtime::new(mmio_base, capability.rtsoff.read_volatile(), mapper.clone());
-        let interrupt_register_set =
+        let interrupter_register_set =
             InterrupterRegisterSet::new(mmio_base, capability.rtsoff.read_volatile(), mapper);
 
         Self {
@@ -92,7 +89,7 @@ where
             operational,
             port_register_set,
             runtime,
-            interrupt_register_set,
+            interrupter_register_set,
         }
     }
 }

src/registers/runtime.rs

@@ -1,11 +1,15 @@
 //! Host Controller Runtime Registers.
 
 use super::capability::RuntimeRegisterSpaceOffset;
-use accessor::array;
+use accessor::marker::AccessorTypeSpecifier;
+use accessor::marker::ReadOnly;
+use accessor::marker::ReadWrite;
+use accessor::marker::Readable;
 use accessor::single;
 use accessor::Mapper;
 use core::convert::TryFrom;
 use core::convert::TryInto;
+use core::marker::PhantomData;
 
 /// Runtime Registers
 ///
@@ -57,21 +61,19 @@ impl_debug_from_methods! {
 
 /// Interrupter Register Set
 #[repr(C)]
-#[derive(Copy, Clone, Debug)]
-pub struct InterrupterRegisterSet {
-    /// Interrupter Management Register
-    pub iman: InterrupterManagementRegister,
-    /// Interrupter Moderation Register
-    pub imod: InterrupterModerationRegister,
-    /// Event Ring Segment Table Size Register
-    pub erstsz: EventRingSegmentTableSizeRegister,
-    _rsvd: u32,
-    /// Event Ring Segment Table Base Address Register
-    pub erstba: EventRingSegmentTableBaseAddressRegister,
-    /// Event Ring Dequeue Pointer Register
-    pub erdp: EventRingDequeuePointerRegister,
+#[derive(Debug)]
+pub struct InterrupterRegisterSet<M>
+where
+    M: Mapper + Clone,
+{
+    base: usize,
+    mapper: M,
 }
-impl InterrupterRegisterSet {
+
+impl<M> InterrupterRegisterSet<M>
+where
+    M: Mapper + Clone,
+{
     /// Creates an accessor to the Interrupter Register Set.
     ///
     /// # Safety
@@ -83,19 +85,79 @@ impl InterrupterRegisterSet {
     ///
     /// This method panics if the base address of the Interrupter Register Sets is not aligned
     /// correctly.
-    pub unsafe fn new<M>(
-        mmio_base: usize,
-        rtoff: RuntimeRegisterSpaceOffset,
-        mapper: M,
-    ) -> array::ReadWrite<Self, M>
-    where
-        M: Mapper,
-    {
-        const NUM_INTERRUPT_REGISTER_SET: usize = 1024;
-
+    pub unsafe fn new(mmio_base: usize, rtoff: RuntimeRegisterSpaceOffset, mapper: M) -> Self {
         let base = mmio_base + usize::try_from(rtoff.get()).unwrap() + 0x20;
+        assert!(base % 0x20 == 0, "base is not aligned");
+
+        Self { base, mapper }
+    }
+
+    /// Returns a handler for an interrupter.
+    ///
+    /// # Panics
+    ///
+    /// This method panics if `index > 1023`.
+    pub fn interrupter(&self, index: usize) -> Interrupter<'_, M, ReadOnly> {
+        unsafe { Interrupter::new(self.base, index, self.mapper.clone()) }
+    }
+
+    /// Returns a mutable handler for an interrupter.
+    ///
+    /// # Panics
+    ///
+    /// This method panics if `index > 1023`.
+    pub fn interrupter_mut(&mut self, index: usize) -> Interrupter<'_, M, ReadWrite> {
+        unsafe { Interrupter::new(self.base, index, self.mapper.clone()) }
+    }
+}
+
+/// Interrupter
+#[derive(Debug)]
+pub struct Interrupter<'a, M, A>
+where
+    M: Mapper + Clone,
+    A: AccessorTypeSpecifier + Readable,
+{
+    /// Interrupter Management Register
+    pub iman: single::Generic<InterrupterManagementRegister, M, A>,
+    /// Interrupter Moderation Register
+    pub imod: single::Generic<InterrupterModerationRegister, M, A>,
+    /// Event Ring Segment Table Size Register
+    pub erstsz: single::Generic<EventRingSegmentTableSizeRegister, M, A>,
+    /// Event Ring Segment Table Base Address Register
+    pub erstba: single::Generic<EventRingSegmentTableBaseAddressRegister, M, A>,
+    /// Event Ring Dequeue Pointer Register
+    pub erdp: single::Generic<EventRingDequeuePointerRegister, M, A>,
+    // Tie the lifetime of this Interrupter to the parent InterrupterRegisterSet.
+    // This prevents multiple mutable handlers from being created.
+    _marker: PhantomData<&'a InterrupterRegisterSet<M>>,
+}
 
-        array::ReadWrite::new(base, NUM_INTERRUPT_REGISTER_SET, mapper)
+impl<M, A> Interrupter<'_, M, A>
+where
+    M: Mapper + Clone,
+    A: AccessorTypeSpecifier + Readable,
+{
+    /// Creates an accessor to an interrupter.
+    ///
+    /// # Safety
+    ///
+    /// Any mutable handlers to this Interrupter must be unique.
+    ///
+    /// # Panics
+    ///
+    /// This method panics if `index > 1023`.
+    unsafe fn new(interrupter_register_set_base: usize, index: usize, mapper: M) -> Self {
+        assert!(index < 1024, "index out of range");
+        let base = interrupter_register_set_base + index * 0x20;
+        Self {
+            iman: single::Generic::new(base, mapper.clone()),
+            imod: single::Generic::new(base + 0x4, mapper.clone()),
+            erstsz: single::Generic::new(base + 0x8, mapper.clone()),
+            erstba: single::Generic::new(base + 0x10, mapper.clone()),
+            erdp: single::Generic::new(base + 0x18, mapper),
+            _marker: PhantomData,
+        }
     }
 }
 
@@ -220,7 +282,3 @@ impl_debug_from_methods! {
         event_ring_dequeue_pointer
     }
 }
-
-/// Alias for [`InterrupterRegisterSet`].
-#[deprecated(note = "use InterrupterRegisterSet instead (note 'er')")]
-pub type InterruptRegisterSet = InterrupterRegisterSet;