TraceEvent()

Control the tracing of kernel events

Synopsis:

#include <sys/neutrino.h>
#include <sys/trace.h>

int TraceEvent( int cmd, 
                ... );

Arguments:

cmd
The control action that you want to make; one of the following:

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:

class
The category of events. All the events are logically grouped into the following classes:

There are also “pseudo classes” defined as a convenience:

event
The event. Because the events are grouped by class, the event must be a member of the class in order to be valid. For more information, see the Events and the Kernel chapter and the Current Trace Events and Data appendix of the System Analysis Toolkit User's Guide.
p1...pn
Any additional parameters that are required to perform the desired control action.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

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:


Note: Filter and mode settings are made regardless of the previous settings. Use care to not accidentally override or delete previous configurations.

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, 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:

bufnum
Number of buffers to allocate.
*linkliststart
Physical address of the beginning of the circular linked list of allocated trace buffers.

Allocated trace buffers can store 1024 simple trace events.


Note: If your application calls TraceEvent() with these commands, it must run as root.

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 trace event number it contains.

_NTO_TRACE_QUERYEVENTS

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).

_NTO_TRACE_SETRINGMODE

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.

_NTO_TRACE_SETLINEARMODE

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.

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, 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:


Note: In order to set up the dynamic rules filter, your application must call ThreadCtl() with the _NTO_TCTL_IO flag to get I/O privileges.

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    */
    _Uint32t*    data_array;  /* initialized by the user      */
    _Uint32t     el_num;      /* number of elements returned  */
    void*        area;        /* user data                    */
    _Uint32t     feature_mask;/* bits indicate valid features */
    _Uint32t     feature[_NTO_TRACE_FI_NUM]; /* feature array 
                                            - additional data */
    } event_data_t;

Caution: The event_data_t structure includes a pointer to an array for the data arguments of the event. You must provide an array, and it must be large enough to hold the data for the event or events that you're handling (see the Current Trace Events and Data appendix of the System Analysis Toolkit User's Guide). For example:
event_data_t e_d_1;
_Uint32t     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_GETEVENT_C(c)
Get the class.
_NTO_TRACE_GETEVENT(c)
Get the type of event.
_NTO_TRACE_GETCPU(h)
Get the number of the CPU that the event occurred on.
_NTO_TRACE_SETEVENT_C(c,cl)
Set the class in the header c to be cl.
_NTO_TRACE_SETEVENT(c, e)
Set the event type in the header c to be e.

_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:

event_hdlr
Pointer to the event handler.
data_struct
Pointer to the data structure event_data_t.

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:

event_hdlr
Pointer to the event handler.
data_struct
Pointer to the data structure event_data_t.

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_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:

head
Header of the trace event.
stamp
Time stamp.
data0
Data d0.
data1
Data d1.

Instead of using the _NTO_TRACE_INSERTEVENT command directly, you can use the following convenience functions:

trace_func_enter()
Insert a trace event for the entry to a function
trace_func_exit()
Insert a trace event for the exit from a function
trace_here()
Insert a trace event for the current address
trace_logbc()
Insert a trace event of an arbitrary class and type with arbitrary data

_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.

_NTO_TRACE_INSERTSUSEREVENT
Add a user simple event containing the data defined by data0 and data1.
_NTO_TRACE_INSERTCUSEREVENT
Add a user combine event containing the data that buf holds.

Note: The len argument represents the number of integers (not bytes) in buf.

_NTO_TRACE_INSERTUSRSTREVENT
Add a user string event containing the null-terminated string defined by str.

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:

trace_logb()
Insert a user combine trace event
trace_logf()
Insert a user string trace event
trace_logi()
Insert a user simple trace event
trace_nlogf()
Insert a user string trace event, specifying a maximum string length
trace_vnlogf()
Insert a user string trace event, using a variable argument list

Returns:

If cmd is set to _NTO_TRACE_QUERYEVENTS
Number of events in the buffer, or -1 if an error occurs (errno is set).
If cmd isn't set to _NTO_TRACE_QUERYEVENTS
0 for success, or -1 if an error occurs (errno is set).

Errors:

ECANCELED
The requested action has been canceled.
EFAULT
Bad internal trace buffer address. The requested action has been specified out of order.
ENOMEM
Insufficient memory to allocate the trace buffers.
ENOTSUP
The requested action isn't supported.
EPERM
The application doesn't have permission to perform the action.

Examples:

See the Tutorials chapter of the System Analysis Toolkit User's Guide.

Classification:

QNX Neutrino

Safety:
Cancellation point No
Interrupt handler Read the Caveats
Signal handler Yes
Thread Yes

Caveats:

You can call TraceEvent() from an interrupt/event handler. However, not all commands are valid in this case. The valid commands are:

See also:

InterruptAttach(), InterruptHookTrace(), trace_func_enter(), trace_func_exit(), trace_here(), trace_logb(), trace_logbc(), trace_logf(), trace_logi(), trace_nlogf(), trace_vnlogf()

tracelogger in the Utilities Reference

System Analysis Toolkit User's Guide

Analyzing Your System with Kernel Tracing chapter of the Integrated Development Environment User's Guide