STM32CubeWBA: Real Time Debug

1. Introduction

The STM32CubeWBA firmware provides real time (RT) debug capabilities. The RTDebug module is GPIO based for a minimal impact on real time timings. The module is present, by default, into the application framework.

While enabling the RTDebug module in the application, the user can choose, among a various list of signals, the ones it wants to monitor and which GPIO is assigned for output.

Some default configurations are already present and can ease debugging related to System, BLE, MAC or Coexistence behaviors.

2. Concepts

2.1. RTDebug general overview

The main objectives of the RTDebug system module is to provide a GPIO probing solution:

RTDebug example

• With accurate timings.
• That is not disturbing real time nor modifying critical executions.
• Easy to configure (debug signal selection and GPIO assignation).
• With low footprint, both memory and execution time.

Regarding these objectives, the RTDebug module is configured at compile time. Only the necessary code is compiled, according to the user configuration.

The debug signals are present, by default, in the system framework (modules and interfaces) and the Link Layer libraries (BLE, 802.15.4 and concurrent modes). If these signals are always present, the effective use is conditioned to the user configuration.

• If the signal is selected, it triggers the associated GPIO.
• If the signal is not selected at compile time, it does not trigger any GPIO.

2.2. RTDebug files

The RTDebug files are present in two distinct repositories

The first part comes under the System/Modules repository and must not be modified by any user.

The second part is located in the System/Config repository and can be modified to suit user needs.

Real Time Debug architecture

2.3. RTDebug configuration

RTDebug module configuration is done at compilation time. This aims to determined which signal is activated and to which GPIOs it is attributed. This relies on definitions, enumerations and hash tables.

Three steps are required to understand / to perform the RTDebug configuration:

• Signal definition
• Debug tables
• Association between Signal and GPIO

2.3.1. Signal definition

The signal definition takes place in the debug_signals.h header file. The signals are defined in their respective enumeration types, for instance, the system signal enumeration is named system_debug_signal_t and contains all the system relative signals. This enumeration is important since it is used later for signal activation or deactivation as a parameter. There are also dedicated enumeration for link layer or application.

The enumeration rt_debug_signal_t is the global signal definition. In this enumeration. you can find all the signals available on your target - It englobes all the possible signals.

Each signal has a specific function and is design to address a specific use case. Some are dedicated to link layer activities some others are dedicated to system events and some can be used to describe application steps.

2.3.2. Debug tables

The debug tables are like hash-tables. They are used to associate a specific signal to a given index inside the rt_debug_signal_t enumeration. They are located in the local_debug_tables.h header file.

2.3.3. Signal/GPIO association

The debug_config.h is the most useful file for RTDebug configuration since it handles the association configuration between a signal and its dedicated GPIO but also manage the activation or not of a signal.

debug config schema

Therefore, if you want to configure a signal activation and/or its GPIO output, you must focus on this file configuration.

2.4. RTDebug Signals

The list of signals handled by the module can not fully stand here. However, you must know that there are 3 main types of signals:

• System signals:
  • Signals dedicated to system tracking
  • I.e.: Low power activation, low power desactivation, system clock configuration, etc.
• Link layer signals:
  • Signals dedicated to link layer activities tracking
  • I.e.: HCI write done, Physical calibration, scheduler event registration, etc.
• Application signals:
  • Signals that can be implemented and managed by the user.
  • I.e: Application initialization, etc.

Information

The full list of signals is available inside the debug_signals.h header file under the rt_debug_signal_t enumeration.

2.5. RTDebug used pins

The RTDebug is designed to be compliant with any version of the WBA product. Therefore, its pin configuration is restricted and is as follows:

GPIO Group	Pin Number
GPIO A	5					12					15
GPIO B	3			4			8			12			15

2.6. RTDebug default configurations

To ease user debug experience, dedicated teams have already worked on default configuration for specific use cases (BLE, MAC, Coex, system, etc.).

Addressed configurations can deal with most common behaviors issues and give a quick overview of the situation.

The default configuration are present at the start of the debug_config.h file and just require the user to activate them.

Information

Configurations are not simultaneously compatible. Since the number of GPIOs is limited, activation of multiple configuration could give non reliable results.

