STM32CubeWBA: Trace management - Log module

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 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

It allows the user to provide a function to add a timestamp for the log output.

Printing macros

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

2.1. Log module configuration

The user can configure the module at three different levels:

• Verbosity
• Regions setting
• Colors

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

2.1.1. Verbosity

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. The 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 enables 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 the user has a task 1 and a task 2. Both of them having info and debug logs. By using them as such, that is, with the same regions, you print the logs of the two tasks as long as the verbose is info or debug. If the user creates a region for task 1 and another for task 2, he can split the logs between them. If needed, he can also print only the debug logs for task 1 (that is, 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

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

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

Where:

pData => The location to insert the new TimeStamp.

iSizeMax => The maximum size for the TimeStamp insert.

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

• He registers his callback with the help of the Log_Module_RegisterTimeStampFunction function.

2.3. Printing macros

Printing macros are the interfaces to output logs, 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 the user is able to use:

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

Nonetheless, the user can create its own set of macros if needed to handle new region declarations 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 the 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:

Region Enumeration setting

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

Information

User shall not assign a value to his created entries.

4.2. Set a new verbose level

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

Verbose enumeration setting

The new verbose level can be used by the user in all over the code even in already existing logging spots. This flexibility allows the user to refine the level of verbosity he desires over the whole application even further.

Information

Beware, user shall not modify the already defined enumeration entries nor assigned a value to his created 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 ANSI color codes, like showed below:

Color enumeration setting

Like any other color, you can then associate your new color with the desired region.

4.4. Custom logging

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

For instance, for the LOG_REGION_MY_NEW_REGION region and with the newly added verbose level, the set of macros would be as follows:

New macro set

With the new set defined, you can directly use it in your application code to print some logs regarding your new region.

Information

If you want to use your new color setting for your new region, you could also do the following:

/* Set the new color to the newly created region */
Log_Module_Set_Color (LOG_REGION_MY_NEW_REGION,LOG_COLOR_CODE_MY_NEW_CUSTOM_COLOR_GREEN);