scsi(7) 						 Miscellaneous Information Manual						   scsi(7)

NAME

       scsi - Small Computer System Interface device drivers

DESCRIPTION

       The  Small  Computer  System Interface (SCSI) is an American National Standard for interconnecting computers and peripheral devices.  HP-UX
       supports the SCSI device protocol on parallel SCSI interfaces (see ANSI Std X3.131-199X, "SCSI-2"), Fibre Channel interfaces (see ANSI  Std
       X3.269-199X, "Fibre Channel Protocol for SCSI"), and Serial Attached SCSI interfaces (SAS).

       The  SCSI  standard  includes specifications for a variety of device types.  This section describes the general SCSI interface for all SCSI
       device drivers.	Information about specific device types can be found in the manual sections which describe SCSI peripheral device  drivers
       for those device types.

       The ioctls described here can be issued either on persistent device files or legacy devices (see intro(7)).  Legacy device files are depre-
       cated with HP-UX release 11i V3.  They are maintained for backward compatibility, and may be obsolete in future releases.

       The behavior of some ioctls may differ depending on whether issued on persistent device files or legacy device files,  and  whether  multi-
       pathing	is  enabled on legacy device files.  Typically ioctls issuing SCSI commands to a device may use any available LUN path to send the
       commands.  However, when multi-pathing is disabled on legacy device files (see attribute in scsimgr(1M)), the ioctl only  attempts  to  use
       the  LUN  path corresponding to the legacy device file.	If this LUN path is not available, the ioctl will fail even if there are other LUN
       paths available.  This behavior corresponds to the legacy behavior.

       The ioctl is supported by all SCSI device drivers.  This ioctl returns the SCSI device-specific INQUIRY command data.  This  data  contains
       device  identification and capability information.  Since there have been multiple versions of the SCSI standard for inquiry data, multiple
       versions of the inquiry data declaration are provided.  The SCSI-1 version is provided for backward compatibility only.	 If  issued  on  a
       legacy  device  file, this ioctl only tries to use the LUN path corresponding to the legacy device file even if multi-pathing is enabled on
       legacy device files.

       The ioctl indicates the current device size.  A device size is defined to be a logical block size and some number of logical  blocks.   The
       means  of  determining this device-size data is particular to the specific device type.	Logical block size and/or number of logical blocks
       equal to zero indicates: the device size is unknown, the device is not currently capable of I/O operations, or I/O operations are not mean-
       ingful  for  the  device.  Note that for very large devices, the ioctl argument can overflow, is a better choice, than where devices can be
       large.  Also note that is preferred (see disk(7)).

       The header file has useful information for SCSI devices.  The following is included from

	      #define SIOC_INQUIRY	      _IOR('S', 2, union inquiry_data)
	      #define SIOC_CAPACITY	      _IOR('S', 3, struct capacity)
	      #define SIOC_STORAGE_CAPACITY   _IOR('S', 101, storage_capacity_t)

	      /* SCSI inquiry structure */
	      struct inquiry {
		      unsigned char   dev_type;
		      unsigned int    rmb     :1;
		      unsigned int    dtq     :7;
		      unsigned int    iso     :2;
		      unsigned int    ecma    :3;
		      unsigned int    ansi    :3;
		      unsigned int    resv    :4;
		      unsigned int    rdf     :4;
		      unsigned char   added_len;
		      unsigned char   dev_class[3];
		      char	      vendor_id[8];
		      char	      product_id[16];
		      char	      rev_num[4];
		      unsigned char   vendor_spec[20];
		      unsigned char   resv4[40];
		      unsigned char   vendor_parm_bytes[32];
	      };

	      /* SCSI-2 inquiry structure */
	      struct inquiry_2 {
		      unsigned int    periph_qualifier:3;
		      unsigned int    dev_type	      :5;
		      unsigned int    rmb	      :1;
		      unsigned int    dtq	      :7;
		      unsigned int    iso	      :2;
		      unsigned int    ecma	      :3;
		      unsigned int    ansi	      :3;
		      unsigned int    aenc	      :1;
		      unsigned int    trmiop	      :1;
		      unsigned int    resv1	      :2;
		      unsigned int    rdf	      :4;
		      unsigned char   added_len;
		      unsigned char   resv2[2];
		      unsigned int    reladr	      :1;
		      unsigned int    wbus32	      :1;
		      unsigned int    wbus16	      :1;
		      unsigned int    sync	      :1;
		      unsigned int    linked	      :1;
		      unsigned int    resv3	      :1;
		      unsigned int    cmdque	      :1;
		      unsigned int    sftre	      :1;
		      char	      vendor_id[8];
		      char	      product_id[16];
		      char	      rev_num[4];
		      unsigned char   vendor_spec[20];
		      unsigned char   resv4[40];
		      unsigned char   vendor_parm_bytes[32];
	      } inquiry_2_t;

	      /* Definition for version description in SPC-2, SPC-3, and SPC-4 inquiry */
	      typedef uint8_t	      vdesc_t[2];

	      /* SCSI-3 inquiry structure */

	      /*
	       * Note that this stucture does not match the SCSI-3 (SPC) spec. Structures
	       * have been added below for SPC, SPC-2, SPC-3, and SPC-4. This structure is
	       * kept here for binary compatibility.
	       */

	      typedef struct inquiry_3 {
		      uint32_t	      pq	      :3;
		      uint32_t	      pdt	      :5;
		      uint32_t	      rmb	      :1;
		      uint32_t	      rsvd1	      :7;
		      uint32_t	      version	      :8;
		      uint32_t	      aerc	      :1;
		      uint32_t	      obslt1	      :1;
		      uint32_t	      naca	      :1;
		      uint32_t	      hisup	      :1;
		      uint32_t	      rdf	      :4;
		      uint32_t	      added_len       :8;
		      uint32_t	      sccs	      :1;
		      uint32_t	      rsvd2	      :7;
		      uint32_t	      bque	      :1;
		      uint32_t	      encserv	      :1;
		      uint32_t	      vs1	      :1;
		      uint32_t	      multip	      :1;
		      uint32_t	      mchngr	      :1;
		      uint32_t	      obslt2	      :1;
		      uint32_t	      obslt3	      :1;
		      uint32_t	      addr16	      :1;
		      uint32_t	      reladr	      :1;
		      uint32_t	      obslt4	      :1;
		      uint32_t	      wbus16	      :1;
		      uint32_t	      sync	      :1;
		      uint32_t	      linked	      :1;
		      uint32_t	      obslt5	      :1;
		      uint32_t	      cmdque	      :1;
		      uint32_t	      vs2	      :1;
		      uint8_t	      vendor_id[8];
		      uint8_t	      product_id[16];
		      uint8_t	      rev_num[4];
		      uint8_t	      vendor_spec[20];
		      uint16_t	      rsvd3	      :4;
		      uint16_t	      clcking	      :2;
		      uint16_t	      qas	      :1;
		      uint16_t	      ius	      :1;
		      uint16_t	      rsvd4	      :8;
		      vdesc_t	      vers_desc[8];
		      uint8_t	      rsvd5[22];
		      uint8_t	      vendor_parm_bytes[32];
	      } inquiry_3_t;

	      /* SCSI-3 inquiry structure for SPC */
	      typedef struct inquiry_3_new {
		      uint32_t	      pq	      :3;
		      uint32_t	      pdt	      :5;
		      uint32_t	      rmb	      :1;
		      uint32_t	      rsvd1	      :7;
		      unsigned int    iso	      :2;
		      unsigned int    ecma	      :3;
		      unsigned int    ansi	      :3;
		      uint32_t	      aerc	      :1;
		      uint32_t	      trmtsk	      :1;
		      uint32_t	      naca	      :1;
		      uint32_t	      rsvd2	      :1;
		      uint32_t	      rdf	      :4;
		      uint32_t	      added_len       :8;
		      uint32_t	      rsvd3	      :8;
		      uint32_t	      rsvd4	      :1;
		      uint32_t	      encserv	      :1;
		      uint32_t	      vs1	      :1;
		      uint32_t	      multip	      :1;
		      uint32_t	      mchngr	      :1;
		      uint32_t	      ackreqq	      :1;
		      uint32_t	      addr32	      :1;
		      uint32_t	      addr16	      :1;
		      uint32_t	      reladr	      :1;
		      uint32_t	      wbus32	      :1;
		      uint32_t	      wbus16	      :1;
		      uint32_t	      sync	      :1;
		      uint32_t	      linked	      :1;
		      uint32_t	      trandis	      :1;
		      uint32_t	      cmdque	      :1;
		      uint32_t	      vs2	      :1;
		      uint8_t	      vendor_id[8];
		      uint8_t	      product_id[16];
		      uint8_t	      rev_num[4];
		      uint8_t	      vendor_spec[20];
		      uint8_t	      rsvd5[40];
		      uint8_t	      vendor_parm_bytes[32];
	      } inquiry_3_t_new;

	      /* SPC-2 inquiry structure */
	      typedef struct inquiry_4 {
		      uint32_t	      pq	      :3;
		      uint32_t	      pdt	      :5;
		      uint32_t	      rmb	      :1;
		      uint32_t	      rsvd1	      :7;
		      uint32_t	      version	      :8;
		      uint32_t	      aerc	      :1;
		      uint32_t	      obslt1	      :1;
		      uint32_t	      naca	      :1;
		      uint32_t	      hisup	      :1;
		      uint32_t	      rdf	      :4;
		      uint32_t	      added_len       :8;
		      uint32_t	      sccs	      :1;
		      uint32_t	      rsvd2	      :7;
		      uint32_t	      bque	      :1;
		      uint32_t	      encserv	      :1;
		      uint32_t	      vs1	      :1;
		      uint32_t	      multip	      :1;
		      uint32_t	      mchngr	      :1;
		      uint32_t	      obslt2	      :1;
		      uint32_t	      obslt3	      :1;
		      uint32_t	      addr16	      :1;
		      uint32_t	      reladr	      :1;
		      uint32_t	      obslt4	      :1;
		      uint32_t	      wbus16	      :1;
		      uint32_t	      sync	      :1;
		      uint32_t	      linked	      :1;
		      uint32_t	      obslt5	      :1;
		      uint32_t	      cmdque	      :1;
		      uint32_t	      vs2	      :1;
		      uint8_t	      vendor_id[8];
		      uint8_t	      product_id[16];
		      uint8_t	      rev_num[4];
		      uint8_t	      vendor_spec[20];
		      uint16_t	      rsvd3	      :4;
		      uint16_t	      clcking	      :2;
		      uint16_t	      qas	      :1;
		      uint16_t	      ius	      :1;
		      uint16_t	      rsvd4	      :8;
		      vdesc_t	      vers_desc[8];
		      uint8_t	      rsvd5[22];
		      uint8_t	      vendor_parm_bytes[32];
	      } inquiry_4_t;

	      /* SPC-3 and SPC-4 inquiry structure */
	      typedef struct inquiry_5 {
		      uint32_t	      pq	      :3;
		      uint32_t	      pdt	      :5;
		      uint32_t	      rmb	      :1;
		      uint32_t	      rsvd1	      :7;
		      uint32_t	      version	      :8;
		      uint32_t	      obslt1	      :2;
		      uint32_t	      naca	      :1;
		      uint32_t	      hisup	      :1;
		      uint32_t	      rdf	      :4;
		      uint32_t	      added_len       :8;
		      uint32_t	      sccs	      :1;
		      uint32_t	      acc	      :1;
		      uint32_t	      tpgs	      :2;
		      uint32_t	      third_pc	      :1;
		      uint32_t	      rsvd2	      :2;
		      uint32_t	      protect	      :1;
		      uint32_t	      bque	      :1;     /* Obsolete for SPC-4 */
		      uint32_t	      encserv	      :1;
		      uint32_t	      vs1	      :1;
		      uint32_t	      multip	      :1;
		      uint32_t	      mchngr	      :1;     /* Obsolete for SPC-4 */
		      uint32_t	      obslt2	      :2;
		      uint32_t	      addr16	      :1;
		      uint32_t	      obslt3	      :2;
		      uint32_t	      wbus16	      :1;
		      uint32_t	      sync	      :1;
		      uint32_t	      linked	      :1;     /* Obsolete for SPC-4 */
		      uint32_t	      obslt4	      :1;
		      uint32_t	      cmdque	      :1;
		      uint32_t	      vs2	      :1;
		      uint8_t	      vendor_id[8];
		      uint8_t	      product_id[16];
		      uint8_t	      rev_num[4];
		      uint8_t	      vendor_spec[20];
		      uint16_t	      rsvd3	      :4;
		      uint16_t	      clcking	      :2;
		      uint16_t	      qas	      :1;
		      uint16_t	      ius	      :1;
		      uint16_t	      rsvd4	      :8;
		      vdesc_t	      vers_desc[8];
		      uint8_t	      rsvd6[22];
		      uint8_t	      vendor_parm_bytes[32];
	      } inquiry_5_t;

	      /* union for SIOC_INQUIRY ioctl */
	      union inquiry_data {
		      struct inquiry   inq1;	/* SCSI-1 inquiry */
		      inquiry_2_t      inq2;	/* SCSI-2 inquiry */
		      inquiry_3_t      inq3;	/* SCSI-3 inquiry */
		      inquiry_3_t_new  inq3n;	/* SCSI-3 (SPC) inquiry */
		      inquiry_4_t      inq4;	/* SPC-2 inquiry */
		      inquiry_5_t      inq5;	/* SPC-3 and SPC-4 inquiry */
	      };

	      /* structure for SIOC_CAPACITY ioctl */
	      struct capacity {
		      uint32_t lba;
		      uint32_t blksz;
	      };

	      /* structure for SIOC_STORAGE_CAPACITY ioctl */
	      typedef struct {
		      uint64_t lba;
		      uint32_t blksz;
	      } storage_capacity_t;

       The ioctl returns detailed information about device status and errors when such information is available.  Since there have  been  multiple
       versions  of  the SCSI standard for sense (status) data, multiple versions of the sense data declaration are provided.  The SCSI-1 and non-
       aligned versions are provided for backward compatibility only.  If no new  CHECK-CONDITION-caused  REQUEST  SENSE  command  data  has  been
       obtained  since	the  last  ioctl call, the and fields will contain the value zero.  Applications which require more accurate REQUEST SENSE
       data handling should use the SCSI device-control driver (see scsi_ctl(7)).

       The following information is included from

	      #define SIOC_XSENSE	   _IOR('S', 7, union sense_data)

	      /* structure for SIOC_XSENSE ioctl */
	      typedef union sense_data {
		      xsense_aligned_t	   r_sense1a;	/* SCSI and CCS devices */
		      sense_2_aligned_t    r_sense2a;	/* SCSI-2 devices */
		      xsense_t		   r_sense1;	/* Do not use; for
							 * compatibility only
							 */
		      sense_2_t 	   r_sense2;	/* Do not use; for
							 * compatibility only
							 */
	      } sense_data_t;

	      /*
	       * Struct xsense_aligned is for examining the sense data of SCSI-1
	       * and CCS devices.
	       */
	      typedef struct xsense_aligned {
		      unsigned int    valid	      :1;
		      unsigned int    error_class     :3;
		      unsigned int    error_code      :4;
		      unsigned char   seg_num;
		      unsigned int    parms:4;
		      unsigned int    sense_key       :4;
		      unsigned char   lba[4];
		      unsigned char   add_len;
		      unsigned char   copysearch[4];  /* Unused by HP-UX */
		      unsigned char   sense_code;
		      unsigned char   resv;
		      unsigned char   fru;
		      unsigned char   field;
		      unsigned char   field_ptr[2];
		      unsigned char   dev_error[4];
		      unsigned char   misc_bytes[106];
	      } xsense_aligned_t;

	      /*
	       *  Struct sense_2_aligned is for examining the sense data
	       *  of SCSI-2 devices
	       */
	      typedef struct sense_2_aligned {
		      unsigned int    info_valid      :1;
		      unsigned int    error_code      :7;
		      unsigned char   seg_num;
		      unsigned int    filemark	      :1;
		      unsigned int    eom	      :1;
		      unsigned int    ili	      :1;
		      unsigned int    resv	      :1;
		      unsigned int    key	      :4;
		      unsigned char   info[4];
		      unsigned char   add_len;
		      unsigned char   cmd_info[4];
		      unsigned char   code;
		      unsigned char   qualifier;
		      unsigned char   fru;
		      unsigned char   key_specific[3];
		      unsigned char   add_sense_bytes[113];
	      } sense_2_aligned_t;

	      /*
	       * Struct xsense is provided for backward source code
	       * compatibility only.
	       * Struct xsense_aligned is the appropriate struct for
	       * examining the sense
	       * data of SCSI-1 and CCS devices.
	       */
	      typedef struct xsense {
		      unsigned int    valid	      :1;
		      unsigned int    error_class     :3;
		      unsigned int    error_code      :4;
		      unsigned char   seg_num;
		      unsigned int    parms	      :4;
		      unsigned int    sense_key       :4;
		      unsigned char   lba[4];
		      unsigned char   add_len;
		      unsigned char   copysearch[4];  /* Unused by HP-UX */
		      unsigned char   sense_code;
		      unsigned char   resv;
		      unsigned char   fru;
		      unsigned char   field;
		      unsigned short  field_ptr;
		      uint32_t	      dev_error;
		      unsigned char   misc_bytes[106];
	      } xsense_t;

	      /*
	       * Struct sense_2 is provided for backward source code
	       * compatibility only.
	       * Struct sense_2_aligned is the appropriate struct for
	       * examining the sense
	       * data of SCSI-2 devices.
	       */
	      typedef struct sense_2 {
		      unsigned int    info_valid      :1;
		      unsigned int    error_code      :7;
		      unsigned char   seg_num;
		      unsigned int    filemark	      :1;
		      unsigned int    eom	      :1;
		      unsigned int    ili	      :1;
		      unsigned int    resv	      :1;
		      unsigned int    key	      :4;
		      unsigned char   info[4];
		      unsigned char   add_len;
		      unsigned int    cmd_info;
		      unsigned char   code;
		      unsigned char   qualifier;
		      unsigned char   fru;
		      unsigned char   key_specific[3];
		      unsigned char   add_sense_bytes[113];
	      } sense_2_t;

