TraceEvent()

Trace kernel events

Synopsis:

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

int TraceEvent( int mode, 
                ... );

Library:

libc

Description:

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:

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

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

See also:

InterruptAttach(), InterruptHookTrace()

System Analysis Toolkit User's Guide