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:

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:

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:

  1. Open target driver

  2. Use B_GETDEV to obtain the pass-through host adapter device number

  3. Close access to the target driver

  4. Use mknod to create a host adapter node

  5. Open the pass-through interface

  6. Create sb and CDB

  7. Send the command to the device

Pass-through ioctl interface errors

SDI_SEND can return the following errors:

Jobs are queued for the device (therefore, the device cannot be accessed).

An attempt to copy an sb or an scb to or from a user program failed.

sb.sb_type is not set to ISCB_TYPE or SCB.sc_mode is set to the unsupported SCB_LINK value.

Memory cannot be allocated for data from the sent CDB or for returned data.

Device has an illegal host adapter ID.

SDI_SEND can return the following values in SCB.sc_comp_code:

Host adapter failure or parity error

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

© 2005 The SCO Group, Inc. All rights reserved.
OpenServer 6 and UnixWare (SVR5) HDK - June 2005