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_ctl(7)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

scsi_ctl — SCSI pass-through driver (esctl/sctl)

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 SCSI pass-through driver enables use of SCSI devices and commands not normally supported by these device-specific drivers.

esctl is the SCSI pass-through driver and works with persistent device files (see intro(7)). sctl is the SCSI pass-through driver already used on HP-UX releases prior to HP-UX 11i V3. It is maintained here for backward compatibility, and works with legacy device files. In this document scsi_ctl refers to both esctl and sctl.

Once the device is opened through scsi_ctl driver, ioctl calls can be used to change SCSI communication parameters or attempt SCSI commands and other SCSI operations. Since pass-through driver does not attempt to logically understand the target device, read() and write() calls are not supported.

Except where noted, the ioctls described here are available through all SCSI device drivers (including device-specific drivers). All reserved fields in the data structures associated with these ioctls must be zero-filled.

The following ioctls which are specific to parallel SCSI, are deprecated for issuance on LUN device special files (DSF). They are not supported on persistent device special files. They continue to be supported on legacy device special files for backward compatibility. But, it is recommended now to issue them or equivalent ioctls introduced with HP-UX 11i V3, directly on the parallel SCSI HBA device special file (DSF).

SIOC_GET_TGT_PARMS

SIOC_GET_BUS_PARMS

SIOC_GET_TGT_LIMITS

SIOC_GET_BUS_LIMITS

SIOC_SET_TGT_LIMITS

SIOC_SET_BUS_LIMITS

The following parallel SCSI specific ioctls introduced with HP-UX 11i V3 should be issued directly on the parallel SCSI HBA DSF. They replace some existing ioctls, which can no longer be issued on LUN persistent device files starting with HP-UX 11i V3:

PSIOC_GET_TGT_LIMITS

replaces SIOC_GET_TGT_PARMS

PSIOC_GET_TGT_PARMS

replaccs SIOC_GET_BUS_PARMS

PDIOC_RSTCLR

replaces DIOC_RSTCLR

PSIOC_RESET_DEV

replaces SIOC_RESET_DEV

Legacy device files are deprecated with HP-UX release 11i V3. They are maintained for backward compatibility, and may be obsolete in a future release (see intro(7) for details about legacy device file and persistent device files). It is recommended to use persistent device files for new applications.

Most of the ioctls described here can be issued either on persistent device files or legacy device files. 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 the device 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.

Device Special File Minor Number

The pass-through driver (esctl/sctl) is the preferred method to perform the ioctls SIOC_IO_EXT (esctl only) and SIOC_IO ioctls, rather than going through a device-specific driver (such as esdisk). To do this, you must create the device special file for the pass-through driver. mksf(1M) is the recommended method to create a pass-through device file for esctl. To create a device file for the legacy pass-through driver sctl, use mknod(1M), substituting the values in the minor number as noted:

/usr/sbin/mknod name c 203 0xiitl0o

where component parts of the minor number are constructed as follows:

ii

Two hexadecimal digits, identifying the controlling interface card by its "Instance" number. The Instance value is displayed in ioscan(1M) output, under column I for the "Interface" hardware type.

t

One hexadecimal digit identifying the drive (target) address.

l

One hexadecimal digit identifying the logical unit number (LUN) within the device.

0

Hexadecimal digit zero, for reserved portion of the minor of the minor number.

o

Optional values as follows:

0

To perform Inquiry on open to to ensure the device exists (recommended); or

2

To inhibit Inquiry on open. Starting with HP-UX 11i V3, option 2 is deprecated. It is maintained for binary compatibility with existing applications already setting it. Inquiry command will actually be sent during open, regardless of this option being set or not to 2.

SCSI Communication Parameters

HP-UX supports the SCSI device protocol on parallel SCSI interfaces, Fibre Channel interfaces, and Serial Attached SCSI interfaces. The SCSI communication parameters described here might only apply to certain SCSI interfaces and are noted as such in the descriptions.

