Revision as of 12:12, 20 February 2024 by Registered User
This message will disappear after all relevant tasks have been resolved.
Semantic MediaWiki
There are 1 incomplete or
pending task to finish installation of
Semantic MediaWiki. An administrator or user with sufficient rights can complete it. This should be done before adding new data to avoid inconsistencies.
|
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
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.
2.3. Printing macros
TBD.
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
TBD.