![[Previous]](../prev.gif) |
![[Contents]](../contents.gif) |
![[Index]](../keyword_index.gif) |
![[Next]](../next.gif) |
|
|
|
|
 |
This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs. |
Trace kernel events
#include <sys/neutrino.h>
#include <sys/trace.h>
int TraceEvent( int mode,
... );
libc
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:
This description also includes these sections:
 |
Filter and mask settings are made regardless of the previous settings. Use care to not accidentally override or delete previous configurations. |
These modes control the buffer set up as well as start and stop logging.
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.
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.
TraceEvent(_NTO_TRACE_FLUSHBUFFER)
Forces flashing of the buffer regardless of the trace event number it contains.
TraceEvent(_NTO_TRACE_QUERYEVENTS)
Returns the number of simple trace events that's currently stored in the trace buffer.
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.)
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.
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.
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. |
TraceEvent(_NTO_TRACE_SETALLCLASSESFAST) TraceEvent(_NTO_TRACE_SETALLCLASSESWIDE)
Sets the fast/wide emitting mode for all classes and events.
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.
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.
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.
TraceEvent(_NTO_TRACE_ADDALLCLASSES) TraceEvent(_NTO_TRACE_DELALLCLASSES)
Emit/suppress trace events for all classes and events.
TraceEvent(_NTO_TRACE_ADDCLASS, class) TraceEvent(_NTO_TRACE_DELCLASS, class)
Emit/suppress all trace events from a specific class.
TraceEvent(_NTO_TRACE_ADDEVENT, class, event) TraceEvent(_NTO_TRACE_DELEVENT, class, event)
Emit/suppress a trace event from a specific class.
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).
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.)
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.
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.
TraceEvent(_NTO_TRACE_ADDEVENTHANDLER,
class,
event,
int (*event_hdlr)(event_data_t*),
event_data_t* data_struct)
TraceEvent(_NTO_TRACE_DELEVENTHANDLER,
class,
event)
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:
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.
These modes control the insertion of “fake” events into the event stream.
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:
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.
The arguments are:
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:
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:
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:
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:
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 |
Specifies any additional parameters that are required to perform the desired control action.
The following are the generic arguments used for the TraceEvent() modes. Mode-specific arguments accompany the mode description:
The class argument may be one of the following:
There are also “pseudo classes” offered as a convenience:
| 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 trace modes are valid in this case. The valid trace modes are:
InterruptAttach(), InterruptHookTrace()
System Analysis Toolkit User's Guide
|
|
|
|