Trace DMA & Dictionary Logging

Circular host DMA trace buffers, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps. More...

Collaboration diagram for Trace DMA & Dictionary Logging:

Files
file	trace.h
	Host-DSP IPC trace DMA configuration, filtering, and panic descriptors.
file	trace.h
	User-space ABI log levels and binary trace packet header definitions.
file	dma-trace.h
	Direct Memory Access (DMA) trace buffer management and host streaming.
file	trace-boot.h
	Early bootloader, architecture, and peripheral initialization trace checkpoint codes.
file	trace-soflogger.h
	Dictionary-based trace logging engine, log filtering, and mailbox trace fallback.

Data Structures
struct	sof_ipc_dma_trace_params
	Legacy host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS). More...
struct	sof_ipc_dma_trace_params_ext
	Extended host DMA trace parameters payload (SOF_IPC_TRACE_DMA_PARAMS_EXT). More...
struct	sof_ipc_dma_trace_posn
	DMA trace circular buffer position report sent to host (SOF_IPC_TRACE_DMA_POSITION). More...
struct	sof_ipc_panic_info
	DSP panic crash dump descriptor reported to host. More...
struct	log_entry_header
	Binary log packet header preceding variable arguments in DMA trace stream. More...
struct	dma_trace_buf
	Internal ring buffer descriptor for DSP trace packets. More...
struct	dma_trace_data
	Main DMA trace context and state machine descriptor. More...
struct	trace_filter
	Runtime trace filter criteria for components and pipelines. More...

Typedefs
typedef void(*	log_func_t) (bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args)
	Function pointer type for formatted trace logger backends.

Functions
int	dma_trace_init_early (struct sof *sof)
	Early initialization of the DMA trace subsystem during bootstrap.
int	dma_trace_init_complete (struct dma_trace_data *d)
	Complete initialization of DMA trace once host channel is negotiated.
int	dma_trace_host_buffer (struct dma_trace_data *d, struct dma_sg_elem_array *elem_array, uint32_t host_size)
	Configure the host-side destination scatter-gather buffer for DMA trace.
int	dma_trace_enable (struct dma_trace_data *d)
	Enable DMA trace streaming to the host.
void	dma_trace_disable (struct dma_trace_data *d)
	Disable DMA trace streaming and cancel pending periodic tasks.
void	dma_trace_flush (void *destination)
	Flush residual trace data from local DSP buffer to destination memory or mailbox.
void	dma_trace_on (void)
	Globally unpause and resume trace event logging.
void	dma_trace_off (void)
	Globally pause trace event logging.
void	dtrace_event (const char *e, uint32_t size)
	Append a binary trace event to the circular buffer.
void	dtrace_event_atomic (const char *e, uint32_t length)
	Append a binary trace event to the buffer from atomic or interrupt context.
static bool	dma_trace_initialized (const struct dma_trace_data *d)
	Check whether DMA trace subsystem has been initialized.
static struct dma_trace_data *	dma_trace_data_get (void)
	Retrieve global DMA trace data context from system runtime.
static uint32_t	dtrace_calc_buf_margin (struct dma_trace_buf *buffer)
	Calculate contiguous bytes remaining until the end of the circular buffer.
static struct trace *	trace_get (void)
	Retrieve global trace subsystem context from SOF runtime.
void	trace_flush_dma_to_mbox (void)
	Flush buffered trace data from DMA buffer to Mailbox Window.
void	trace_on (void)
	Globally resume trace event logging.
void	trace_off (void)
	Globally pause trace event logging.
void	trace_init (struct sof *sof)
	Initialize the trace subsystem and allocate global trace buffers.
void	trace_log_filtered (bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args)
	Emit a filtered dictionary trace message.
void	trace_log_unfiltered (bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args)
	Emit an unfiltered dictionary trace message directly to buffers.
struct sof_ipc_trace_filter_elem *	trace_filter_fill (struct sof_ipc_trace_filter_elem *elem, struct sof_ipc_trace_filter_elem *end, struct trace_filter *filter)
	Populate an IPC trace filter element array.
int	trace_filter_update (const struct trace_filter *elem)
	Update runtime trace filtering configuration from IPC payload.
void	mtrace_dict_entry (bool atomic_context, uint32_t log_entry_pointer, int n_args,...)
	Appends one SOF dictionary entry and log statement to shared memory mtrace.
