Simple and combine events, event buffer slots, and the traceevent_t structure

A simple event is an event that can be described in a single event buffer slot; a combine event is an event that's larger and can be fully described only in multiple event buffer slots. Both simple and combine events consist of only one kernel event.

Each event buffer slot is a traceevent_t structure:

typedef _Uint32t __traceentry;

typedef struct traceevent {
	__traceentry header;  /* CPU, event, format */
	__traceentry data[3]; /* event data         */
} traceevent_t;

The traceevent_t structure is only 16 bytes long, and only half of that describes the event. This small size reduces instrumentation overhead and improves granularity. This “thin” protocol doesn't burden the instrumented kernel and keeps the traceevent_t structure small. The trade-off is that it may take many traceevent_t structures to represent a single kernel event.

In order to distinguish simple events from combine events, the traceevent_t structure includes a 2-bit flag that indicates whether the event is a single event or whether it's the first, middle, or last traceevent_t structure of the event. The flag is also used as a rudimentary integrity check. The timestamp element of the combine event is identical in each buffer slot; no other event will have the same timestamp.

The members of the traceevent_t structure are as follows:

header

An encoded header that identifies the event, event class, the CPU, and whether this structure represents a simple or combine event. Use the macros described below to extract these pieces.

data

The data associated with the event. The first element of this array holds the least significant bits of the time stamp. The contents of the remaining elements depend on the event; see the “Current Trace Events and Data” appendix.

The following macros extract the information from the event header:

_NTO_TRACE_GETCPU(h)

Get the number of the CPU that the event occurred on.

_NTO_TRACE_GETEVENT(h)

Get the type of event.

_NTO_TRACE_GETEVENT_C(h)

Get the class.

_TRACE_GET_STRUCT(h)

Get the flag that indicates whether this is a simple or combine event:

If the flag equals:	The structure is:
_TRACE_STRUCT_CB	The beginning of a combine event
_TRACE_STRUCT_CC	A continuation of a combine event
_TRACE_STRUCT_CE	The end of a combine event
_TRACE_STRUCT_S	A simple event