SCSI communication parameters control features related to communication for three different scope levels: bus (link), target, and logical unit number (LUN). Bus communication parameters apply to all targets connected to a specific bus. Target communication parameters apply to all LUNs associated with a specific target. LUN communication parameters apply to a specific LUN. SCSI communication parameters apply to all device drivers (both device-specific and scsi_ctl).

At power-up and after being reset, all parallel SCSI devices and hosts communicate using asynchronous data transfers. Asynchronous data transfers use request (REQ) and acknowledge (ACK) signaling. The strict ordering of REQ and ACK signaling simplifies the communication protocol but limits I/O performance. A SCSI target and host pair may agree to use synchronous data transfers to increase I/O performance.

Synchronous data transfers improve I/O performance by lessening the ordering requirements on REQs and ACKs. By allowing multiple outstanding REQs, signal propagation delays and temporary rate imbalances are better tolerated. To make use of synchronous data transfers, a SCSI target and host must negotiate to determine mutually acceptable maximum REQ-ACK-offset and data-transfer rate parameters.

The maximum REQ-ACK-offset parameter indicates the maximum allowable number of outstanding REQs. The value zero is used to indicate asynchronous data transfer. Other values indicate synchronous data transfer. The appropriate value is generally dependent on the size of the receive data FIFO. High values tend to improve data transfer rates. The maximum data-transfer rate parameter indicates the "burst" data transfer rate (minimum allowable time between successive synchronous data transfers). A SCSI synchronous data transfer request (SDTR) message, used to initiate the negotiation process, is associated with the processing of a SCSI command.

At power-up and after being reset, all parallel SCSI devices and hosts communicate using eight-bit data transfers. A SCSI target and host pair may agree to use sixteen-bit (wide) data transfers to increase I/O performance. To make use of wide data transfers, a SCSI target and host must negotiate to determine a mutually acceptable data transfer width parameter. A SCSI wide data transfer request (WDTR) message, used to initiate the negotiation process, is associated with the processing of a SCSI command.

Some SCSI devices are able to simultaneously manage multiple active commands. Such a device has a command queue that holds commands for processing. Command queuing can improve I/O performance by reducing the time spent by the device waiting for new commands from the host. Note that command queuing might not improve I/O performance substantially for devices that support "read-ahead" and "immediate-reporting" (see scsi_disk(7) and scsi_tape(7)). The SCSI device and host use command tags to correctly manage these multiple simultaneously active commands. At all times when command queuing is in effect, each active command being handled by a specific LUN has a unique command tag.

SCSI devices indicate their ability to support the special communication features described above in their SCSI INQUIRY command data. Normally the SCSI INQUIRY command data and negotiation protocols allow hosts and devices to determine the optimal communication parameters so that I/O performance is maximized.

The current operating communication parameters may be determined by use of the: SIOC_GET_LUN_PARMS, PSIOC_GET_TGT_PARMS (recommended) or SIOC_GET_TGT_PARMS (for backward compatibility), and SIOC_GET_BUS_PARMS ioctls.

Occasionally, it is desirable to limit SCSI communication parameters to work around a communication problem or to provide external insight in determining optimal parameters. SCSI communication parameter limit suggestions can be specified by use of the: SIOC_SET_LUN_LIMITS, SIOC_SET_TGT_LIMITS, and SIOC_SET_BUS_LIMITS ioctls.

Note that there might be substantial differences between specified communication parameter limit suggestions and the corresponding actual current communication parameters being used for communication. These differences are a result of device-specific driver capabilities, interface driver capabilities, interface hardware capabilities, device capabilities, delays due to the negotiation process, delays due to currently active commands, and delays due to commands waiting to be sent to devices. Note that communication parameter limit suggestions might not survive between close() and open() calls, when no SCSI device drivers (device-specific or scsi_ctl) have associated LUN(s) open.

The current SCSI communication parameter limit suggestions may be determined by use of the SIOC_GET_LUN_LIMITS, SIOC_GET_TGT_LIMITS, and SIOC_GET_BUS_LIMITS ioctls.

Logical unit communication parameters may be managed by use of the SIOC_GET_LUN_PARMS, SIOC_SET_LUN_LIMITS, and SIOC_GET_LUN_LIMITS, SIOC_RESET_DEV, SIOC_RESET_BUS ioctls.

The SIOC_GET_LUN_PARMS ioctl indicates the current LUN communication parameter values. The max_q_depth field indicates whether or not tagged queuing is enabled, and if enabled, the maximum number of simultaneously active commands allowed. When max_q_depth is zero, tagged queuing is disabled. When it is one, tags are being used but commands are still being serially processed. When it is greater than one, tags are being used and max_q_depth specifies the maximum number of simultaneously active commands allowed.

The SIOC_SET_LUN_LIMITS ioctl may be used to provide LUN communication parameter limit suggestions. The max_q_depth field indicates whether or not tagged queuing should be enabled, and if enabled, the maximum number of simultaneously active commands that should be allowed. The SIOC_GET_LUN_LIMITS ioctl indicates the current LUN communication parameter limit suggestions.

Target communication parameters may be managed by use of the PSIOC_GET_TGT_PARMS ioctl on any associated HBA DSF, or SIOC_GET_TGT_PARMS, SIOC_SET_TGT_LIMITS, and SIOC_GET_TGT_LIMITS ioctls to any associated LUN.

The PSIOC_GET_TGT_PARMS and SIOC_GET_TGT_PARMS ioctls indicate the current target communication parameter values. The width, reqack_offset, and xfer_rate fields indicate the currently negotiated data transfer parameters. When width is eight, narrow transfers are in effect. When it is sixteen, wide transfers are in effect. When reqack_offset is zero, asynchronous transfers are in effect and xfer_rate is meaningless. When reqack_offset is non-zero, synchronous transfers are in effect and the maximum "burst" data transfer rate is xfer_rate words per second, where the size of a word is as indicated in width.

The SIOC_SET_TGT_LIMITS ioctl specifies the target communication parameter limit suggestions. The max_width field specifies maximum bus width that should be used for data transfers. The max_reqack_offset field specifies the maximum number of outstanding REQs that should be attempted during data transfers. The max_xfer_rate field specifies the maximum "burst" data rate that should be allowed during synchronous data transfers. The SIOC_GET_TGT_LIMITS ioctl indicates the current target communication parameter limit suggestions. The width, reqack_offset, xfer_rate, max_width, max_reqack_offset, max_xfer_rate fields only apply to parallel SCSI.

Bus communication parameters may be managed by use of the SIOC_GET_BUS_PARMS, SIOC_SET_BUS_LIMITS, and SIOC_GET_BUS_LIMITS ioctls to any associated LUN.

The SIOC_GET_BUS_PARMS ioctl indicates the current bus communication parameter values. The max_width field indicates the maximum data transfer width that will be attempted for data transfers to any target device connected to the associated bus. The max_reqack_offset field indicates the maximum number of outstanding REQs that will be attempted during data transfers to any target device connected to the associated bus. The max_xfer_rate field indicates the maximum "burst" data transfer rate that will be attempted for data transfers to any target device connected to the associated bus.

The SIOC_SET_BUS_LIMITS ioctl specifies the bus communication parameter limit suggestions for targets connected to the associated bus. The max_width field specifies the suggested maximum data transfer width that should be attempted for data transfers to any target device connected to the associated bus. The max_reqack_offset field specifies the maximum number of outstanding REQs that should be attempted during data transfers to any target device connected to the associated bus. The max_xfer_rate field specifies the maximum synchronous "burst" data transfer rate that should be attempted for data transfers to any target device connected to the associated bus. The SIOC_GET_BUS_LIMITS ioctl indicates the current bus communication parameter limit suggestions. The max_width, max_reqack_offset, and max_xfer_rate fields only apply to parallel SCSI.

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

