STM32CubeWBA: Trace management - Log module

Coming soon

Information

This page is not yet finished but will be soon.

1. Introduction

The log module is a module that provides a logging mechanism for embedded systems. It allows developers to print logs with different verbose levels and regions, making it easier to debug and troubleshoot issues in your project.

The module is highly customizable and can be configured to meet the specific user needs.

It relies on the stm32_adv_trace.c/.h utility module. The user can therefore configure the output medium this way - by configuring the utility module.

2. Concepts

The Log module relies on different main concepts:

Log module configuration

Configuration of the future logs regarding verbose levels, regions and colors.

Verbose levels are used to categorize logs based on their importance, while regions are used to separate logs into different places. The module also defines color codes that can be used to highlight logs from different regions.

Timestamp registration

Allows the user to provide a function to add a timestamp for the logs output.

Printing macros

Log printings macros specific to each region. They are defined to ease user interface.

2.1. Log module configuration

User can configure the module at three different levels:

• Verbosity
• Regions setting
• Colors

Their configuration takes places in the log_module.h header file.

2.1.1. Verbosity

Verbosity indicates which kind of information the log module shall outputs. User can select among a list of verbosity levels to select which information should or should not be output on the logging medium.

The different levels of verbosity are the followings

LOG_VERBOSE_INFO

LOG_VERBOSE_ERROR

LOG_VERBOSE_WARNING

LOG_VERBOSE_DEBUG

LOG_VERBOSE_ALL_LOGS

Verbosity levels are available in the log_module.h file under the Log_Verbose_Level_t enumeration. User can easily add his own verbosity levels setting a new value in this enumeration.

Information

Selecting a verbosity higher level will automatically enable the lower logging verbose levels. For instance, selecting LOG_VERBOSE_DEBUG will enable LOG_VERBOSE_WARNING, LOG_VERBOSE_ERROR and LOG_VERBOSE_INFO

2.1.2. Regions

Another key point of the log module regards the regions. Regions are used to separate the logs into different places.

For instance,

If user have a Task 1 and a Task 2. Both of them having Info and Debug logs. By using them as such, i.e. with the same regions, you'll print the logs of the 2 tasks as long as the verbose is Info or Debug. If user create a region for Task 1 and another for Task 2, he can split the logs between them, and, if needed, only print the Debug logs for Task 1 only (i.e. Task 1 logs for Info and Debug).

The current regions presents are the followings

LOG_REGION_BLE

LOG_REGION_SYSTEM

LOG_REGION_APP

LOG_REGION_LINKLAYER

LOG_REGION_MAC

LOG_REGION_ZIGBEE

LOG_REGION_THREAD

LOG_REGION_RTOS

The user can add its own regions but must NOT add a value to them. The log module handles the mask on its own.

2.2. Timestamp registration

The timestamp management allows the user to add a timestamp buffer inside the frame to output.

User shall follow two steps

• Create a callback function that deals with the time stamp insertion. Such as this:

void CallBack_TimeStamp( char * pData, uint16_t iSizeMax, uint16_t * piSize );

Where:

pData => The location where insert the new TimeStamp.

iSizeMax => The maximum size for the TimeStamp insert.

piSize => Pointer on the size of the TimeStamp insert.

• Register his callback with the help of the register function .

2.3. Printing macros

Printing macros are the preferred interfaces to use the log module, they are designed to ease user experience with abstraction and enhance the code clarity.

They manage the verbose level and the region selection to avoid any misutilization.

Each region has its own set of dedicated macros, for instance, regarding the LOG_REGION_BLE user will be able to use:

• LOG_INFO_BLE(...) to drop information logging
• LOG_ERROR_BLE(...) to drop error logging
• LOG_WARNING_BLE(...) to drop warning logging
• LOG_DEBUG_BLE(...) to drop debug logging

Nonetheless, user can create its own set of macros if needed to handle new region declaration or new verbose levels.

3. Interface

3.1. Functions

Log_Module_Init
Description Initializes the log module with the given configuration. Syntax void Log_Module_Init(Log_Module_t log_configuration); Parameters [in] log_configuration Type: Log_Module_t Description: The configuration of the log module. Return Value None

Log_Module_DeInit
Description Deinitializes the log module. Syntax void Log_Module_DeInit(void); Parameters None Return Value None

Log_Module_Set_Verbose_Level
Description Sets the verbose level of the log. Syntax void Log_Module_Set_Verbose_Level(Log_Verbose_Level_t new_verbose_level); Parameters [in] new_verbose_level Type: Log_Verbose_Level_t Description: The new verbose level to be set. Return Value None

Log_Module_Set_Region
Description Replaces the current region mask to use and sets only the given region. Syntax void Log_Module_Set_Region(Log_Region_t new_region); Parameters [in] new_region Type: Log_Region_t Description: The new region to use. Return Value None

Log_Module_Add_Region
Description Adds the given region to the current region mask. Syntax void Log_Module_Add_Region(Log_Region_t new_region); Parameters [in] new_region Type: Log_Region_t Description: The new region to use, alongside the others. Return Value None

Log_Module_Enable_All_Regions
Description Enables all the regions. Syntax void Log_Module_Enable_All_Regions(void); Parameters None Return Value None

Log_Module_Set_Color
Description Sets/Replaces the color for a region. Syntax void Log_Module_Set_Color(Log_Region_t eRegion, Log_Color_t eNewColor); Parameters [in] eRegion Type: Log_Region_t Description: The region where to apply the color. [in] eNewColor Type: Log_Color_t Description: The color to apply to the selected region. Return Value None

Log_Module_RegisterTimeStampFunction
Description Registers a callback function to insert the 'TimeStamp' to the log. Syntax void Log_Module_RegisterTimeStampFunction(CallBack_TimeStamp * pCallbackFunc); Parameters [in] pCallbackFunc Type: CallBack_TimeStamp * Description: Callback function to insert Time Stamp. Return Value None

Log_Module_Print

Description Prints a log with the given verbose level and region. Syntax void Log_Module_Print(Log_Verbose_Level_t eVerboseLevel, Log_Region_t eRegion, const char * pText, ...); Parameters [in] eVerboseLevel Type: Log_Verbose_Level_t Description: The level of verbose for this log. [in] eRegion Type: Log_Region_t Description: The region where the log is issued. [in] pText Type: const char * Description: Pointer to the text to be printed. [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

Log_Module_PrintWithArg

Description Prints a log with already an arg list. Syntax void Log_Module_PrintWithArg(Log_Verbose_Level_t eVerboseLevel, Log_Region_t eRegion, const char * pText, va_list args); Parameters [in] eVerboseLevel Type: Log_Verbose_Level_t Description: The level of verbose for this log. [in] eRegion Type: Log_Region_t Description: The region where the log is issued. [in] pText Type: const char * Description: Pointer to the text to be printed. [in] args Type: va_list Description: Arguments list. Return Value None

3.2. Macros

LOG_INFO_BLE
Description Macro to print an info log for the BLE region. Syntax LOG_INFO_BLE(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_ERROR_BLE
Description Macro to print an error log for the BLE region. Syntax LOG_ERROR_BLE(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_WARNING_BLE
Description Macro to print a warning log for the BLE region. Syntax LOG_WARNING_BLE(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_DEBUG_BLE
Description Macro to print a debug log for the BLE region. Syntax LOG_DEBUG_BLE(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_INFO_SYSTEM
Description Macro to print an info log for the System region. Syntax LOG_INFO_SYSTEM(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_ERROR_SYSTEM
Description Macro to print an error log for the System region. Syntax LOG_ERROR_SYSTEM(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_WARNING_SYSTEM
Description Macro to print a warning log for the System region. Syntax LOG_WARNING_SYSTEM(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_DEBUG_SYSTEM
Description Macro to print a debug log for the System region. Syntax LOG_DEBUG_SYSTEM(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_INFO_APP
Description Macro to print an info log for the App region. Syntax LOG_INFO_APP(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_ERROR_APP
Description Macro to print an error log for the App region. Syntax LOG_ERROR_APP(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_WARNING_APP
Description Macro to print a warning log for the App region. Syntax LOG_WARNING_APP(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

LOG_DEBUG_APP
Description Macro to print a debug log for the App region. Syntax LOG_DEBUG_APP(...); Parameters [in] ... Type: ... Description: Any other parameters to be printed with the text. Return Value None

4. How to

The following chapters explain how to configure and use the Log Module with user own region, verbosity and color logging.

4.1. Set a new region

If you want to create a new region, for instance for your application, you just need to create a new entry in the Log_Region_t enumeration in log_module.h, like bellow:

File:RegionEnumeration.png

Region Enumeration setting

User can right after use his new enumeration entry as a value for the different log module functions.

4.2. Set a new verbose level

Same behavior as above, user simply needs to provide a new entry inside the Log_Verbose_Level_t enumeration in log_module.h, like bellow:

File:VerboseEnumeration.png

Verbose enumeration setting

The new verbose level can be used by user right after in all over the code even in already existing logging spots. This flexibility allow the user to raffinate even more the level of verbosity he desire over the whole application.

Information

Beware, user shall not modify the already defined enumeration entries. They are mapped 1 per 1 with the utility, the log module is relying on.

4.3. Configure a color

Just like the others, if you want to set a new color, you need to create a new entry in the dedicated enumeration tracking the colors. The responsible enumeration is the Log_Color_t located in log_module.h.

You can add your custom color choice here basing its value on the ASCII color codes, like showed below:

File:Color enumeration setting.png

Color enumeration setting

Like any other color, you can after associate your new color to the desired region.

4.4. Custom logging

If you have followed the steps above, the last step to achieve is to create your own set of logging macros that will suits your needs.

TBD.