TraceEvent()

QNX SDP8.0C Library ReferenceAPIDeveloper

Control the tracing of kernel events

Synopsis:

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

int TraceEvent( int cmd, 
                ... );

Arguments:

cmd
The control action that you want to make; for lists of the supported actions by category, see the Description.

Some commands accept additional parameters, such as the following:

int class
The class of events. The events are 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_INT — events related to interrupts.
  • _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 — events related to security.
  • _NTO_TRACE_SYSTEM — events related to the system.

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.
int event
The event type. 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 controlled by commands in 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.
  • A process that wants to capture trace events (i.e., allocate the kernel's trace buffers and consume the generated data with _NTO_TRACE_WAITBUFFER) must have the PROCMGR_AID_TRACE ability enabled. For more information, see procmgr_ability(). Then, this process must register as the designated trace-logging process by issuing the _NTO_TRACE_LOGGER_ATTACH command; only one such process can be registered in the system.
  • For tracing, events are captured independently on each CPU. To capture all events, the trace-logging process must bind a thread to each CPU by issuing the _NTO_TRACE_WAITBUFFER command for each thread.

Buffer and execution control

These commands control the buffer setup, and start and stop logging:

Note:
The commands in this category require the PROCMGR_AID_TRACE ability.

_NTO_TRACE_ALLOCBUFFER, _NTO_TRACE_DEALLOCBUFFER

TraceEvent(_NTO_TRACE_ALLOCBUFFER, uint32_t bufs_per_cpu, tracebuf_t **buffers_base)
TraceEvent(_NTO_TRACE_DEALLOCBUFFER)
Note:
These commands can only be performed by the registered trace-logging process, which must have the PROCMGR_AID_TRACE ability.

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

bufs_per_cpu
The number of buffers to allocate per CPU.
buffers_base
Base address of the full array of trace buffers mapped into the user address space.

Allocated trace buffers can store 1024 simple trace events.

The deallocation option deallocates all of the previously allocated trace buffers, unmapping them from the user address space. 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_LOGGER_ATTACH

TraceEvent(_NTO_TRACE_LOGGER_ATTACH, struct sigevent *start_ev, struct sigevent *stop_ev)

Attaches the current process as the designated trace-logging process. start_ev and stop_ev are NULL, or sigevents to be delivered whenever tracing starts or stops, respectively.

_NTO_TRACE_LOGGER_DETACH

TraceEvent(_NTO_TRACE_LOGGER_DETACH)
Note:
This command can only be performed by the registered trace-logging process.

Detaches the current process from the tracing subsystem. All event masks are implicitly cleared. This operation is performed implicitly if the process dies while still attached.

_NTO_TRACE_SETBUFFER

TraceEvent(_NTO_TRACE_SETBUFFER, paddr64_t *addr, size_t size)
Note:
This command can only be performed by the registered trace-logging process.

Use the previously allocated physical memory, at the given address and for the given size, as the trace buffer. The region must be large enough for at least one trace buffer per CPU, or the command will fail with EINVAL. 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_MEM_PHYS and PROCMGR_AID_TRACE abilities enabled. For more information, see procmgr_ability().

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)
Note:
These commands can only be performed by the registered trace-logging process.

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 an _NTO_TRACE_STOP, which will flush the active buffer on every CPU, after each _NTO_TRACE_START or _NTO_TRACE_STARTNOSTATE command.

_NTO_TRACE_WAITBUFFER

TraceEvent(_NTO_TRACE_WAITBUFFER, int *buffer_id)
Note:
This command can only be performed by the registered trace-logging process.

Get the next buffer queued to be flushed by the kernel on this CPU, blocking if one is not currently available. The global index of the buffer is returned in buffer_id (i.e., the index into the tracebuffer array returned by _NTO_TRACE_ALLOCBUFFER) This must be called by a thread runmasked to one CPU and belonging to the registered trace-logging process.

When the caller is finished processing the buffer's data, it must be returned to the kernel by clearing the _TRACE_FLAGS_FLUSH flag.

System information retrieval

These commands retrieve information about the tracing and the OS:

Note:
The commands in this category do not require the PROCMGR_AID_TRACE ability.

_NTO_TRACE_QUERYEVENTS

TraceEvent(_NTO_TRACE_QUERYEVENTS)

Returns the number of events in the active buffer of the CPU the calling thread is running on.

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

Fast/wide mode configuration

Note:
The commands in this category require the PROCMGR_AID_TRACE ability.

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

Note:
The commands in this category require the PROCMGR_AID_TRACE ability.

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

User-generated trace events

Note:
The commands in this category do not require the PROCMGR_AID_TRACE ability.

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_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.
_NTO_TRACE_WAITBUFFER
EOK if a buffer was returned, _TRACE_WAITBUFFER_DONE if tracing is disabled and there are no more buffers queued to be flushed, -1 if an error occurred.
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 OS

Safety:
Cancellation pointNo
Signal handlerYes
ThreadYes

Caveats:

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

Page updated: