devio(7)						 Miscellaneous Information Manual						  devio(7)

NAME

       devio - device information interface

SYNOPSIS

       #include <sys/ioctl.h>
       #include <sys/devgetinfo.h>
       #include <sys/devio.h>

DESCRIPTION

       The  devio  interface  obtains  status, device attributes, and other information by polling the controlling device driver.  There are three
       ioctl requests associated with this interface: DEVIOCGET, DEVGETINFO and DEVGETGEOM.

       The file <sys/devgetinfo.h> contains the structures and definitions needed by the DEVGETINFO ioctl request; the file <sys/devio.h> contains
       the structures and definitions needed by the DEVIOCGET and DEVGETGEOM ioctl requests.

       The DEVGETINFO and DEVIOCGET ioctl requests are used to obtain generic device information by polling the underlying device driver.  DEVGET-
       INFO is used by disk and tape device drivers; DEVIOCGET is used by other kernel subsystems.

       For DEVIOCGET, the devget structure is the basic structured used by this request.  The devget structure has the following definition:

       /* Structure for DEVIOCGET ioctl - device get status command */

       struct devget  {
	  short   category;	       /* Category		     */
	  short   bus;		       /* Bus			     */
	  char	  interface[DEV_SIZE]; /* Interface (string)	     */
	  char	  device[DEV_SIZE];    /* Device (string)	     */
	  short   adpt_num;	       /* Adapter number	     */
	  short   nexus_num;	       /* Nexus or node on adapter # */
	  short   bus_num;	       /* Bus number		     */
	  short   ctlr_num;	       /* Controller number	     */
	  short   rctlr_num;	       /* Remote controller number   */
	  short   slave_num;	       /* Plug or line number	     */
	  char	  dev_name[DEV_SIZE];  /* Device mnemonic	     */
	  short   unit_num;	       /* Device unit number	     */
	  unsigned soft_count;	       /* Driver soft error count    */
	  unsigned hard_count;	       /* Driver hard error count    */
	  long	  stat; 	       /* Generic status mask	     */
	  long	  category_stat;       /* Category specific mask     */ };

       For DEVGETINFO, the device_info_t union is the top-level definition of the information returned to the device_info_t union is the top-level
       definition of the information returned to the DEVGETINFO ioctl request.	It has the following definition:

       typedef union device_info {
	   int version; 	 /* version number	       */
	   v1_device_info_t v1;  /* bus and device information */
	   uchar_t pad[1024];	 /* unused		       */ } device_info_t;

       The  v1_device_info_t structure contains all the information returned to the user data buffer by the DEVGETINFO ioctl command.  This struc-
       ture is contained within the device_info_t structure so that the same interface can be used for various versions of the data structure.	It
       has the following definition:

       typedef struct v1_device_info  {
	   int version; 		   /* version number		   */
	   short category;		   /* device type, i.e., disk	   */
	   short bus;			   /* bus type			   */
	   char interface[DEV_STRING_SIZE]; /* interface type, i.e., HSC40 */
	   char device[DEV_STRING_SIZE];   /* device description	   */
	   char dev_name[DEV_STRING_SIZE]; /* device name		   */
	   ulong_t soft_count;		   /* number of soft errors	   */
	   ulong_t hard_count;		   /* number of hard errors	   */
	   v1_devtype_info_t devinfo;	   /* device-type information	   */
	   v1_bustype_info_t businfo;	   /* bus-type information	   */
	    uchar_t private[DEV_PRIVATE_LEN]; /* driver-specific	   */ } v1_device_info_t;

       The v1_bustype_info_t structure returns information about the bus type.	It has the following definition: typedef struct v1_bustype_info {
	   int adpt_num;  /* controller chip relative to current adaptor */
	   int nexus_num; /* slot that the adaptor is using		 */
	   int bus_num;   /* logical bus number for the adaptor 	 */
	   int ctlr_num;  /* system-wide instance number of the adaptor  */
	   int rctlr_num; /* remote ID for the adaptor			 */
	   int slave_num; /* number of the device relative to the		  controlling hardware			      */
	   int unit_num;  /* system-wide number of this device		 */
	   int pad0;	  /* unused					 */
	   union  {	       v1_scsi_bus_info_t  scsi;  /*  SCSI-specific		 */	     uchar_t busdata[DEV_BUS_LEN]; /* bus-specific
       */
	   } bus; } v1_bustype_info_t;

       The v1_devtype_info_t union returns device-specific information.  The contents of the v1_devtype_info_t union depends on the  device  type,
       either disk, tape, or other device type.  The structure has the following definition:

       typedef union v1_devtype_info {
	   v1_disk_dev_info_t disk;	  /* disk-specific status	 */
	   v1_tape_dev_info_t tape;	  /* tape-specific status	 */
	   uchar_t devdata[DEV_TYPE_LEN]; /* other device-type status	 */ } v1_devtype_info_t;

       For disk devices, the v1_devtype_info_t union contains a v1_disk_dev_info_t structure, defined as follows:

       typedef struct v1_disk_dev_info {
	   ulong_t  status;	      /* device status			    */
	   ulong_t  capacity;	      /* number of blocks on the device     */
	   ulong_t  blocksz;	      /* number of bytes per block	    */
	   uchar_t  class;	      /* disk class, such as diskette	    */
	   uchar_t  part_num;	      /* total number of partitions	    */
	   uchar_t  raid_level	      /* RAID level of the device	    */
	   uchar_t  pad0;	      /* unused 			    */
	   ushort_t media_changes;    /* number of media changes (diskette) */
	   ushort_t pad1;	      /* unused 			    */
	   union {
	       struct  {	    uchar_t  density_code;  /*	SCSI  density  code		   */	       uchar_t flags;	     /* SCSI flags
       */
	       } scsi;	    uchar_t archdata[DEV_ARCH_LEN]; /* architecture-specific	 */
	   } arch; } v1_disk_dev_info_t;

       For tape devices, the v1_devtype_info_t union contains a v1_tape_dev_info_t structure, defined as follows:

       typedef struct v1_tape_dev_info {
	   uint_t  media_status;	  /* current status of the media    */
	   uint_t  unit_status; 	  /* current status of the unit     */
	   long    recordsz;		  /* record size, or 0 for
					     variable-sized records	    */
	   long    density_bpi; 	  /* current density setting	    */
	   long    density_bpi_wrt;	  /* density used for writes	    */
	   long    position;		  /* number of records written since
					     the last file mark 	    */
	   long    fm_cnt;		  /* number of file marks since the
					     beginning of the tape	    */
	   uchar_t class;		  /* tape device class		    */
	   uchar_t pad[7];		  /* unused			    */
	   union {
	       struct { 	 uint_t  blocking_factor; /*  blocking	factor		*/	      uchar_t  valid_flags;	 /*   valid  flags
       */	    uchar_t density_code;    /*  density code		 */	     uchar_t buffered_mode;   /*  buffered mode 	  */
       uchar_t speed;		/* tape speed		    */		uchar_t compression_code; /* compression code	     */
	       } scsi;	    uchar_t archdata[DEV_ARCH_LEN]; /* architecture-specific */
	   } arch; } v1_tape_dev_info_t;

       The DEVGETGEOM ioctl request is used to obtain disk geometry and attributes by polling the underlying device driver.  The  ioctl  fails	on
       other  types  of  drivers  which do not support DEVGETGEOM.  The DEVGETGEOM may also fail if the device driver is unable to obtain geometry
       information.  This could happen if the disk media is removable and there is no media loaded in the drive.

       The following example shows the basic structure used by this request:

       typedef union devgeom {
	 struct {
	    unsigned long  dev_size;   /* number of blocks in user area    */
	    unsigned short  ntracks;   /* number of tracks per cylinder    */
	    unsigned short  nsectors;  /* number of sectors per track	   */
	    unsigned short  ncylinders; /* total number of cylinders	   */
	    unsigned long   attributes; /* device attributes		   */
	    unsigned long sector_size;	/* number of bytes per sector	   */
	    unsigned long min_trans;	/* minimum transer size 	   */
	    unsigned long max_trans;	/* maximum transfer size	   */
	    unsigned long prefer_trans; /* perferred transfer size	   */
	    unsigned int    headswitch; /* head switch time		   */
	    unsigned int    trkseek;	/* track-to-track seek time	   */
	    unsigned int    acylinders; /* alternate cylinders per unit    */
	    unsigned short  rpm;	/* rotational speed		   */
	    unsigned short  interleave; /* hardware sector interleave	   */
	    unsigned short  trackskew;	/* sector 0 skew, per track	   */
	    unsigned short  sparespertrack; /* spare sectors per track	   */
	    unsigned short  sparespercyl;   /* spare sectors per cylinder  */
	    unsigned short  cylskew;	/* sector 0 skew, per cylinder	   */
	  } geom_info;
	  unsigned char       pad[108];  /* Allocate space for expansion */ } DEVGEOMST;

       The following is a description of the fields of the DEVGEOMST data structure.  Many of the fields correspond to attributes that	are  often
       specified  in the disk description file /etc/disktab .  This ioctl is used by the creatediskbyname subroutine to dynamically generate disk-
       tab entries.

       dev_size    This field contains the number of user accessible blocks on the disk.  The corresponding disktab field is pc,  which  describes
		   the size of the "c" partition.

       ntracks	   This field contains the number of tracks per cylinder and corresponds to the nt field of a disktab entry.

       nsectors    This field contains the number of sectors per track and corresponds to the ns field of a disktab entry.

       ncylinders  This field contains the number of cylinders on the disk and corresponds to the nc field of a disktab entry.

       attributes  This field represents disk attributes.

       sector_size This field specifies the number of bytes per sector.

       min_trans   This field specifies the minimum number of bytes that can be transferred at one time.

       max_trans   This field specifies the maximum number of bytes that can be transferred at one time.

       prefer_trans
		   This field specifies the preferred number of bytes in any single transfer.

       headswitch  This field specifies the number of microseconds the disk takes to switch heads.

       trkseek	   This field specifies the number of microseconds the disk takes to seek from track to track.

       acylinders  This field specifies the number of alternate cylinders that exist on the unit.

       rpm	   This field specifies the rotational speed of the disk.

       interleave  This field specifies the hardware sector interleave.

       trackskew   This field specifies the sector 0 skew, per track.

       sparespertrack
		   This field specifies the number of spare sectors that exist on each track.

       sparespercyl
		   This field specifies the number of spare sectors that exist on each cynlinder.

       cylskew	   This field specifies the sector 0 skew, per cylinder.

       pad	   This  field	is not used to store disk information.	The pad element of the DEVGEOMST is used to provide room for future expan-
		   sion of the information fields.

RELATED INFORMATION

       disktab(4) delim off

																	  devio(7)