sioc_io(7)

NAME

sioc_io — SCSI pass-through interface

DESCRIPTION

SCSI devices are controlled by a device-specific driver, when one exists. Device-specific drivers, such as those for SCSI direct access (disk) and sequential access (tape) devices, coordinate device and driver states to accomplish correct logical device behavior. The sioc_io pass-through interface enables the use of SCSI devices and commands not normally supported by these device-specific drivers. It is composed of two ioctls: SIOC_IO_EXT, and SIOC_IO.

SIOC_IO_EXT is the pass-through interface introduced with HP-UX 11i V3 release. It is the recommended interface. It should be issued on persistent device files (see intro(7)). It allows to send the SCSI command through any of the available LUN paths or through a specific LUN path.

SIOC_IO is the pass-through interface that existed prior to HP-UX 11i V3. This interface is deprecated with HP-UX 11i V3 release. It is maintained for backward compatibility. It can be used on persistent device files or legacy device files. If issued on a persistent device file, the SCSI command is sent through any of the available LUN paths. If issued on a legacy device file, the SCSI command will be sent through any available LUN paths. However, if multi-pathing is disabled legacy device files (see leg_mpath_enable in scsimgr(1M)), the SCSI command will be sent only through the LUN path corresponding to the legacy device file.

All reserved fields in the data structure associated to the interface must be zero-filled.

The SIOC_IO_EXT/SIOC_IO ioctl allows an arbitrary SCSI command to be sent to a device. All details of the SCSI command protocol are handled automatically.

The data structure for the SIOC_IO_EXT/SIOC_IO ioctl is included from <sys/scsi.h>:

/* SCSI device control ioctls */

#define SIOC_IO_EXT         _IOWR('S', 102, esctl_io_t)
#define SIOC_IO             _IOWR('S', 22, struct sctl_io)

/* Structure for SIOC_IO_EXT ioctl */
typedef struct {
        int                     version;
        escsi_sctl_io_flags_t   flags;
        int                     max_msecs;
        uint32_t                cdb_length;
        uint32_t                data_length;
        ptr64_t                 data;
        union sense_data        sense;
        escsi_hw_path_t         lpt_hwp;
        uint32_t                data_xfer;
        uint32_t                sense_xfer;
        uint32_t                cdb_status;
        uint32_t                sense_status;
        uint8_t                 cdb[ESCSI_MAX_CDB_LEN];
        uint32_t                rsvd[32];  /* Reserved for
                                            * future use
                                            */
} esctl_io_t;

/* Structure for SIOC_IO ioctl */
typedef struct sctl_io {
        unsigned        flags;
        unsigned char   cdb_length;
        unsigned char   cdb[16];
        void            *data;
        unsigned        data_length;
        unsigned        max_msecs;
        unsigned        data_xfer;
        unsigned        cdb_status;
        unsigned char   sense[256];
        unsigned        sense_status;
        unsigned char   sense_xfer;
        unsigned char   reserved[64];
} sctl_io_t;

The following flags can be used to specify the flags field value of both SIOC_IO_EXT and SIOC_IO unless indicated otherwise:

SCTL_READ: Data-in phase expected if the data_length field is non-zero. The absence of this flag implies that a data-out phase is expected if the data_length field is non-zero.
ESCTL_IO_LPT: The SCSI command is to be issued on a given LUN path. This flag can only be specified with SIOC_IO_EXT ioctl. When specified the hardware path of the LUN path to use is specified in field lpt_hwp

The cdb field specifies the SCSI command bytes. The number of command bytes is specified by the cdb_length field. These command bytes are sent to the target device during the SCSI command phase.

The address of the data area for the data phase of the SCSI command is specified by the data field. The data_length field specifies the maximum number of data bytes to be transferred. A zero-valued data_length indicates that no data phase should occur. Most SCSI commands with a data phase expect the data length information to be included somewhere in the command bytes. The caller is responsible for correctly specifying both the data_length field and any cdb data length values. The length may not be larger than SCSI_MAXPHYS and some implementations further restrict this length.

The max_msecs field specifies the maximum time, in milliseconds, that the device should need to complete the command. If this period of time expires without command completion, the system might attempt recovery procedures to regain the device's attention. These recovery procedures might include abort tag, abort, and device and bus reset operations. A zero value in the max_msec field indicates that the timeout period is infinite and the system should wait indefinitely for command completion.

