scsi_ctl(7)

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:

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

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

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

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:

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:

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

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.

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

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.