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 (see ANSI Std X3.131-199X, “SCSI-2”). 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 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.

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.

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

#defineSIOC_INQUIRY            _IOR(’S’, 2, union inquiry_data)
#defineSIOC_CAPACITY           _IOR(’S’, 3, struct capacity)
/* SCSI-1 inquiry structure */
struct inquiry {
        unsigned char    dev_type;
        unsigned char    rmb:1;
        unsigned char    dtq:7;
        unsigned char    iso:2;
        unsigned char    ecma:3;
        unsigned char    ansi:3;
        unsigned char    resv:4;
        unsigned char    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 char    periph_qualifier:3;
        unsigned char    dev_type:5;
        unsigned char    rmb:1;
        unsigned char    dtq:7;
        unsigned char    iso:2;
        unsigned char    ecma:3;
        unsigned char    ansi:3;
        unsigned char    aenc:1;
        unsigned char    trmiop:1;
        unsigned char    resv1:2;
        unsigned char    rdf:4;
        unsigned char    added_len;
        unsigned char    resv2[2];
        unsigned char    reladr:1;
        unsigned char    wbus32:1;
        unsigned char    wbus16:1;
        unsigned char    sync:1;
        unsigned char    linked:1;
        unsigned char    resv3:1;
        unsigned char    cmdque:1;
        unsigned char    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];
};
/* union for SIOC_INQUIRY ioctl */
union inquiry_data {
        struct inquiry   inq1;    /* SCSI-1 inquiry */
        struct inquiry_2 inq2;    /* SCSI-2 inquiry */
};
/* structure for SIOC_CAPACITY ioctl */
struct capacity {
        int   lba;
        int   blksz;
};

DEPENDENCIES

Series 300/400/700

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 */
union sense_data {
        struct xsense_aligned r_sense1a; /* SCSI and CCS devices */
        struct sense_2_aligned r_sense2a;       /* SCSI-2 devices */
};
/* structure for SCSI-1 and SCSI-CCS sense data */
struct xsense_aligned {
        unsigned char   valid:1;
        unsigned char   error_class:3;
        unsigned char   error_code:4;
        unsigned char   seg_num;
        unsigned char   parms:4;
        unsigned char   sense_key:4;
        unsigned char   lba[4];
        unsigned char   add_len;
        unsigned char   copysearch[4];
        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];
};
/* structure for SCSI-2 sense data */
struct sense_2_aligned {
        unsigned char   info_valid:1;
        unsigned char   error_code:7;
        unsigned char   seg_num;
        unsigned char   filemark:1;
        unsigned char   eom:1;
        unsigned char   ili:1;
        unsigned char   resv:1;
        unsigned char   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];
};

Series 700

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:

0 Release exclusive access to logical unit (LUN).

1 Gain exclusive access to logical unit (LUN).

2 Release exclusive access to associated SCSI target.

3 Gain exclusive access to associated SCSI target.

4 Release exclusive access to associated SCSI bus.

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

Series 800

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.

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 */
};

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.

ERRORS

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

[EACCES] Required permission is denied for the 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.

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

Museum

Related Articles

scsi(7)

NAME

DESCRIPTION

DEPENDENCIES

Series 300/400/700

Series 700

Series 800

WARNINGS

ERRORS

SEE ALSO