Coming 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 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
- 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.
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 My_Custom_TimeStamp_cb( 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 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 user will be 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, 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 |
---|
|
Log_Module_DeInit |
---|
|
Log_Module_Set_Verbose_Level |
---|
|
Log_Module_Set_Region |
---|
|
Log_Module_Add_Region |
---|
|
Log_Module_Enable_All_Regions |
---|
|
Log_Module_Set_Color |
---|
|
Log_Module_RegisterTimeStampFunction |
---|
|
Log_Module_Print |
---|
|
Log_Module_PrintWithArg |
---|
|
3.2. Macros
LOG_INFO_BLE |
---|
|
LOG_ERROR_BLE |
---|
|
LOG_WARNING_BLE |
---|
|
LOG_DEBUG_BLE |
---|
|
LOG_INFO_SYSTEM |
---|
|
LOG_ERROR_SYSTEM |
---|
|
LOG_WARNING_SYSTEM |
---|
|
LOG_DEBUG_SYSTEM |
---|
|
LOG_INFO_APP |
---|
|
LOG_ERROR_APP |
---|
|
LOG_WARNING_APP |
---|
|
LOG_DEBUG_APP |
---|
|
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:
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:
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.
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:
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 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 follow:
With the new set defined, you can be directly use it in your application code to print some logs regarding your new region.
/* 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