cortex-m tidyups

cortex-m/src/asm.rs

@@ -464,10 +464,13 @@ core::arch::global_asm!(
 );
 
 /// This instruction moves one Register to a Coprocessor Register.
+///
 /// This function generates inline assembly and needs the instruction configuration
 /// during compilation time (i.e. as `const`).
+///
 /// The values of the constants required by this function should be defined by
 /// the coprocessor's reference manual.
+///
 ///  - CP: The coprocessor's index.
 ///  - OP1: First optional operation for the coprocessor.
 ///  - CRN: Coprocessor register N.
@@ -493,10 +496,13 @@ pub unsafe fn mcr<const CP: u32, const OP1: u32, const CRN: u32, const CRM: u32,
 }
 
 /// This instruction moves one Coprocessor Register to a Register.
+///
 /// This function generates inline assembly and needs the instruction configuration
 /// during compilation time (i.e. as `const`).
+///
 /// The values of the constants required by this function should be defined by
 /// the coprocessor's reference manual.
+///
 ///  - CP: The coprocessor's index.
 ///  - OP1: First optional operation for the coprocessor.
 ///  - CRN: Coprocessor register N.
@@ -525,10 +531,13 @@ pub unsafe fn mrc<const CP: u32, const OP1: u32, const CRN: u32, const CRM: u32,
 }
 
 /// This instruction moves two Registers to Coprocessor Registers.
+///
 /// This function generates inline assembly and needs the instruction configuration
 /// during compilation time (i.e. as `const`).
+///
 /// The values of the constants required by this function should be defined by
 /// the coprocessor's reference manual.
+///
 ///  - CP: The coprocessor's index.
 ///  - OP1: First optional operation for the coprocessor.
 ///  - CRM: Coprocessor register M.
@@ -549,10 +558,13 @@ pub unsafe fn mcrr<const CP: u32, const OP1: u32, const CRM: u32>(a: u32, b: u32
 }
 
 /// This instruction moves two Coprocessor Registers to Registers.
+///
 /// This function generates inline assembly and needs the instruction configuration
 /// during compilation time (i.e. as `const`).
+///
 /// The values of the constants required by this function should be defined by
 /// the coprocessor's reference manual.
+///
 ///  - CP: The coprocessor's index.
 ///  - OP1: First optional operation for the coprocessor.
 ///  - CRM: Coprocessor register M.

cortex-m/src/cmse.rs

@@ -4,7 +4,7 @@
 //! Extensions.
 //! Most of this implementation is directly inspired by the "Armv8-M Security Extensions:
 //! Requirements on Development Tools" document available here:
-//! https://developer.arm.com/docs/ecm0359818/latest
+//! <https://developer.arm.com/docs/ecm0359818/latest>
 //!
 //! Please note that the TT instructions support as described part 4 of the document linked above is
 //! not part of CMSE but is still present in this module. The TT instructions return the

cortex-m/src/lib.rs

@@ -49,6 +49,12 @@
 //! [Linker-Plugin LTO]: https://doc.rust-lang.org/stable/rustc/linker-plugin-lto.html
 //! [rust-lang/rust#75940]: https://github.com/rust-lang/rust/issues/75940
 //!
+//! ## `secure-mode`
+//!
+//! Adds extra non-secure peripherals to the `Peripherals` struct. Only set when your
+//! processor is running in Secure mode, and you need to control operations in nonsecure
+//! mode (e.g. to bootload some nonsecure firmware).
+//!
 //! ## `inline-asm`
 //!
 //! This feature is deprecated.

cortex-m/src/peripheral/mod.rs

@@ -37,7 +37,7 @@
 //! let cyccnt = DWT::cycle_count();
 //! ```
 //!
-//! The singleton property can be *unsafely* bypassed using the `ptr` static method which is
+//! The singleton property can be *unsafely* bypassed using the `PTR` associated const which is
 //! available on all the peripheral types. This method is a useful building block for implementing
 //! safe higher level abstractions.
 //!