void	mtrace_event (const char *complete_packet, uint32_t length)
	Posts a fully prepared log header and log entry packet to mtrace buffer.
void	_log_sofdict (log_func_t sofdict_logf, bool atomic, const void *log_entry, const struct tr_ctx *ctx, const uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count,...)
	Internal dictionary logger formatting and dispatch helper.

Detailed Description

Circular host DMA trace buffers, dictionary-based logger (.ldc), runtime log level filtering, and panic crash dumps.

Typedef Documentation

log_func_t

typedef void(* log_func_t) (bool send_atomic, const void *log_entry, const struct tr_ctx *ctx, uint32_t lvl, uint32_t id_1, uint32_t id_2, int arg_count, va_list args)

Function pointer type for formatted trace logger backends.

Parameters

[in]	send_atomic	True if logging from atomic or interrupt context.
[in]	log_entry	Pointer to static log entry descriptor.
[in]	ctx	Pointer to caller trace context.
[in]	lvl	Severity log level (LOG_LEVEL_*).
[in]	id_1	Primary component/pipe identifier.
[in]	id_2	Secondary component/subid identifier.
[in]	arg_count	Number of variable arguments.
[in]	args	Variable arguments list.

Function Documentation

_log_sofdict()

void _log_sofdict	(	log_func_t	sofdict_logf,
		bool	atomic,
		const void *	log_entry,
		const struct tr_ctx *	ctx,
		const uint32_t	lvl,
		uint32_t	id_1,
		uint32_t	id_2,
		int	arg_count,
			...
	)

Internal dictionary logger formatting and dispatch helper.

Parameters

sofdict_logf	Backend log emission callback function.
atomic	True if executed in atomic context.
log_entry	Pointer to static log entry.
ctx	Trace context.
lvl	Log severity level.
id_1	Primary identifier.
id_2	Secondary identifier.
arg_count	Number of format arguments.

dma_trace_data_get()

static struct dma_trace_data * dma_trace_data_get ( void  )

inlinestatic

Retrieve global DMA trace data context from system runtime.

Returns

Pointer to struct dma_trace_data.

dma_trace_disable()

void dma_trace_disable

(

struct dma_trace_data *

d

)

Disable DMA trace streaming and cancel pending periodic tasks.

Parameters

[in,out]

d

DMA trace data context.

dma_trace_enable()

int dma_trace_enable

(

struct dma_trace_data *

d

)

Enable DMA trace streaming to the host.

Parameters

[in,out]

d

DMA trace data context.

Returns

0 on success, or negative error code on failure.

dma_trace_flush()

void dma_trace_flush

(

void *

destination

)

Flush residual trace data from local DSP buffer to destination memory or mailbox.

Parameters

[out]

destination

Pointer to destination memory buffer, or NULL for default mailbox.

dma_trace_host_buffer()

int dma_trace_host_buffer	(	struct dma_trace_data *	d,
		struct dma_sg_elem_array *	elem_array,
		uint32_t	host_size
	)

Configure the host-side destination scatter-gather buffer for DMA trace.

Parameters

[in,out]	d	DMA trace data context.
[in]	elem_array	Array of scatter-gather buffer page elements.
[in]	host_size	Total size in bytes of the host buffer.

Returns

0 on success, or negative error code on failure.

dma_trace_init_complete()

int dma_trace_init_complete

(

struct dma_trace_data *

d

)

Complete initialization of DMA trace once host channel is negotiated.

Parameters

[in,out]

d

DMA trace data context.

Returns

0 on success, or negative error code on failure.

dma_trace_init_early()

int dma_trace_init_early

(

struct sof *

sof

)

Early initialization of the DMA trace subsystem during bootstrap.

Parameters

[in,out]

sof

Global SOF system context.

Returns

0 on success, or negative error code on failure.

dma_trace_initialized()

static bool dma_trace_initialized ( const struct dma_trace_data *  d )

inlinestatic

Check whether DMA trace subsystem has been initialized.

Parameters

[in]

d

DMA trace context.

Returns

True if initialized with valid buffer memory, false otherwise.

dma_trace_off()

void dma_trace_off

(

void

)

Globally pause trace event logging.

dma_trace_on()

void dma_trace_on

(

void

)

Globally unpause and resume trace event logging.

