TraceEvent()

Trace kernel events

Synopsis:

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

int TraceEvent( int mode, 
                ... );

The TraceEvent() function controls all stages of the instrumentation process including initialization, starting, stopping, filter control and event insertion. These stages are broadly grouped into the following categories:

Buffer and execution control
Fast/wide mask configuration
Static rules filter configuration
Dynamic rules filter configuration
User-generated trace events

This description also includes these sections:

Argument descriptions
class argument descriptions

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

Buffer and execution control

These modes control the buffer set up as well as 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 internal circular link list of trace buffers. The created and initialized trace buffers hold the emitting trace events.

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

Allocated trace buffers can store 1024 simple trace events.

If your application calls this mode, it must run as root.

The deallocation option deallocates all of the previously allocated trace buffers. All events stored inside of the trace buffers are lost.

_NTO_TRACE_FLUSHBUFFER

TraceEvent(_NTO_TRACE_FLUSHBUFFER)

Forces flashing 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's 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)

Starts/stops the instrumentation process. The event stream containing the trace events is opened/closed.

The _NTO_TRACE_START and _NTO_TRACE_STARTNOSTATE options are the same except the latter suppresses the initial system state information (names of processes and thread IDs.)

_NTO_TRACE_SETRINGMODE

TraceEvent(_NTO_TRACE_SETRINGMODE)

Sets a ring mode of the internal circular link list. When an external application uses this mode, the kernel stores all events in a circular fashion inside the link 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)

Sets a default linear mode of the internal circular link list. When using this mode, every filled-up buffer is captured and flushed immediately.

Fast/wide mask configuration

These modes control the operation of the fast/wide mask. For more information about this mask, see the Filtering chapter in the System Analysis Toolkit User's Guide.

Currently, only the kernel call related classes are affected by the fast/wide modes. In fast mode, only two of the most important kernel call arguments and two of the most important kernel call return values are intercepted. See the Kernel call arguments and return values appendix for the list of the intercepted arguments and return values.

_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 modes 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)

Emits/suppresses 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)

Emits/suppresses a specific event for a specified process ID (and thread ID.)

Dynamic rules filter configuration

These modes control the operation of the dynamic rules filter. For more information about this filter, see the Filtering chapter in the System Analysis Toolkit User's Guide.

Event Handler Data Access

The access to the trace event information from within the event handler can be done using members of the event_data_t.

The valid layout of the event_data_t structure (declared in sys/trace.h) is as follow:

