vxtrace - Volume Manager I/O Tracing Device
The vxtrace device implements the Volume Manager I/O tracing and the error tracing. An I/O tracing interface is available that users or processes can use to get a trace of I/Os for specified sets of kernel objects. Each separate user of the I/O tracing interface can specify the set of desired trace data independent of all other users. I/O events include regular read and write operations, special I/O operations (ioctls), as well as special recovery operations (e.g. recovery reads). A special tracing mechanism exists for getting error trace data. The error tracing mechanism is independent of any I/O tracing and is always enabled for all pertinent kernel I/O objects. It is possible for a process to get both a set of saved errors and to wait for new errors.
The ioctl commands supported by the vxtrace device are discussed later in this section. The format for calling each ioctl command is
struct tag arg;
int ioctl (int fd, int cmd, struct tag arg);
The first argument fd is a file descriptor which is returned from opening the /dev/vx/trace device. Each tracing device opened is a cloned device which can be used as a private kernel trace channel. The value of cmd is the ioctl command code, and arg is usually a pointer to a structure containing the arguments that need to be passed to the kernel.
The return value for all these ioctls is 0 if the command was successful, and -1 if it was rejected. If the return value is -1, then errno is set to indicate the cause of the error.
The following ioctl commands are supported:
- This command accepts no argument.
ioctl initializes a kernel trace channel to
return error trace data. The trace channel will be initialized to
return any previously accumulated error trace data that has not yet
been discarded. The accumulated trace data can be skipped by issuing
VOLIOT_DISCARD on the channel. This call can be issued
on a trace channel that was previously initialized either for error
tracing or for regular I/O tracing. In this case, the channel is
effectively closed down and then reinitialized as described above. To
get the error trace data, issue the read(2) system
call. The error trace data consists of a set of variable length trace
event records. The first byte of each record indicates the length, in
bytes, of the entire record (including the length byte), the second
byte indicates the type of the entry (which can be used to determine
the format of the entry). Each call to read() returns
an integral number of trace event records, not to exceed the number of
bytes requested in the read() call; the return value
from read() will be adjusted to the number of bytes
of trace data actually returned. If the O_NONBLOCK flag is set on the
trace channel, and no trace data is available, EAGAIN
will be returned; otherwise, the read will block interruptibly until at
least one trace record is available. When some trace data is
available, the available unread trace records will be returned, up to
the limit specified in the call to read(). If more
trace records are available, subsequent reads will return those
- The VOLIOT_IO_TRACE_INIT ioctl initializes a kernel trace channel to return I/O trace data.
This command accepts bufsize as the argument. Initially, no objects are selected for I/O
tracing. To select objects to trace, issue the VOLIOT_IO_TRACE ioctl. The bufsize
argument specifies the kernel buffer size to use for gathering events. A larger size reduces
the chance that events are lost due to scheduling delays in the event reading process. A
bufsize value of 0 requests a default size which is considered reasonable for the system.
The value of bufsize will be silently truncated to a maximum value to avoid extreme use of
system resources. A bufsize value of (size_t)-1 will yield the maximum buffer size.
- VOLIOT_IO_TRACE, VOLIOT_IO_UNTRACE
- The VOLIOT_IO_TRACE and VOLIOT_IO_UNTRACE ioctls enable and disable,
respectively, I/O tracing for particular sets of objects on an I/O tracing channel. They both
accept a voliot_want_list structure tracelist as the argument. The tracelist argument
specifies object sets. The voliot_want_list structure specifies an array of desired object
sets. Each object set is identified by a union of structures (the voliot_want_set union), each
representing different types of object sets. See the declaration of these structures in
voltrace.h for more detail.
Copyright © 2005 The SCO Group, Inc. All rights reserved.