NAME

trace − kernel trace mechanism

DESCRIPTION

trace is a pseudo-device driver that traces the operation of the kernel.  Embedded in the kernel are various trace points that will log a trace record to a kernel trace buffer when a process executes the kernel routine that contains the trace point. 

The trace device will be created by the standard MAKEDEV script that is shipped with the system, however the trace device can not be accessed unless the TRACE option is specified in the configuration file. 

No trace points are compiled into the kernel, unless the kernel is built with the TRACE option.  Note that standard kernel object will not contain any trace points.  Users that have source and can build the kernel libraries from scratch, will be able to get all of the trace points that are available.  Users that have only the kernel libraries are able to compile a subset of trace points into the kernel by using the TRACE option when reconfiguring the kernel. 

Trace data is logged by a trace point only when that trace point is enabled via an ioctl call.  The trace points that can be enabled are listed in the include file /usr/include/sys/trace.h.

Trace buffers can be read from the kernel via the read system call, by reading from the trace device (/dev/trace).  When reading from the trace device, the character count specified to the read system service should be the size of a trace buffer.  A read will always attempt to return a full buffer of trace records, so specifying a smaller character count will simply truncate the trace buffer, and the truncated data will be lost.  A read will block until a full buffer of trace records is available. 

The following ioctl calls are defined in sys/trace.h and apply only to the trace device:

TRACE_ON
Turns on the tracing mechanism in the kernel.  This ioctl call must be made before any trace points will be taken.  Takes no parameter. 

TRACE_OFF
Turns off the tracing mechanism in the kernel.  Takes no parameter.

TRACE_ENABLE
Enables the given trace points.  The argument for this ioctl call is a pointer to a tr_enable structure, which specifies which trace points should be enabled.  For example, if the TR_INTERRUPT_ENTRY trace point were enabled, then a trace record would be saved in the kernel’s trace buffer each time that the kernel entered an interrupt routine. 

TRACE_DISABLE
Disable the given trace points. The argument to this ioctl call is a pointer to a tr_enable structure, which specifies which trace points should be disabled. 

TRACE_MODE
Set modes for the operation of the trace mechanism. The argument for this ioctl is a bit mask specifying the mode(s) being set.  The following modes are available:

NOWRAP
In this mode trace records will not be overwritten.  If the trace buffer fills up because the user is not reading trace records fast enough, then a count of lost trace records is incremented, which is reported in a read of the following trace buffer.  In normal operating mode, trace records are written into the kernel buffers in a circular manner, overwriting previous trace records as necessary.

TRREAD
While this mode is set the current process reserves the right to read from the trace device. This ioctl call will return the error EBUSY if someone else has already declared that they are reading from the trace device.  However, this ioctl is used in an advisory manner only, as any process with read access can read from the trace device.  To avoid confusion it is best if only one program reads from the trace device at a time, since it will appear that there are gaps in the data if there is more than one active reader. 

TRACE_POINT_1
Write a user record to the trace buffer.  The ioctl argument is an int that is written as the first parameter in a trace record of type TR_USER_1. 

TRACE_POINT_3
Write a user record to the trace buffer.  The ioctl argument is a pointer to a tr_3parms structure, which contains the three data words that should be saved in a trace record of type TR_USER_3.  Note that two trace records are allocated for a TR_USER_3 trace record, the second trace record will be of type TR_CONTINUE, with the second parameter stored in the time field, and the third parameter stored in the param1 field of the TR_CONTINUE trace record. 

Kernel trace buffers are described by struct tr_buffer_type in the file /usr/include/sys/trace.h as follows:

struct tr_buffer_type {
inttr_events_lost;
inttr_spare1;
inttr_spare2;
structtr_recordevent[TR_BUFFER_SIZE];
};

Note that the field tr_events_lost contains the number of trace records that were lost, if there was not enough buffer space in the kernel to hold the trace records that are being generated.  The array tr_record contains the trace record data. 

The number of trace buffers in the kernel can be changed by changing the value of TR_BUFFER_COUNT in the file usr/src/uts/machine/cf/space.c.  It might be necessary to have a larger number of trace buffers if the process reading from the trace device is not able to read trace records as fast as the kernel is generating trace records. 

Each record within a trace buffer is defined as follows:

struct tr_record {
unsigned shortcode;/∗ trace record type ∗/
unsigned shortcpu;/∗ cpu where the trace point occurred ∗/
unsigned inttime;/∗ time of trace point ∗/
unsigned intparam1;/∗ parameters (dependent on record type) ∗/
};

On the Series 4000 the time field is the number of clock tics as read from the interval timer.  Each clock tic is 400 nanoseconds. 

CX/UX Administrator’s Reference