/* 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;

The bits of the member feature_mask are related to any additional feature (argument) 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. If any particular bit of the feature_mask is set to 1, then the feature corresponding to this bit can be accessed within the feature array. Otherwise, the feature should not be accessed. For example, if the expression:

feature_mask & _NTO_TRACE_FMPID

has its logical value equal to TRUE, then, the additional feature corresponding to identifier _NTO_TRACE_FMPID (PID) can be accessed as:

my_pid = feature[_NTO_TRACE_FIPID];

For every additional feature there have been provided two constants:

_NTO_TRACE_FM*** - feature parameter masks

_NTO_TRACE_FI*** - feature index parameters

to check and to access the given feature.

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

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

User-generated trace events

These modes control the insertion of “fake” events into the event stream.

_NTO_TRACE_INSERTEVENT

TraceEvent(_NTO_TRACE_INSERTEVENT, int head, int stamp,
           int data0, int data1)

Inserts a generic, “real” event into the event stream. It's powerful but because the API doesn't do any of the interpretation for you, this function should be used with care by advanced users only. The data-interpretation program must be modified to properly interpret the event.

The arguments are:

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

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

The len argument represents the number of integers in buf.

These modes insert user-created events into the event stream. Because the API handles details such as timestamping, they're reasonably easy to use.

_NTO_TRACE_INSERTSUSEREVENT: Simple user event.
_NTO_TRACE_INSERTCUSEREVENT: Complex user event.
_NTO_TRACE_INSERTUSRSTREVENT: User string event.

The arguments are:

event: User defined event code. The value should be between _NTO_TRACE_USERFIRST and _NTO_TRACE_USERLAST.
str: Null terminated string.
data0: Data d0.
data1: Data d1.

The TraceEvent() function controls all stages of the instrumentation process such as initialization, starting, execution control, and stopping. These stages consist of the following activities:

creating an internal circular linked list of trace buffers
initializing filters
turning on or off the event stream
deallocating the internal circular linked list of trace buffers

The TraceEvent() function accepts any number of arguments grouped logically as follows:

TraceEvent(mode [,class [,event]] [,p1 [,p2 [,p3 ... [,pn]]]])

Here's a description of the arguments:

mode

Specifies a control action (compulsory).

You'll find a description for each mode argument listed below in the mode argument descriptions section.

Some mode arguments require additional arguments; see the table of argument hierarchy for details. Valid arguments are:

_NTO_TRACE_ADDALLCLASSES
_NTO_TRACE_ADDCLASS
_NTO_TRACE_ADDEVENT
_NTO_TRACE_ADDEVENTHANDLER
_NTO_TRACE_ALLOCBUFFER
_NTO_TRACE_CLRCLASSPID
_NTO_TRACE_CLRCLASSTID
_NTO_TRACE_CLREVENTPID
_NTO_TRACE_CLREVENTTID
_NTO_TRACE_DEALLOCBUFFER
_NTO_TRACE_DELALLCLASSES
_NTO_TRACE_DELCLASS
_NTO_TRACE_DELEVENT
_NTO_TRACE_DELEVENTHANDLER
_NTO_TRACE_FLUSHBUFFER
_NTO_TRACE_INSERTCUSEREVENT
_NTO_TRACE_INSERTEVENT
_NTO_TRACESUSEREVENT
_NTO_TRACE_INSERTUSRSTREVENT
_NTO_TRACE_QUERYEVENTS
_NTO_TRACE_SETRINGMODE
_NTO_TRACE_SETLINEARMODE
_NTO_TRACE_SETALLCLASSESFAST
_NTO_TRACE_SETALLCLASSESWIDE
_NTO_TRACE_SETCLASSFAST
_NTO_TRACE_SETCLASSPID
_NTO_TRACE_SETCLASSTID
_NTO_TRACE_SETCLASSWIDE
_NTO_TRACE_SETEVENTFAST
_NTO_TRACE_SETEVENTPID
_NTO_TRACE_SETEVENTTID
_NTO_TRACE_SETEVENTWIDE
_NTO_TRACE_START
_NTO_TRACE_STOP
_NTO_TRACE_STARTNOSTATE

class

You'll find a description for each class argument listed below in the class argument descriptions section. Some class arguments may require additional arguments; see the table of argument hierarchy for details.

Valid arguments are:

_NTO_TRACE_CONTROL
_NTO_TRACE_INT
_NTO_TRACE_INTENTER
_NTO_TRACE_INTEXIT
_NTO_TRACE_KERCALL
_NTO_TRACE_KERCALLENTER
_NTO_TRACE_KERCALLEXIT
_NTO_TRACE_PROCESS
_NTO_TRACE_THREAD
_NTO_TRACE_VTHREAD

event

Redirects the control action specified by the mode and class towards a trace event within the class.

You'll find a description for each event argument listed below in the event argument descriptions section. Some event arguments may require additional arguments; see the table of argument hierarchy for details.

The following table shows the valid event arguments for a particular class:

If the value of class is:	Then a valid event argument is:
_NTO_TRACE_CONTROL	_NTO_TRACE_CONTROLTIME
_NTO_TRACE_INT, _NTO_TRACE_INTENTER, _NTO_TRACE_INTEXIT	a logical interrupt vector number
_NTO_TRACE_KERCALL, _NTO_TRACE_KERCALLENTER, _NTO_TRACE_KERCALLEXIT	A valid __KER_* keyword from `<sys/kercalls.h>` (such as __KER_MSG_SENDV.)
_NTO_TRACE_PROCESS	_NTO_TRACE_PROCCREATE, _NTO_TRACE_PROCCREATE_NAME, _NTO_TRACE_PROCDESTROY, _NTO_TRACE_PROCDESTROY_NAME
_NTO_TRACE_THREAD	_NTO_TRACE_THCONDVAR, _NTO_TRACE_THCREATE, _NTO_TRACE_THDEAD, _NTO_TRACE_THDESTROY, _NTO_TRACE_THINTR, _NTO_TRACE_THJOIN, _NTO_TRACE_THMUTEX, _NTO_TRACE_THNANOSLEEP, _NTO_TRACE_THNET_REPLY, _NTO_TRACE_THNET_SEND, _NTO_TRACE_THREADY, _NTO_TRACE_THRECEIVE, _NTO_TRACE_THREPLY, _NTO_TRACE_THRUNNING, _NTO_TRACE_THSEM, _NTO_TRACE_THSEND, _NTO_TRACE_THSIGSUSPEND, _NTO_TRACE_THSIGWAITINFO, _NTO_TRACE_THSTACK, _NTO_TRACE_THSTOPPED, _NTO_TRACE_THWAITCTX, _NTO_TRACE_THWAITPAGE, _NTO_TRACE_THWAITTHREAD
_NTO_TRACE_VTHREAD	_NTO_TRACE_VTHCONDVAR, _NTO_TRACE_VTHCREATE, _NTO_TRACE_VTHDEAD, _NTO_TRACE_VTHDESTROY, _NTO_TRACE_VTHINTR, _NTO_TRACE_VTHJOIN, _NTO_TRACE_VTHMUTEX, _NTO_TRACE_VTHNANOSLEEP, _NTO_TRACE_VTHNET_REPLY, _NTO_TRACE_VTHNET_SEND, _NTO_TRACE_VTHREADY, _NTO_TRACE_VTHRECEIVE, _NTO_TRACE_VTHREPLY, _NTO_TRACE_VTHRUNNING, _NTO_TRACE_VTHSEM, _NTO_TRACE_VTHSEND, _NTO_TRACE_VTHSIGSUSPEND, _NTO_TRACE_VTHSIGWAITINFO, _NTO_TRACE_VTHSTACK, _NTO_TRACE_VTHSTOPPED, _NTO_TRACE_VTHWAITCTX, _NTO_TRACE_VTHWAITPAGE, _NTO_TRACE_VTHWAITTHREAD

p1...pn

Specifies any additional parameters that are required to perform the desired control action.

Argument descriptions

The following are the generic arguments used for the TraceEvent() modes. Mode-specific arguments accompany the mode description:

mode: The control action. The mode is always the first argument in the TraceEvent() function. Depending upon the value of mode, further arguments may be necessary. The description of what each mode does appears earlier in this section. Examples of the mode include: _NTO_TRACE_ALLOCBUFFER,, _NTO_TRACE_SETCLASSFAST.
class: The category of events. All the events are logically grouped into several classes. A list of valid classes is given in class argument descriptions, later in this section.
event: The event. Because the events are grouped by class, the event must be a member of the class in order to be valid. A list of events can be found in the Kernel Call Arguments and Return Values chapter in the System Analysis Toolkit User's Guide.
pid: Process ID to be registered.
tid: Thread ID to be registered.

class argument descriptions

The class argument may be one of the following:

_NTO_TRACE_CONTROL: Specifies the set of control events (i.e. time-overflow event) that're used by the communication protocol between the microkernel and tracelogger.
_NTO_TRACE_INTENTER, _NTO_TRACE_INTEXIT: Specifies the set of interrupt entry/exit events.
_NTO_TRACE_KERCALLENTER, _NTO_TRACE_KERCALLEXIT: Specifies the set of kernel call entry/exit events.
_NTO_TRACE_PROCESS: Specifies the set of events associated with process creation and destruction.
_NTO_TRACE_THREAD, _NTO_TRACE_VTHREAD: Specifies the set of class arguments that contain thread (or virtual thread) state changes, and create or destroy events.

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

_NTO_TRACE_KERCALL: Specifies all of the kernel call events: _NTO_TRACE_KERCALLENTER and _NTO_TRACE_KERCALLEXIT.
_NTO_TRACE_INT: Specifies all of the interrupt events: _NTO_TRACE_INTENTER and _NTO_TRACE_INTEXIT.

Returns:

If mode is set to _NTO_TRACE_QUERYEVENTS: Number of events in the buffer, or -1 if an error occurs (errno is set).
If mode 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.
ENOSUP: The requested action isn't supported.
EPERM: The application doesn't have permission to perform the action.

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 trace modes are valid in this case. The valid trace modes are:

_NTO_TRACE_INSERTSUSEREVENT
_NTO_TRACE_INSERTCUSEREVENT
_NTO_TRACE_INSERTUSRSTREVENT
_NTO_TRACE_INSERTEVENT
_NTO_TRACE_STOP
_NTO_TRACE_STARTNOSTATE
_NTO_TRACE_START

TraceEvent