cortex-m/src/peripheral/sau.rs

@@ -161,11 +161,13 @@ impl SAU {
 
     /// Disable the SAU and mark all memory Non-Secure (ALLNS mode).
     ///
-    /// Sets `CTRL.ALLNS = 1`, `CTRL.ENABLE = 0`. When the SAU is disabled with ALLNS set, the
-    /// entire address space is treated as Non-Secure (subject to any IDAU overrides). Use this
-    /// when running entirely in Non-Secure mode with no security boundary enforcement.
+    /// Sets `CTRL.ALLNS = 1`, `CTRL.ENABLE = 0`. When the SAU is disabled with
+    /// ALLNS set, the entire address space is treated as Non-Secure (subject to
+    /// any IDAU overrides). Use this when running entirely in Non-Secure mode
+    /// with no security boundary enforcement.
     ///
-    /// To re-enable security boundaries, call [`init`] or [`enable`] after programming regions.
+    /// To re-enable security boundaries, call [`init`](Self::init) or
+    /// [`enable`](Self::enable) after programming regions.
     #[inline]
     pub fn disable_allns(&mut self) {
         unsafe {
@@ -175,21 +177,27 @@ impl SAU {
 
     /// Program SAU regions and enable the SAU.
     ///
-    /// This is a convenience wrapper around [`set_region`] + [`enable`]:
+    /// This is a convenience wrapper around [`set_region`](Self::set_region) +
+    /// [`enable`](Self::enable):
+    ///
     /// 1. Disables the SAU temporarily.
     /// 2. Programs all regions from `regions`.
     /// 3. Re-enables the SAU.
     ///
-    /// Memory not covered by any enabled region is treated as Secure once the SAU is enabled.
+    /// Memory not covered by any enabled region is treated as Secure once the
+    /// SAU is enabled.
     ///
-    /// To also enable the `SecureFault` exception so TrustZone violations surface as a dedicated
-    /// fault rather than escalating to `HardFault`, call
-    /// `scb.enable(cortex_m::peripheral::scb::Exception::SecureFault)` after this.
+    /// To also enable the `SecureFault` exception so TrustZone violations
+    /// surface as a dedicated fault rather than escalating to `HardFault`, call
+    /// `scb.enable(cortex_m::peripheral::scb::Exception::SecureFault)` after
+    /// this.
     ///
     /// # Errors
-    /// Returns [`SauError::TooManyRegions`] if `regions.len()` exceeds the number of regions
-    /// implemented in hardware (see [`region_numbers`]). Returns other [`SauError`] variants if
-    /// any region descriptor has a misaligned base or limit address.
+    /// Returns [`SauError::TooManyRegions`] if `regions.len()` exceeds the
+    /// number of regions implemented in hardware (see
+    /// [`region_numbers`](Self::region_numbers). Returns other [`SauError`]
+    /// variants if any region descriptor has a misaligned base or limit
+    /// address.
     ///
     /// On error the SAU is left disabled (in the state set at step 1 above).
     #[inline]

cortex-m/src/register/primask.rs

@@ -40,7 +40,7 @@ pub fn read() -> Primask {
 }
 
 /// Reads the entire PRIMASK register
-/// Note that bits [31:1] are reserved and UNK (Unknown)
+/// Note that bits `[31:1]` are reserved and UNK (Unknown)
 #[inline]
 #[asm_cfg(cortex_m)]
 pub fn read_raw() -> u32 {
@@ -50,7 +50,8 @@ pub fn read_raw() -> u32 {
 }
 
 /// Writes the entire PRIMASK register
-/// Note that bits [31:1] are reserved and SBZP (Should-Be-Zero-or-Preserved)
+///
+/// Note that bits `[31:1]` are reserved and SBZP (Should-Be-Zero-or-Preserved)
 ///
 /// # Safety
 ///