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:
Buffer and execution control
These commands control the buffer setup, and start and stop logging:
_NTO_TRACE_ALLOCBUFFER, _NTO_TRACE_DEALLOCBUFFER
TraceEvent(_NTO_TRACE_ALLOCBUFFER, uint bufnum, paddr_t *paddr) TraceEvent(_NTO_TRACE_DEALLOCBUFFER)
The allocation option creates and initializes the instrumented kernel's ring 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.
_NTO_TRACE_FLUSHBUFFER
TraceEvent(_NTO_TRACE_FLUSHBUFFER)
Forces flushing of the buffer regardless of the number of trace events it contains.
_NTO_TRACE_OVERWRITEBUFFER
TraceEvent(_NTO_TRACE_OVERWRITEBUFFER)
Overwrite the first buffer when the ring overflows.
_NTO_TRACE_QUERYEVENTS
TraceEvent(_NTO_TRACE_QUERYEVENTS)
Returns the number of simple trace events that are currently stored in the trace buffer.
_NTO_TRACE_QUERYSUPPORT
TraceEvent(_NTO_TRACE_QUERYSUPPORT)
Returns _NTO_TRACE_SUPPINSTR if instrumentation is enabled, or _NTO_TRACE_NOINSTRSUPP if it isn't.
_NTO_TRACE_QUERYVERSION
TraceEvent(_NTO_TRACE_QUERYVERSION)
Returns the version of the OS multiplied by 100.
_NTO_TRACE_SETBUFFER (QNX Neutrino 6.6 or later)
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.
_NTO_TRACE_SETLINEARMODE, _NTO_TRACE_SETRINGMODE
TraceEvent(_NTO_TRACE_SETLINEARMODE) TraceEvent(_NTO_TRACE_SETRINGMODE)
Set the mode for logging the trace events:
The kernel treats its trace buffers as a ring in either mode.
_NTO_TRACE_SKIPBUFFER
TraceEvent(_NTO_TRACE_SKIPBUFFER)
Skip the first buffer when the ring overflows.
_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). This information is overwritten when the kernel reuses the buffer; if you're logging events in ring mode, you can make sure you capture the process names by issuing an _NTO_TRACE_START command followed by _NTO_TRACE_STOP after you've finished tracing.
Fast/wide mode configuration
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, int class) TraceEvent(_NTO_TRACE_DELCLASS, int class)
Emit/suppress all trace events from a specific class.
_NTO_TRACE_ADDEVENT, _NTO_TRACE_DELEVENT
TraceEvent(_NTO_TRACE_ADDEVENT, int class, int event) TraceEvent(_NTO_TRACE_DELEVENT, int class, int 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, uint32_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, uint32_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.
You can use the _NTO_TRACE_GET*() macros to extract the class, event, and CPU from the header member. Note that the class and event numbers are internal representations of the _NTO_TRACE_* numbers.
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.
_NTO_TRACE_ADDEVENTHANDLER, _NTO_TRACE_DELEVENTHANDLER
TraceEvent(_NTO_TRACE_ADDEVENTHANDLER,
int class,
int event,
int (*event_hdlr)(event_data_t*),
event_data_t* data_struct)
TraceEvent(_NTO_TRACE_DELEVENTHANDLER,
int class,
int event)
Attaches/deletes the event handler for a specified class and event, where:
Before attaching an event handler:
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,
int class,
int (*event_hdlr)(event_data_t*),
event_data_t* data_struct)
TraceEvent(_NTO_TRACE_DELCLASSEVHANDLER,
int class)
Attaches/deletes the event handler for a specified class, where:
Before attaching an event handler:
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.
User-generated trace events
These commands let you insert your own events into the event stream:
_NTO_TRACE_INSERTCCLASSEVENT, _NTO_TRACE_INSERTSCLASSEVENT
TraceEvent(_NTO_TRACE_INSERTCCLASSEVENT, int class, int event,
unsigned *buf, unsigned len)
TraceEvent(_NTO_TRACE_INSERTSCLASSEVENT, int class, int event,
int data0, int data1)
These commands insert user-created events of a specified class into the event stream. The API handles details such as timestamping.
The trace_logbc() is a convenient cover function for this command.
_NTO_TRACE_INSERTEVENT
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:
The value that TraceEvent() returns depends on the value of the cmd argument:
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:
If you use TraceEvent() to add a dynamic rules filter, the only library functions that you can call in your event handler are those that are safe to call from an interrupt handler.