scsi_pt(7)

NAME

scsi_pt — SCSI pass-through device driver for Series 800 NIO based systems

DESCRIPTION

SCSI devices are normally controlled by a device-type-specific driver when the appropriate device-type-specific driver exists. Device-type-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 (also called spt) enables use of SCSI devices and commands that are not supported by these device-type-specific drivers.

A successful scsi_pt open() call requires no device I/O operations. Once open, ioctl() calls can be used to change SCSI communication parameters, attempt SCSI commands, or other SCSI operations. Since the SCSI pass-through driver does not attempt to logically understand the target device, read() and write() calls are not supported. Super-user privileges or device write permissions are required to use these ioctls. All reserved fields in the data structures associated with these ioctls must be zero-filled.

Since the SCSI pass-through driver is a separate device driver, the default device-type-specific driver cannot be used for the same device at the same time as the pass-through driver.

SCSI Commands and Operations

Only two ioctl commands are supported by the NIO SCSI pass through driver; the SIOC_EXCLUSIVE command and the SIOC_IO command.

The SIOC_EXCLUSIVE ioctl provides a mechanism to prevent other opens of a device. This allows exclusive access by the locking application. There are two different levels of locks supported; SCSI target level and SCSI lun level. These levels are specified via the data field of the ioctl() call:

0: release exclusive access to SCSI lun
1: gain exclusive access to SCSI lun
2: release exclusive access to SCSI target
3: gain exclusive access to SCSI target

For example, to lock the device (SCSI target):

three = 3;
if (err = ioctl(fd, SIOC_EXCLUSIVE, &three)) {
   /* Could not lock the device -- check err */
}

NOTE: The corresponding unlock must be made for the acquired lock. An unlock of the SCSI target (data == 2) will NOT unlock all of the individual SCSI luns (data == 0).

The SIOC_IO ioctl allows an arbitrary SCSI command to be sent to a device. All details of the SCSI command protocol are handled automatically. See EXAMPLE mentioned below.

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

/* SCSI device control ioctls */
#define SIOC_IO                 _IOWR('S', 22, struct sctl_io)
#define SIOC_EXCLUSIVE          _IOW('S', 68, int)

