trace.h File Reference

Trace program flows. More...

Detailed Description

Trace program flows.

This module allows recording program flow traces. It is meant for debugging in multi-threaded applications or when ISR's are involved.

The trace() function takes an arbitrary (user chosen) uint32 value. Calling the function is safe from anywhere (user code, ISR, ...) and safely logs the function call time and user value in a trace buffer.

At any point, trace_dump() can be used to print the trace buffer.

The buffer has a default size of 512 entries, which can be overridden by defining CONFIG_TRACE_BUFSIZE. It can be cleared using trace_reset(). The trace buffer works like a ring-buffer. If it is full, it will start overwriting from the beginning.

Tracing is made thread safe by disabling interrupts for critical sections.

It does incur some overhead (at least a function call, getting the current time, a pair of enable/disable interrupts and a couple of memory accesses).


#include "trace.h"
trace(<user chosen uint32 value);

Execution tracing module API

Kaspar Schleiser

Definition in file trace.h.

#include <stdint.h>
+ Include dependency graph for trace.h:

Go to the source code of this file.

void trace (uint32_t val)
 Add entry to trace buffer. More...
void trace_dump (void)
 Print the current trace buffer. More...
void trace_reset (void)
 Empty the trace buffer.

Function Documentation

◆ trace()

void trace ( uint32_t  val)

Add entry to trace buffer.

Adds the current time (e.g., xtimer_now_usec()) and val to the trace buffer.

The value parameter is not used by the trace module itself. The caller is supposed to provide a meaningful value. It could be e.g., 0 at the beginning of a task and 1at the end.

[in]valuser defined value

◆ trace_dump()

void trace_dump ( void  )

Print the current trace buffer.

Will print the number of the trace log entry, the timestamp (first entry) or relative time since last entry, and the value supplied to the trace() call of each entry.

Example output (after adding two traces, 3us apart, with values 0 and 1):

n=   0 t=  1815312 v=0x00000000
n=   1 t=+       3 v=0x00000001