MPE/iX SCSI Pass-Through Programmer’s Guide vCSY Hewlett-Packard -1-
Contents Document Summary ................................................................................................................. 3 What is “SCSI Pass Through”? ................................................................................................ 4 Why and when one might use SPT? ..................................................................................... 4 History and some caveats..................................................................................................
Document Summary The aim of this document is two fold: 1) To educate an application programmer on how to use ioctl() calls on SCSI pass through (SPT) device files to send SCSI commands directly to SCSI devices 2) Discuss the various recent enhancements in MPE/iX to make the SPT interface better and convenient to use We begin with a discussion of SPT (what is it?, why use it?) followed by a program setup for using SPT to directly communicate with SCSI devices.
What is “SCSI Pass Through”? “SCSI Pass Through” (SPT) refers to the ability of an application to send a SCSI Device Command through the MPE/iX OS and HP e3000 hardware to a SCSI Device: This is illustrated below in Figure #1. Hp e3000 Abstract SCSI “Pass Through” User Application SCSI Command Bytes (12 00 00 00 80 00) MPE/iX O.S. I/O Card I/O Bus Generic SCSI Device Figure #1 Why and when one might use SPT? Most succinctly SPT allows a programmer to closely control the behavior of a SCSI device.
1. Some SCSI hardware implementations include a controller that can monitor the status of devices in the enclosure and provide this information through SCSI commands. In practice, this information can be used to detect problem conditions like high temperatures or simply allow one to set an LED on a device to help pin-point it in a data center. SPT would enable programmers to obtain this information despite the fact that MPE/iX does not have a “SCSI Enclosure Controller Device Manager.” 2.
Program Setup for SPT I/O The programming example is derived from a program which was written in “C” to perform SCSI pass-through commands to a tape device connected to an HP-UX system. Appendix-A includes a listing and sample output of a C program that issues the SCSI Inquiry command using the MPE/iX SPT interface. The appendix also has a snapshot of the output from the inquiry command on various device types. Overview The following is an outline of important steps performed by the example program: 1. 2.
device file name is made up using the prefix “/dev/tm_diag” followed by the device path. As paths almost always include a forward slash “/” which has special meaning for the file system, all the “/” are first converted to “_” (under bar) to produce a more “usable” name. For example a path of “10/4/4.12.0” becomes “10_4_4.12.0” and so the device file will be named “/dev/tm_diag10_4_4.12.0.
Opening the SPT device file Open() is used to open the SPT device file after it has been created via mknod(). The file is opened as an ordinary disc file. The device file is actually a “sharable” file, so it is possible to have multiple opens from multiple processes. The application program could also create child processes via fork() and can issue many parallel SCSI commands to the device that is opened.
These ioctl() calls are “blocking” and follow a single-threaded path. ioctl() does not return until the I/O is completed. Completion includes normal I/O completion as well as requests which are aborted due to timeouts or errors. MPE/iX does security and bounds checking of the data and sense buffers. Again, there is no cross checking of the CDB vs. the other command fields; it is up the caller to be able to construct a valid CDB as well as make it consistent with the other parameters.
S_RESV_CONFLICT S_COMMAND_TERMINATED S_QUEUE_FULL S_I_CONDITION_MET 0x18 0x22 0x28 (S_INTERMEDIATE + S_CONDITION_MET) The following are the sense keys: S_NO_SENSE S_RECOVERED_ERROR S_NOT_READY S_MEDIUM_ERROR S_HARDWARE_ERROR S_ILLEGAL_REQUEST S_UNIT_ATTENTION S_DATA_PROTECT S_BLANK_CHECK S_VENDOR_SPECIFIC S_COPY_ABORTED S_ABORTED_COMMAND S_EQUAL S_VOLUME_OVERFLOW S_MISCOMPARE S_RESERVED 0x00 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08 0x09 0x0a 0x0b 0x0c 0x0d 0x0e 0x0f Please see http://docs.hp.
Device Configuration using SYSGEN WARNING: Sending SPT commands to a device in use by MPE or other applications may result in data loss, data corruption and/or System Aborts. We do not recommend sending SPT commands to Disks with MPE/iX Volumes present nor should one access tapes devices which are used for normal back-up or data logging purposes. Rule of thumb: Don’t do SPT to tape or disk media you cannot recover at a time you don’t wish to cause a system outage.
LDEV: 8 DEVNAME: ID: HPC1504B PATH: 0/0/2/0.3.0 CLASS: TAPE DDUMP OUTDEV: RSIZE: MPETYPE: 0 128 24 MODE: DEVTYPE: TAPE MPESUBTYPE: 7 LDEV: 100 DEVNAME: 00000100 ID: PASSTHRU PATH: 0/6/2/0.3.0 CLASS: OUTDEV: RSIZE: MPETYPE: 0 128 24 MODE: DEVTYPE: MOSAR_AC MPESUBTYPE: 4 LDEV: 400 DEVNAME: 00000400 ID: HVDDISK PATH: 0/6/0/0.0.
Recent Enhancements 1. User notification of Bus Resets Without this enhancement a bus reset (a.k.a powerfail reset, power-on reset) will result in device configuration settings (SCSI MODE SELECT) made by an application program being lost silently. This enhancement enables the different SCSI DMs (SCSI Tape DM, SCSI Tape2 DM, SCSI Disc DM and SCSI DISC ARRAY DM) to ‘remember’ a bus reset and return a device_reset status back to the application program.
2. LDEV number to I/O path Conversion A new user callable routine (call privilege 3, execution privilege 0) is available in MPE/iX to obtain the I/O path of a given logical device. The following are the external specifications of this procedure: Syntax HPLDEVTOIOPATH (ldev, iopath, status); Parameters • ldev (required) is of type ldev_type which is a 16 bit unsigned value (bit16). This parameter is passed by value.
3. Dup capability on SPT device files A ‘dup’ function has been introduced for SPT device files to duplicate them and thus have multiple forked processes making SPT calls. SPT calls are made as described in the previous section (please see appendix A for a program listing). Child processes can be created after opening the SPT device file using the fork() call. This enhancement is available via patch MPENX04A for MPE/iX release C.75.00 4.
LIBIO.H Bug fixed in /usr/include/sys/libIO.h File /usr/include/sys/libIO.h has the following include statement at the beginning: #ifndef MPEIX #include #else #include #endif The leading / in the path under the MPEIX inclusion is incorrect. This / makes the path absolute and file /sys/ioparams.h is non existent on MPE systems. This will hence result in a compilation error. The compilation will succeed if the leading / is removed.
Appendix A Program listing to execute a SCSI Inquiry command by SPT via TM_Diag tmdiag.c #pragma width 132 #define _POSIX_SOURCE /* tmdiag.c */ /* Given an MPE SCSI Device Path, attempt to mknod a device file and */ /* then open, ioctl(two times), close, unlink the file. . . */ /* Open with parameters that will have us go through the tm_diag TM */ /* */ /* Original SCSI ioctl() code written by Chris Moore of HP-UX GSC */ /* ported from HP-UX to MPE/iX POSIX by Jim Hawkins MPE-iX Lab. . .
for (i=0; i < sizeof (struct sctl_io); i=i+4) { printf ("%08x ", *j++); } /* for loop */ printf ("\n"); } void check_diag_command ( struct sctl_io command ) { int i; struct inquiry_2 *inq; /* ptr to some inquiry data, location tbd */ printf ("\n"); if (command.cdb_status != S_GOOD) { fprintf(stderr, "SCSI command returned status 0x%02x\n", command.cdb_status); if (command.cdb_status == S_CHECK_CONDITION) { if (command.
/* sizeof either uses "(type)" or "expression" */ /* in this case we don't have a type for inquiry so use the expression */ /* inq->vendor_id to get the size of the subfield of the structure */ printf ("Vendor: "); for (i=0; i < (sizeof inq->vendor_id) ;i++) { printf ("%c", inq->vendor_id[i]); } /* print vendor_id as chars */ printf ("\n"); printf ("Product : "); for (i=0; i < (sizeof inq->product_id) ;i++) { printf ("%c", inq->product_id[i]); } /* print product_id as chars */ printf ("\n"); printf ("Rev: "
/* that path.
command.flags = SCTL_READ; command.cdb_length = 6; command.cdb[0] = CMDinquiry; /* Inquiry */ command.cdb[4] = sizeof(struct inquiry_2); /* Allocation Length */ command.data = buf; command.data_length = 64*1024; command.
Sample output (Disk) :tmdiag "0/0/1/1.15.0" /dev/tm_diag_0_0_1_1.15.
Appendix B A simple modcal program to invoke HPLDEVTOIOPATH { File: xldevtoiop This program accepts an LDEV number and returns its I/O path. The path is returned in an array of 32 characters. The I/O path returned is followed by spaces and hence may need trimming before use. Steps to link and add capabilities: 1. PASXL xld2iop, yld2iop 2. link yld2iop, eld2iop; cap=ba,ia,pm,ph } $standard_level 'ext_modcal'$ program testldevtoiopath(input,output); type pac32_t = packed array[1..
Sample output :eld2iop Enter LDEV number: 20 The I/O path is: 0/0/4/1.0 :eld2iop Enter LDEV number: 6 The I/O path is: 0/0/1/0.16.0 :eld2iop Enter LDEV number: 7 The I/O path is: 0/0/1/0.6.0 :eld2iop Enter LDEV number: 1 The I/O path is: 0/0/2/1.6.
A simple C program to invoke HPLDEVTOIOPATH /* File: ldevtoiop.c This program accepts an LDEV number and returns its I/O path. The path is returned in an array of 32 characters. The I/O path returned is followed by spaces and hence may need trimming before use. Steps to link and add capabilities: 1. In POSIX Shell run: c89 ldevtoiop.c -o ELD2IOP 2. Exit shell, run linkedit 3. altprog ELD2IOP;CAP=BA,IA,PM,PH */ #pragma standard_level "ext_modcal" #pragma intrinsic GETPRIVMODE #include
Sample output :eld2iop Please enter the ldev no. for which you need the I/O path: 20 IO Path returned is 0/0/4/1.0 :eld2iop Please enter the ldev no. for which you need the I/O path: 6 IO Path returned is 0/0/1/0.16.0 :eld2iop Please enter the ldev no. for which you need the I/O path: 7 IO Path returned is 0/0/1/0.6.0 :eld2iop Please enter the ldev no. for which you need the I/O path: 1 IO Path returned is 0/0/2/1.6.0 :eld2iop Please enter the ldev no.
Appendix C CR numbers and Patch IDs (all patches are for MPE/iX release C.75.00) DESCRIPTION User notification of Bus Reset User callable routine to convert LDEV to IOPATH TM_DIAG dup capability Using TM_DIAG device files across boots Fix for libIO.
