iostadd Kernel Service

Purpose

Registers an I/O statistics structure used for updating I/O statistics reported by the iostat subroutine.

Syntax 

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/iostat.h>
#include <sys/devinfo.h>

int iostadd ( devtype,  devstatp)
int devtype;
union {
       struct ttystat *ttystp;
       struct dkstat  *dkstp;
       } devstatp;

Description

The iostadd kernel service is used to register the I/O statistics structure required to maintain statistics on a device. The iostadd service is typically called by a tty, disk, or CD-ROM device driver to provide the statistical information used by the iostat subroutine. The iostat subroutine displays statistic information for tty and disk devices on the system. The iostadd service should be used once for each configured device.

In AIX® 5.2, support for Multi-Path I/O (MPIO) was added to the iostadd kernel service and the dkstat structure. The dkstat structure was expanded to accomodate the MPIO data. The iostadd kernel service was modified to handle the new version of the dkstat structure as well as older, legacy versions. For an MPIO device, the anchor is the disk's dkstat structure. This must be the first dkstat structure registered using the iostadd kernel service. Any path dkstat structures that are registered subsequently must reference the address of the anchor dkstat (disk) structure in the dkstat.dk_mpio_anchor field.

For tty devices, the devtype parameter has a value of DD_tty. In this case, the iostadd service uses the devstatp parameter to return a pointer to a ttystat structure.

For disk or CD-ROM devices with a devtype value of DD_DISK or DD_CD-ROM, the caller must provide a pinned and initialized dkstat structure as an input parameter. This structure is pointed to by the devstatp parameter on entry to the iostadd kernel service.

If the device driver support for a device is terminated, the dkstat or ttystat structure registered with the iostadd kernel service should be deregistered by calling the iostdel kernel service.

I/O Statistics Structures

The iostadd kernel service uses two structures that are found in the usr/include/sys/iostat.h file: the ttystat structure and the dkstat structure.

The ttystat structure contains the following tty-related fields:

Field Description
rawinch Count of raw characters received by the tty device
caninch Count of canonical characters generated from canonical processing
outch Count of the characters output to a tty device

The second structure used by the iostadd kernel service is the dkstat structure, which contains information about disk devices. This structure contains the following fields:

Field Description
diskname 32-character string name for the disk's logical device
dknextp Pointer to the next dkstat structure in the chain
dk_status Disk entry-status flags
dk_time Time the disk is active
dk_bsize Number of bytes in a block
dk_xfers Number of transfers to or from the disk
dk_rblks Number of blocks read from the disk
dk_wblks Number of blocks written to the disk
dk_seeks Number of seek operations for disks
dk_version Version of the dkstat structure
dk_q_depth Que depth
dk_mpio_anchor Pointer to the path data anchor (disk)
dk_mpio_next_path Pointer to the next path dkstat structure in the chain
dk_mpio_path_id Path ID

tty Device Driver Support

The rawinch field in the ttystat structure should be incremented by the number of characters received by the tty device. The caninch field in the ttystat structure should be incremented by the number of input characters generated from canonical processing. The outch field is increased by the number of characters output to tty devices. These fields should be incremented by the device driver, but never be cleared.

Disk Device Driver Support

A disk device driver must perform these four tasks:

If a disk device driver supports MPIO, it must perform the following tasks:
  • Allocate and pin a dkstat structure during device initialization.
  • Update the dkstat.diskname field with the device's logical name.
  • Update the dkstat.dk_bsize field with the number of bytes in a block on the device.
  • Set the value of dkstat.dk_version to dk_qd_mpio_magic.
  • Set the value of dkstat.dk_mpio_anchor to 0 if the dkstat structure being added is the disk.
  • Set the value of dkstat.dk_mpio_anchor to the address of the path's anchor (disk) dkstat structure, and set dkstat.dk_mpio_path_id to the path's ID if the dkstat structure being added is a path.
  • Set all other fields to 0.

If the device supports discrete seek commands, the dkstat.dk_xrate field in the structure should be set to the transfer rate capability of the device (KB/sec). The device's dkstat structure should then be registered using the iostadd kernel service.

