Overview

Submodules
	pw_trace_tokenized

Macros
#define	PW_TRACE_TYPE_INSTANT 1

#define	PW_TRACE_TYPE_INSTANT_GROUP 1

#define	PW_TRACE_TYPE_DURATION_START 1

#define	PW_TRACE_TYPE_DURATION_END 1

#define	PW_TRACE_TYPE_DURATION_GROUP_START 1

#define	PW_TRACE_TYPE_DURATION_GROUP_END 1

#define	PW_TRACE_TYPE_ASYNC_START 1

#define	PW_TRACE_TYPE_ASYNC_INSTANT 1

#define	PW_TRACE_TYPE_ASYNC_END 1

#define	PW_TRACE(event_type, flags, label, group, trace_id) _pw_trace_Ignored(event_type, flags, label, group, trace_id)

#define	PW_TRACE_DATA( event_type, flags, label, group, trace_id, type, data, size)

#define	PW_TRACE_FLAGS_DEFAULT 0

#define	PW_TRACE_TRACE_ID_DEFAULT 0

#define	PW_TRACE_GROUP_LABEL_DEFAULT ""

#define	PW_TRACE_HAS_TRACE_ID(TRACE_TYPE)

#define	PW_TRACE_HAS_GROUP_LABEL(TRACE_TYPE) (false)

#define	PW_TRACE_FUNCTION_LABEL __PRETTY_FUNCTION__

#define	PW_TRACE_ENABLE 1

#define	PW_TRACE_MODULE_NAME ""

#define	PW_TRACE_FLAGS PW_TRACE_FLAGS_DEFAULT

#define	PW_TRACE_INSTANT(...) PW_TRACE_INSTANT_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

#define	PW_TRACE_INSTANT_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_INSTANT_ARGS, __VA_ARGS__)

#define	PW_TRACE_INSTANT_DATA(...) PW_TRACE_INSTANT_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

#define	PW_TRACE_INSTANT_DATA_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_INSTANT_DATA_ARGS, __VA_ARGS__)

#define	PW_TRACE_START(...) PW_TRACE_START_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

#define	PW_TRACE_START_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_START_ARGS, __VA_ARGS__)

#define	PW_TRACE_START_DATA(...) PW_TRACE_START_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

#define	PW_TRACE_START_DATA_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_START_DATA_ARGS, __VA_ARGS__)

#define	PW_TRACE_END(...) PW_TRACE_END_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

#define	PW_TRACE_END_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_END_ARGS, __VA_ARGS__)

#define	PW_TRACE_END_DATA(...) PW_TRACE_END_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

#define	PW_TRACE_END_DATA_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_END_DATA_ARGS, __VA_ARGS__)

#define	PW_TRACE_SCOPE(...) PW_TRACE_SCOPE_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

#define	PW_TRACE_SCOPE_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_SCOPE_ARGS, __VA_ARGS__)

#define	PW_TRACE_FUNCTION(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_FUNCTION_ARGS, __VA_ARGS__)

#define	PW_TRACE_FUNCTION_FLAG(...) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_FUNCTION_FLAGS_ARGS, __VA_ARGS__)

Macro Definition Documentation

◆ PW_TRACE

#define PW_TRACE	(	event_type,
		flags,
		label,
		group,
		trace_id
	)	_pw_trace_Ignored(event_type, flags, label, group, trace_id)

Records a trace event. Every pw_trace backend must implement this macro. The facade invokes it from each of the trace event macros, such as PW_TRACE_INSTANT, PW_TRACE_START, and PW_TRACE_END.

Parameters

[in]	event_type	The value of the `PW_TRACE_TYPE_*` macro that the backend defined for this trace type, such as `PW_TRACE_TYPE_INSTANT`.
[in]	flags	The flags value for the event.
[in]	label	A string literal which describes the trace.
[in]	group	The group label: a string literal which groups this trace with others in the same module and group, or `PW_TRACE_GROUP_LABEL_DEFAULT`.
[in]	trace_id	A runtime `uint32_t` which groups this trace with others with the same module, group, and trace ID, or `PW_TRACE_TRACE_ID_DEFAULT`.

