Revision as of 16:50, 19 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
An application often needs to manage a system of trace for debug purpose or to communicate with another system (console, monitoring, …). The Advanced Trace is a simple module designed to provides all the trace services.
This module has been designed with three major constraints:
- Low impact on the real time execution.
- No specific associated processing, the trace evacuations are managed in background.
- Low footprint.
2. Concepts
The Advanced Trace is split into two layers:
- Advanced Trace services
- API that regroups all the services available for traces.
- Trace Interface
- Interface between the HW and the Advance Trace services layer.
2.1. Advanced Trace services
The advanced trace proposes some interesting features to users for Trace debugging or logging:
- Trace FIFO management
- The advanced trace module manages a circular FIFO - Size is customizable - to store all the application data before their push on the media. The module guarantees the data integrity and parallel access to the trace services.
- The “unchunk” mode is an optional mode which could be enabled inside the utilities’ configuration header. The goal of this mode is to guarantee that a frame is not split inside two transfers.
- The timestamp management allows the user to add a timestamp buffer ahead of the frame to output.
- However, user shall follow two steps:
- User shall create a callback function that returns a time stamp buffer and its buffer size.
- Use the adequate functions that allow timestamp management.
- This mode can be activated within the utilities’ configuration header.
- Verbose level and region management:
- The Verbose Level and the Region are two different levels to determine whether a frame can be sent or not. If one of these two condition fails, the frame is discarded.
- The Verbose Level
- The user can define his own current verbose level. The default setup is 0 meaning only value frame with verbose level equal to zero are sent through the Advanced Trace. If the application verbose level is lower or equal to the current verbose level, the frame is sent else discarded.
- The Region
- The user can define his own region mask. The default setup is 0 meaning only application frame with region equal to zero are sent through the Advanced Trace. If the application region value is equal to zero or if value is aligned with the mask region, the frame is sent else discarded.
- This feature aims to indicate when frame has been discarded due to a FIFO full. The switch enabled is not enough to make it functional, the user shall provide a callback function which returns an overrun frame and the size of this frame.
- This feature can be activated within the utilities’ configuration header.
2.2. Trace interface
The trace interface handles the HW interface. The only requirements for the HW are to provide characteristics such as:
- Shall be able to send data (8-bit data).
- Shall be able to receive data.
This hardware layer has been built to match with the UART but there is others’ HW IPs compatibles with these requirements: USB, I2C, SPI, etc. The choice shall be managed by the application designer according to the available resources and the application requirements.
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
|
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
|
3. How to
TBD.