Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > S

scsi(7)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

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 deprecated 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 leg_mpath_enable 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 SIOC_INQUIRY 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 SIOC_CAPACITY 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 meaningful for the device. Note that for very large devices, the ioctl argument can overflow, SIOC_STORAGE_CAPACITY is a better choice, than SIOC_CAPACITY where devices can be large. Also note that DIOC_CAPACITY is preferred (see disk(7)).

The header file <sys/scsi.h> has useful information for SCSI devices. The following is included from <sys/scsi.h>:

#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-1 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 SCSI-3 inquiry */ typedef uint8_t vdesc_t[2]; /* SCSI-3 inquiry structure */ 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 rsvd6[22]; uint8_t vendor_parm_bytes[32]; } inquiry_3_t; /* union for SIOC_INQUIRY ioctl */ union inquiry_data { struct inquiry inq1; /* SCSI-1 inquiry */ struct inquiry_2 inq2; /* SCSI-2 inquiry */ inquiry_3_t inq3; /* SCSI-3 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 SIOC_XSENSE 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 SIOC_XSENSE ioctl call, the xsense_aligned.error_class and sense_2_aligned.error_code 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 <sys/scsi.h>:

#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:

EACCES

Required permission is denied for the device or operation.

ENXIO

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.

EINVAL

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 indicates the request or some request argument is invalid. If resulting from the SIOC_CAPACITY ioctl, one or more of the fields in the argument structure may have overflowed.

EBUSY

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).

EIO

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 scsi_ctl interface, the SIOC_CMD_MODE, SIOC_SET_CMD, and SIOC_RETURN_STATUS ioctls are obsolete (see scsi_ctl(7)). Direct manipulation of SCSI devices via the scsi_ctl interface 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 SIOC_CAPACITY ioctl. Total device size in bytes may exceed 232-1 for some devices.

DEPENDENCIES

esdisk/estape/eschgr/sdisk/schgr/stape

The SIOC_EXCLUSIVE 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 supported. The corresponding values are defined in <sys/scsi.h> If the ioctl is issued on a persistent device file, target and bus exclusive access actually 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 SIOC_MEDIUM_CHANGED 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 SIOC_MEDIUM_CHANGED 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 SIOC_EXCLUSIVE ioctl, can be used to avoid this problem.

The following information is included from <sys/scsi.h>:

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

disc3

The SIOC_VPD_INQUIRY ioctl allows access to detailed device specific information. The page_code field specifies which SCSI vital product data page is requested. The page_buf 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 <sys/scsi.h>:

#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

/usr/include/sys/scsi.h

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.