1.. _debugmon:
2
3Cortex-M Debug Monitor
4######################
5
6Monitor mode debugging is a Cortex-M feature, that provides a non-halting approach to
7debugging. With this it's possible to continue the execution of high-priority interrupts,
8even when waiting on a breakpoint.
9This strategy makes it possible to debug time-sensitive software, that would
10otherwise crash when the core halts (e.g. applications that need to keep
11communication links alive).
12
13Zephyr provides support for enabling and configuring the Debug Monitor exception.
14It also contains a ready implementation of the interrupt, which can be used with
15SEGGER J-Link debuggers.
16
17Configuration
18*************
19
20Configure this module using the following options.
21
22* :kconfig:option:`CONFIG_CORTEX_M_DEBUG_MONITOR_HOOK`: enable the module. This option, by itself,
23  requires an implementation of debug monitor interrupt that will be executed
24  every time the program enters a breakpoint.
25
26With a SEGGER debug probe, it's possible to use a ready, SEGGER-provided implementation
27of the interrupt.
28
29* :kconfig:option:`CONFIG_SEGGER_DEBUGMON`: enables SEGGER debug monitor interrupt. Can be
30  used with SEGGER JLinkGDBServer and a SEGGER debug probe.
31
32
33Usage
34*****
35
36When monitor mode debugging is enabled, entering a breakpoint will not halt the
37processor, but rather generate an interrupt with ISR implemented under
38``z_arm_debug_monitor`` symbol.  :kconfig:option:`CONFIG_CORTEX_M_DEBUG_MONITOR_HOOK` config configures this interrupt
39to be the lowest available priority, which will allow other interrupts to execute
40while processor spins on a breakpoint.
41
42Using SEGGER-provided ISR
43=========================
44
45The ready implementation provided with :kconfig:option:`CONFIG_SEGGER_DEBUGMON` provides functionality
46required to debug in the monitor mode using regular GDB commands.
47Steps to configure SEGGER debug monitor:
48
491. Build a sample with :kconfig:option:`CONFIG_CORTEX_M_DEBUG_MONITOR_HOOK`` and :kconfig:option:`CONFIG_SEGGER_DEBUGMON`
50   configs enabled.
51
522. Attach JLink GDB server to the target.
53   Example linux command: ``JLinkGDBServerCLExe -device <device> -if swd``.
54
553. Connect to the server with your GDB installation.
56   Example linux command: ``arm-none-eabi-gdb --ex="file build/zephyr.elf" --ex="target remote localhost:2331"``.
57
584. Enable monitor mode debugging in GDB using command: ``monitor exec SetMonModeDebug=1``.
59
60After these steps use regular gdb commands to debug your program.
61
62
63Using other custom ISR
64======================
65In order to provide a custom debug monitor interrupt, override ``z_arm_debug_monitor``
66symbol. Additionally, manual configuration of some registers is required
67(see :ref:`debug monitor sample<debugmon-sample>`).
68