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.

Info white.png 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.

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.

Info white.png 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.

Info white.png 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[1], 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.


Info white.png 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);

5. References