Overview ¶

Purpose ¶

Advanced Trace is a trace management system for STM32 microcontrollers. Use it for debugging or for communicating with another system, such as a console or monitoring tool, over UART or a custom input/output interface. The system uses a FIFO buffer to store data and transfers it in the background using direct memory access (DMA).

Key Features ¶

The main features of Advanced Trace are:

Adjustable FIFO size: Sets the trace buffer capacity to match the application requirements.
Override FIFO memory address: Places the buffer in a custom memory region.
Conditional tracing: Controls trace output with verbosity levels and region masks.
Trace timestamp: Adds timestamps to the trace data to track events over time.
Trace overrun: Reports and handles trace buffer overflows to ensure correct processing and storage.
Unchunk mode: Streams traces without chunking to provide continuous output.
Trace data reception: Allows the application to receive data from the trace interface.

Architecture ¶

The following diagram illustrates the software components of the Advanced Trace module. It shows the interactions between the user application, the core layer, the input/output interfaces (UART or custom), the supporting system libraries (HAL), and the hardware components.

Component Structure ¶

Core ( adv_trace_core.c / adv_trace_core.h): Provides the core APIs and FIFO buffering to collect and send traces over the selected interface (UART or custom). It handles initialization, data enqueueing, optional timestamp insertion, conditional filtering, overrun reporting, and send callbacks.

Optional Configuration ( adv_trace_user_conf.h): Build-time configuration layer for the tracing system. Use it to set limits such as FIFO and format buffer sizes, enable optional features, and map utility functions. Define how critical sections are handled on the target platform. Replace small utility macros when needed. Keep platform-specific tweaks outside the core so the main logic remains clean and portable. Safe defaults apply automatically when no custom settings are provided.

Interfaces : Software layer that connects Advanced Trace to the hardware component. Two interfaces are available:

UART: Ready-to-use implementation that only requires enabling and initialization, with no code changes.
Template: Empty interface that allows users to develop their own interface. Copy the file into the user space; it contains empty functions with the prototypes required by the core.

Modules and Files ¶

The following diagram shows the Advanced Trace module and its associated files:

@startuml Advanced_Trace_modules
skinparam componentStyle rectangle
skinparam defaultFontName Courier
skinparam ArrowColor #2A4B8D
skinparam ArrowFontSize 10
skinparam RectangleBackgroundColor #FFFFFF
skinparam RectangleBorderColor #2A4B8D
skinparam Shadowing false
skinparam linetype ortho

title Advanced Trace Modules Overview

package "Application" {
component APP as "User Application"
}

package "Advanced Trace" {
component CORE_H as "adv_trace_core.h"
component CORE_C as "adv_trace_core.c"
component ITF_H as "adv_trace_itf_data.h"
component B_TEMPLATE as "adv_trace_itfdata_template.c" #DAE8FC
component B_UART as "adv_trace_itfdata_uart.c" #DAE8FC
component ADV_TRACE_USER_CONF as "adv_trace_user_conf.h"
}

APP --> CORE_C
CORE_C ..> CORE_H : include
CORE_H ..> ADV_TRACE_USER_CONF : include (if "ADV_TRACE_USER_CONF" is defined)
CORE_C ..> ITF_H : include
CORE_C --> B_UART : interface
CORE_C --> B_TEMPLATE : interface
B_UART ..> ITF_H : include
B_TEMPLATE ..> ITF_H : include

@enduml

Configuration Table ¶

The following table lists the configuration defines for the Advanced Trace module:

Config Defines	Where	Description
ADV_TRACE_USER_CONF	Preprocessor environment	Enable custom user configuration ( `adv_trace_user_conf.h`)