ERRORS

       The following errors may result from a call to a SCSI device driver:

       Required permission is denied for the device or operation.

       If resulting from an open call,
		      this indicates there is no device at the specified address.  For other calls, this indicates the specified address is out of
		      range or the device may no longer be accessed.

       If resulting from an open call,
		      this  indicates the device is not supported by the device driver (e.g., incorrect device type).  For other calls, this indi-
		      cates the request or some request argument is invalid.  If resulting from the ioctl, one or more of the fields in the  argu-
		      ment structure may have overflowed.

       This indicates the device is not ready for use
		      or  that	the  requested	operation  conflicts  with other operations (e.g., the device is currently open via another device
		      driver or exclusive access is in effect).

       Indicates a SCSI protocol or communication problem has occurred,
		      or that a SCSI command resulted in a non-good status.

       Manual entries that describe specific SCSI peripheral device drivers may provide additional qualification of error results.

WARNINGS

       Use of devices that are not officially supported can cause data loss, system panics and device damage.  HP-UX device drivers expect devices
       to  be  SCSI-2  compliant.  Unsupported devices that are only SCSI-CCS compliant may work but their use is discouraged.	Use of unsupported
       devices that are only SCSI-1 compliant is strongly discouraged.

       Changing SCSI bus connectivity (recabling) while the system is running is not supported.  Switching SCSI device power on or off	while  the
       device  is  connected to a system that does not support powerfail recovery is not supported.  These activities are known to cause data loss
       and system panics.

       On systems that support the interface, the and ioctls are obsolete (see scsi_ctl(7)).  Direct manipulation of SCSI devices via  the  inter-
       face provides a more functionally complete and easier-to-use means of low level SCSI device control (see scsi_ctl(7)).

       Drivers	that support only devices which have no meaningful size may not support the ioctl.  Total device size in bytes may exceed for some
       devices.

