DEVSTAT(9) | Kernel Developer's Manual | DEVSTAT(9) |
NAME¶
devstat, devstat_add_entry, devstat_end_transaction, devstat_end_transaction_bio, devstat_remove_entry, devstat_start_transaction — kernel interface for keeping device statisticsSYNOPSIS¶
#include <sys/devicestat.h> voiddevstat_add_entry(struct devstat *ds, const char *dev_name, int unit_number, u_int32_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, u_int32_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.
- 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.
- 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.
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;
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;
- 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.
typedef enum { DEVSTAT_NO_DATA = 0x00, DEVSTAT_READ = 0x01, DEVSTAT_WRITE = 0x02, DEVSTAT_FREE = 0x03 } devstat_trans_flags;
- 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.
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 insure, 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.May 22, 1998 | Debian |