◆ PW_TRACE_DATA

#define PW_TRACE_DATA	(	event_type,
		flags,
		label,
		group,
		trace_id,
		type,
		data,
		size
	)

Value:

_pw_trace_IgnoredData( \

event_type, flags, label, group, trace_id, type, data, size)

Records a trace event with an attached user-supplied data buffer. The facade invokes it from each of the *_DATA trace event macros, such as PW_TRACE_INSTANT_DATA. Implementing this macro is optional; if the backend does not define it, all data trace events are removed.

Parameters

[in]	event_type	The value of the `PW_TRACE_TYPE_*` macro that the backend defined for this trace type, such as `PW_TRACE_TYPE_INSTANT`.
[in]	flags	The flags value for the event.
[in]	label	A string literal which describes the trace.
[in]	group	The group label: a string literal which groups this trace with others in the same module and group, or `PW_TRACE_GROUP_LABEL_DEFAULT`.
[in]	trace_id	A runtime `uint32_t` which groups this trace with others with the same module, group, and trace ID, or `PW_TRACE_TRACE_ID_DEFAULT`.
[in]	type	The data format string: a string which is used by the decoder to identify the data.
[in]	data	A pointer to a buffer of arbitrary caller-provided data (`const void*`).
[in]	size	The size of the data (`size_t`).

◆ PW_TRACE_ENABLE

#define PW_TRACE_ENABLE 1

Controls whether tracing is enabled in the current file. A value of 0 causes traces to be disabled. A non-zero value enables traces.

While tracing defaults to enabled, it is best practice to define PW_TRACE_ENABLE explicitly in files that use tracing, as the default may change in the future. A good pattern is to have a module-level configuration parameter for enabling tracing and to define PW_TRACE_ENABLE in terms of that at the top of each of the module's files:

// Enable tracing based on pw_example module config parameter.

#define PW_TRACE_ENABLE PW_EXAMPLE_TRACE_ENABLE

Specific trace points (or sets of points) can also be enabled or disabled by redefining PW_TRACE_ENABLE around them:

// Assuming tracing is disabled at the top of the file.
 
// Enable specific trace.
#undef PW_TRACE_ENABLE
#define PW_TRACE_ENABLE 1
PW_TRACE_INSTANT("important trace");
 
// Set traces back to disabled. PW_TRACE_ENABLE can not be left undefined.
#undef PW_TRACE_ENABLE
#define PW_TRACE_ENABLE 0

◆ PW_TRACE_END

#define PW_TRACE_END ( ... ) PW_TRACE_END_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

Ends tracing a duration event. Must be paired with a PW_TRACE_START (or PW_TRACE_START_DATA) with the same module, label, group_label, and trace_id.

Overloads:

Arguments:

label - A string literal which describes the trace.
group_label (optional) - A string literal which groups this trace with others in the same module and group.
trace_id (optional) - A runtime uint32_t which groups this trace with others with the same module, group, and trace ID. Every trace with a trace_id must also have a group_label.

Example:

PW_TRACE_START("label");
// Do something.
PW_TRACE_END("label");

◆ PW_TRACE_END_DATA

#define PW_TRACE_END_DATA ( ... ) PW_TRACE_END_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

Same as PW_TRACE_END, but appends a user-supplied data buffer to the trace event.

Overloads:

Arguments:

data_format_string - A string which is used by the decoder to identify the data. This could for example be printf-style tokens, a Python struct packed format string, or a custom label recognized by the decoder.
data - A pointer to a buffer of arbitrary caller-provided data (const void*).
size - The size of the data (size_t).

Note: A trace duration start/end can be combined with a duration data start/end, to include data at only one of the trace points and not the other.

◆ PW_TRACE_END_DATA_FLAG

#define PW_TRACE_END_DATA_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_END_DATA_ARGS, __VA_ARGS__)

Same as PW_TRACE_END_DATA, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional.

Overloads:

◆ PW_TRACE_END_FLAG

#define PW_TRACE_END_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_END_ARGS, __VA_ARGS__)