DEPENDENCIES

   esdisk/estape/eschgr/sdisk/schgr/stape
       The ioctl may be used to obtain and release exclusive access.  Exclusive access, which prevents simultaneous access by other  applications,
       is  required  for  some	operations and may be desirable in other circumstances.  The following exclusive access control arguments are sup-
       ported.	The corresponding values are defined in If the ioctl is issued on a persistent device file, target and bus exclusive access  actu-
       ally result to LUN exclusive access.
	      SIOC_REL_LUN_EXCL Release exclusive access to logical unit (LUN).

	      SIOC_SET_LUN_EXCL
		     Gain exclusive access to logical unit (LUN).

	      SIOC_REL_TGT_EXCL
		     Release exclusive access to associated SCSI target.

	      SIOC_SET_TGT_EXCL
		     Gain exclusive access to associated SCSI target.

	      SIOC_REL_BUS_EXCL
		     Release exclusive access to associated SCSI bus.

	      SIOC_SET_BUS_EXCL
		     Gain exclusive access to associated SCSI bus.

       The  ioctl  indicates  when  the  media	in  a removable-media device may have changed.	A value of "1" indicates the device media may have
       changed since the last ioctl call.  Note that only the first such call after a media change receives  this  indication.	 This  means  that
       media  changes are likely to be missed if multiple applications are attempting to detect media changes.	Exclusive access, obtained through
       use of the ioctl, can be used to avoid this problem.

       The following information is included from

	      #define SIOC_MEDIUM_CHANGED  _IOR('S', 42, int)
	      #define SIOC_EXCLUSIVE	   _IOR('S', 68, int)

   disc3
       The ioctl allows access to detailed device specific information.  The field specifies which SCSI vital product data page is requested.  The
       field  is  filled  with	the requested page data.  This ioctl when issued on a legacy device file only attempts to send the INQUIRY command
       through the LUN path corresponding to the legacy device file even if  multi-pathing is enabled on legacy device files.

       The following information is included from

	      #define SIOC_VPD_INQUIRY	_IOWR('S', 10, struct vpd_inquiry)

	      /* union for SIOC_VPD_INQUIRY ioctl */
	      struct vpd_inquiry {
		     char    page_code;       /* VPD page code		   */
		     char    page_buf[126];   /* buffer for VPD page info  */
	      };

FILES

SEE ALSO

       diskinfo(1M), ioctl(2), autochanger(7), intro(7), scsi_ctl(7), scsi_disk(7), scsi_tape(7).

																	   scsi(7)