HDK Technical Reference

Using the pass-through ioctl interface

CAUTION: When a user program opens access to the pass-through interface, all other jobs heading for the targe device are blocked until the pass-through access is closed. This is not generally a problem for devices like tape drives, but may present problems when accessing disk devices from multi-user states. As a general rule, the pass-through interface for disks should be used only to implement operations that can be performed in single-user state. In extreme cases, executing pass-through operations to a disk when the system is in a multi-user state can cause the system to hang.

Any use of read or write during pass-through access fails. In addition, a process using pass-through cannot use system calls that require target driver access. If a process opens the pass-through interface and then executes a system call that accesses the device, the system call fails. When the system call generates an SDI_SEND, the process will hang. (Some ioctl commands may not generate an SDI_SEND.) If your pass-through interface access requires device reads and write operations, you must do so either before pass-through is started or with CDB commands utilizing SDI_SEND (explained later in this chapter).

The following guidelines must be observed when writing a program that accesses the pass-through interface:

One major-minor number pair is associated with each logical unit.
Permissions on the special device files must be set so that only the owner has read-write permissions.
Only one process may have a special device file open. Processing of jobs from the target driver to the logical unit is suspended while the device file is open. For an ISA -bus computer, this is identical to the suspension that takes place after a check condition.
The only sb_type value which can be used is ISCB_TYPE. (sb_type is a member of the sb(D4sdi) structure.)

NOTE: The pass-through interface requires that a target driver include access to the two ioctls, B_GETDEV and B_GETTYPE.

The pass-through interface provides a means to send a command directly to a device. A sample of the functionality provided by these commands is:

Data copying
Device formatting
Mode selecting
Preventing and allowing media removal
Reserving and releasing unit
Reading and writing data

Commands are sent by creating a Command Descriptor Block (defined by the scb(D4sdi) and scm(D4sdi) structures and described in the ANSI Small Computer System Interface (SCSI), X3T9, 2/82-2, Revision 17B.

The method for using the SDI_SEND command is:

Open target driver
Use B_GETDEV to obtain the pass-through host adapter device number
Close access to the target driver
Use mknod to create a host adapter node
Open the pass-through interface
Create sb and CDB
Send the command to the device

Pass-through ioctl interface errors

SDI_SEND can return the following errors:

EBUSY: Jobs are queued for the device (therefore, the device cannot be accessed).
EFAULT: An attempt to copy an sb or an scb to or from a user program failed.
EINVAL: sb.sb_type is not set to ISCB_TYPE or SCB.sc_mode is set to the unsupported SCB_LINK value.
ENOMEM: Memory cannot be allocated for data from the sent CDB or for returned data.
ENXIO: Device has an illegal host adapter ID.

SDI_SEND can return the following values in SCB.sc_comp_code:

SDI_HAERR: Host adapter failure or parity error
SDI_PROGRES: The job is not complete during time when sb is being sent to the host)

SCSI addressing in pass-through ioctl operations

The SDI limitation in previous releases of the operating system of 8 HBA controllers in the system, 4 LUNs per target, and 8 targets was a result of the design of the HBA pass-through operation. When a process uses pass-through to interface directly to an HBA device, the process requests a device number from SDI, and makes the node for that given device. The device number calculation had assumed the minor number to be an 8-bit field. The pass-through minor number contains the controller, target, and LUN, and all components were made to fit into an 8-bit field as follows:

                          ------------
          minor number:  | ccc ttt ll |
                          ------------
   
   ccc    controller number   3 bits (5-7)
   ttt    target number       3 bits (2-4)
   ll     LUN                 2 bits (0-1)

Since the minor number is an 18-bit field and binary compatibility must be maintained, the low order 8 bits remain defined as before. The remaining 10 bits, however, extend the existing controller, target, and LUN fields, and add the bus number.

The pass-through minor number is now defined as:

   /*
    *                  ------------------------
    * minor number:   |bbb lll tt ccccc ttt ll|
    *                  ------------------------
    *      bbb     bus number            3 bits (15-17)
    *      lll     extended LUN          3 bits (12-14)
    *      tt      extended target       2 bits (10-11)
    *      ccccc   extended controller   2 bits (5-9)
    *      ttt     target number         3 bits (2-4)
    *      ll      LUN                   2 bits (0-1)
    */
   
   #define SDI_MINOR(c,t,l,b) (((b)&0x07 <<15) |
                               ((l)&0x1C <<12) |
                               ((t)&0x18 <<10) |
                               ((c)&0x1F <<05) |
                               ((t)&0x07 <<02) |
                               ((l)&0x03))