Same as PW_TRACE_END, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional.

Overloads:

◆ PW_TRACE_FLAGS

#define PW_TRACE_FLAGS PW_TRACE_FLAGS_DEFAULT

The flags value used by the trace macros that don't take an explicit flag argument, such as PW_TRACE_INSTANT. Defaults to PW_TRACE_FLAGS_DEFAULT.

◆ PW_TRACE_FLAGS_DEFAULT

#define PW_TRACE_FLAGS_DEFAULT 0

The default flags value for trace events when no flags are provided. The backend can define this macro to change the default. Defaults to 0.

◆ PW_TRACE_FUNCTION

#define PW_TRACE_FUNCTION ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_FUNCTION_ARGS, __VA_ARGS__)

Traces the duration of the current function. This is the same as PW_TRACE_SCOPE, but uses the function name (PW_TRACE_FUNCTION_LABEL) as the label. This is the only trace macro which does not require a label. C++ only.

Overloads:

Arguments:

group_label (optional) - A string literal which groups this trace with others in the same module and group.
trace_id (optional) - A runtime uint32_t which groups this trace with others with the same module, group, and trace ID. Every trace with a trace_id must also have a group_label.

Example:

void Bar() {
  PW_TRACE_FUNCTION();
  // Do some stuff.
}
 
void Child() {
  PW_TRACE_FUNCTION("Group");
  // Do some stuff.
}
 
void Parent() {
  PW_TRACE_FUNCTION("Group");
  // Do some stuff.
  Child();
}

Which can be visualized as:

Bar:   [----------------Bar----------------]
Group: [----------------Parent----------------]
                  [------Child-------]

◆ PW_TRACE_FUNCTION_FLAG

#define PW_TRACE_FUNCTION_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_FUNCTION_FLAGS_ARGS, __VA_ARGS__)

Same as PW_TRACE_FUNCTION, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional. C++ only.

Overloads:

◆ PW_TRACE_FUNCTION_LABEL

#define PW_TRACE_FUNCTION_LABEL __PRETTY_FUNCTION__

The label used for PW_TRACE_FUNCTION trace events. The backend can override this macro. Defaults to __PRETTY_FUNCTION__.

◆ PW_TRACE_GROUP_LABEL_DEFAULT

#define PW_TRACE_GROUP_LABEL_DEFAULT ""

The default group_label value for trace events when no group label is provided. The backend can define this macro to change the default. Defaults to an empty string.

◆ PW_TRACE_HAS_GROUP_LABEL

#define PW_TRACE_HAS_GROUP_LABEL ( TRACE_TYPE ) (false)

Evaluates to true if trace events of the given TRACE_TYPE contain a group_label. The backend can override this macro. Defaults to false.

Parameters

[in] TRACE_TYPE The PW_TRACE_TYPE_* macro value to check.

◆ PW_TRACE_HAS_TRACE_ID

#define PW_TRACE_HAS_TRACE_ID ( TRACE_TYPE )

Value:

  ((TRACE_TYPE) == PW_TRACE_TYPE_ASYNC_START ||   \
   (TRACE_TYPE) == PW_TRACE_TYPE_ASYNC_INSTANT || \
   (TRACE_TYPE) == PW_TRACE_TYPE_ASYNC_END)

Evaluates to true if trace events of the given TRACE_TYPE contain a trace_id. The backend can override this macro.

Parameters

[in] TRACE_TYPE The PW_TRACE_TYPE_* macro value to check.

◆ PW_TRACE_INSTANT

#define PW_TRACE_INSTANT ( ... ) PW_TRACE_INSTANT_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

Traces an instantaneous event, which has no duration.

Overloads:

Arguments:

label - A string literal which describes the trace.
group_label (optional) - A string literal which groups this trace with others in the same module and group.
trace_id (optional) - A runtime uint32_t which groups this trace with others with the same module, group, and trace ID. Every trace with a trace_id must also have a group_label.

Example:

PW_TRACE_INSTANT("HERE");

◆ PW_TRACE_INSTANT_DATA

#define PW_TRACE_INSTANT_DATA ( ... ) PW_TRACE_INSTANT_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

