How To Use ¶

Use Advanced Trace as follows:

1. Selecting Files ¶

Add the following source and header files to the project:

Core (mandatory): core/adv_trace_core.c and core/adv_trace_core.h
Interface (one interface to select):
- UART (HAL-only): interface_data/adv_trace_itfdata_uart.c and interface_data/adv_trace_itf_data.h
- Custom: Copy interface_data/adv_trace_itfdata_template.c into your project, implement the interface functions, and include interface_data/adv_trace_itf_data.h
Configuration (optional): adv_trace_user_conf.h (if ADV_TRACE_USER_CONF is defined)

Required files when the UART interface is selected with the default configuration:

           /Required files
        ├─ Core/
        │   ├─ adv_trace_core.c
        │   └─ adv_trace_core.h
        ├─ Interface/
        │   ├─ adv_trace_itfdata_uart.c
        └─  └─ adv_trace_itf_data.h

          

Required files when a custom interface is selected with a user configuration:

           /Required files
        ├─ Core/
        │   ├─ adv_trace_core.c
        │   └─ adv_trace_core.h
        ├─ Interface/
        │   ├─ adv_trace_itfdata_template.c (copy this file from the template and adapt it)
        |   └─ adv_trace_itf_data.h
        ├─ Config/
        └─  └─ adv_trace_user_conf.h  (if "ADV_TRACE_USER_CONF" is defined copy this file from templates and adapt it)

          

2. Configuration ¶

2.1. Optional Configuration ¶

Enable the custom configuration header by defining ADV_TRACE_USER_CONF in the preprocessor options. Copy the template header and adapt it as needed.

The following table summarizes the configurable items in the optional user configuration header adv_trace_user_conf.h:

Config Item	Description	Default Value	Max Value	Min Value
`ADV_TRACE_FIFO_SIZE`	Trace FIFO size (in bytes)	1024	N/A	1
`ADV_TRACE_MAX_FORMAT_BUF_SIZE`	Temporary formatting buffer size (in bytes)	128	N/A	1
`ADV_TRACE_MAX_TIMESTAMP_SIZE`	Timestamp buffer size (in bytes)	128	N/A	1
`ADV_TRACE_INIT_CRITICAL_SECTION`	Macro to initialize the critical section	Empty	N/A	N/A
`ADV_TRACE_ENTER_CRITICAL_SECTION`	Macro to enter the critical section	uint32_t primask_bit = __get_PRIMASK(); __disable_irq()	N/A	N/A
`ADV_TRACE_EXIT_CRITICAL_SECTION`	Macro to exit the critical section	__set_PRIMASK(primask_bit)	N/A	N/A
`ADV_TRACE_MEMSET8(dest, value, size)`	Utility macro that maps to a memory fill function using an 8-bit value	Standard C: memset((dest),(value),(size))	N/A	N/A
`ADV_TRACE_VSNPRINTF(...)`	Utility macro that maps to the formatted output function	Standard C: vsnprintf(__VA_ARGS__)	N/A	N/A
`ADV_TRACE_CONDITIONAL`	Feature flag that enables conditional trace functions	defined	N/A	N/A
`ADV_TRACE_UNCHUNK_MODE`	Feature flag that enables unchunk mode	defined	N/A	N/A

Example of a minimal custom header (adv_trace_user_conf.h):

            /* Minimal Advanced Trace configuration (adjust sizes as needed) */
#define ADV_TRACE_FIFO_SIZE                 (1024U)
#define ADV_TRACE_MAX_FORMAT_BUF_SIZE       (128U)
#define ADV_TRACE_MAX_TIMESTAMP_SIZE        (128U)

/* Critical section hooks */
#define ADV_TRACE_INIT_CRITICAL_SECTION()
#define ADV_TRACE_ENTER_CRITICAL_SECTION()  uint32_t primask_bit = __get_PRIMASK(); __disable_irq()
#define ADV_TRACE_EXIT_CRITICAL_SECTION()   __set_PRIMASK(primask_bit)

/* Utility mappings */
#define ADV_TRACE_MEMSET8(dest, value, size)  memset((dest),(value),(size))
#define ADV_TRACE_VSNPRINTF(...)              vsnprintf(__VA_ARGS__)

           

2.2. Interface Configuration ¶

UART Interface ¶

Initialize the UART with the STM32 HAL (or the board BSP): enable peripheral and GPIO clocks, configure TX/RX pins and the USART instance, and set the communication parameters (baud rate, word length, stop bits, parity, mode).
Enable DMA for TX.
For detailed steps, refer to the STM32 HAL USART documentation.

Custom Interface ¶

Copy the template file and implement the interface APIs.
Enable DMA for TX on the chosen output peripheral.
Refer to the corresponding driver documentation for the exact configuration parameters.

3. Advanced Trace Initialization ¶

Call ADV_TRACE_Init() once after the basic hardware setup and before entering the main loop. Use the appropriate handle for the selected interface (UART or custom).

Example:

           ADV_TRACE_Init(&io_handle);   /* Initialize the Advanced Trace */

          

4. Advanced Trace Usage ¶

After completing file selection, interface configuration, and initialization, call ADV_TRACE_FSend(const char *fmt, ...) to transmit data over the configured interface (for example UART or a custom interface, typically using DMA for TX).

Examples ¶

            /* Simple log example */
if (ADV_TRACE_FSend("Hello world \r\n") != ADV_TRACE_OK)
{
  /* Handle ADV_TRACE_MEM_FULL or ADV_TRACE_ERROR */
}

           