Control the tracing of kernel events
#include <sys/neutrino.h>
#include <sys/trace.h>
int TraceEvent( int cmd,
... );
Some commands require additional arguments, as described below. In general, the arguments are grouped logically as follows:
TraceEvent(cmd [,class [,event]] [,p1 [,p2 [,p3 ... [,pn]]]])
Aside from the cmd, these arguments are:
There are also "pseudo classes" defined as a convenience:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
The TraceEvent() function lets you control all stages of the instrumentation process, including initializing, starting, stopping, controlling filters, and inserting events. These stages are broadly grouped into the following categories:
These commands control the buffer setup, and start and stop logging:
_NTO_TRACE_ALLOCBUFFER, _NTO_TRACE_DEALLOCBUFFER
TraceEvent(_NTO_TRACE_ALLOCBUFFER, uint bufnum, void** linkliststart) TraceEvent(_NTO_TRACE_DEALLOCBUFFER)
The allocation option creates and initializes the instrumented kernel's internal circular linked list of trace buffers. These buffers hold the emitted trace events. The extra arguments for the _NTO_TRACE_ALLOCBUFFER command are:
Allocated trace buffers can store 1024 simple trace events.
The deallocation option deallocates all of the previously allocated trace buffers. All events stored in the trace buffers are lost.
TraceEvent(_NTO_TRACE_FLUSHBUFFER)
Forces flushing of the buffer regardless of the trace event number it contains.
TraceEvent(_NTO_TRACE_QUERYEVENTS)
Returns the number of simple trace events that are currently stored in the trace buffer.
_NTO_TRACE_START, _NTO_TRACE_STARTNOSTATE, _NTO_TRACE_STOP
TraceEvent(_NTO_TRACE_START) TraceEvent(_NTO_TRACE_STARTNOSTATE) TraceEvent(_NTO_TRACE_STOP)
These commands start and stop the instrumentation process. The event stream containing the trace events is opened or closed as appropriate.
The _NTO_TRACE_START and _NTO_TRACE_STARTNOSTATE options are similar, except that the latter suppresses the initial system state information (thread IDs and names of processes).
TraceEvent(_NTO_TRACE_SETBUFFER, paddr64_t addr, size_t size)
Use the previously allocated physical memory, at the given address and for the given size, as the trace buffer. The intended application is to place the buffer in an area of memory that will be preserved across system resets, facilitating post-crash analysis.
TraceEvent(_NTO_TRACE_SETRINGMODE)
Use the internal circular linked list in ring mode. In ring mode, the kernel stores all events in a circular fashion inside the linked list without flushing them. The maximum capturing time (without history overwriting) is determined by the number of allocated buffers, as well as by the number of generated trace events.
TraceEvent(_NTO_TRACE_SETLINEARMODE)
Use the internal circular linked list in linear mode (the default). When you use this mode, every filled-up buffer is captured and flushed immediately.
These commands control whether fast or wide events are emitted:
For more information about fast and wide modes, see the System Analysis Toolkit User's Guide:
_NTO_TRACE_SETALLCLASSESFAST, _NTO_TRACE_SETALLCLASSESWIDE
TraceEvent(_NTO_TRACE_SETALLCLASSESFAST) TraceEvent(_NTO_TRACE_SETALLCLASSESWIDE)
Sets the fast/wide emitting mode for all classes and events.
_NTO_TRACE_SETCLASSFAST, _NTO_TRACE_SETCLASSWIDE
TraceEvent(_NTO_TRACE_SETCLASSFAST, int class) TraceEvent(_NTO_TRACE_SETCLASSWIDE, int class)
Sets the fast/wide emitting mode for all events within the specified class.
_NTO_TRACE_SETEVENTFAST, _NTO_TRACE_SETEVENTWIDE
TraceEvent(_NTO_TRACE_SETEVENTFAST, int class, int event) TraceEvent(_NTO_TRACE_SETEVENTWIDE, int class, int event)
Sets the fast/wide emitting mode for the specified event for the specified class.
Static rules filter configuration
These commands control the operation of the static rules filter:
For more information about this filter, see the Filtering chapter in the System Analysis Toolkit User's Guide.
_NTO_TRACE_ADDALLCLASSES, _NTO_TRACE_DELALLCLASSES
TraceEvent(_NTO_TRACE_ADDALLCLASSES) TraceEvent(_NTO_TRACE_DELALLCLASSES)
Emit/suppress trace events for all classes and events.
_NTO_TRACE_ADDCLASS, _NTO_TRACE_DELCLASS
TraceEvent(_NTO_TRACE_ADDCLASS, class) TraceEvent(_NTO_TRACE_DELCLASS, class)
Emit/suppress all trace events from a specific class.
_NTO_TRACE_ADDEVENT, _NTO_TRACE_DELEVENT
TraceEvent(_NTO_TRACE_ADDEVENT, class, event) TraceEvent(_NTO_TRACE_DELEVENT, class, event)
Emit/suppress a trace event from a specific class.
_NTO_TRACE_SETCLASSPID, _NTO_TRACE_CLRCLASSPID, _NTO_TRACE_SETCLASSTID, _NTO_TRACE_CLRCLASSTID
TraceEvent(_NTO_TRACE_SETCLASSPID, int class, pid_t pid) TraceEvent(_NTO_TRACE_CLRCLASSPID, int class) TraceEvent(_NTO_TRACE_SETCLASSTID, int class, pid_t pid, tid_t tid) TraceEvent(_NTO_TRACE_CLRCLASSTID, int class)
Emit/suppress all events from a specified process ID (and thread ID).
_NTO_TRACE_SETEVENTPID, _NTO_TRACE_CLREVENTPID, _NTO_TRACE_SETEVENTTID, _NTO_TRACE_CLREVENTTID
TraceEvent(_NTO_TRACE_SETEVENTPID, int class, int event, pid_t pid)
TraceEvent(_NTO_TRACE_CLREVENTPID, int class, int event)
TraceEvent(_NTO_TRACE_SETEVENTTID, int class, int event,
pid_t pid, tid_t tid)
TraceEvent(_NTO_TRACE_CLREVENTTID, int class, int event)
Emit/suppress a specific event for a specified process ID (and thread ID).
Dynamic rules filter configuration
These commands control the operation of the dynamic rules filter, in which you set up handlers for the events you're interested in:
For more information about this filter, see the Filtering chapter in the System Analysis Toolkit User's Guide.
Accessing data in the event handler
You can access the trace event information from within the event handler by using members of the event_data_t structure.
The layout of the event_data_t structure (declared in <sys/trace.h>) is as follows:
/* event data filled by an event handler */
typedef struct
{
__traceentry header; /* same as traceevent header */
uint32_t* data_array; /* initialized by the user */
uint32_t el_num; /* number of elements returned */
void* area; /* user data */
uint32_t feature_mask;/* bits indicate valid features */
uint32_t feature[_NTO_TRACE_FI_NUM]; /* feature array
- additional data */
} event_data_t;
event_data_t e_d_1; uint32_t data_array_1[20]; /* 20 elements for potential args. */ e_d_1.data_array = data_array_1;
If you don't provide the data array, or it isn't big enough, your data segment could become corrupted.
The bits of the member feature_mask are related to any additional features (arguments) that could be accessed inside the event handler. All standard data arguments — the ones that correspond to the data arguments of the trace event — are delivered without changes within the data_array.
There are two constants associated with each additional feature:
The currently defined features are:
| Feature | Parameter mask | Index |
|---|---|---|
| Process ID | _NTO_TRACE_FMPID | _NTO_TRACE_FIPID |
| Thread ID | _NTO_TRACE_FMTID | _NTO_TRACE_FITID |
If any particular bit of the feature_mask is set to 1, then you can access the feature corresponding to this bit within the feature array. Otherwise, you must not access the feature.
Macros for use with the event header
You can use the following macros, defined in <sys/trace.h>, to work with the header of an event:
_NTO_TRACE_ADDEVENTHANDLER, _NTO_TRACE_DELEVENTHANDLER
TraceEvent(_NTO_TRACE_ADDEVENTHANDLER,
class,
event,
int (*event_hdlr)(event_data_t*),
event_data_t* data_struct)
TraceEvent(_NTO_TRACE_DELEVENTHANDLER,
class,
event)
Attaches/deletes the event handler for a specified class and event, where:
Before attaching an event handler, the thread must:
ThreadCtl( _NTO_TCTL_IO, 0 );
If the thread doesn't do all of the above, the attachment fails with an error code of EPERM.
In order to emit an event data, a dynamic filter (event handler) has to return a non-zero value. If both types of the dynamic filters (event handler and class event handler) are applicable to a particular event, the event is emitted if both event handlers return non-zero values.
_NTO_TRACE_ADDCLASSEVHANDLER, _NTO_TRACE_DELCLASSEVHANDLER
TraceEvent(_NTO_TRACE_ADDCLASSEVHANDLER,
class,
int (*event_hdlr)(event_data_t*),
event_data_t* data_struct)
TraceEvent(_NTO_TRACE_DELCLASSEVHANDLER,
class)
Attaches/deletes the event handler for a specified class, where:
Before attaching an event handler, the thread must:
ThreadCtl( _NTO_TCTL_IO, 0 );
If the thread doesn't do all of the above, the attachment fails with an error code of EPERM.
In order to emit an event data, a dynamic filter (event handler) has to return a non-zero value. If both types of the dynamic filters (event handler and class event handler) are applicable to a particular event, the event is emitted if both event handlers return non-zero values.
These commands let you insert your own events into the event stream:
TraceEvent(_NTO_TRACE_INSERTEVENT, int head, int stamp,
int data0, int data1)
Inserts an event of an arbitrary type and class into the event stream. It's powerful, but because the API doesn't do any of the interpretation for you, you should use this function (with care!) only if you're an advanced user. You'll have to modify the data-interpretation program to properly interpret the event.
The arguments are:
Instead of using the _NTO_TRACE_INSERTEVENT command directly, you can use the following convenience functions:
_NTO_TRACE_INSERTSUSEREVENT, _NTO_TRACE_INSERTCUSEREVENT, _NTO_TRACE_INSERTUSRSTREVENT
TraceEvent(_NTO_TRACE_INSERTSUSEREVENT, int event, int data0,
int data1)
TraceEvent(_NTO_TRACE_INSERTCUSEREVENT, int event, unsigned * buf,
unsigned len)
TraceEvent(_NTO_TRACE_INSERTUSRSTREVENT, int event, const char * str)
These commands insert user-created events into the event stream. Because the API handles details such as timestamping, they're reasonably easy to use. The class is _NTO_TRACE_USER.
The event argument must be in the range from _NTO_TRACE_USERFIRST through _NTO_TRACE_USERLAST, but you can decide what each event means.
Instead of using these commands directly, you can use the following convenience functions:
See the Tutorials chapter of the System Analysis Toolkit User's Guide.
| Safety: | |
|---|---|
| Cancellation point | No |
| Interrupt handler | Read the Caveats |
| Signal handler | Yes |
| Thread | Yes |
You can call TraceEvent() from an interrupt/event handler. However, not all commands are valid in this case. The valid commands are: