TraceEvent()

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:

int class

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

_NTO_TRACE_COMM — events related to communication.
_NTO_TRACE_CONTROL — the set of control events (e.g. time-overflow event) that are used by the communication protocol between the microkernel and tracelogger.
_NTO_TRACE_INTENTER, _NTO_TRACE_INTEXIT — the set of interrupt entry/exit events.
_NTO_TRACE_INT_HANDLER_ENTER, _NTO_TRACE_INT_HANDLER_EXIT — entrances to and exits from interrupt handlers.
_NTO_TRACE_KERCALLENTER, _NTO_TRACE_KERCALLEXIT — the set of events for entries to and exits from kernel calls.
_NTO_TRACE_KERCALLINT — the set of events for interrupted kernel calls.
_NTO_TRACE_PROCESS — the set of events associated with process creation and destruction.
_NTO_TRACE_SEC — (QNX Neutrino 7.0 or later) events related to security.
_NTO_TRACE_SYSTEM — events related to the system, including those for adaptive partitioning.
_NTO_TRACE_THREAD, _NTO_TRACE_VTHREAD — the set of events for the creation and destruction of threads (or virtual threads), and for state changes.

There are also pseudo-classes defined as a convenience:

_NTO_TRACE_KERCALL — all of the kernel-call events: _NTO_TRACE_KERCALLENTER, _NTO_TRACE_KERCALLEXIT, and _NTO_TRACE_KERCALLINT.
_NTO_TRACE_INT — all of the interrupt events: _NTO_TRACE_INTENTER, _NTO_TRACE_INTEXIT, _NTO_TRACE_INT_HANDLER_ENTER, and _NTO_TRACE_INT_HANDLER_EXIT.

int 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.
In order to add handlers for trace events or allocate the instrumented kernel's trace buffers, your process must have the PROCMGR_AID_TRACE ability enabled. For more information, see procmgr_ability().

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, paddr_t *paddr)
TraceEvent(_NTO_TRACE_DEALLOCBUFFER)

Note:

If your application calls TraceEvent() with these commands, it must have the PROCMGR_AID_TRACE ability enabled. For more information, see procmgr_ability().

The allocation option creates and initializes the instrumented kernel's ring of trace buffers. These buffers hold the emitted trace events. The extra arguments for the _NTO_TRACE_ALLOCBUFFER command are:

bufnum: The number of buffers to allocate.
paddr: A pointer to a location where the function can store the physical address of the beginning of the ring of allocated trace buffers.

Allocated trace buffers can store 1024 simple trace events.

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

_NTO_TRACE_OVERWRITEBUFFER

TraceEvent(_NTO_TRACE_OVERWRITEBUFFER)

Overwrite the first buffer when the ring overflows.

_NTO_TRACE_QUERYEVENTS

TraceEvent(_NTO_TRACE_QUERYEVENTS)

Returns the number of simple trace events that are currently stored in the trace buffer.

_NTO_TRACE_QUERYSUPPORT

TraceEvent(_NTO_TRACE_QUERYSUPPORT)

Returns _NTO_TRACE_SUPPINSTR if instrumentation is enabled, or _NTO_TRACE_NOINSTRSUPP if it isn't.

_NTO_TRACE_QUERYVERSION

TraceEvent(_NTO_TRACE_QUERYVERSION)

Returns the version of the OS multiplied by 100.

_NTO_TRACE_SETBUFFER (QNX Neutrino 6.6 or later)

TraceEvent(_NTO_TRACE_SETBUFFER, paddr64_t *addr, size_t size)

Use the previously allocated physical memory, at the given address and for the given size, as the trace buffer. The intended application is to place the buffer in an area of memory that will be preserved across system resets, facilitating post-crash analysis.

Before setting the buffer:

The process must have the PROCMGR_AID_TRACE and PROCMGR_AID_IO abilities enabled. For more information, see procmgr_ability().
The calling thread must obtain Level 1 I/O privileges by calling ThreadCtl() as follows:
```
ThreadCtl( _NTO_TCTL_IO_LEVEL, (void*)_NTO_IO_LEVEL_1 );
```

If the thread doesn't do all of the above, the setting fails with an error code of EPERM.

_NTO_TRACE_SETLINEARMODE, _NTO_TRACE_SETRINGMODE

TraceEvent(_NTO_TRACE_SETLINEARMODE)
TraceEvent(_NTO_TRACE_SETRINGMODE)

Set the mode for logging the trace events:

In linear mode (the default), every filled buffer is captured and flushed immediately.
In ring mode, the kernel stores all events in the ring of buffers 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.

The kernel treats its trace buffers as a ring in either mode.

Note:

_NTO_TRACE_SETLINEARMODE and _NTO_TRACE_SETRINGMODE cause the trace buffers to be cleared, so you should use these commands before you start tracing.

_NTO_TRACE_SKIPBUFFER

TraceEvent(_NTO_TRACE_SKIPBUFFER)

Skip the first buffer when the ring overflows.

_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). This information is overwritten when the kernel reuses the buffer; if you're logging events in ring mode, you can make sure you capture the process names by issuing an _NTO_TRACE_START command followed by _NTO_TRACE_STOP after you've finished tracing.

Note:

If an application has called TraceEvent(_NTO_TRACE_START), and you then try to start tracelogger, tracelogger might fail with a resource busy message. To help avoid this:

Start tracelogger before your application issues a _NTO_TRACE_START or _NTO_TRACE_STARTNOSTATE command.
Don't leave tracing on indefinitely; be sure to issue a _NTO_TRACE_STOP after each _NTO_TRACE_START or _NTO_TRACE_STARTNOSTATE command.

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:

For descriptions of each mode, see Fast and wide modes in the Events and the Kernel chapter.
For a list of the intercepted arguments and return values for each event in both modes, see the Current Trace Events and Data appendix of 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, int class)
TraceEvent(_NTO_TRACE_DELCLASS, int class)

Emit/suppress all trace events from a specific class.

_NTO_TRACE_ADDEVENT, _NTO_TRACE_DELEVENT

TraceEvent(_NTO_TRACE_ADDEVENT, int class, int event)
TraceEvent(_NTO_TRACE_DELEVENT, int class, int 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, uint32_t tid)
TraceEvent(_NTO_TRACE_CLRCLASSTID, int class)

Restrict emission of all events of a given class to only events from a particular process (pid) or thread (pid), or remove the restriction.

Note:

The class must be one of the following:

_NTO_TRACE_COMM
_NTO_TRACE_KERCALL, _NTO_TRACE_KERCALLENTER, _NTO_TRACE_KERCALLEXIT
_NTO_TRACE_SYSTEM
_NTO_TRACE_THREAD
_NTO_TRACE_VTHREAD

_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, uint32_t tid)
TraceEvent(_NTO_TRACE_CLREVENTTID, int class, int event)

Restrict emission of a specific event to only this event from a particular process (pid) or thread (tid), or remove the restriction.

Note:

The class must be one of the following:

_NTO_TRACE_COMM
_NTO_TRACE_KERCALL, _NTO_TRACE_KERCALLENTER, _NTO_TRACE_KERCALLEXIT
_NTO_TRACE_SYSTEM
_NTO_TRACE_THREAD
_NTO_TRACE_VTHREAD

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:

For more information about this filter, see the Filtering chapter in the System Analysis Toolkit User's Guide.

CAUTION:

The only library functions that you can call in your event handler are those that are safe to call from an interrupt handler. For a list of these functions, see the Full Safety Information appendix. If you call an unsafe function—such as printf()—in your event handler, you'll crash your entire system. Your event handler must also be reentrant.

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    */
    uint32_t*    data_array;  /* initialized by the user      */
    uint32_t     el_num;      /* number of elements returned  */
    void*        area;        /* user data                    */
    uint32_t     feature_mask;/* bits indicate valid features */
    uint32_t     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;
uint32_t     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.

You can use the _NTO_TRACE_GET*() macros to extract the class, event, and CPU from the header member. Note that the class and event numbers are internal representations of the _NTO_TRACE_* numbers.

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:

_NTO_TRACE_FM*** — feature parameter masks
_NTO_TRACE_FI*** — feature index parameters

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.

_NTO_TRACE_ADDEVENTHANDLER, _NTO_TRACE_DELEVENTHANDLER

TraceEvent(_NTO_TRACE_ADDEVENTHANDLER, 
           int class, 
           int event, 
           int (*event_hdlr)(event_data_t*), 
           event_data_t* data_struct)

TraceEvent(_NTO_TRACE_DELEVENTHANDLER, 
           int class, 
           int event)

Attaches/deletes the event handler for a specified class and event, where:

event_hdlr: A pointer to the event handler. For more information, see Dynamic rules filter configuration, above.
data_struct: A pointer to the data structure event_data_t.