/* SCSI communication parameter ioctls */ #define SIOC_GET_LUN_PARMS _IOR('S', 58, struct sioc_lun_parms) #define SIOC_GET_TGT_PARMS _IOR('S', 59, struct sioc_tgt_parms) #define SIOC_GET_BUS_PARMS _IOR('S', 60, struct sioc_bus_parms) #define SIOC_GET_LUN_LIMITS _IOR('S', 61, struct sioc_lun_limits) #define SIOC_GET_TGT_LIMITS _IOR('S', 62, struct sioc_tgt_limits) #define SIOC_GET_BUS_LIMITS _IOR('S', 63, struct sioc_bus_limits) #define SIOC_SET_LUN_LIMITS _IOW('S', 64, struct sioc_lun_limits) #define SIOC_SET_TGT_LIMITS _IOW('S', 65, struct sioc_tgt_limits) #define SIOC_SET_BUS_LIMITS _IOW('S', 66, struct sioc_bus_limits) struct sioc_lun_parms { unsigned int flags; unsigned int max_q_depth; /* maximum active I/O's */ unsigned int reserved[4]; /* reserved for future * use */ } sioc_lun_parms_t; struct sioc_lun_limits { unsigned int flags; unsigned int max_q_depth; unsigned int reserved[4]; /* reserved for * future use */ } sioc_lun_limits_t; typedef struct sioc_tgt_parms { unsigned int flags; unsigned int width; /* bits per word */ unsigned int xfer_rate; /* words per second */ unsigned int reqack_offset; /* REQ/ACK offset */ unsigned int tgt_id; /* target Id */ unsigned int reserved[3]; /* reserved * for future use */ } sioc_tgt_parms_t; typedef struct sioc_tgt_limits { unsigned int flags; unsigned int max_width; /* Bits per word */ unsigned int max_xfer_rate; /* Words per second */ unsigned int max_reqack_offset; /* REQ/ACK offset */ unsigned int tgt_id; /* target Id */ unsigned int reserved[3]; /* Reserved for future * use */ } sioc_tgt_limits_t; struct sioc_bus_parms { unsigned int flags; /* reserved for future * use */ unsigned int max_width; unsigned int max_reqack_offset; unsigned int max_xfer_rate; /* bytes/sec */ unsigned int reserved[4]; /* reserved for future * use */ } sioc_bus_parms_t; struct sioc_bus_limits { unsigned int flags; /* reserved for future * use */ unsigned int max_width; unsigned int max_reqack_offset; unsigned int max_xfer_rate; /* bytes/sec */ unsigned int reserved[4]; /* reserved for future * use */ } sioc_bus_limits_t;

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

#define PSIOC_GET_TGT_PARMS _IOWR('S', 114, struct sioc_tgt_parms) #define PSIOC_GET_TGT_LIMITS _IOWR('S', 115, struct sioc_tgt_limits) #define PSIOC_RESET_DEV _IOW('S', 116, int) #define PDIOC_RSTCLR _IOW('S', 117, int)

SCSI Commands and Operations

SIOC_IO_EXT and SIOC_IO ioctls allow an arbitrary SCSI command to be sent to a device. All details of the SCSI command protocol are handled automatically. SIOC_IO_EXT should only be issued on persistent device files. it allows to send the scsi command through any available LUN path or through a selected LUN path. SIOC_IO is deprecated. It can be issued on both persistent and legacy device files. When issued on a persistent device file, the SCSI command is sent through any available LUN path.

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 read operation is expected if data_length field is non-zero. The absence of this flag implies that data write operation is expected if the data_length field is non-zero.

SCTL_INIT_SDTR

Synchronous data transfer request negotiations should be attempted with this command. This flag only applies to parallel SCSI and is maintained for backward compatibility.

SCTL_INIT_WDTR