Same as PW_TRACE_INSTANT, but appends a user-supplied data buffer to the trace event.

Overloads:

Arguments:

data_format_string - A string which is used by the decoder to identify the data. This could for example be printf-style tokens, a Python struct packed format string, or a custom label recognized by the decoder.
data - A pointer to a buffer of arbitrary caller-provided data (const void*).
size - The size of the data (size_t).

◆ PW_TRACE_INSTANT_DATA_FLAG

#define PW_TRACE_INSTANT_DATA_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_INSTANT_DATA_ARGS, __VA_ARGS__)

Same as PW_TRACE_INSTANT_DATA, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional.

Overloads:

◆ PW_TRACE_INSTANT_FLAG

#define PW_TRACE_INSTANT_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_INSTANT_ARGS, __VA_ARGS__)

Same as PW_TRACE_INSTANT, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional.

Overloads:

◆ PW_TRACE_MODULE_NAME

#define PW_TRACE_MODULE_NAME ""

The module name that the backend associates with the trace events in the current file. Traces can be grouped into modules, similar to logging, by defining this macro before including pw_trace/trace.h:

#define PW_TRACE_MODULE_NAME "Input"

#include "pw_trace/trace.h"

Defaults to an empty string.

◆ PW_TRACE_SCOPE

#define PW_TRACE_SCOPE ( ... ) PW_TRACE_SCOPE_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

Traces the duration of the current scope. Emits a start event where the macro appears in code and an end event when the enclosing scope exits. This provides a convenient method of tracing functions or loops. C++ only.

Overloads:

Arguments:

label - A string literal which describes the trace.
group_label (optional) - A string literal which groups this trace with others in the same module and group.
trace_id (optional) - A runtime uint32_t which groups this trace with others with the same module, group, and trace ID. Every trace with a trace_id must also have a group_label.

Example:

{
  PW_TRACE_SCOPE("Bar");
  // Do some stuff.
}
 
{
  PW_TRACE_SCOPE("Foo", "Group");
  {
    PW_TRACE_SCOPE("SubFoo", "Group");
    // Do some stuff.
  }
  // Do some stuff.
}

Which can be visualized as:

Bar:   [----------------Bar----------------]
Group: [----------------Foo----------------]
                  [------SubFoo-------]

◆ PW_TRACE_SCOPE_FLAG

#define PW_TRACE_SCOPE_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_SCOPE_ARGS, __VA_ARGS__)

Same as PW_TRACE_SCOPE, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional. C++ only.

Overloads:

◆ PW_TRACE_START

#define PW_TRACE_START ( ... ) PW_TRACE_START_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

Starts tracing a duration event. Must be paired with a PW_TRACE_END (or PW_TRACE_END_DATA) with the same module, label, group_label, and trace_id.

Overloads:

Arguments:

label - A string literal which describes the trace.
group_label (optional) - A string literal which groups this trace with others in the same module and group.
trace_id (optional) - A runtime uint32_t which groups this trace with others with the same module, group, and trace ID. Every trace with a trace_id must also have a group_label.

Example:

PW_TRACE_START("label");
// Do something.
PW_TRACE_END("label");

◆ PW_TRACE_START_DATA

#define PW_TRACE_START_DATA ( ... ) PW_TRACE_START_DATA_FLAG(PW_TRACE_FLAGS, __VA_ARGS__)

Same as PW_TRACE_START, but appends a user-supplied data buffer to the trace event.

Overloads:

Arguments:

data_format_string - A string which is used by the decoder to identify the data. This could for example be printf-style tokens, a Python struct packed format string, or a custom label recognized by the decoder.
data - A pointer to a buffer of arbitrary caller-provided data (const void*).
size - The size of the data (size_t).

Note: A trace duration start/end can be combined with a duration data start/end, to include data at only one of the trace points and not the other.

◆ PW_TRACE_START_DATA_FLAG

#define PW_TRACE_START_DATA_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_START_DATA_ARGS, __VA_ARGS__)

Same as PW_TRACE_START_DATA, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional.

