From f9e81a55f2391096016ea4f3aeceda6c3a57dd7a Mon Sep 17 00:00:00 2001
From: Viktor Sonesten <viktor.sonesten@grepit.se>
Date: Thu, 13 Jan 2022 17:34:03 +0100
Subject: [PATCH] itm: bitfield LSR; add has_software_lock, locked; amend docs

Related to #392.
---
 CHANGELOG.md          |  2 +-
 src/peripheral/itm.rs | 33 ++++++++++++++++++++++++++++++---
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b6d405c6..0a91cb8b 100644
--- a/CHANGELOG.md
+++ b/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).
 
diff --git a/src/peripheral/itm.rs b/src/peripheral/itm.rs
index 7d121506..53d1e822 100644
--- a/src/peripheral/itm.rs
+++ b/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,7 +220,7 @@ 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) {
@@ -217,6 +228,22 @@ impl ITM {
         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]