![[Previous]](../prev.gif) |
![[Contents]](../contents.gif) |
![[Index]](../keyword_index.gif) |
![[Next]](../next.gif) |
|
|
|
|
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:
 |
Filter and mode settings are made regardless of the previous settings. Use care to not accidentally override or delete previous configurations. |
These commands control the buffer setup, and start and stop logging:
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:
Allocated trace buffers can store 1024 simple trace events.
|
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.
TraceEvent(_NTO_TRACE_FLUSHBUFFER)
Forces flushing of the buffer regardless of the trace event number it contains.
TraceEvent(_NTO_TRACE_QUERYEVENTS)
Returns the number of simple trace events that are currently stored in the trace buffer.
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).
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.
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.
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:
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 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.
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)
Emit/suppress 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)
Emit/suppress a specific event for a specified process ID (and thread ID).
These commands control the operation of the dynamic rules filter, in which you set up handlers for the events you're interested in:
|
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.
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;
 |
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.
You can use the following macros, defined in <sys/trace.h>, to work with the header of an event:
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:
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.
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 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.
These commands let you insert your own events into the event stream:
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:
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 len argument represents the number of integers (not bytes) in buf. |
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:
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:
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
|
|
|
|