Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
DEVSTAT(9)	       FreeBSD 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 statis-
     tics

SYNOPSIS
     #include <sys/devicestat.h>

     void
     devstat_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	sev-
     eral 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 cur-
			rently 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 regis-
			tering 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 sys-
			tems 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 driv-
			ers 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 pro-
			grams 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	inter-
     face 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 periph-
     erals, 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 fol-
     lows:

	   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 fol-
     lows:

     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 cur-
			      rently 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 doesn't 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 deter-
     mine 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 mea-
     sure time per transaction.	 The only feasible way to accurately measure
     time per transaction would	be to record a timestamp for every transac-
     tion.  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.

FreeBSD	9.2			 May 22, 1998			   FreeBSD 9.2

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=devstat&sektion=9&manpath=FreeBSD+5.2.1-RELEASE>

home | help