During drive operation update, the dkstat.dk_status field should show the busy/nonbusy state of the device. This can be done by setting and resetting the IOST_DK_BUSY flag. The dkstat.dk_xfers field should be incremented for each transfer initiated to or from the device. The dkstat.dk_rblks and dkstat.dk_wblks fields should be incremented by the number of blocks read or written.

If the device supports discrete seek commands, the dkstat.dk_seek field should be incremented by the number of seek commands sent to the device. If the device does not support discrete seek commands, both the dkstat.dk_seek and dkstat.dk_xrate fields should be left with a value of 0.

The base kernel updates the dkstat.dk_nextp and dkstat.dk_time fields. They should not be modified by the device driver after initialization. For MPIO devices, the base kernel also updates the dkstat.dk_mpio_next_path field.

Note: The same dkstat structure must not be registered more than once.
In addition to basic tasks, a disk driver must perform the following tasks before calling the iostadd kernel service if the driver supports the -D option of the iostat command:
  • Set the value of dkstat.dk_version to dk_qd_service2_magic.
  • Set the dkstat.ident.adapter field to the adapter name if the driver does not support MPIO.
During I/O operations, the driver must perform the following tasks:
  • Increase the dkstat.__dk_rxfers field for each read transfer.
  • Update the dkstat.dk_q_depth field with the number of I/O requests which are in progress.
  • Increase the dkstat.dk_q_full field when the number of I/O requests which are in progress reaches the maximum queue depth.
  • Increase the dkstat.dk_rserv field by the service time which is the delta-time base value between when the devstrat kernel service sends a read request to the adapter driver and when the iodone kernel service returns the request from the adapter driver.
  • Increase the dkstat.dk_rtimeout field when the driver retries a failed read request.
  • Increase the dkstat.dk_rfailed field when the driver returns a failed read request as an error.
  • Update the dkstat.dk_min_rserv field with the minimum service time for a read request.
  • Update the dkstat.dk_max_rserv field with the maximum service time for a read request.
  • Increase the dkstat.dk_wserv field by the service time which is the delta-time base value between when the devstrat kernel service sends a write request to the adapter driver and when the iodone kernel service returns the request from the adapter driver.
  • Increase the dkstat.dk_wtimeout field when the driver retries a failed write request.
  • Increase the dkstat.dk_wfailed field when the driver returns a failed write request as an error.
  • Update the dkstat.dk_min_wserv field with the minimum service time for a write request.
  • Update the dkstat.dk_max_wserv field with the maximum service time for a write request.
  • Increase and decrease the dkstat.dk_wq_depth field when the driver enqueues and dequeues an I/O request.
  • Increase the dkstat.dk_wq_time field by the wait time which is the delta-time base value between when the driver enqueues an I/O request and when the devstrat kernel service sends the request to the adapter driver.
  • Update the dkstat.dk_wq_min_time field with the minimum wait time.
  • Update the dkstat.dk_wq_max_time field with the maximum wait time.

Parameters

Item Description
devtype Specifies the type of device for which I/O statistics are kept. The various device types are defined in the /usr/include/sys/devinfo.h file. Currently, I/O statistics are only kept for disks, CD-ROMs, and tty devices. Possible values for this parameter are:
DD_DISK
For disks
DD_CD-ROM
For CD-ROMs
DD_TTY
For tty devices
devstatp Points to an I/O statistics structure for the device type specified by the devtype parameter. For a devtype parameter of DD_tty, the address of a pinned ttystat structure is returned. For a devtype parameter of DD_DISK or DD_CD-ROM, the parameter is an input parameter pointing to a dkstat structure previously allocated by the caller.

On a platform that supports storage keys, the passed in devstatp parameter must be in the KKEY_PUBLIC or KKEY_BLOCK_DEV protection domain.

Execution Environment

The iostadd kernel service can be called from the process environment only.

Return Values

Item Description
0 Indicates that no error has been detected.
EINVAL Indicates that the devtype parameter specified a device type that is not valid. For MPIO devices, indicates that an anchor for a path dkstat structure was not found.