TraceEvent()
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:
- Buffer and execution control
- System information retrieval
- Fast/wide mode configuration
- Static rules filter configuration
- User-generated trace events
- 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:
- _NTO_TRACE_ALLOCBUFFER
- _NTO_TRACE_DEALLOCBUFFER
- _NTO_TRACE_FLUSHBUFFER
- _NTO_TRACE_LOGGER_ATTACH
- _NTO_TRACE_LOGGER_DETACH
- _NTO_TRACE_SETBUFFER
- _NTO_TRACE_SETLINEARMODE
- _NTO_TRACE_SETRINGMODE
- _NTO_TRACE_SKIPBUFFER
- _NTO_TRACE_START
- _NTO_TRACE_STARTNOSTATE
- _NTO_TRACE_STOP
- _NTO_TRACE_WAITBUFFER
_NTO_TRACE_ALLOCBUFFER, _NTO_TRACE_DEALLOCBUFFER
TraceEvent(_NTO_TRACE_ALLOCBUFFER, uint32_t bufs_per_cpu, tracebuf_t **buffers_base)
TraceEvent(_NTO_TRACE_DEALLOCBUFFER)
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)
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)
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)
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.
_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.
TraceEvent(_NTO_TRACE_START)
, and you then try
to start tracelogger, tracelogger might fail with a
resource busymessage. 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)
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:
_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
These commands control whether fast or wide events are emitted:
- _NTO_TRACE_SETALLCLASSESFAST
- _NTO_TRACE_SETALLCLASSESWIDE
- _NTO_TRACE_SETCLASSFAST
- _NTO_TRACE_SETCLASSWIDE
- _NTO_TRACE_SETEVENTFAST
- _NTO_TRACE_SETEVENTWIDE
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:
- _NTO_TRACE_ADDALLCLASSES
- _NTO_TRACE_ADDCLASS
- _NTO_TRACE_ADDEVENT
- _NTO_TRACE_CLRCLASSPID
- _NTO_TRACE_CLRCLASSTID
- _NTO_TRACE_CLREVENTPID
- _NTO_TRACE_CLREVENTTID
- _NTO_TRACE_DELALLCLASSES
- _NTO_TRACE_DELCLASS
- _NTO_TRACE_DELEVENT
- _NTO_TRACE_SETCLASSPID
- _NTO_TRACE_SETCLASSTID
- _NTO_TRACE_SETEVENTPID
- _NTO_TRACE_SETEVENTTID
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.
- _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.
- _NTO_TRACE_COMM
- _NTO_TRACE_KERCALL, _NTO_TRACE_KERCALLENTER, _NTO_TRACE_KERCALLEXIT
- _NTO_TRACE_SYSTEM
- _NTO_TRACE_THREAD
User-generated trace events
These commands let you insert your own events into the event stream:
- _NTO_TRACE_INSERTCCLASSEVENT
- _NTO_TRACE_INSERTCUSEREVENT
- _NTO_TRACE_INSERTSCLASSEVENT
- _NTO_TRACE_INSERTSUSEREVENT
- _NTO_TRACE_INSERTUSRSTREVENT
_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:
Safety: | |
---|---|
Cancellation point | No |
Signal handler | Yes |
Thread | Yes |
Caveats:
Don't call TraceEvent() with interrupts disabled; this function reenables interrupts.