Skip to main content

DBGMCU MCAL Module

Supported STM32 families: H5
Not supported: F4, F7, G4, H7, L4, U3, U5

This module provides an abstraction layer for the microcontroller debug unit (DBGMCU) of STM32 MCUs: the identification of the device and its revision, the debug in the low-power modes (the debugger stays connected in Sleep, Stop and Standby), the freezing of the peripherals while the core is halted (the watchdogs, the timers, the RTC, the I2C timeout counters, the DMA channels) and the enable of the trace pins. It is a low-level MCAL module: it owns the DBGMCU hardware, the application and the other modules never touch the registers.

The public interface (DbgMcu_Port.h, DbgMcu_Types.h) is identical for all supported families. The implementation for a family lives in its own branch (Dev/<Family> for development, Releases/<Family> for the released versions), so a module or an application written against the interface does not change when the MCU family changes.

This README is the landing page and the specification of the interface (master). The family branches contain their own README with everything that is specific to the family: the instances of the device, their settings and the status of the implementation.

Status: design. No implementation exists yet, the interface below is a proposal. Stories and branches follow.


Intent and purpose​

  • When a debugger halts the core at a breakpoint, the rest of the chip keeps running: the independent watchdog resets the MCU after a few hundred milliseconds, the PWM timers keep driving a motor with the last duty, the DMA moves data into a buffer that nobody reads. Debugging such a system is a fight with the peripherals. The freeze registers of the DBGMCU stop the selected peripherals when the core stops. The module offers them as one list (dbgMcu_Periph_t) and one call.
  • The low-power modes switch off the clocks of the debug logic, so the debugger loses the connection at the first WFI. The DBGMCU keeps the debug clocks alive in Sleep, Stop and Standby at the cost of a higher consumption; the module offers it as a development-only setting that is not left on in the released firmware (the configuration is a build option of the application).
  • The identification (DbgMcu_Get_DeviceId, DbgMcu_Get_RevisionId) tells which device and which silicon revision the firmware runs on; it is the value the tools use to recognise the chip, and an application can use it to select a workaround of an erratum by the revision.
  • The module hides the differences between the families: the names and the number of the freeze registers (per bus), the bits, the debug domain, the trace pins and the authentication state differ, the interface stays the same.

What the module is not: it does not configure the trace and the instrumentation macrocells of the core (the Core module with Dwt and Itm does), it does not open the debug port of a closed product (the debug authentication is a protocol of the product life cycle) and it does not detect the connection of a debugger for the product logic - the module only reports the state that the hardware shows.


Concept​

ItemFunctionsMeaning
IdentificationDbgMcu_Get_DeviceId, DbgMcu_Get_RevisionIdThe 12-bit device identifier and the 16-bit revision of the silicon.
Low-power debugDbgMcu_Set_LowPowerDebugDBGMCU_LP_SLEEP, DBGMCU_LP_STOP, DBGMCU_LP_STANDBY - keep the debug connection in the selected modes.
Peripheral freezeDbgMcu_Set_PeriphFreeze, DbgMcu_Get_PeriphFreezeFor a peripheral from dbgMcu_Periph_t (DBGMCU_PERIPH_IWDG, _WWDG, _TIM1, _LPTIM1, _RTC, _I2C1_TIMEOUT, _GPDMA1_CH0 ...): stop it while the core is halted, or let it run.
TraceDbgMcu_Set_TraceEnableThe trace pins and the trace clock (the debugger side of the trace; the sources are configured in the Core module).
Debug stateDbgMcu_Get_DebugStateThe state the hardware reports: the debugger connected, the authentication state of the family.

Rules:

  1. The freeze is a property of debugging: it is active only while the core is halted by the debugger; in the free running firmware without a debugger it has no effect. It is therefore safe to leave in the code, but the module keeps it as a debug build option (DbgMcu_Init applies the table of the configuration).
  2. DbgMcu_Set_PeriphFreeze of a peripheral the device does not have returns an error and writes no register.
  3. The setting of the low-power debug is a write to the register of the debug domain; the clock of the DBGMCU registers is requested from the RCC module. Leaving the low-power debug enabled raises the consumption in the Stop and the Standby (a measurement of the current in the low-power modes is done without it).
  4. The identification functions do not depend on the configuration and are usable before DbgMcu_Init.
  5. All parameters are checked before a register is written; the registers are accessed with the privilege rules of the family.

Supported families​

Every family gets its own story, its own tasks and its own branches Dev/<Family> and Releases/<Family> cut from this master.