/* 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        reserved[16];
};

The flags field can have the following values (if supported):

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.
SCTL_INIT_SDTR: synchronous data transfer request negotiations should be attempted with this command.
SCTL_INIT_WDTR: wide data transfer request negotiations should be attempted with this command.
SCTL_NO_ATN: device should be selected without attention (ATN). This implies that no SCSI message phase should be attempted with this command. (Not supported)
SCTL_2BYTE: device maintains 2-byte alignment. (Not supported)
SCTL_4BYTE: device maintains 4-byte alignment. (Not supported)

The cdb_length field specifies the number of valid command bytes in the cdb field.

The cdb field specifies the SCSI command bytes. These command bytes are sent to the target device during the SCSI command phase.

The data field specifies the address of the data area for the data phase of the SCSI command.

The data_length field specifies the maximum number of data bytes to be transferred. A zero value in the data_length field 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 field data length values. Unexpected system behavior occurs if these fields are not consistent. The data_length value may not be larger than 1 Megabyte.

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 attempts recovery procedures to regain the device's attention. These recovery procedures may include 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. Note that very large (or infinite) timeout values can cause the SCSI bus (potentially the entire system) to ``hang''.

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, S_CHECK_CONDITION or, S_CONDITION_MET.

The cdb_status field indicates the results of the cdb command. When the SIOC_IO ioctl call returns, all command processing has been completed. Most SIOC_IO ioctl calls will return zero (success). It is important, however, to always check the return value from the ioctl to ensure that an unexpected error has not occurred. The resulting detailed ioctl data should be used to evaluate ``success'' or ``failure'' from the caller's perspective. 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 was not attempted.
SCTL_SELECT_TIMEOUT: The target device did not answer to selection by the host SCSI interface (the device does not exist or did not respond).
SCTL_INCOMPLETE: The device answered selection but the command was not completed (the device took too long or a communication failure occurred, ie. device powerfail).
SCTL_POWERFAIL: A system power recovery occurred. Error handling and retrying the command may be necessary. The pass-through driver does not perform any powerfail recovery.
S_GOOD: Device successfully completed the command.
S_CHECK_CONDITION: Device indicated sense data was available.
S_CONDITION_MET: Device successfully completed the command and the requested (search or pre-fetch) operation was satisfied.
S_BUSY: Device indicated it was unable to accept the command because it is busy doing other operations.
S_RESV_CONFLICT: Device indicated the command conflicted with an existing reservation.
S_COMMAND_TERMINATED: Device indicated the command was terminated early by the host system.
S_QUEUE_FULL: Device indicated it was unable to accept the command because its command queue is currently full.
S_INTERMEDIATE: Device successfully completed this command, which was one in a series of linked commands. (Not supported)
S_I_CONDITION_MET: Both S_INTERMEDIATE and S_CONDITION_MET indicated by the device. (Not supported)

The sense field indicates the sense data of the SCSI REQUEST SENSE command. It is only valid if the sense_status field indicates successful status.

The sense_status field indicates the results of the SCSI REQUEST SENSE command used to collect the associated sense data. It is only valid if the cdb_status field indicates a S_CHECK_CONDITION status.

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.

EXAMPLE

The configuration test program provided with the SCSI pass-through driver product can be used as an example. It sends a SCSI INQUIRY command to the device referenced by the required special device file and prints out the returned inquiry data. The source for this program can be found in the file: /usr/contrib/src/scsi_io.c.

WARNINGS

Incorrect use of SCSI device-control operations can easily cause data loss, resulting in a corrupted system.
Only two ioctl commands are supported; the SIOC_EXCLUSIVE command and the SIOC_IO command. Any other commands attempted will return the EINVAL error.
It is recommended that the SIOC_EXCLUSIVE ioctl be used to gain exclusive access to a device prior to attempting SIOC_IO commands. This will protect against other device opens from external sources (for example, from another user program). If exclusive access is not obtained, SIOC_IO commands may be intermixed between a number of different applications which can lead to undesirable results.
Most SCSI commands have a logical unit number (LUN) field. 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.
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 timeout values can cause the SCSI bus and potentially the entire system to appear to be ``hung''.
Unlike on the S700, the NIO SCSI pass-through driver is implemented as a stand-alone driver. To ensure system integrity, certain restrictions exist with its use of the bus and its interactions with other drivers.
Any device accessed via the NIO SCSI pass-through driver must be on a STAND-ALONE APPLICATION BUS. Therefore, no boot, dump, or swap devices can be connected to this bus. While a NIO SCSI pass-through driver application is running, it should have exclusive use of the application bus. There should be no other accesses to this bus, be it from the operating system, a user, or another application.
The controlling application can access its device(s) via the NIO SCSI pass-through driver and other HP standard driver(s) as long as the application handles the coordination between the various drivers. Thus, the application is responsible for initiating all communications to device(s) on this bus. For example, a tar command can not be directly used to a device on the exclusive application bus while the owning application is running. Any problems encountered must be displayed on this supported configuration (a stand-alone application bus) before support can be extended.

INSTALLATION AND CONFIGURATION

The SCSI pass-through file set comes with the core system and will exist after an install or an update. The files in this set (and their proper destinations) are:

 Filename       Protections      Full path
 ========       ===========      =========
 libspt.a       -r--r--r--       /usr/conf/lib/libspt.a
 scsi_io.c      -r--r--r--       /usr/contrib/src/scsi_io.c
 scsi_pt.7      -r--r--r--       /usr/share/man/man7.Z/scsi_pt.7
 spt            -r--r--r--       /usr/conf/master.d/spt

The following configuration steps need to be completed to successfully use the NIO SCSI pass-through driver. This driver does not auto-configure.

Go to the build area:

$ cd /stand/build 

Create a system file from your existing kernel:

$ /usr/lbin/sysadm/system_prep -s system 

Get information about peripherals attached to your system:

$ ioscan -f 

Check if the SCSI pass-through driver is already configured into your current kernel:

$ grep spt system 

If no ``spt'' line was printed, add a line to the ``SCSI drivers'' area of the system file:

spt

A driver statement is needed to override the standard driver which gets autoconfigured for any device. One statement is required for each desired NIO SCSI pass-through device (be it a SCSI target, or a SCSI lun). Append the driver line(s) to the system file:

$ cat >> system 
driver <path> spt
     ...
^D     # control-D to exit the cat command 

where <path> is the complete hardware path of desired device (from ioscan cmd)

Create the conf.c and config.mk files:

$ /usr/sbin/config -s system 

Build a new kernel:

$ make -f config.mk 

Verify that the pass-through driver has been built into the new kernel. (A line giving the revision information should be printed):

$ what ./vmunix_test | grep scsi_pt 

Save the old system file:

$ mv /stand/system /stand/system.prev 

Move the new system file to be the current one:

$ mv ./system /stand/system 

Save the old kernel:

$ mv /stand/vmunix /stand/vmunix.prev 

Move the new kernel to be the current one:

$ mv ./vmunix_test /stand/vmunix 

Boot the system from the new kernel:

$ exec reboot 

ONCE THE SYSTEM REBOOTS:

Verify the peripheral configuration:

$ ioscan -f 

Determine the major number for the SCSI pass-through driver:

$ lsdev -d spt 

Create the special device file to access the scsi_pt peripheral (refer to the example in the TROUBLESHOOTING section):

$ mknod /dev/<devfilename> c  <major #>  <minor #>

where

<devfilename>

name of the special device file

<major #>

character major number (from lsdev cmd)

<minor #>

minor number in the format 0xIITL00

where

II: 2 digit card instance number (from ioscan command; proper ext_bus entry)
T: Target ID number (SCSI ID)
L: Lun number (SCSI LUN)
00: Reserved fields, must be zero

All ready for use,try the sample program: 

Compile the sample program:

$ cc /usr/contrib/src/scsi_io.c 

Execute the sample program:

$ ./a.out /dev/<devfilename>

The sample program should have returned the inquiry data of the target device. If this did not happen, refer to the TROUBLESHOOTING section.

TROUBLESHOOTING

If the NIO SCSI pass-through driver is not working:

Verify the proper configuration of the SCSI pass-through driver into the kernel.
Verify that the hardware is set up properly.
—
Check that the device is connected, and that its SCSI Bus address is set properly.
—
Check the reference manual for the device to verify that it is configured properly.
—
Check that the SCSI Bus is properly terminated.
—
Verify that the device is operational using some other driver if possible. If a hardware problem is suspected, the SCSI pass-through driver must be unconfigured for that device and the HP specific device driver must be configured before any diagnostic software can be run.
Verify the special device file.
—
Execute lsdev -d spt to find the major number for the SCSI pass-through driver. For example, lsdev -d spt might show:
Character Block Driver Class 136 -1 spt spt
—
Run ioscan -kf to find the card instance number, target SCSI ID and SCSI LUN for the desired device. For example ioscan -kf might show:
Class I H/W Path Driver S/W State H/W Type Description ============================================================== bc 0 root CLAIMED BUS_NEXUS ext_bus 2 8 scsi1 CLAIMED INTERFACE HP 28655A - SC target 0 8.3 target CLAIMED DEVICE spt 0 8.3.0 spt CLAIMED DEVICE HP C1718T target 1 8.4 target CLAIMED DEVICE spt 1 8.4.0 spt CLAIMED DEVICE HP C1716T ...
In this example there are two desired devices:
Device #1 Device #2 ========= ========= card instance number = 2 card instance number = 2 target SCSI ID = 3 target SCSI ID = 4 SCSI LUN = 0 SCSI LUN = 0
—
Verify that these are the same values used in the special device files. For example, ll /dev/c2t*d0 might show:
crw-rw-rw- 1 root sys 136 0x023000 Dec 14 15:10 c2t3d0 crw-rw-rw- 1 root sys 136 0x024000 Dec 14 15:10 c2t4d0

scsi_pt(7)

Technical documentation

» Table of Contents

» Index