When the SIOC_IO_EXT/SIOC_IO ioctl call returns, all command processing has been completed. Most SIOC_IO_EXT/SIOC_IO ioctl calls will return zero (success). The resulting detailed ioctl data should be used to evaluate "success" or "failure" from the caller's perspective. The cdb_status field indicates the results of the cdb command. If the cdb_status field indicates a S_CHECK_CONDITION status, the sense_status field indicates the results of the SCSI REQUEST SENSE command used to collect the associated sense data. These status fields will contain one of the following values:

SCTL_INVALID_REQUEST: The SCSI command request is invalid and thus not attempted.
SCTL_SELECT_TIMEOUT: The target device does not answer to selection by the host SCSI interface (the device does not exist or does not respond).
SCTL_INCOMPLETE: The device answered selection but the command is not completed (the device took too long or a communication failure occurred).
S_GOOD: Device successfully completed the command.
S_CHECK_CONDITION: Device indicated sense data is available.
S_CONDITION_MET: Device successfully completed the command and the requested (search or pre-fetch) operation is satisfied.
S_BUSY: Device indicated it is unable to accept the command because it is busy doing other operations.
S_INTERMEDIATE: Device successfully completed this command, which is one in a series of linked commands (not supported, see WARNINGS).
S_I_CONDITION_MET: Device indicated both S_INTERMEDIATE and S_CONDITION_MET (not supported, see WARNINGS).
S_RESV_CONFLICT: Device indicated the command conflicted with an existing reservation.
S_COMMAND_TERMINATED: Device indicated the command is terminated early by the host system.
S_QUEUE_FULL: Device indicated it is unable to accept the command because its command queue is currently full.

The data_xfer field indicates the number of data bytes actually transferred during the data phase of the cdb command. This field is valid only when the cdb_status field contains one of the following values: S_GOOD or S_CHECK_CONDITION. The sense_xfer field indicates the number of valid sense data bytes. This field is valid only when the cdb_status field contains the value S_CHECK_CONDITION and the sense_status field contains the value S_GOOD.

Security Restrictions

Use of the SIOC_IO ioctl requires the superuser or DEVOPS privilege, or device write permissions. See privileges(5) for more information about privileged access on systems that support fine-grained privileges.

EXAMPLES

Assume that fildes is a valid file descriptor for a persistent device file of a SCSI device, and leg_fildes is a valid file descriptor for a legacy device file of a SCSI device, and lpt_hwp contains a valid hardware path of a LUN path to the device. The first example attempts a SCSI INQUIRY command:

#include <sys/scsi.h>

esctl_io_t esctl_io;
#define MAX_LEN 255
unsigned char inquiry_data[MAX_LEN];

memset(&esctl_io, 0, sizeof(esctl_io)); /* clear reserved fields */
esctl_io.flags = SCTL_READ;   /* input data expected */
esctl_io.cdb[0] = CMDinquiry;
esctl_io.cdb[1] = 0x00;
esctl_io.cdb[2] = 0x00;
esctl_io.cdb[3] = 0x00;
esctl_io.cdb[4] = MAX_LEN;            /* allocation length */
esctl_io.cdb[5] = 0x00;
esctl_io.cdb_length = 6;              /* 6 byte command */
esctl_io.data = &inquiry_data[0];     /* data buffer location */
esctl_io.data_length = MAX_LEN;       /* maximum transfer length */
esctl_io.max_msecs = 10000;           /* allow 10 seconds for cmd */
if (ioctl(fildes, SIOC_IO_EXT, &esctl_io) < 0) {
        /* request is invalid */
} else {
        if ( esctl_io.cdb_status == S_GOOD) {
                /* success. display inquiry data */
        else {
                /* failure. process depending on cdb_status */
        }
}

The second example attempts a SCSI INQUIRY command via a specific LUN path.

#include <sys/scsi.h>

esctl_io_t esctl_io;
#define MAX_LEN 255
unsigned char inquiry_data[MAX_LEN];
memset(&esctl_io, 0, sizeof(esctl_io)); /* clear reserved fields */
esctl_io.flags = SCTL_READ | SCTL_IO_LPT;  /* input data
                                            * expected and command
                                            * to be sent on given
                                            * LUN path
                                            */
memcpy(&esctl_io.lpt_hwp, lpt_hwp, sizeof(lpt_hwp); /* specify
                                            * the hardware path of
                                            * LUN path through which
                                            * command must be sent
                                            */
esctl_io.cdb[0] = CMDinquiry;
esctl_io.cdb[1] = 0x00;
esctl_io.cdb[2] = 0x00;
esctl_io.cdb[3] = 0x00;
esctl_io.cdb[4] = MAX_LEN;            /* allocation length */
esctl_io.cdb[5] = 0x00;
esctl_io.cdb_length = 6;              /* 6 byte command */
esctl_io.data = &inquiry_data[0];     /* data buffer location */
esctl_io.data_length = MAX_LEN;       /* maximum transfer length */
esctl_io.max_msecs = 10000;           /* allow 10 seconds for cmd */
if (ioctl(fildes, SIOC_IO_EXT, &esctl_io) < 0) {
        /* request is invalid */
} else {
        if ( esctl_io.cdb_status == S_GOOD) {
                /* success. display inquiry data */
        else {
                /* failure. process depending on cdb_status */
        }
}

The following example attempts a SCSI TEST UNIT READY command and checks to see if the device is ready, not ready, or in some other state.

#include <sys/scsi.h>

struct sctl_io sctl_io;

memset(&sctl_io, 0, sizeof(sctl_io)); /* clear reserved fields */
sctl_io.flags = 0;                   /* no data transfer expected */
sctl_io.cdb[0] = 0x00;               /* can use CMDtest_unit_ready */
sctl_io.cdb[1] = 0x00;
sctl_io.cdb[2] = 0x00;
sctl_io.cdb[3] = 0x00;
sctl_io.cdb[4] = 0x00;
sctl_io.cdb[5] = 0x00;
sctl_io.cdb_length = 6;              /* 6 byte command */
sctl_io.data = NULL;                 /* no data buffer is provided */
sctl_io.data_length = 0;             /* do not transfer data */
sctl_io.max_msecs = 10000;           /* allow 10 seconds for cmd */
if (ioctl(leg_fildes, SIOC_IO, &sctl_io) < 0) {
        /* request is invalid */
}
else if (sctl_io.cdb_status == S_GOOD) {
        /* device is ready */
}
else if (sctl_io.cdb_status == S_BUSY ||
         (sctl_io.cdb_status == S_CHECK_CONDITION &&
          sctl_io.sense_status == S_GOOD &&
          sctl_io.sense_xfer > 2 &&
          (sctl_io.sense[2] & 0x0F) == 2)) {
         /* can use sense_data */
        /* device is not ready */
} else {
        /* unknown state */
}

WARNINGS

Incorrect use of sioc_io operations (even those attempting access to non-existent devices) can cause data loss, system panics, and device damage.

The SIOC_EXCLUSIVE ioctl should be used to gain exclusive access to a device prior to attempting SIOC_IO commands. If exclusive access is not obtained, SIOC_IO commands will be intermixed with device-specific driver commands, which can lead to undesirable results.

Device-specific drivers can reject inappropriate or troublesome SIOC_IO commands. However, since not all such operations are known and detected, care should be exercised to avoid disrupting device-specific drivers when using commands that modify internal device states.

Most SCSI commands have a logical unit number (LUN) field. Parallel SCSI implementations on the HP-UX operating system select logical units via the SCSI IDENTIFY message. The LUN portion of the cdb should normally be set to zero, even when the LUN being accessed is not zero.

Use of linked commands is not supported.

Most SCSI commands with a data phase expect the data length information to be included somewhere in the command bytes. Both the data_length field and any cdb data length values must be correctly specified to get correct command results.

Very large (or infinite) timeout values can cause a parallel SCSI bus (potentially the entire system) to hang.

Device and/or bus reset operations can be used to regain a device's attention when a timeout expires.

Resetting a device can cause I/O errors and/or loss of cached data. This can result in loss of data and/or system panics.

Obtaining SCSI INQUIRY data by use of the SIOC_INQUIRY ioctl instead of by use of the SIOC_IO ioctl is generally preferable since SCSI implementations on the HP-UX operating system synchronize access of inquiry data during driver open calls.

Since communication parameters can be affected by device-specific driver capabilities, device-specific driver use might result in communication parameter changes.

FILES

/usr/include/sys/scsi.h
/usr/include/sys/scsi_ctl.h

sioc_io(7)

Technical documentation

» Table of Contents

» Index