FamilyBranchDebug unitStatus
STM32H5Dev/STM32H5DBGMCU: the device and revision identifier, the freeze registers of the AHB1 (GPDMA), APB1 (low and high), APB2 and APB3 peripherals, low-power debug, trace enable, the debug authentication stateplanned (first)
STM32U5Dev/STM32U5DBGMCUplanned
STM32U3Dev/STM32U3DBGMCUplanned
STM32G4, STM32L4Dev/STM32G4, Dev/STM32L4DBGMCU: the freeze registers of the APB1 / APB2 peripherals, the low-power debug bitsplanned
STM32H7Dev/STM32H7DBGMCU: the freeze registers of the domains, the trace and the debug clock of the domainsplanned
STM32F4, STM32F7Dev/STM32F4, Dev/STM32F7DBGMCU: DBGMCU_CR (sleep / stop / standby), APB1_FZ, APB2_FZplanned

A function without a meaning in a family stays in the interface, returns DBGMCU_REQUEST_ERROR and suppresses the unused parameters (for example a peripheral the device does not have, the authentication state on a family without it).


Public interface in short (proposal)​

GroupFunctions
Module managementDbgMcu_Get_ModuleVersion, DbgMcu_Init, DbgMcu_Deinit, DbgMcu_Task, DbgMcu_Get_DefaultConfig
IdentificationDbgMcu_Get_DeviceId, DbgMcu_Get_RevisionId
Low-power debugDbgMcu_Set_LowPowerDebug, DbgMcu_Get_LowPowerDebug
Peripheral freezeDbgMcu_Set_PeriphFreeze, DbgMcu_Get_PeriphFreeze, DbgMcu_Set_PeriphFreezeAll
Trace and stateDbgMcu_Set_TraceEnable, DbgMcu_Get_DebugState
dbgMcu_ModuleVersion_t DbgMcu_Get_ModuleVersion ( void );

dbgMcu_RequestState_t DbgMcu_Init ( const dbgMcu_Config_t * const dbgMcuConfig );
dbgMcu_RequestState_t DbgMcu_Deinit ( void );
void DbgMcu_Task ( void );
dbgMcu_RequestState_t DbgMcu_Get_DefaultConfig ( dbgMcu_Config_t * const dbgMcuConfig );

dbgMcu_RequestState_t DbgMcu_Get_DeviceId ( dbgMcu_DeviceId_t * const deviceId );
dbgMcu_RequestState_t DbgMcu_Get_RevisionId ( dbgMcu_RevisionId_t * const revisionId );

dbgMcu_RequestState_t DbgMcu_Set_LowPowerDebug ( dbgMcu_LowPower_t lowPower, dbgMcu_FunctionState_t state );
dbgMcu_RequestState_t DbgMcu_Set_PeriphFreeze ( dbgMcu_Periph_t periph, dbgMcu_FunctionState_t freeze );
dbgMcu_RequestState_t DbgMcu_Set_PeriphFreezeAll( dbgMcu_FunctionState_t freeze );
dbgMcu_RequestState_t DbgMcu_Get_DebugState ( dbgMcu_DebugState_t * const debugState );

Every function returns DBGMCU_REQUEST_OK / DBGMCU_REQUEST_ERROR and checks its parameters and the state of the module before it touches a register.

TypeMeaning
dbgMcu_Config_tLow-power debug flags, the table of the frozen peripherals, the trace enable
dbgMcu_Periph_tDBGMCU_PERIPH_* - only the freezable peripherals of the device
dbgMcu_LowPower_tDBGMCU_LP_SLEEP, DBGMCU_LP_STOP, DBGMCU_LP_STANDBY
dbgMcu_DeviceId_t, dbgMcu_RevisionId_tThe 12-bit device identifier, the 16-bit revision
dbgMcu_DebugState_tBit mask: debugger connected, authentication state of the family

Usage​

A development build: watchdogs and PWM frozen at the breakpoint, debug alive in Stop mode​

#include "DbgMcu_Port.h"

dbgMcu_Config_t dbgMcuConfig;

(void)DbgMcu_Get_DefaultConfig( &dbgMcuConfig );

dbgMcuConfig.LowPowerSleep = DBGMCU_FUNCTION_ACTIVE;
dbgMcuConfig.LowPowerStop = DBGMCU_FUNCTION_ACTIVE;
dbgMcuConfig.Freeze[ DBGMCU_PERIPH_IWDG ] = DBGMCU_FUNCTION_ACTIVE;
dbgMcuConfig.Freeze[ DBGMCU_PERIPH_WWDG ] = DBGMCU_FUNCTION_ACTIVE;
dbgMcuConfig.Freeze[ DBGMCU_PERIPH_TIM1 ] = DBGMCU_FUNCTION_ACTIVE;

