NAME¶
devstat
,
devstat_add_entry
,
devstat_end_transaction
,
devstat_end_transaction_bio
,
devstat_remove_entry
,
devstat_start_transaction
—
kernel interface for keeping device statistics
SYNOPSIS¶
#include
<sys/devicestat.h>
void
devstat_add_entry
(
struct
devstat *ds,
const char *dev_name,
int unit_number,
uint32_t block_size,
devstat_support_flags flags,
devstat_type_flags device_type,
devstat_priority priority);
void
devstat_remove_entry
(
struct
devstat *ds);
void
devstat_start_transaction
(
struct
devstat *ds);
void
devstat_end_transaction
(
struct
devstat *ds,
uint32_t bytes,
devstat_tag_type tag_type,
devstat_trans_flags flags);
void
devstat_end_transaction_bio
(
struct
devstat *ds,
struct bio *bp);
DESCRIPTION¶
The devstat subsystem is an interface for recording device statistics, as its
name implies. The idea is to keep reasonably detailed statistics while
utilizing a minimum amount of CPU time to record them. Thus, no statistical
calculations are actually performed in the kernel portion of the
devstat
code. Instead, that is left for
user programs to handle.
devstat_add_entry
() registers a device with
the
devstat
subsystem. The caller is
expected to have already allocated
and zeroed the devstat structure
before calling this function.
devstat_add_entry
() takes several
arguments:
- ds
- The devstat structure, allocated and
zeroed by the client.
- dev_name
- The device name, e.g. da, cd, sa.
- unit_number
- Device unit number.
- block_size
- Block size of the device, if supported. If the device does not support a
block size, or if the blocksize is unknown at the time the device is added
to the
devstat
list, it should be set
to 0.
- flags
- Flags indicating operations supported or not supported by the device. See
below for details.
- device_type
- The device type. This is broken into three sections: base device type
(e.g. direct access, CDROM, sequential access), interface type (IDE, SCSI
or other) and a pass-through flag to indicate pas-through devices. See
below for a complete list of types.
- priority
- The device priority. The priority is used to determine how devices are
sorted within
devstat
's list of
devices. Devices are sorted first by priority (highest to lowest), and
then by attach order. See below for a complete list of available
priorities.
devstat_remove_entry
() removes a device from
the
devstat
subsystem. It takes the devstat
structure for the device in question as an argument. The
devstat
generation number is incremented
and the number of devices is decremented.
devstat_start_transaction
() registers the
start of a transaction with the
devstat
subsystem. The busy count is incremented with each transaction start. When a
device goes from idle to busy, the system uptime is recorded in the
start_time field of the
devstat structure.
devstat_end_transaction
() registers the end
of a transaction with the
devstat
subsystem. It takes four arguments:
- ds
- The devstat structure for the device in
question.
- bytes
- The number of bytes transferred in this transaction.
- tag_type
- Transaction tag type. See below for tag types.
- flags
- Transaction flags indicating whether the transaction was a read, write, or
whether no data was transferred.
devstat_end_transaction_bio
() is a wrapper
for
devstat_end_transaction
() which pulls
all the information from a
struct bio which
is ready for biodone().
The
devstat structure is composed of the
following fields:
- dev_links
- Each devstat structure is placed in a
linked list when it is registered. The
dev_links field contains a pointer to the
next entry in the list of devstat
structures.
- device_number
- The device number is a unique identifier for each device. The device
number is incremented for each new device that is registered. The device
number is currently only a 32-bit integer, but it could be enlarged if
someone has a system with more than four billion device arrival
events.
- device_name
- The device name is a text string given by the registering driver to
identify itself. (e.g. “da”, “cd”,
“sa”, etc.)
- unit_number
- The unit number identifies the particular instance of the peripheral
driver in question.
- bytes_written
- This is the number of bytes that have been written to the device. This
number is currently an unsigned 64 bit integer. This will hopefully
eliminate the counter wrap that would come very quickly on some systems if
32 bit integers were used.
- bytes_read
- This is the number of bytes that have been read from the device.
- bytes_freed
- This is the number of bytes that have been freed/erased on the
device.
- num_reads
- This is the number of reads from the device.
- num_writes
- This is the number of writes to the device.
- num_frees
- This is the number of free/erase operations on the device.
- num_other
- This is the number of transactions to the device which are neither reads
or writes. For instance, SCSI drivers often send a test unit ready command
to SCSI devices. The test unit ready command does not read or write any
data. It merely causes the device to return its status.
- busy_count
- This is the current number of outstanding transactions for the device.
This should never go below zero, and on an idle device it should be zero.
If either one of these conditions is not true, it indicates a problem in
the way
devstat_start_transaction
() and
devstat_end_transaction
() are being
called in client code. There should be one and only one transaction start
event and one transaction end event for each transaction.
- block_size
- This is the block size of the device, if the device has a block size.
- tag_types
- This is an array of counters to record the number of various tag types
that are sent to a device. See below for a list of tag types.
- dev_creation_time
- This is the time, as reported by
getmicrotime
() that the device was
registered.
- busy_time
- This is the amount of time that the device busy count has been greater
than zero. This is only updated when the busy count returns to zero.
- start_time
- This is the time, as reported by
getmicrouptime
() that the device busy
count went from zero to one.
- last_comp_time
- This is the time as reported by
getmicrouptime
() that a transaction
last completed. It is used along with
start_time to calculate the device busy
time.
- flags
- These flags indicate which statistics measurements are supported by a
particular device. These flags are primarily intended to serve as an aid
to userland programs that decipher the statistics.
- device_type
- This is the device type. It consists of three parts: the device type (e.g.
direct access, CDROM, sequential access, etc.), the interface (IDE, SCSI
or other) and whether or not the device in question is a pass-through
driver. See below for a complete list of device types.
- priority
- This is the priority. This is the first parameter used to determine where
to insert a device in the
devstat
list.
The second parameter is attach order. See below for a list of available
priorities.
Each device is given a device type. Pass-through devices have the same
underlying device type and interface as the device they provide an interface
for, but they also have the pass-through flag set. The base device types are
identical to the SCSI device type numbers, so with SCSI peripherals, the
device type returned from an inquiry is usually ORed with the SCSI interface
type and the pass-through flag if appropriate. The device type flags are as
follows:
typedef enum {
DEVSTAT_TYPE_DIRECT = 0x000,
DEVSTAT_TYPE_SEQUENTIAL = 0x001,
DEVSTAT_TYPE_PRINTER = 0x002,
DEVSTAT_TYPE_PROCESSOR = 0x003,
DEVSTAT_TYPE_WORM = 0x004,
DEVSTAT_TYPE_CDROM = 0x005,
DEVSTAT_TYPE_SCANNER = 0x006,
DEVSTAT_TYPE_OPTICAL = 0x007,
DEVSTAT_TYPE_CHANGER = 0x008,
DEVSTAT_TYPE_COMM = 0x009,
DEVSTAT_TYPE_ASC0 = 0x00a,
DEVSTAT_TYPE_ASC1 = 0x00b,
DEVSTAT_TYPE_STORARRAY = 0x00c,
DEVSTAT_TYPE_ENCLOSURE = 0x00d,
DEVSTAT_TYPE_FLOPPY = 0x00e,
DEVSTAT_TYPE_MASK = 0x00f,
DEVSTAT_TYPE_IF_SCSI = 0x010,
DEVSTAT_TYPE_IF_IDE = 0x020,
DEVSTAT_TYPE_IF_OTHER = 0x030,
DEVSTAT_TYPE_IF_MASK = 0x0f0,
DEVSTAT_TYPE_PASS = 0x100
} devstat_type_flags;
Devices have a priority associated with them, which controls roughly where they
are placed in the
devstat
list. The
priorities are as follows:
typedef enum {
DEVSTAT_PRIORITY_MIN = 0x000,
DEVSTAT_PRIORITY_OTHER = 0x020,
DEVSTAT_PRIORITY_PASS = 0x030,
DEVSTAT_PRIORITY_FD = 0x040,
DEVSTAT_PRIORITY_WFD = 0x050,
DEVSTAT_PRIORITY_TAPE = 0x060,
DEVSTAT_PRIORITY_CD = 0x090,
DEVSTAT_PRIORITY_DISK = 0x110,
DEVSTAT_PRIORITY_ARRAY = 0x120,
DEVSTAT_PRIORITY_MAX = 0xfff
} devstat_priority;
Each device has associated with it flags to indicate what operations are
supported or not supported. The
devstat_support_flags values are as follows:
- DEVSTAT_ALL_SUPPORTED
- Every statistic type is supported by the device.
- DEVSTAT_NO_BLOCKSIZE
- This device does not have a blocksize.
- DEVSTAT_NO_ORDERED_TAGS
- This device does not support ordered tags.
- DEVSTAT_BS_UNAVAILABLE
- This device supports a blocksize, but it is currently unavailable. This
flag is most often used with removable media drives.
Transactions to a device fall into one of three categories, which are
represented in the
flags passed into
devstat_end_transaction
(). The transaction
types are as follows:
typedef enum {
DEVSTAT_NO_DATA = 0x00,
DEVSTAT_READ = 0x01,
DEVSTAT_WRITE = 0x02,
DEVSTAT_FREE = 0x03
} devstat_trans_flags;
There are four possible values for the
tag_type
argument to
devstat_end_transaction
():
- DEVSTAT_TAG_SIMPLE
- The transaction had a simple tag.
- DEVSTAT_TAG_HEAD
- The transaction had a head of queue tag.
- DEVSTAT_TAG_ORDERED
- The transaction had an ordered tag.
- DEVSTAT_TAG_NONE
- The device does not support tags.
The tag type values correspond to the lower four bits of the SCSI tag
definitions. In CAM, for instance, the
tag_action from the CCB is ORed with 0xf to
determine the tag type to pass in to
devstat_end_transaction
().
There is a macro,
DEVSTAT_VERSION
that is
defined in
<sys/devicestat.h>
.
This is the current version of the
devstat
subsystem, and it should be incremented each time a change is made that would
require recompilation of userland programs that access
devstat
statistics. Userland programs use
this version, via the
kern.devstat.version
sysctl
variable to determine whether they
are in sync with the kernel
devstat
structures.
SEE ALSO¶
systat(1),
devstat(3),
iostat(8),
rpc.rstatd(8),
vmstat(8)
HISTORY¶
The
devstat
statistics system appeared in
FreeBSD 3.0.
AUTHORS¶
Kenneth Merry ⟨ken@FreeBSD.org⟩
BUGS¶
There may be a need for
spl
() protection
around some of the
devstat
list
manipulation code to ensure, for example, that the list of devices is not
changed while someone is fetching the
kern.devstat.all
sysctl
variable.
It is impossible with the current
devstat
architecture to accurately measure time per transaction. The only feasible way
to accurately measure time per transaction would be to record a timestamp for
every transaction. This measurement is probably not worthwhile for most people
as it would adversely affect the performance of the system and cost space to
store the timestamps for individual transactions.