Wide data transfer request negotiations should be attempted with this command. This flag only applies to parallel SCSI and is maintained for backward compatibility.

SCTL_NO_DISC

discpriv bit in Identify message is not set. This flag only applies to parallel SCSI and is maintained for backward compatibility.

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_msecs field indicates that the timeout period is infinite and the system should wait indefinitely for command completion.

When the SIO_IO_EXT or 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.

The SIOC_ABORT ioctl causes a SCSI ABORT message to be sent to the LUN. This clears all active commands to the LUN from this initiator.

The SIOC_TASK_MGMT ioctl causes a SCSI task management function to be performed if supported by the SCSI transport. The following task management function values can be specified. They are defined in <sys/scsi.h>:

SIOC_TM_LUN_RESET

Lun Reset

SIOC_TM_WARM_TGT_RESET

Warm Target Reset

SIOC_TM_COLD_TGT_RESET

Cold Target Reset

The SIOC_RESET_DEV ioctl causes a SCSI device to be reset (including clearing all active commands). On parallel SCSI a PSIOC_RESET_DEV and SIOC_RESET_DEV ioctls cause a SCSI BUS DEVICE RESET message to be sent to the associated target. On Fibre Channel a SIOC_RESET_DEV ioctl causes a "TARGET RESET" task management function to be sent to the associated target followed by a Global Process Logout (GPRLO).

The SIOC_RESET_BUS ioctl causes the system to generate a SCSI bus reset condition on the associated bus. A SCSI bus reset condition causes all devices on the bus to be reset (including clearing all active commands on all devices). The SIOC_RESET_BUS ioctl does not apply to Fibre Channel.

Often it is necessary or useful to prohibit other SCSI commands while performing device-control operations. This should be done by gaining exclusive access via the SIOC_EXCLUSIVE ioctl. The associated argument points to an integer with one of these values defined in <sys/scsi.h>. Note that if the ioctl is issued on a persistent device file, target and bus exclusive access requests result to a LUN exclusive access being performed.

SIOC_REL_LUN_EXCL

release exclusive access to logical unit

SIOC_SET_LUN_EXCL

obtain exclusive access to logical unit

SIOC_REL_TGT_EXCL

release exclusive access to target

SIOC_SET_TGT_EXCL

obtain exclusive access to target

SIOC_REL_BUS_EXCL

release exclusive access to bus

SIOC_SET_BUS_EXCL

obtain exclusive access to bus

The ioctl SIOC_PRIORITY_MODE is deprecated with HP-UX release 11i V3. If called, it will just fake success. This ioctl was used to workaround situations where it is not possible to set exclusive access to the device. It put the device in "Priority mode". This caused all device-specific driver I/O operations (for example, file system I/O and virtual memory page swapping) and all SCSI device driver open calls (including pass-through driver open calls) to the associated LUN to block. These I/O operations and open calls were blocked for the entire duration that priority mode was in effect. While priority mode was in effect only SIOC_IO operations could be attempted. (these operations will not be blocked). It was very easy to cause system deadlock through incorrect use of the SIOC_PRIORITY_MODE ioctl. It normally required to lock the calling process into memory (see plock(2)) prior to enabling priority mode.

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

/* SCSI device control ioctls */ #define SIOC_IO _IOWR('S', 22, struct sctl_io) #define SIOC_RESET_DEV _IO('S', 16) #define SIOC_RESET_BUS _IO('S', 9) #define SIOC_PRIORITY_MODE _IOW('S', 67, int) #define SIOC_IO_EXT _IOWR('S', 102, esctl_io_t) #define SIOC_TASK_MGMT _IOWR('S', 104, sioc_task_mgmt_t) /* 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 */ 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;

Security Restrictions

Superuser or DEVOPS privilege, or device write permissions are required to use these ioctls. 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 commmand * 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 scsi_ctl 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_EXT/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.

The SIOC_CAPACITY ioctl is not supported by scsi_ctl because the meaning of capacity is device-specific.

FILES

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

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