(void)DbgMcu_Init( &dbgMcuConfig );

Selecting a workaround by the silicon revision​

dbgMcu_RevisionId_t revisionId = 0u;

(void)DbgMcu_Get_RevisionId( &revisionId );

if( APP_REVISION_WITH_ERRATUM == revisionId )
{
/* apply the software workaround of the erratum */
}
else
{
/* The silicon does not have the erratum */
}

Behaviour and limits​

  • Only with a debugger. The freeze acts while the core is halted; a free running firmware is not affected. A freeze that is not enough to debug the problem (a peripheral with no freeze bit) is stopped by the application at the breakpoint.
  • Consumption. The debug in the low-power modes keeps the clocks and the regulators of the debug domain on - never measure the low-power current with it enabled and do not ship the firmware with it.
  • Authentication and closed devices. On a closed product the debug port is closed; the module reports the state but does not open it.
  • Core debug. The trace sources and the instrumentation (Dwt, Itm) are configured in the Core module; this module only enables the pins and the clock on the chip side.
  • Not part of the first version: the detection of a debugger as a product feature (a halting-debug read of the core), the dual-core synchronization of the debug of the STM32H7 cores, the cross-trigger interface.

Dependencies​

  • Rcc - the clock of the DBGMCU registers
  • Core - the trace and the instrumentation sources (Dwt, Itm) that use the enabled trace pins
  • RAL (Register Abstraction Layer) - used internally to access the registers

All mandatory RCC configurations are handled internally.


Testing​

  • Unit tests (host, Unity + CMock + RegMem): the decoding of the identifier and the revision, the mapping of every peripheral to its freeze bit per family line, the rejection of the missing peripherals, the table application, the low-power flags, the debug state decoding.
  • Integration tests (target, probe-rs): the identifier and the revision read on the board match the known values, a halted core stops the frozen timer and the watchdog (the counter does not advance while halted), the debug connection survives the Stop mode with the low-power debug enabled.

Interface conventions​

The module follows the common rules of the MCAL layer, so that it behaves like the other modules:

  • Lists instead of free members. Everything that the hardware restricts (the pins, the kernel clock sources, the DMA channels, the triggers and the other selectable sources) is a typedef enum list with exactly the items that are valid for the device line; a pin is an item DBGMCU_<SIGNAL>_PIN_<INSTANCE>_P<port><pin> and there is an *_UNUSED item. A choice that is not in the list cannot be written.
  • Own peripheral only. The module calls only the registers / LL functions of its own peripheral. The clocks, the interrupts, the pins, the DMA and the EXTI lines go through the API of the Rcc, Nvic, Gpio, Gpdma and Exti modules; a missing function is added to that module, it is not bypassed.
  • Init verifies itself. DbgMcu_Init checks the result at the end; when it is not as required, the module is deinitialized and an error is returned. The waiting for the hardware is a loop on the register state with a timeout, never a blind delay.
  • Transfer modes. Where the module moves data, the POLL (served by DbgMcu_Task), ISR and DMA modes have the same configuration structure, the same request and the same callbacks (error, half transfer, transfer complete).
  • Flags and states are enums of the module (dbgMcu_FunctionState_t, dbgMcu_FlagState_t), the limits and the constants are named, there are no magic numbers in the interface.
  • Unsupported functions stay. A function without a meaning in a family keeps its signature, suppresses the unused parameters and returns DBGMCU_REQUEST_ERROR.
  • Documentation. Every function and type has a Doxygen description, the main header has the \defgroup.

Repository layout and branches​

The master holds this README and the license. The family branches (Dev/<Family>, Releases/<Family>) hold:

PathContent
README.mdREADME of the family: the instances of the device, specifics, errata, status
DbgMcu_Port.h, DbgMcu_Types.hPublic interface (identical in all families)
DbgMcu*.c, DbgMcu.hImplementation of the family
CMakeLists.txtLibrary DbgMcu_Lib of the EmBi platform
Tests/UnitTestsUnit tests (Unity + CMock + RegMem)
Tests/IntegrationTestsIntegration tests on the target (probe-rs)

A change of the public interface is made in all families.


CMake integration​

target_link_libraries( User_Lib PRIVATE DbgMcu_Lib )
  1. Link DbgMcu_Lib to your CMake library.
  2. Include DbgMcu_Port.h in your project.
  3. Configure the module as needed for your hardware.

License​

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International (CC BY-NC 4.0).

You are free to use, modify, and share this work for non-commercial purposes, provided appropriate credit is given.

See LICENSE.md for full terms or visit creativecommons.org/licenses/by-nc/4.0.


Authors​

Contributions are welcome! Please open a pull request.