itm: bitfield LSR; add has_software_lock, locked; amend docs

Related to rust-embedded#392.

CHANGELOG.md

@@ -12,7 +12,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   Also fixes `VectActive::from` to take a `u16` and subtract `16` for
   `VectActive::Interrupt`s to match `SBC::vect_active()` (#373).
 - DWT: add `configure` API for address, cycle count comparison (#342, #367).
-- ITM: add `configure` API; `lock`, `unlock`, and `busy` functions (#342, #383).
+- ITM: add `configure` API; `lock`, `unlock`, `busy`, `locked` functions (#342, #383).
 - TPIU: add API for *Formatter and Flush Control* (FFCR) and *Selected Pin Control* (SPPR) registers (#342).
 - Add `std` and `serde` crate features for improved host-side ITM decode functionality when working with the downstream `itm`, `cargo-rtic-scope` crates (#363, #366).
 

src/peripheral/itm.rs

@@ -34,7 +34,7 @@ pub struct RegisterBlock {
     /// Lock Access
     pub lar: WO<u32>,
     /// Lock Status
-    pub lsr: RO<u32>,
+    pub lsr: RO<Lsr>,
 }
 
 bitfield! {
@@ -53,6 +53,15 @@ bitfield! {
     busy, _: 23;
 }
 
+bitfield! {
+    /// Software Lock Status Register
+    #[repr(C)]
+    #[derive(Copy, Clone)]
+    pub struct Lsr(u32);
+    sli, _: 0;
+    slk, _: 1;
+}
+
 /// Stimulus Port
 pub struct Stim {
     register: UnsafeCell<u32>,
@@ -200,7 +209,9 @@ pub enum ITMConfigurationError {
 }
 
 impl ITM {
-    /// Removes the software lock on the [`ITM`]. Must be called before any other [`ITM`] functions.
+    /// Removes the software lock on the [`ITM`]. Must be called before
+    /// any mutating [`ITM`] functions if a software lock mechanism is
+    /// implemented. See [`has_software_lock`].
     ///
     /// See (coresight, B2.3.10).
     #[inline]
@@ -209,14 +220,30 @@ impl ITM {
         unsafe { self.lar.write(0xC5AC_CE55) }
     }
 
-    /// Adds the software lock on the [`ITM`]. Should be called after any other [`ITM`] functions.
+    /// Adds the software lock on the [`ITM`]. Should be called after any other mutating [`ITM`] functions.
     ///
     /// See (coresight, B2.3.10).
     pub fn lock(&mut self) {
         // NOTE(unsafe) atomic write to a stateless, write-only register
         unsafe { self.lar.write(0) }
     }
 
+    /// Checks whether the target implements the software lock
+    /// mechanism. If `true`, [`unlock`] must be called before any other
+    /// mutating [`ITM`] functions.
+    ///
+    /// See (coresight, B2.3.10).
+    pub fn has_software_lock(&self) -> bool {
+        self.lsr.read().sli()
+    }
+
+    /// Checks whether the peripheral is locked.
+    ///
+    /// See (coresight, B2.3.10).
+    pub fn locked(&self) -> bool {
+        self.lsr.read().slk()
+    }
+
     /// Indicates whether the [`ITM`] is currently processing events.
     /// Returns `true` if [`ITM`] events are present and are being drained.
     #[inline]