Runtime ISR binding and simple public API docs for assist-debug

esp-hal/CHANGELOG.md

@@ -52,6 +52,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `UsbSerialJtag` can be created in async or blocking mode. The blocking constructor takes an optional interrupt handler argument (#1377)
 - SYSTIMER and TIMG instances can now be created in async or blocking mode (#1348)
 - Runtime ISR binding for TWAI (#1384)
+- Runtime ISR binding for assist_debug (#1395)
 
 ### Removed
 

esp-hal/src/assist_debug.rs

@@ -9,35 +9,62 @@
 //! Debug Assistant is an auxiliary module that features a set of functions to
 //! help locate bugs and issues during software debugging.
 //!
-//! While all the targets support PC logging it's API is not exposed here.
-//! Instead the ROM bootloader will always enable it and print the last seen PC
-//! (e.g. _Saved PC:0x42002ff2_). Make sure the reset was triggered by a TIMG
-//! watchdog. Not an RTC or SWD watchdog.
+//! While all the targets support program counter (PC) logging it's API is not
+//! exposed here. Instead the ROM bootloader will always enable it and print the
+//! last seen PC (e.g. _Saved PC:0x42002ff2_). Make sure the reset was triggered
+//! by a TIMG watchdog. Not an RTC or SWD watchdog.
 //!
 //! ⚠️ Bus write access logging is not available via this API. ⚠️
+//!
+//! ⚠️ This driver has only blocking API. ⚠️
 
 use crate::{
+    interrupt::InterruptHandler,
     peripheral::{Peripheral, PeripheralRef},
     peripherals::ASSIST_DEBUG,
 };
 
+/// The debug assist driver instance.
 pub struct DebugAssist<'d> {
     debug_assist: PeripheralRef<'d, ASSIST_DEBUG>,
 }
 
 impl<'d> DebugAssist<'d> {
-    pub fn new(debug_assist: impl Peripheral<P = ASSIST_DEBUG> + 'd) -> Self {
+    /// Create a new instance in [crate::Blocking] mode.
+    ///
+    /// Optionally an interrupt handler can be bound.
+    pub fn new(
+        debug_assist: impl Peripheral<P = ASSIST_DEBUG> + 'd,
+        interrupt: Option<InterruptHandler>,
+    ) -> Self {
         crate::into_ref!(debug_assist);
 
         // NOTE: We should enable the debug assist, however, it's always enabled in ROM
         //       code already.
 
+        if let Some(interrupt) = interrupt {
+            unsafe {
+                crate::interrupt::bind_interrupt(
+                    crate::peripherals::Interrupt::ASSIST_DEBUG,
+                    interrupt.handler(),
+                );
+                crate::interrupt::enable(
+                    crate::peripherals::Interrupt::ASSIST_DEBUG,
+                    interrupt.priority(),
+                )
+                .unwrap();
+            }
+        }
+
         DebugAssist { debug_assist }
     }
 }
 
 #[cfg(assist_debug_sp_monitor)]
 impl<'d> DebugAssist<'d> {
+    /// Enable SP monitoring on main core. When the SP exceeds the
+    /// `lower_bound` or `upper_bound` treshold, the module will record the PC
+    /// pointer and generate an interrupt.
     pub fn enable_sp_monitor(&mut self, lower_bound: u32, upper_bound: u32) {
         self.debug_assist
             .core_0_sp_min()
@@ -64,6 +91,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Disable SP monitoring on main core.
     pub fn disable_sp_monitor(&mut self) {
         self.debug_assist.core_0_intr_ena().modify(|_, w| {
             w.core_0_sp_spill_max_intr_ena()
@@ -80,6 +108,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Clear SP monitoring interrupt on main core.
     pub fn clear_sp_monitor_interrupt(&mut self) {
         self.debug_assist.core_0_intr_clr().write(|w| {
             w.core_0_sp_spill_max_clr()
@@ -89,6 +118,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Check, if SP monitoring interrupt is set on main core.
     pub fn is_sp_monitor_interrupt_set(&self) -> bool {
         self.debug_assist
             .core_0_intr_raw()
@@ -103,6 +133,7 @@ impl<'d> DebugAssist<'d> {
                 .bit_is_set()
     }
 
+    /// Get SP monitoring PC value on main core.
     pub fn get_sp_monitor_pc(&self) -> u32 {
         self.debug_assist
             .core_0_sp_pc()
@@ -114,6 +145,9 @@ impl<'d> DebugAssist<'d> {
 
 #[cfg(all(assist_debug_sp_monitor, multi_core))]
 impl<'d> DebugAssist<'d> {
+    /// Enable SP monitoring on secondondary core. When the SP exceeds the
+    /// `lower_bound` or `upper_bound` treshold, the module will record the PC
+    /// pointer and generate an interrupt.
     pub fn enable_core1_sp_monitor(&mut self, lower_bound: u32, upper_bound: u32) {
         self.debug_assist
             .core_1_sp_min
@@ -140,6 +174,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Disable SP monitoring on secondary core.
     pub fn disable_core1_sp_monitor(&mut self) {
         self.debug_assist.core_1_intr_ena.modify(|_, w| {
             w.core_1_sp_spill_max_intr_ena()
@@ -156,6 +191,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Clear SP monitoring interrupt on secondary core.
     pub fn clear_core1_sp_monitor_interrupt(&mut self) {
         self.debug_assist.core_1_intr_clr.write(|w| {
             w.core_1_sp_spill_max_clr()
@@ -165,6 +201,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Check, if SP monitoring interrupt is set on secondary core.
     pub fn is_core1_sp_monitor_interrupt_set(&self) -> bool {
         self.debug_assist
             .core_1_intr_raw
@@ -179,13 +216,18 @@ impl<'d> DebugAssist<'d> {
                 .bit_is_set()
     }
 
+    /// Get SP monitoring PC value on secondary core.
     pub fn get_core1_sp_monitor_pc(&self) -> u32 {
         self.debug_assist.core_1_sp_pc.read().core_1_sp_pc().bits()
     }
 }
 
 #[cfg(assist_debug_region_monitor)]
 impl<'d> DebugAssist<'d> {
+    /// Enable region monitoring of read/write performed by the main CPU in a
+    /// certain memory region0. Whenever the bus reads or writes in the
+    /// specified memory region, an interrupt will be triggered. Two memory
+    /// regions (region0, region1) can be monitored at the same time.
     pub fn enable_region0_monitor(
         &mut self,
         lower_bound: u32,
@@ -218,6 +260,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Disable region0 monitoring on main core.
     pub fn disable_region0_monitor(&mut self) {
         self.debug_assist.core_0_intr_ena().modify(|_, w| {
             w.core_0_area_dram0_0_rd_intr_ena()
@@ -234,6 +277,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Clear region0 monitoring interrupt on main core.
     pub fn clear_region0_monitor_interrupt(&mut self) {
         self.debug_assist.core_0_intr_clr().write(|w| {
             w.core_0_area_dram0_0_rd_clr()
@@ -243,6 +287,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Check, if region0 monitoring interrupt is set on main core.
     pub fn is_region0_monitor_interrupt_set(&self) -> bool {
         self.debug_assist
             .core_0_intr_raw()
@@ -257,6 +302,9 @@ impl<'d> DebugAssist<'d> {
                 .bit_is_set()
     }
 
+    /// Enable region monitoring of read/write performed by the main CPU in a
+    /// certain memory region1. Whenever the bus reads or writes in the
+    /// specified memory region, an interrupt will be triggered.
     pub fn enable_region1_monitor(
         &mut self,
         lower_bound: u32,
@@ -289,6 +337,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Disable region1 monitoring on main core.
     pub fn disable_region1_monitor(&mut self) {
         self.debug_assist.core_0_intr_ena().modify(|_, w| {
             w.core_0_area_dram0_1_rd_intr_ena()
@@ -305,6 +354,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Clear region1 monitoring interrupt on main core.
     pub fn clear_region1_monitor_interrupt(&mut self) {
         self.debug_assist.core_0_intr_clr().write(|w| {
             w.core_0_area_dram0_1_rd_clr()
@@ -314,6 +364,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Check, if region1 monitoring interrupt is set on main core.
     pub fn is_region1_monitor_interrupt_set(&self) -> bool {
         self.debug_assist
             .core_0_intr_raw()
@@ -328,6 +379,7 @@ impl<'d> DebugAssist<'d> {
                 .bit_is_set()
     }
 
+    /// Get region monotoring PC value on main core.
     pub fn get_region_monitor_pc(&self) -> u32 {
         self.debug_assist
             .core_0_area_pc()
@@ -339,6 +391,9 @@ impl<'d> DebugAssist<'d> {
 
 #[cfg(all(assist_debug_region_monitor, multi_core))]
 impl<'d> DebugAssist<'d> {
+    /// Enable region monitoring of read/write performed by the secondary CPU in
+    /// a certain memory region0. Whenever the bus reads or writes in the
+    /// specified memory region, an interrupt will be triggered.
     pub fn enable_core1_region0_monitor(
         &mut self,
         lower_bound: u32,
@@ -371,6 +426,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Disable region0 monitoring on secondary core.
     pub fn disable_core1_region0_monitor(&mut self) {
         self.debug_assist.core_1_intr_ena().modify(|_, w| {
             w.core_1_area_dram0_0_rd_intr_ena()
@@ -387,6 +443,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Clear region0 monitoring interrupt on secondary core.
     pub fn clear_core1_region0_monitor_interrupt(&mut self) {
         self.debug_assist.core_1_intr_clr().write(|w| {
             w.core_1_area_dram0_0_rd_clr()
@@ -396,6 +453,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Check, if region0 monitoring interrupt is set on secondary core.
     pub fn is_core1_region0_monitor_interrupt_set(&self) -> bool {
         self.debug_assist
             .core_1_intr_raw()
@@ -410,6 +468,9 @@ impl<'d> DebugAssist<'d> {
                 .bit_is_set()
     }
 
+    /// Enable region monitoring of read/write performed by the secondary CPU in
+    /// a certain memory region1. Whenever the bus reads or writes in the
+    /// specified memory region, an interrupt will be triggered.
     pub fn enable_core1_region1_monitor(
         &mut self,
         lower_bound: u32,
@@ -442,6 +503,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Disable region1 monitoring on secondary core.
     pub fn disable_core1_region1_monitor(&mut self) {
         self.debug_assist.core_1_intr_ena().modify(|_, w| {
             w.core_1_area_dram0_1_rd_intr_ena()
@@ -458,6 +520,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Clear region1 monitoring interrupt on secondary core.
     pub fn clear_core1_region1_monitor_interrupt(&mut self) {
         self.debug_assist.core_1_intr_clr().write(|w| {
             w.core_1_area_dram0_1_rd_clr()
@@ -467,6 +530,7 @@ impl<'d> DebugAssist<'d> {
         });
     }
 
+    /// Check, if region1 monitoring interrupt is set on secondary core.
     pub fn is_core1_region1_monitor_interrupt_set(&self) -> bool {
         self.debug_assist
             .core_1_intr_raw()
@@ -481,6 +545,7 @@ impl<'d> DebugAssist<'d> {
                 .bit_is_set()
     }
 
+    /// Get region monotoring PC value on secondary core.
     pub fn get_core1_region_monitor_pc(&self) -> u32 {
         self.debug_assist
             .core_1_area_pc()

examples/src/bin/debug_assist.rs

@@ -14,8 +14,7 @@ use esp_backtrace as _;
 use esp_hal::{
     assist_debug::DebugAssist,
     clock::ClockControl,
-    interrupt::{self, Priority},
-    peripherals::{Interrupt, Peripherals},
+    peripherals::Peripherals,
     prelude::*,
 };
 use esp_println::println;
@@ -28,7 +27,7 @@ fn main() -> ! {
     let system = peripherals.SYSTEM.split();
     let _clocks = ClockControl::boot_defaults(system.clock_control).freeze();
 
-    let mut da = DebugAssist::new(peripherals.ASSIST_DEBUG);
+    let mut da = DebugAssist::new(peripherals.ASSIST_DEBUG, Some(interrupt_handler));
 
     cfg_if::cfg_if! {
         if #[cfg(not(feature = "esp32s3"))] {
@@ -68,8 +67,6 @@ fn main() -> ! {
 
     critical_section::with(|cs| DA.borrow_ref_mut(cs).replace(da));
 
-    interrupt::enable(Interrupt::ASSIST_DEBUG, Priority::Priority3).unwrap();
-
     eat_up_stack(0);
 
     loop {}
@@ -81,8 +78,8 @@ fn eat_up_stack(v: u32) {
     eat_up_stack(v + 1);
 }
 
-#[interrupt]
-fn ASSIST_DEBUG() {
+#[handler(priority = esp_hal::interrupt::Priority::min())]
+fn interrupt_handler() {
     critical_section::with(|cs| {
         println!("\n\nDEBUG_ASSIST interrupt");
         let mut da = DA.borrow_ref_mut(cs);