CAUTION:

The generation of trace events is designed to be as lightweight as possible. Adding (attaching) a handler to an event significantly increases the cost of generating each event, even if the handler returns zero to prevent logging of the event.

Before attaching an event handler:

The process must have the PROCMGR_AID_TRACE and PROCMGR_AID_IO abilities enabled. For more information, see procmgr_ability().
The calling thread must obtain Level 1 I/O privileges by calling ThreadCtl() as follows:
```
ThreadCtl( _NTO_TCTL_IO_LEVEL, (void*)_NTO_IO_LEVEL_1 );
```

If the thread doesn't do all of the above, the attachment fails with an error code of EPERM.

In order to emit an event's 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.

Note that an event handler can only be added for the following classes:

_NTO_TRACE_EMPTY
_NTO_TRACE_CONTROL
_NTO_TRACE_KERCALLENTER
_NTO_TRACE_KERCALLEXIT
_NTO_TRACE_INTENTER
_NTO_TRACE_INTEXIT
_NTO_TRACE_PROCESS
_NTO_TRACE_THREAD
_NTO_TRACE_VTHREAD
_NTO_TRACE_SYSTEM
_NTO_TRACE_COMM

_NTO_TRACE_ADDCLASSEVHANDLER, _NTO_TRACE_DELCLASSEVHANDLER

TraceEvent(_NTO_TRACE_ADDCLASSEVHANDLER,
           int class,
           int (*event_hdlr)(event_data_t*),
           event_data_t* data_struct)
       
TraceEvent(_NTO_TRACE_DELCLASSEVHANDLER,
           int class)

Attaches/deletes the event handler for a specified class, where:

event_hdlr: A pointer to the event handler. For more information, see Dynamic rules filter configuration, above.
data_struct: A pointer to the data structure event_data_t.

CAUTION:

The generation of trace events is designed to be as lightweight as possible. Adding (attaching) a handler to an event significantly increases the cost of generating each event, even if the handler returns zero to prevent logging of the event.

Before attaching an event handler:

The process must have the PROCMGR_AID_TRACE and PROCMGR_AID_IO abilities enabled. For more information, see procmgr_ability().
The calling thread must obtain Level 1 I/O privileges by calling ThreadCtl() as follows:
```
ThreadCtl( _NTO_TCTL_IO_LEVEL, (void*)_NTO_IO_LEVEL_1 );
```

If the thread doesn't do all of the above, the attachment fails with an error code of EPERM.

In order to emit an event's 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_INSERTCCLASSEVENT, _NTO_TRACE_INSERTSCLASSEVENT

TraceEvent(_NTO_TRACE_INSERTCCLASSEVENT, int class, int event,
           unsigned *buf, unsigned len)

TraceEvent(_NTO_TRACE_INSERTSCLASSEVENT, int class, int event,
           int data0, int data1)

These commands insert user-created events of a specified class into the event stream. The API handles details such as timestamping.

_NTO_TRACE_INSERTSCLASSEVENT: Add a user simple event containing the data defined by data0 and data1.
_NTO_TRACE_INSERTCCLASSEVENT: Add a user combine event containing the data that buf holds.
Note:
The len argument represents the number of 32-bit values (not bytes) in buf.

The trace_logbc() is a convenient cover function for this command.

_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 32-bit values (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:

The value that TraceEvent() returns depends on the value of the cmd argument:

_NTO_TRACE_QUERYEVENTS: The number of events in the buffer, or -1 if an error occurs (errno is set).
_NTO_TRACE_QUERYSUPPORT: _NTO_TRACE_SUPPINSTR if instrumentation is enabled, or _NTO_TRACE_NOINSTRSUPP if it isn't.
_NTO_TRACE_QUERYVERSION: The version of the OS multiplied by 100.
Other commands: 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 calling process doesn't have the required permission; see procmgr_ability().

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:

_NTO_TRACE_INSERTSUSEREVENT
_NTO_TRACE_INSERTCUSEREVENT
_NTO_TRACE_INSERTUSRSTREVENT
_NTO_TRACE_INSERTEVENT
_NTO_TRACE_STOP
_NTO_TRACE_STARTNOSTATE
_NTO_TRACE_START

If you use TraceEvent() to add a dynamic rules filter, the only library functions that you can call in your event handler are those that are safe to call from an interrupt handler.

Don't call TraceEvent() with interrupts disabled; this function reenables interrupts.