3. Interfaces

The RTDebug is quite minimalist since for the main part it is already implemented inside the application, the system calls, the link layer routines, etc.

However, user could want to integrate some probing on his own work and could necessitate to access signal activation and deactivation functions.

The available function are the following:

RT_DEBUG_GPIO_Init
Description Initialize the RTDebug module and required GPIOs. Syntax void RT_DEBUG_GPIO_Init(void); Parameters None Return Value None

APP_DEBUG_SIGNAL_SET
Description Set the given application signal - The signal must be activated and present in the different configuration files. Syntax void APP_DEBUG_SIGNAL_SET(app_debug_signal_t signal); Parameters [in] signal Type: app_debug_signal_t Description: Application signal to be set. Return Value None

APP_DEBUG_SIGNAL_RESET
Description Reset the given application signal - The signal must be activated and present in the different configuration files. Syntax void APP_DEBUG_SIGNAL_RESET(app_debug_signal_t signal); Parameters [in] signal Type: app_debug_signal_t Description: Application signal to be reset. Return Value None

APP_DEBUG_SIGNAL_TOGGLE
Description Toggle the given application signal - The signal must be activated and present in the different configuration files. Syntax void APP_DEBUG_SIGNAL_TOGGLE(app_debug_signal_t signal); Parameters [in] signal Type: app_debug_signal_t Description: Application signal to be reset. Return Value None

4. How to

The following chapters explain how to configure and use the Real Time Debug.

4.1. Default configuration activation

First you must enable the RTDebug and to do so, you must indicate that you want to use the RTDebug in your app_conf.h file.

RTDebug enabled

The next step is to activate the desiderated configuration in the debug_config.h file.

RTDebug default configuration

Depending on your need, you can select one of each already prepared configuration.

If you want to check which signal is selected, you can search for USE_RT_DEBUG_CONFIGURATION_SYSTEM for system configuration for instance. You should come to the selected signal list like below:

RTDebug system configuration

Following these steps, you should be able to see your signals coming to life on your GPIO signal analyzer.

4.2. Create your own configuration

If the default configurations do not fit your needs, you can actually create your own configuration by modifying the debug_config.h.

You can inspire yourself with the example of the default configurations and create a custom define that handles the signal activation of your need:

RTDebug custom configuration

If you do not want to bother with a custom configuration, you can actually select, one by one, your signals - up to 8 - to fit your needs. You only have to activate their usage and set an adequate GPIO output. This is still done in the debug_config.h file. Like this:

RTDebug signal enabled

Keep in mind that there are only 8 GPIOs available and no signal should share its GPIOs output with another one since the behavior of the GPIO could be misleading.

If two signals have the same output GPIO set, the result might be unpredictable, beware.

Information

You can also create your own configuration based on your own signals.

Important

Unused signals are commonly associated with GPIO A #0. Be sure to replace default GPIO before using theses signals.

4.3. Integrate application signals

The RTDebug is not only designed for intern signals tracking but can also be used for user application step tracking.

In fact, user can create his own signals to mark the begin and the end of a step in his code.

To achieve such a thing, user can create his signal(s) to be managed by the RTDebug and, in a later time, use the RTDebug to keep track the evolution of the application process.

4.3.1. Signal creation

The signal creation is the first step to perform. It impacts two files app_debug.h and app_debug_signal_def.h.

App_debug.h

If you want to integrate your signal, first you need to define it inside the app_debug.h file:

RTDebug custom signal creation

App_debug_signal_def.h

Then, you need to declare your new signal in the rt_debug_signal_t which can be achieved only adding your signal in the app_debug_signal_def.h:

RTDebug custom signal creation 2

4.3.2. Hash table update

After the signal is being created, inside the app_debug.h file, you can fulfil the hash table with your new signal.

App_debug.h

RTDebug hash table

4.3.3. Debug config update

The last step consist to add the enable flag to the debug_config.h file and update the general table.

Debug_config.h

This way you can select the associated GPIO and enable or disable your signal in a later time:

RTDebug signal configuration flag

And update the general table with:

RTDebug general table custom

You can now call the public API and set, reset and toggle your own signals in your application.