Overloads:

◆ PW_TRACE_START_FLAG

#define PW_TRACE_START_FLAG ( ... ) PW_DELEGATE_BY_ARG_COUNT(_PW_TRACE_START_ARGS, __VA_ARGS__)

Same as PW_TRACE_START, but uses the provided flag value instead of PW_TRACE_FLAGS. The flag goes at the start; the group_label and trace_id arguments are still optional.

Overloads:

◆ PW_TRACE_TRACE_ID_DEFAULT

#define PW_TRACE_TRACE_ID_DEFAULT 0

The default trace_id value for trace events when no trace ID is provided. The backend can define this macro to change the default. Defaults to 0.

◆ PW_TRACE_TYPE_ASYNC_END

#define PW_TRACE_TYPE_ASYNC_END 1

Enables end trace events with a label, group, and trace ID. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_ASYNC_INSTANT

#define PW_TRACE_TYPE_ASYNC_INSTANT 1

Enables instant trace events with a label, group, and trace ID. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_ASYNC_START

#define PW_TRACE_TYPE_ASYNC_START 1

Enables start trace events with a label, group, and trace ID. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_DURATION_END

#define PW_TRACE_TYPE_DURATION_END 1

Enables end trace events with only a label. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_DURATION_GROUP_END

#define PW_TRACE_TYPE_DURATION_GROUP_END 1

Enables end trace events with a label and a group. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_DURATION_GROUP_START

#define PW_TRACE_TYPE_DURATION_GROUP_START 1

Enables start trace events with a label and a group. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_DURATION_START

#define PW_TRACE_TYPE_DURATION_START 1

Enables start trace events with only a label. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_INSTANT

#define PW_TRACE_TYPE_INSTANT 1

Enables instant trace events with only a label. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

◆ PW_TRACE_TYPE_INSTANT_GROUP

#define PW_TRACE_TYPE_INSTANT_GROUP 1

Enables instant trace events with a label and a group. The backend must define this macro to enable this trace type; if left undefined, traces of this type are removed. The macro's value is passed to PW_TRACE and PW_TRACE_DATA as the event_type argument.

Overview

Submodules

Macros

Macro Definition Documentation

◆ PW_TRACE

◆ PW_TRACE_DATA

◆ PW_TRACE_ENABLE

◆ PW_TRACE_END

◆ PW_TRACE_END_DATA

◆ PW_TRACE_END_DATA_FLAG

◆ PW_TRACE_END_FLAG

◆ PW_TRACE_FLAGS

◆ PW_TRACE_FLAGS_DEFAULT

◆ PW_TRACE_FUNCTION

◆ PW_TRACE_FUNCTION_FLAG

◆ PW_TRACE_FUNCTION_LABEL

◆ PW_TRACE_GROUP_LABEL_DEFAULT

◆ PW_TRACE_HAS_GROUP_LABEL

◆ PW_TRACE_HAS_TRACE_ID

◆ PW_TRACE_INSTANT

◆ PW_TRACE_INSTANT_DATA

◆ PW_TRACE_INSTANT_DATA_FLAG

◆ PW_TRACE_INSTANT_FLAG

◆ PW_TRACE_MODULE_NAME

◆ PW_TRACE_SCOPE

◆ PW_TRACE_SCOPE_FLAG

◆ PW_TRACE_START

◆ PW_TRACE_START_DATA

◆ PW_TRACE_START_DATA_FLAG

◆ PW_TRACE_START_FLAG

◆ PW_TRACE_TRACE_ID_DEFAULT

◆ PW_TRACE_TYPE_ASYNC_END

◆ PW_TRACE_TYPE_ASYNC_INSTANT

◆ PW_TRACE_TYPE_ASYNC_START

◆ PW_TRACE_TYPE_DURATION_END

◆ PW_TRACE_TYPE_DURATION_GROUP_END

◆ PW_TRACE_TYPE_DURATION_GROUP_START

◆ PW_TRACE_TYPE_DURATION_START

◆ PW_TRACE_TYPE_INSTANT

◆ PW_TRACE_TYPE_INSTANT_GROUP