pw_trace_tokenized

Overview

Main docs: Home

Classes
class	pw::trace::BaseTraceService
class	pw::trace::TraceService
class	pw::trace::internal::TraceQueue< kSize >
struct	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock
class	pw::trace::TokenizedTracer
class	pw::trace::TraceTransferHandler
class	pw::trace::TraceBufferReader

Macros
#define	PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES   20
#define	PW_TRACE_QUEUE_SIZE_EVENTS   5
#define	PW_TRACE_TIME_TYPE   uint32_t
	The type for trace time.
#define	PW_TRACE_GET_TIME_DELTA(last_time, current_time)    ((current_time) - (last_time))
#define	PW_TRACE_CONFIG_MAX_EVENT_CALLBACKS   2
	The maximum number of event callbacks which can be registered at a time.
#define	PW_TRACE_CONFIG_MAX_SINKS   2
	The maximum number of encoded event sinks which can be registered at a time.
#define	PW_TRACE_BUFFER_SIZE_BYTES   256
#define	PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES   (32)
#define	PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES
#define	PW_TRACE_BUFFER_MAX_BLOCK_SIZE_BYTES    PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES + PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES
#define	PW_TRACE_SET_ENABLED(enabled)   pw_trace_Enable(enabled)
	Enables or disables tracing.
#define	PW_TRACE_REF(event_type, module, label, flags, group)
#define	PW_TRACE_REF_DATA(event_type, module, label, flags, group, type)

Typedefs
typedef uint32_t	pw_trace_TraceEventReturnFlags
typedef size_t	pw_trace_EventCallbackHandle
typedef pw_trace_TraceEventReturnFlags(*	pw_trace_EventCallback) (void *user_data, pw_trace_tokenized_TraceEvent *event)
typedef void(*	pw_trace_SinkStartBlock) (void *user_data, size_t size)
typedef void(*	pw_trace_SinkAddBytes) (void *user_data, const void *bytes, size_t size)
typedef void(*	pw_trace_SinkEndBlock) (void *user_data)
typedef size_t	pw_trace_SinkHandle

Enumerations
enum	pw_trace_ShouldCallOnEveryEvent { PW_TRACE_CALL_ONLY_WHEN_ENABLED = 0 , PW_TRACE_CALL_ON_EVERY_EVENT = 1 }
enum	{ PW_TRACE_EVENT_RETURN_FLAGS_NONE = 0 , PW_TRACE_EVENT_RETURN_FLAGS_SKIP_EVENT = 1 << 0 , PW_TRACE_EVENT_RETURN_FLAGS_DISABLE_AFTER_PROCESSING = 1 << 1 }

Functions
uint32_t	pw_trace_GetTraceTime (void)
size_t	pw_trace_GetTraceTimeTicksPerSecond (void)
pw_Status	pw_trace_RegisterEventCallback (pw_trace_EventCallback callback, pw_trace_ShouldCallOnEveryEvent called_on_every_event, void *user_data, pw_trace_EventCallbackHandle *handle)
pw_Status	pw_trace_UnregisterEventCallback (pw_trace_EventCallbackHandle handle)
	Causes the callback to not receive any more events.
pw_Status	pw_trace_RegisterSink (pw_trace_SinkStartBlock start_func, pw_trace_SinkAddBytes add_bytes_func, pw_trace_SinkEndBlock end_block_func, void *user_data, pw_trace_SinkHandle *handle)
pw_Status	pw_trace_UnregisterSink (pw_trace_SinkHandle handle)
	Causes the sink to stop receiving trace data.
pw::Status	pw::trace::internal::TraceQueue< kSize >::TryPushBack (uint32_t trace_token, EventType event_type, const char *module, uint32_t trace_id, uint8_t flags, const void *data_buffer, size_t data_size)
const volatile QueueEventBlock *	pw::trace::internal::TraceQueue< kSize >::PeekFront () const
void	pw::trace::internal::TraceQueue< kSize >::PopFront ()
void	pw::trace::internal::TraceQueue< kSize >::Clear ()
bool	pw::trace::internal::TraceQueue< kSize >::IsEmpty () const
bool	pw::trace::internal::TraceQueue< kSize >::IsFull () const
	pw::trace::TokenizedTracer::TokenizedTracer (Callbacks &callbacks)
void	pw::trace::TokenizedTracer::Enable (bool enable)
bool	pw::trace::TokenizedTracer::IsEnabled () const
void	pw::trace::TokenizedTracer::HandleTraceEvent (uint32_t trace_token, EventType event_type, const char *module, uint32_t trace_id, uint8_t flags, const void *data_buffer, size_t data_size)
TokenizedTracer &	pw::trace::GetTokenizedTracer ()
TraceBufferReader &	pw::trace::GetTraceBufferReader ()

Variables
uint32_t	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock::trace_token
EventType	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock::event_type
const char *	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock::module
uint32_t	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock::trace_id
uint8_t	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock::flags
size_t	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock::data_size
std::byte	pw::trace::internal::TraceQueue< kSize >::QueueEventBlock::data_buffer [PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES]

Macro Definition Documentation

PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES

#define PW_TRACE_BUFFER_MAX_DATA_SIZE_BYTES   (32)

The maximum size any individual encoded trace event could be. This is used internally to buffer up a sample before saving into the buffer. The below calculation is provided to help determine a suitable value, using the max data size bytes.

PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES

#define PW_TRACE_BUFFER_MAX_HEADER_SIZE_BYTES

Value:

  (pw::varint::kMaxVarint64SizeBytes) +     /* worst case delta time varint */ \
      (sizeof(uint32_t)) +                  /* trace token size */             \
      (pw::varint::kMaxVarint64SizeBytes) + /* worst case trace id varint */

