raw_access

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [v0.34.0] - 2024-11-05
 
+- Add `raw-access` options
+
 - Revert #711
 - Add `defmt` impls for `TryFromInterruptError`, riscv interrupt enums
 - Fix calculating `modifiedWriteValues` bitmasks with field arrays

src/config.rs

@@ -36,6 +36,7 @@ pub struct Config {
     pub field_names_for_enums: bool,
     pub base_address_shift: u64,
     pub html_url: Option<url::Url>,
+    pub raw_access: bool,
     /// Path to YAML file with chip-specific settings
     pub settings: Option<PathBuf>,
 }

src/generate/device.rs

@@ -76,8 +76,12 @@ pub fn render(d: &Device, config: &Config, device_x: &mut String) -> Result<Toke
 
     out.extend(quote! {
         use core::ops::Deref;
-        use core::marker::PhantomData;
     });
+    if !config.raw_access {
+        out.extend(quote! {
+            use core::marker::PhantomData;
+        });
+    }
 
     // Retaining the previous assumption
     let mut fpu_present = true;
@@ -153,7 +157,11 @@ pub fn render(d: &Device, config: &Config, device_x: &mut String) -> Result<Toke
     }
 
     let generic_file = include_str!("generic.rs");
-    let generic_reg_file = include_str!("generic_reg_vcell.rs");
+    let generic_reg_file = if config.raw_access {
+        include_str!("generic_reg_raw.rs")
+    } else {
+        include_str!("generic_reg_vcell.rs")
+    };
     let generic_atomic_file = include_str!("generic_atomic.rs");
     if config.generic_mod {
         let mut file = File::create(

src/generate/generic_reg_raw.rs

@@ -0,0 +1,301 @@
+/// This structure provides unsafe volatile access to registers.
+pub struct Reg<REG: RegisterSpec> {
+    ptr: *mut u8,
+    _marker: marker::PhantomData<REG>,
+}
+
+unsafe impl<REG: RegisterSpec> Send for Reg<REG> where REG::Ux: Send {}
+
+impl<REG: RegisterSpec> Reg<REG> {
+    #[inline(always)]
+    pub const fn new(ptr: *mut u8) -> Self {
+        Self {
+            ptr,
+            _marker: marker::PhantomData,
+        }
+    }
+    /// Returns the underlying memory address of register.
+    ///
+    /// ```ignore
+    /// let reg_ptr = periph.reg.as_ptr();
+    /// ```
+    #[inline(always)]
+    pub const fn as_ptr(&self) -> *mut REG::Ux {
+        self.ptr.cast()
+    }
+}
+
+impl<REG: Readable> Reg<REG> {
+    /// Reads the contents of a `Readable` register.
+    ///
+    /// You can read the raw contents of a register by using `bits`:
+    /// ```ignore
+    /// let bits = periph.reg.read().bits();
+    /// ```
+    /// or get the content of a particular field of a register:
+    /// ```ignore
+    /// let reader = periph.reg.read();
+    /// let bits = reader.field1().bits();
+    /// let flag = reader.field2().bit_is_set();
+    /// ```
+    #[inline(always)]
+    pub unsafe fn read(&self) -> R<REG> {
+        R {
+            bits: self.as_ptr().read_volatile(),
+            _reg: marker::PhantomData,
+        }
+    }
+}
+
+impl<REG: Resettable + Writable> Reg<REG> {
+    /// Writes the reset value to `Writable` register.
+    ///
+    /// Resets the register to its initial state.
+    #[inline(always)]
+    pub unsafe fn reset(&self) {
+        self.as_ptr().write_volatile(REG::RESET_VALUE)
+    }
+
+    /// Writes bits to a `Writable` register.
+    ///
+    /// You can write raw bits into a register:
+    /// ```ignore
+    /// periph.reg.write(|w| unsafe { w.bits(rawbits) });
+    /// ```
+    /// or write only the fields you need:
+    /// ```ignore
+    /// periph.reg.write(|w| w
+    ///     .field1().bits(newfield1bits)
+    ///     .field2().set_bit()
+    ///     .field3().variant(VARIANT)
+    /// );
+    /// ```
+    /// or an alternative way of saying the same:
+    /// ```ignore
+    /// periph.reg.write(|w| {
+    ///     w.field1().bits(newfield1bits);
+    ///     w.field2().set_bit();
+    ///     w.field3().variant(VARIANT)
+    /// });
+    /// ```
+    /// In the latter case, other fields will be set to their reset value.
+    #[inline(always)]
+    pub unsafe fn write<F>(&self, f: F) -> REG::Ux
+    where
+        F: FnOnce(&mut W<REG>) -> &mut W<REG>,
+    {
+        let value = f(&mut W {
+            bits: REG::RESET_VALUE & !REG::ONE_TO_MODIFY_FIELDS_BITMAP
+                | REG::ZERO_TO_MODIFY_FIELDS_BITMAP,
+            _reg: marker::PhantomData,
+        })
+        .bits;
+        self.as_ptr().write_volatile(value);
+        value
+    }
+
+    /// Writes bits to a `Writable` register and produce a value.
+    ///
+    /// You can write raw bits into a register:
+    /// ```ignore
+    /// periph.reg.write_and(|w| unsafe { w.bits(rawbits); });
+    /// ```
+    /// or write only the fields you need:
+    /// ```ignore
+    /// periph.reg.write_and(|w| {
+    ///     w.field1().bits(newfield1bits)
+    ///         .field2().set_bit()
+    ///         .field3().variant(VARIANT);
+    /// });
+    /// ```
+    /// or an alternative way of saying the same:
+    /// ```ignore
+    /// periph.reg.write_and(|w| {
+    ///     w.field1().bits(newfield1bits);
+    ///     w.field2().set_bit();
+    ///     w.field3().variant(VARIANT);
+    /// });
+    /// ```
+    /// In the latter case, other fields will be set to their reset value.
+    ///
+    /// Values can be returned from the closure:
+    /// ```ignore
+    /// let state = periph.reg.write_and(|w| State::set(w.field1()));
+    /// ```
+    #[inline(always)]
+    pub fn from_write<F, T>(&self, f: F) -> T
+    where
+        F: FnOnce(&mut W<REG>) -> T,
+    {
+        let mut writer = W {
+            bits: REG::RESET_VALUE & !REG::ONE_TO_MODIFY_FIELDS_BITMAP
+                | REG::ZERO_TO_MODIFY_FIELDS_BITMAP,
+            _reg: marker::PhantomData,
+        };
+        let result = f(&mut writer);
+
+        self.as_ptr().write_volatile(writer.bits);
+
+        result
+    }
+}
+
+impl<REG: Writable> Reg<REG> {
+    /// Writes 0 to a `Writable` register.
+    ///
+    /// Similar to `write`, but unused bits will contain 0.
+    ///
+    /// # Safety
+    ///
+    /// Unsafe to use with registers which don't allow to write 0.
+    #[inline(always)]
+    pub unsafe fn write_with_zero<F>(&self, f: F)
+    where
+        F: FnOnce(&mut W<REG>) -> &mut W<REG>,
+    {
+        let value = f(&mut W {
+            bits: REG::Ux::default(),
+            _reg: marker::PhantomData,
+        })
+        .bits;
+        self.as_ptr().write_volatile(value);
+        value
+    }
+
+    /// Writes 0 to a `Writable` register and produces a value.
+    ///
+    /// Similar to `write`, but unused bits will contain 0.
+    ///
+    /// # Safety
+    ///
+    /// Unsafe to use with registers which don't allow to write 0.
+    #[inline(always)]
+    pub unsafe fn from_write_with_zero<F, T>(&self, f: F) -> T
+    where
+        F: FnOnce(&mut W<REG>) -> T,
+    {
+        let mut writer = W {
+            bits: REG::Ux::default(),
+            _reg: marker::PhantomData,
+        };
+
+        let result = f(&mut writer);
+
+        self.as_ptr().write_volatile(writer.bits);
+
+        result
+    }
+}
+
+impl<REG: Readable + Writable> Reg<REG> {
+    /// Modifies the contents of the register by reading and then writing it.
+    ///
+    /// E.g. to do a read-modify-write sequence to change parts of a register:
+    /// ```ignore
+    /// periph.reg.modify(|r, w| unsafe { w.bits(
+    ///    r.bits() | 3
+    /// ) });
+    /// ```
+    /// or
+    /// ```ignore
+    /// periph.reg.modify(|_, w| w
+    ///     .field1().bits(newfield1bits)
+    ///     .field2().set_bit()
+    ///     .field3().variant(VARIANT)
+    /// );
+    /// ```
+    /// or an alternative way of saying the same:
+    /// ```ignore
+    /// periph.reg.modify(|_, w| {
+    ///     w.field1().bits(newfield1bits);
+    ///     w.field2().set_bit();
+    ///     w.field3().variant(VARIANT)
+    /// });
+    /// ```
+    /// Other fields will have the value they had before the call to `modify`.
+    #[inline(always)]
+    pub unsafe fn modify<F>(&self, f: F)
+    where
+        for<'w> F: FnOnce(&R<REG>, &'w mut W<REG>) -> &'w mut W<REG>,
+    {
+        let bits = self.as_ptr().read_volatile();
+        let value = f(
+            &R {
+                bits,
+                _reg: marker::PhantomData,
+            },
+            &mut W {
+                bits: bits & !REG::ONE_TO_MODIFY_FIELDS_BITMAP | REG::ZERO_TO_MODIFY_FIELDS_BITMAP,
+                _reg: marker::PhantomData,
+            },
+        )
+        .bits;
+        self.as_ptr().write_volatile(value);
+        value
+    }
+
+    /// Modifies the contents of the register by reading and then writing it
+    /// and produces a value.
+    ///
+    /// E.g. to do a read-modify-write sequence to change parts of a register:
+    /// ```ignore
+    /// let bits = periph.reg.modify(|r, w| {
+    ///     let new_bits = r.bits() | 3;
+    ///     unsafe {
+    ///         w.bits(new_bits);
+    ///     }
+    ///
+    ///     new_bits
+    /// });
+    /// ```
+    /// or
+    /// ```ignore
+    /// periph.reg.modify(|_, w| {
+    ///     w.field1().bits(newfield1bits)
+    ///         .field2().set_bit()
+    ///         .field3().variant(VARIANT);
+    /// });
+    /// ```
+    /// or an alternative way of saying the same:
+    /// ```ignore
+    /// periph.reg.modify(|_, w| {
+    ///     w.field1().bits(newfield1bits);
+    ///     w.field2().set_bit();
+    ///     w.field3().variant(VARIANT);
+    /// });
+    /// ```
+    /// Other fields will have the value they had before the call to `modify`.
+    #[inline(always)]
+    pub fn from_modify<F, T>(&self, f: F) -> T
+    where
+        for<'w> F: FnOnce(&R<REG>, &'w mut W<REG>) -> T,
+    {
+        let bits = self.as_ptr().read_volatile();
+
+        let mut writer = W {
+            bits: bits & !REG::ONE_TO_MODIFY_FIELDS_BITMAP | REG::ZERO_TO_MODIFY_FIELDS_BITMAP,
+            _reg: marker::PhantomData,
+        };
+
+        let result = f(
+            &R {
+                bits,
+                _reg: marker::PhantomData,
+            },
+            &mut writer,
+        );
+
+        self.as_ptr().write_volatile(writer.bits);
+
+        result
+    }
+}
+
+impl<REG: Readable> core::fmt::Debug for crate::generic::Reg<REG>
+where
+    R<REG>: core::fmt::Debug,
+{
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        unsafe { core::fmt::Debug::fmt(&self.read(), f) }
+    }
+}