dtrace_calc_buf_margin()

static uint32_t dtrace_calc_buf_margin ( struct dma_trace_buf *  buffer )

inlinestatic

Calculate contiguous bytes remaining until the end of the circular buffer.

Parameters

[in]

buffer

Pointer to circular trace buffer descriptor.

Returns

Contiguous byte margin before write wrap-around.

dtrace_event()

void dtrace_event	(	const char *	e,
		uint32_t	size
	)

Append a binary trace event to the circular buffer.

Parameters

[in]	e	Pointer to binary event packet.
[in]	size	Packet size in bytes.

dtrace_event_atomic()

void dtrace_event_atomic	(	const char *	e,
		uint32_t	length
	)

Append a binary trace event to the buffer from atomic or interrupt context.

Parameters

[in]	e	Pointer to binary event packet.
[in]	length	Size of packet in bytes.

mtrace_dict_entry()

void mtrace_dict_entry	(	bool	atomic_context,
		uint32_t	log_entry_pointer,
		int	n_args,
			...
	)

Appends one SOF dictionary entry and log statement to shared memory mtrace.

Parameters

atomic_context	Take the trace->lock if false.
log_entry_pointer	Dictionary index produced by _DECLARE_LOG_ENTRY macro.
n_args	Number of variable arguments.

mtrace_event()

void mtrace_event	(	const char *	complete_packet,
		uint32_t	length
	)

Posts a fully prepared log header and log entry packet to mtrace buffer.

Parameters

complete_packet	Pointer to prepared log packet buffer.
length	Packet size in bytes.

trace_filter_fill()

struct sof_ipc_trace_filter_elem * trace_filter_fill	(	struct sof_ipc_trace_filter_elem *	elem,
		struct sof_ipc_trace_filter_elem *	end,
		struct trace_filter *	filter
	)

Populate an IPC trace filter element array.

Parameters

[in,out]	elem	Pointer to current output filter element.
[in]	end	Boundary pointer of element array.
[in]	filter	Source trace filter configuration.

Returns

Pointer to next available filter element slot.

trace_filter_update()

int trace_filter_update

(

const struct trace_filter *

elem

)

Update runtime trace filtering configuration from IPC payload.

Parameters

[in]

elem

Trace filter descriptor to apply.

Returns

0 on success, or negative error code on failure.

trace_flush_dma_to_mbox()

void trace_flush_dma_to_mbox

(

void

)

Flush buffered trace data from DMA buffer to Mailbox Window.

trace_get()

static struct trace * trace_get ( void  )

inlinestatic

Retrieve global trace subsystem context from SOF runtime.

Returns

Pointer to struct trace.

trace_init()

void trace_init

(

struct sof *

sof

)

Initialize the trace subsystem and allocate global trace buffers.

Parameters

[in,out]

sof

Global SOF runtime context.

trace_log_filtered()

void trace_log_filtered	(	bool	send_atomic,
		const void *	log_entry,
		const struct tr_ctx *	ctx,
		uint32_t	lvl,
		uint32_t	id_1,
		uint32_t	id_2,
		int	arg_count,
		va_list	args
	)

Emit a filtered dictionary trace message.

Parameters

[in]	send_atomic	True if logging from atomic context.
[in]	log_entry	Pointer to static log entry.
[in]	ctx	Trace context.
[in]	lvl	Log level.
[in]	id_1	Primary identifier.
[in]	id_2	Secondary identifier.
[in]	arg_count	Argument count.
[in]	args	Argument list.

trace_log_unfiltered()

void trace_log_unfiltered	(	bool	send_atomic,
		const void *	log_entry,
		const struct tr_ctx *	ctx,
		uint32_t	lvl,
		uint32_t	id_1,
		uint32_t	id_2,
		int	arg_count,
		va_list	args
	)

Emit an unfiltered dictionary trace message directly to buffers.

Parameters

[in]	send_atomic	True if logging from atomic context.
[in]	log_entry	Pointer to static log entry.
[in]	ctx	Trace context.
[in]	lvl	Log level.
[in]	id_1	Primary identifier.
[in]	id_2	Secondary identifier.
[in]	arg_count	Argument count.
[in]	args	Argument list.

trace_off()

void trace_off

(

void

)

Globally pause trace event logging.

trace_on()

void trace_on

(

void

)

Globally resume trace event logging.