PW_TRACE_BUFFER_SIZE_BYTES

#define PW_TRACE_BUFFER_SIZE_BYTES   256

The size in bytes of the optional trace buffer. The buffer is automatically registered at boot if the buffer size is not 0.

PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES

#define PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES   20

Since not all strings are tokenizeable, labels can be passed as arguments. PW_TRACE_CONFIG_ARG_LABEL_SIZE_BYTES configures the maximum number of characters to include, if more are provided the string will be clipped.

PW_TRACE_GET_TIME_DELTA

#define PW_TRACE_GET_TIME_DELTA	(		last_time,
			current_time
	)		((current_time) - (last_time))

The macro which is called to determine the delta between two PW_TRACE_TIME_TYPE variables. It should return a delta of the two times, in the same type. The default implementation just subtracts the two, which is suitable if values either never wrap, or are unsigned and do not wrap multiple times between trace events. If either of these are not the case a different implementation should be used.

PW_TRACE_QUEUE_SIZE_EVENTS

#define PW_TRACE_QUEUE_SIZE_EVENTS   5

The number of events which can be queued up internally. This is needed to support concurrent trace events.

PW_TRACE_REF

#define PW_TRACE_REF	(		event_type,
			module,
			label,
			flags,
			group
	)

Value:

  PW_TOKENIZE_STRING_DOMAIN("trace",                                   \
                            PW_STRINGIFY(event_type) "|" PW_STRINGIFY( \
                                flags) "|" module "|" group "|" label)

Provides the uint32_t token value for a specific trace event. This can be used in the callback to perform specific actions for that trace. All the fields must match exactly to generate the correct trace reference. If the trace does not have a group, use PW_TRACE_GROUP_LABEL_DEFAULT.

For example this can be used to skip a specific trace:

pw_trace_TraceEventReturnFlags TraceEventCallback(
    uint32_t trace_ref,
    pw_trace_EventType event_type,
    const char* module,
    uint32_t trace_id,
    uint8_t flags) {
  auto skip_trace_ref = PW_TRACE_REF(PW_TRACE_TYPE_INSTANT,
                                     "test_module",    // Module
                                     "test_label",     // Label
                                     PW_TRACE_FLAGS_DEFAULT,
                                     PW_TRACE_GROUP_LABEL_DEFAULT);
  if (trace_ref == skip_trace_ref) {
    return PW_TRACE_EVENT_RETURN_FLAGS_SKIP_EVENT;
  }
  return 0;
}

The above trace ref would provide the token value for the string: 1|0|test_module||test_label

Another example:

#define PW_TRACE_MODULE test_module
PW_TRACE_INSTANT_DATA_FLAG(2, "label", "group", id, "%d", 5, 1);

Would internally generate a token value for the string: 1|2|test_module|group|label|d

The trace_id and data value are runtime values and not included in the token string.

PW_TRACE_REF_DATA

#define PW_TRACE_REF_DATA	(		event_type,
			module,
			label,
			flags,
			group,
			type
	)

Value:

  PW_TOKENIZE_STRING_DOMAIN(                                                \
      "trace",                                                              \
      PW_STRINGIFY(event_type) "|" PW_STRINGIFY(flags) "|" module "|" group \
                                                       "|" label "|" type)

Typedef Documentation

pw_trace_SinkStartBlock

typedef void(* pw_trace_SinkStartBlock) (void *user_data, size_t size)

The pw_trace_Sink* functions are called after the trace event is encoded. Trace will internally handle locking, so every Start event will have a matching End event before another sequence is started. The number of bytes sent to AddBytes will be the number provided at the start, allowing buffers to allocate the required amount at the start when necessary.

If OkStatus() is not returned from Start, the events bytes will be skipped.

Note

Called while tracing is locked (which might be a critical section depending on application), so quick/simple operations only. One trace event might result in multiple callbacks if the data is split up.

If a handle pointer is provided it will be set to a value, which can be later used to unregister the callback.

The user_data pointer is provider for use by the application, it can be used to allow a single function callback to be registered multiple times but act differently by providing it with different user_data values.

Note

Since callbacks are called within the trace event lock, they should not register/unregister sinks or callbacks or trigger other trace events.

Enumeration Type Documentation

pw_trace_ShouldCallOnEveryEvent

enum pw_trace_ShouldCallOnEveryEvent

pw_trace_EventCallback is called before the sample is encoded or sent to the sinks. Bits in the return argument can be set to change the behavior of tracing.

• PW_TRACE_EVENT_RETURN_FLAGS_SKIP_EVENT can optionally be set true to skip this sample.
• PW_TRACE_EVENT_RETURN_FLAGS_DISABLE_AFTER_PROCESSING can be set true to disable tracing after this sample.

When registering the callback the parameter called_on_every_event is used to indicate if the callback should be called even when tracing is disabled. This behavior is useful to implement a tracing behaviour, where tracing can turn on when a specific event occurs.

If a handle pointer is provided it will be set to a value, which can be later used to unregister the callback.

The user_data pointer is provided for use by the application. It can be used to allow a single function callback to be registered multiple times but act differently by providing it with different context objects as pointers.

Note

Since callbacks are called within the trace event lock, they should not register/unregister sinks or callbacks or trigger other trace events.

Function Documentation

GetTokenizedTracer()

TokenizedTracer & pw::trace::GetTokenizedTracer

(

)

Returns

A reference of the global tokenized tracer

pw_trace_GetTraceTime()

uint32_t pw_trace_GetTraceTime

(

void

)

The macro which is called to get the current time for a trace event. It must be provided by the platform.

pw_trace_GetTraceTimeTicksPerSecond()

size_t pw_trace_GetTraceTimeTicksPerSecond

(

void

)

The function which is called to determine the unit of the trace time. It must be provided by the platform.