File syn_trace.h¶

FileList > debug > syn_trace.h

Lightweight trace buffer — timestamped event recorder. More...

#include "../port/syn_port_system.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Classes¶

Type	Name
struct	SYN_Trace Circular trace event buffer.
struct	SYN_TraceEntry Single trace event entry.

Public Types¶

Type	Name
typedef void(*	SYN_TracePrintFunc

Public Functions¶

Type	Name
void	syn_trace_clear (SYN_Trace * trace) Clear the trace buffer.
void	syn_trace_dump (const SYN_Trace * trace, SYN_TracePrintFunc print) Dump all entries via a print callback.
void	syn_trace_enable (SYN_Trace * trace, bool enable) Enable/disable recording.
void	syn_trace_init (SYN_Trace * trace, SYN_TraceEntry * entries, uint16_t capacity) Initialize the trace buffer.
bool	syn_trace_read (const SYN_Trace * trace, uint32_t index, SYN_TraceEntry * entry) Read an entry by index (0 = oldest available).
void	syn_trace_record (SYN_Trace * trace, uint16_t event_id, uint16_t value) Record a trace event.

Public Static Functions¶

Type	Name
uint32_t	syn_trace_count (const SYN_Trace * trace) Get total event count (may exceed capacity — indicates wrapping).

Macros¶

Type	Name
define	SYN_TRACE (trace, id, val) `[syn\_trace\_record](syn__trace_8c.md#function-syn_trace_record)((trace), (id), (val))`

Detailed Description¶

Records events (id + optional 16-bit value) into a fixed-size circular buffer for post-mortem debugging. No UART, no printf — just stamp and store. Read it out with a debugger or dump over CLI.

** **

static SYN_TraceEntry entries[64];
static SYN_Trace trace;
syn_trace_init(&trace, entries, 64);

SYN_TRACE(&trace, EVT_ISR_ENTER, irq_num);
SYN_TRACE(&trace, EVT_TASK_SWITCH, task_id);

// Dump from CLI or debugger:
syn_trace_dump(&trace, print_func);

Public Types Documentation¶

typedef SYN_TracePrintFunc¶

typedef void(* SYN_TracePrintFunc) (const char *str);

Print callback for dump.

Public Functions Documentation¶

function syn_trace_clear¶

Clear the trace buffer.

void syn_trace_clear (
    SYN_Trace * trace
)

Parameters:

trace Trace instance to reset.

function syn_trace_dump¶

Dump all entries via a print callback.

void syn_trace_dump (
    const SYN_Trace * trace,
    SYN_TracePrintFunc print
)

Output format: "[tick] event_id=0xNNNN value=0xNNNN\n"

Parameters:

trace Trace instance.
print Print function (e.g., write to UART).

function syn_trace_enable¶

Enable/disable recording.

void syn_trace_enable (
    SYN_Trace * trace,
    bool enable
)

Parameters:

trace Trace instance.
enable True to enable recording, false to pause.

function syn_trace_init¶

Initialize the trace buffer.

void syn_trace_init (
    SYN_Trace * trace,
    SYN_TraceEntry * entries,
    uint16_t capacity
)

Parameters:

trace Trace instance to initialize.
entries Array of trace entries (caller-owned).
capacity Number of entries in the array.

function syn_trace_read¶

Read an entry by index (0 = oldest available).

bool syn_trace_read (
    const SYN_Trace * trace,
    uint32_t index,
    SYN_TraceEntry * entry
)

Parameters:

trace Trace instance.
index Index from oldest available.
entry Output entry.

Returns:

true if a valid entry was read.

function syn_trace_record¶

Record a trace event.

void syn_trace_record (
    SYN_Trace * trace,
    uint16_t event_id,
    uint16_t value
)

Parameters:

trace Trace instance.
event_id Application-defined event ID.
value Optional 16-bit payload.

Public Static Functions Documentation¶

function syn_trace_count¶

Get total event count (may exceed capacity — indicates wrapping).

static inline uint32_t syn_trace_count (
    const SYN_Trace * trace
)

Parameters:

trace Trace instance.

Returns:

Total number of events written since initialization.

Macro Definition Documentation¶

define SYN_TRACE¶

#define SYN_TRACE (
    trace,
    id,
    val
) `syn_trace_record ((trace), (id), (val))`

Convenience macro with auto-timestamping.

The documentation for this class was generated from the following file src/syntropic/debug/syn_trace.h