From 7d9eb7d204602f25040814f3b168cddf82b66142 Mon Sep 17 00:00:00 2001
From: Taeseung Sohn <paulsohn@outlook.kr>
Date: Tue, 5 Dec 2023 08:43:46 +0900
Subject: [PATCH] PR for Misc Issue #164 (#167)

* Clarify the exact behavior of RW1C setters

* rename doorbell::Register to Doorbell

* mark cap registers as read-only.

* convention fix

Co-authored-by: Hiroki Tokunaga <tokusan441@gmail.com>

---------

Co-authored-by: Hiroki Tokunaga <tokusan441@gmail.com>
---
 src/registers/capability.rs | 22 +++++++++++-----------
 src/registers/doorbell.rs   | 10 +++++++---
 src/registers/mod.rs        |  4 ++--
 3 files changed, 20 insertions(+), 16 deletions(-)

diff --git a/src/registers/capability.rs b/src/registers/capability.rs
index 8b5cc72..323863c 100644
--- a/src/registers/capability.rs
+++ b/src/registers/capability.rs
@@ -11,25 +11,25 @@ where
     M: Mapper + Clone,
 {
     /// Capability Registers Length
-    pub caplength: single::ReadWrite<CapabilityRegistersLength, M>,
+    pub caplength: single::ReadOnly<CapabilityRegistersLength, M>,
     /// Host Controller Interface Version Number
-    pub hciversion: single::ReadWrite<InterfaceVersionNumber, M>,
+    pub hciversion: single::ReadOnly<InterfaceVersionNumber, M>,
     /// Structural Parameters 1
-    pub hcsparams1: single::ReadWrite<StructuralParameters1, M>,
+    pub hcsparams1: single::ReadOnly<StructuralParameters1, M>,
     /// Structural Parameters 2
-    pub hcsparams2: single::ReadWrite<StructuralParameters2, M>,
+    pub hcsparams2: single::ReadOnly<StructuralParameters2, M>,
     /// Structural Parameters 3
-    pub hcsparams3: single::ReadWrite<StructuralParameters3, M>,
+    pub hcsparams3: single::ReadOnly<StructuralParameters3, M>,
     /// Capability Parameters 1
-    pub hccparams1: single::ReadWrite<CapabilityParameters1, M>,
+    pub hccparams1: single::ReadOnly<CapabilityParameters1, M>,
     /// Doorbell Offset
-    pub dboff: single::ReadWrite<DoorbellOffset, M>,
+    pub dboff: single::ReadOnly<DoorbellOffset, M>,
     /// Runtime Register Space Offset
-    pub rtsoff: single::ReadWrite<RuntimeRegisterSpaceOffset, M>,
+    pub rtsoff: single::ReadOnly<RuntimeRegisterSpaceOffset, M>,
     /// Capability Parameters 2
-    pub hccparams2: single::ReadWrite<CapabilityParameters2, M>,
+    pub hccparams2: single::ReadOnly<CapabilityParameters2, M>,
     /// Virtualization Based Trusted IO Register Space Offset
-    pub vtiosoff: single::ReadWrite<VirtualizationBasedTrustedIoRegisterSpaceOffset, M>,
+    pub vtiosoff: single::ReadOnly<VirtualizationBasedTrustedIoRegisterSpaceOffset, M>,
 }
 impl<M> Capability<M>
 where
@@ -51,7 +51,7 @@ where
     {
         macro_rules! m {
             ($offset:expr) => {
-                single::ReadWrite::new(mmio_base + $offset, mapper.clone())
+                single::ReadOnly::new(mmio_base + $offset, mapper.clone())
             };
         }
 
diff --git a/src/registers/doorbell.rs b/src/registers/doorbell.rs
index 989f3e1..0406013 100644
--- a/src/registers/doorbell.rs
+++ b/src/registers/doorbell.rs
@@ -5,11 +5,15 @@ use accessor::array;
 use accessor::Mapper;
 use core::{convert::TryFrom, fmt};
 
+/// A type alias to [`Doorbell`] register for backward compability.
+#[deprecated = "Use `Doorbell` instead of `Register`."]
+pub type Register = Doorbell;
+
 /// The element of the Doorbell Array.
 #[repr(transparent)]
 #[derive(Copy, Clone, Default)]
-pub struct Register(u32);
-impl Register {
+pub struct Doorbell(u32);
+impl Doorbell {
     /// Creates a new accessor to the Doorbell Array.
     ///
     /// # Safety
@@ -44,7 +48,7 @@ impl Register {
     rw_field!(0..=7, doorbell_target, "Doorbell Target", u8);
     rw_field!(16..=31, doorbell_stream_id, "Doorbell Stream ID", u16);
 }
-impl fmt::Debug for Register {
+impl fmt::Debug for Doorbell {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         f.debug_struct("doorbell::Register")
             .field("doorbell_target", &self.doorbell_target())
diff --git a/src/registers/mod.rs b/src/registers/mod.rs
index d98507b..a34472c 100644
--- a/src/registers/mod.rs
+++ b/src/registers/mod.rs
@@ -22,7 +22,7 @@ where
     /// Host Controller Capability Register
     pub capability: Capability<M>,
     /// Doorbell Array
-    pub doorbell: array::ReadWrite<doorbell::Register, M>,
+    pub doorbell: array::ReadWrite<doorbell::Doorbell, M>,
     /// Host Controller Operational Register
     pub operational: Operational<M>,
     /// Port Register Set Array
@@ -75,7 +75,7 @@ where
     /// ```
     pub unsafe fn new(mmio_base: usize, mapper: M) -> Self {
         let capability = Capability::new(mmio_base, &mapper);
-        let doorbell = doorbell::Register::new(mmio_base, &capability, mapper.clone());
+        let doorbell = doorbell::Doorbell::new(mmio_base, &capability, mapper.clone());
         let operational =
             Operational::new(mmio_base, capability.caplength.read_volatile(), &mapper);
         let port_register_set = PortRegisterSet::new(mmio_base, &capability, mapper.clone());