Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers Abstract This manual assists developers in designing devices for connection to HP Integrity NonStop™ NS-series servers through their Fibre Channel ServerNet adapter (FCSA) in the I/O adapter module (IOAM) enclosure. This manual describes the SCSI-FC protocol supported over Fibre Channel by the FCSA.
Document History Part Number Product Version Published 529967-001 N.A. July 2005 529967-002 N.A.
Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers Glossary Index Figures What’s New in This Manual Manual Information v Tables v About This Manual vii Who Should Use This Manual What’s in This Manual viii Related Documents viii vii 1. Overview The Open SCSI Interface Hardware 1-1 Software 1-1 1-1 2. Integrating Hardware Adding a Device 2-1 Assigning Worldwide Names 2-1 Addressing Open SCSI Devices 2-1 MMF Cables 2-2 3.
. Configuring Open SCSI Devices Contents 4. Configuring Open SCSI Devices Viewing Configuration Information About Open SCSI Devices Examples 4-1 Example of an INFO SCSI Detailed Report 4-1 Adding an Open SCSI Device 4-3 Altering Open SCSI Attribute Values 4-3 Deleting an Open SCSI Device 4-4 Changing the Name of an Open SCSI Device 4-4 4-1 5.
Contents Table 3-6. Table 3-7. Table 3-8. Table 3-9. Table 5-1.
Contents Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— iv
What’s New in This Manual Manual Information Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers Abstract This manual assists developers in designing devices for connection to HP Integrity NonStop™ NS-series servers through their Fibre Channel ServerNet adapter (FCSA) in the I/O adapter module (IOAM) enclosure. This manual describes the SCSI-FC protocol supported over Fibre Channel by the FCSA.
What’s New in This Manual What’s New and Changed Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— vi
About This Manual This manual assists developers in designing devices for connection to NonStop NS-series servers through their Fibre Channel ServerNet adapter (FCSA). This manual describes the SCSI-FC protocol (FCP) supported over Fibre Channel by the IOAM enclosure. This manual provides information on developing interface software and describes the use of maintenance, diagnostic, and configuration software.
What’s in This Manual About This Manual Table -1.
About This Manual • • • • • • • • • • • • File Utility Program (FUP) Reference Manual Guardian Procedure Calls Reference Manual Guardian Procedure Errors and Messages Manual Guardian User’s Guide Information Technology - Small Computer System Interface - 3 (ANSI) Information Technology - SCSI-2 Common Access Method Transport and SCSI Interface Module (ANSI X3.
About This Manual Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— x
1 Overview This section provides an overview of the Open SCSI for Fibre Channel controller and how to interface with devices supplied by third-party integrators. The Open SCSI Interface The Open SCSI for Fibre Channel controller provides the hardware and software for a SCSI-FC protocol over Fibre Channel interface that runs on NonStop NS-series servers and to which developers can attach a single Fibre Channel device that uses the small computer system interface (SCSI) protocol.
Overview Software Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— 1 -2
2 Integrating Hardware This section describes the hardware tasks required to attach devices to the Open SCSI for Fibre Channel controller and lists specifications for necessary hardware. The IOP supports the attachment of unmodified Fibre Channel drives from their original manufacturer to NonStop NS-series servers. The IOP contains the vendor ID, product ID, and device characteristics of Fibre Channel drives. Fibre Channel drives require a device login before you can attempt any I/O operation on them.
MMF Cables Integrating Hardware MMF Cables The fiber cable is a multimode/short-wave fiber-optic cable (MMF).The MMF cable connects an external device to a Fibre Channel port connector on the FCSA. These cables are available for purchase from HP. See Table 2-2. To view part numbers, from the NonStop Technical Library (NTL) home page, select Support and Service > Service Information > Part Numbers. Table 2-2.
3 Interfacing With the Open SCSI I/O Process (IOP) This section discusses software topics associated with writing device drivers to interface with the Open SCSI I/O process (IOP), T8995. These methods include Common Access Method (CAM) control blocks (CCBs), CAM operations, and IOP status values.
Interfacing With the Open SCSI I/O Process (IOP) Using the FILE_OPEN_ Procedure subsequent file-system procedure calls. The syntax of the FILE_OPEN_ procedure call is: error := FILE_OPEN_ ( filename:length ! ,filenum ! ,[access] ! ,[exclusion] ! ,[nowait-depth] ! ,[sync-depth] ! ,[options] ! ,[seq-buffer-id] ! ,[seq-buffer-len] ! ,[primary-processhandle] ); ! i:i i,o i i i i i i i i error This integer value is returned from the file system to indicate the outcome of the operation.
Interfacing With the Open SCSI I/O Process (IOP) Using the WRITEREAD[X] Procedures sync-depth This parameter is optional. The Open SCSI IOP does not support the sync-ID mechanism. Even if a nonzero value is assigned to sync-depth, the IOP treats it as 0. options This parameter is not handled directly by the Open SCSI IOP. seq-buffer-id The Open SCSI IOP does not perform sequential block buffering. seq-buffer-len The Open SCSI IOP does not perform sequential block buffering.
Interfacing With the Open SCSI I/O Process (IOP) Using the WRITEREAD[X] Procedures buffer This parameter specifies the buffer that contains control information as well as any data the application or driver sends to or receives from the device. On return, the buffer contains updated control information and sense information that was requested and needed and any data that was read from the device because of the request. The buffer consists of these basic components: • • • • A header block.
Interfacing With the Open SCSI I/O Process (IOP) Structure of the WRITEREAD Buffer Structure of the WRITEREAD Buffer The buffer passed to and returned from the WRITEREAD procedure contains a header block, a control field whose structure corresponds to that of a CAM control block (CCB), an optional sense-buffer field, and an optional data-buffer field. Figure 3-1 shows the basic layout of the buffer. Figure 3-1.
Structure of the WRITEREAD Buffer Interfacing With the Open SCSI I/O Process (IOP) CCB. However, the application reads back the entire buffer, which contains the header block, the updated CCB, and both the sense buffer and data buffer, which now contain information. Figure 3-2. WRITEREAD Buffer Structure for Read Operation Header Block CCB Sense Buffer (optional) Data Buffer (optional) Write Count Read Count CDT 007.
The WRITEREAD Buffer Header Block Interfacing With the Open SCSI I/O Process (IOP) The WRITEREAD Buffer Header Block The header block for the WRITEREAD buffer (Figure 3-4) contains fields needed by the IOP to determine whether the buffer contains a CCB for controlling the device, to check for compatibility, and to find the relevant pieces of data in the buffer. Figure 3-4.
Interfacing With the Open SCSI I/O Process (IOP) • • The WRITEREAD Buffer Header Block The IOP does not support the specified version of the header block. The IOP detects an error in the organization and layout of the buffer or in these contents of the buffer that can be checked before the CCB is executed. ccb_offset This 2-byte field contains the value of the byte offset of the CCB from the beginning of the WRITEREAD buffer.
Interfacing With the Open SCSI I/O Process (IOP) The CAM Control Block (CCB) The CAM Control Block (CCB) When you use the Open SCSI interface, the CCB control field in the WRITEREAD buffer must correspond exactly to the structure of a CCB for each CAM operation even if not all the fields of the CCB are needed by a particular operation.
The CAM Control Block (CCB) Interfacing With the Open SCSI I/O Process (IOP) Table 3-1. CAM Operations (page 2 of 2) CAM Operation Code (in hex) Description Supported by Open SCSI? 81 (Reserved — used by HP) - 82 Set I/O Characteristics (See Table 3-3 on page 3-12.) Yes 83-FF (Reserved for vendor-unique values.) - * In the current implementation, the application or peripheral driver must cancel outstanding requests before issuing a Reset SCSI Device operation.
The CAM Control Block (CCB) Interfacing With the Open SCSI I/O Process (IOP) Table 3-2. Cam-Flag Bits (page 2 of 2) Flag Byte Bits Description Supported by Open SCSI IOP? 5 Disable synchronous transfers Yes Supported only with the Set I/O Characteristics operation. Yes For restrictions, use, and implementation, see SIM Queue Operations on page 3-14.
Interfacing With the Open SCSI I/O Process (IOP) The CAM Control Block (CCB) Basic CCB Structure Table 3-3 shows the basic CCB structure, which is used for these CAM operations: • • • • No Operation Release SIM Queue Reset SCSI Device Set I/O Characteristics See also Table 3-1 on page 3-9. Table 3-3.
Interfacing With the Open SCSI I/O Process (IOP) The CAM Control Block (CCB) CCB Structure for Abort SCSI Command The CCB structure shown in Table 3-4 is used for only one of the supported CAM operations, Abort SCSI Command. See also Table 3-1 on page 3-9. Table 3-4.
Interfacing With the Open SCSI I/O Process (IOP) SIM Queue Operations Table 3-5.
IOP Status Values Interfacing With the Open SCSI I/O Process (IOP) • • • • • Freezing the SIM queue results in setting the I/O subsystem’s queue to a level that prevents normal I/O operation. The IOP can initiate I/O recovery operations even when the SIM queue is frozen. Operations that have the SIM queue priority flag set have sufficient priority to be dispatched even if the SIM queue is frozen. A 10-second timer starts when the SIM queue experiences an application-related freeze.
Interfacing With the Open SCSI I/O Process (IOP) File-System (FESTATUS) Error-Code Values Table 3-6. File-System Error Codes and Their Meanings (page 1 of 3) Error Code Corresponding FESTATUS Literal 0 FEOK No error detected by IOP in command execution. However, also check the CAM status values (Table 3-8 on page 3-20) and SCSI status values (Table 3-9 on page 3-21).
Interfacing With the Open SCSI I/O Process (IOP) File-System (FESTATUS) Error-Code Values Table 3-6. File-System Error Codes and Their Meanings (page 2 of 3) Error Code Corresponding FESTATUS Literal Meaning or Error Cause 32 FENOPOOLSPACE Check for one of these causes: • • • 33 35 FENOIOBUFSPACE FENOIOCBSPACE The IOP encountered an error in allocating a needed memory segment. A memory pool was not set up correctly. The IOP could not initialize some control structures.
File-System (FESTATUS) Error-Code Values Interfacing With the Open SCSI I/O Process (IOP) Table 3-6. File-System Error Codes and Their Meanings (page 3 of 3) Error Code Corresponding FESTATUS Literal Meaning or Error Cause 200 FEOWNERSHIP Check for one of these causes: • • 201 FEPATHDOWN The backup IOP received a request that should have gone to the primary IOP. The controller port for this processor is not enabled.
Buffer-Status Values Interfacing With the Open SCSI I/O Process (IOP) Buffer-Status Values Buffer status is indicated by a 2-byte field in the WRITEREAD buffer header block. See Figure 3-4 on page 3-7. This field is set to a nonzero value by the IOP if either: • • The IOP does not support the specified version of the header block. The IOP detects an error in the organization and layout of the buffer or in the contents of the buffer that can be checked before the CCB is executed.
Interfacing With the Open SCSI I/O Process (IOP) CAM-StatusValues detect completion of the request. An AWAITIO[X] procedure call must be used to detect completion of the request and transfer of the data back to the user buffer. These CAM-status values are added or changed as follows: • • CAM-status value 1B is reserved under the current CAM specification.
SCSI-Status Values Interfacing With the Open SCSI I/O Process (IOP) SCSI-Status Values The SCSI status value from the CAM operation Execute SCSI I/O is put into the appropriate field in the CAM structure and returned to the application. The application should check the SCSI-status value even if the file-system error-code value returned is 0 or the FEOK literal (no error). SCSI-status values are returned by the IOP exactly as they are received from the IOAM.
Interfacing With the Open SCSI I/O Process (IOP) SCSI-Status Values Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— 3- 22
4 Configuring Open SCSI Devices This section describes the software and hardware tasks required for configuring devices on the Open SCSI bus. Viewing Configuration Information About Open SCSI Devices You use the Subsystem Control Facility (SCF) INFO SCSI command to display configuration information about Open SCSI devices. For complete details about the INFO SCSI command, including command syntax, see the SCF Reference Manual for the Storage Subsystem.
Example of an INFO SCSI Detailed Report Configuring Open SCSI Devices Detailed Report Information The fields shown in the previous example of a detailed report have these meanings. This Open SCSI I/O process configuration information is listed in the detailed report produced by the INFO SCSI, DETAIL command: Explanation of Fields I/O Process Information: * indicates an attribute whose value you can change by using the SCF ALTER SCSI command.
Adding an Open SCSI Device Configuring Open SCSI Devices LUN is the logical unit number (LUN) of the device used by the IOP to select any additional devices that are attached to the device. SAC Name is the name of the SAC on the adapter, determined by the location of the adapter in the system. SAC Number is the subdevice number of the SAC on the adapter which determines which SCSI bus accesses the device. SCSI ID / Portname For Open SCSI devices, the SCSI ID that the IOP uses to access the device.
Deleting an Open SCSI Device Configuring Open SCSI Devices Deleting an Open SCSI Device The SCF DELETE SCSI command removes an Open SCSI device from the system configuration database: 1. Stop the device: -> STOP $S11500 2. Verify the device is in the STOPPED state: -> STATUS $S11500 3. Remove the device from the system configuration database: -> DELETE $S11500 4.
Configuring Open SCSI Devices Changing the Name of an Open SCSI Device 3. Use the SCF NAMES command to verify that the Open SCSI device is in the system configuration database with the new name. For example: -> NAMES $ZZSTO, SUB SCSI STORAGE Names SUBSYS \ALM171.$ZZSTO SCSI $DEV1 $DEV2 For complete details about the DELETE SCSI and ADD SCSI commands, including command syntax, see the SCF Reference Manual for the Storage Subsystem.
Configuring Open SCSI Devices Changing the Name of an Open SCSI Device Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— 4 -6
5 Managing Open SCSI Devices This section describes how to display status information and control Open SCSI devices. Open SCSI Object States and Substates The state and substate of a SCSI object describe the status of the Open SCSI device or path to the device. Table 5-1 lists SCSI DEVICE object states and substates. Table 5-1. SCSI DEVICE Object States and Substates State Substate Description STARTED (none) The Open SCSI device is available. STOPPED (none) The Open SCSI device is not available.
Example of a STATUS SCSI Detailed Report Managing Open SCSI Devices Summary Report Information The fields shown in the previous example of a summary report have these meanings: LDev shows the logical device number for the Open SCSI device. This number is arbitrarily assigned to a device when the device is configured and every time the system is loaded. Primary shows the current SCF state for the primary access path to the device (see Table 5-1 on page 5-1).
Example of a STATUS SCSI Detailed Report Managing Open SCSI Devices Detailed Report Information These subsections describe the fields in the STATUS SCSI detailed report. SCSI Path Information This Open SCSI device path information is provided in the detailed report produced by the STATUS SCSI, DETAIL command: LDev shows the logical device number for the Open SCSI device. This number is arbitrarily assigned to a device when the device is configured and every time the system is loaded.
Example of a STATUS SCSI Detailed Report Managing Open SCSI Devices SIM Queue Status shows the current status of the SCSI interface module (SIM) queue. The status can be FROZEN or UNFROZEN. When the SIM Queue Status is FROZEN, the application is responsible for the error recovery process. The rules of operation when the SIM queue is frozen are: • • • • • This condition prevents normal I/O operations. The IOP can initiate an I/O recovery operation while the SIM queue is frozen.
Viewing the Object Names of Open SCSI Devices Managing Open SCSI Devices Viewing the Object Names of Open SCSI Devices You use the SCF NAMES command to view the object names of any objects managed by the storage subsystem. The NAMES command does not change the state of any object. For complete details about the NAMES command, including command syntax, see the SCF Reference Manual for the Storage Subsystem.
Managing Open SCSI Devices Starting an Open SCSI Device Report Information The fields shown in the previous examples of NAMES reports have these meanings: SUBSYS shows the name of the storage subsystem manager process. DISK shows a list of the names of the DISK objects associated with the storage subsystem manager process. SCSI shows a list of the names of the Open SCSI objects associated with the storage subsystem manager process.
Managing Open SCSI Devices Example Example To stop the Open SCSI device $DEV0: -> STOP $DEV0 Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— 5 -7
Managing Open SCSI Devices Example Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— 5 -8
Index A Adding an Open SCSI device 4-3 AWAITIOX 3-1, 3-4, 3-20 C Cable specifications SCSI bus 2-2 shielded twisted-pair 2-2 CAM control block (CCB) 3-9, 3-14 CAM operations 3-9 CAM-flag bits 3-10 CAM-status values 3-19/3-20 CCB structures Abort SCSI Command 3-13 basic 3-12 Execute SCSI I/O 3-13 WRITEREAD buffer 3-5 CANCELREQ 3-1 CCB See CAM control block (CCB) CDB length in CCB 3-14 use by application 1-1 Changing Open SCSI attributes 4-3 Command descriptor block (CDB) See CDB Commands DELETE (SCF) 4-4 DE
F Index viewing current status information about devices 5-1 F FESTATUS literals 3-15/3-18 File-system error-code values 3-15/3-18 FILE_CLOSE_ 3-1 FILE_GETINFOBYNAME_ 3-1 FILE_GETINFOLISTBYNAME_ 3-1 FILE_GETINFOLIST_ 3-1 FILE_GETINFO_ 3-1 FILE_OPEN_ 3-1/3-3 G Guardian procedure calls AWAITIOX 3-1, 3-4, 3-20 CANCELREQ 3-1 DEVICE_GETINFOBYLDEV_ 3-1 DEVICE_GETINFOBYNAME_ 3-1 FILE_CLOSE_ 3-1 FILE_GETINFOBYNAME_ 3-1 FILE_GETINFOLISTBYNAME_ 3-1 FILE_GETINFOLIST_ 3-1 FILE_GETINFO_ 3-1 FILE_OPEN_ 3-1/3-3 WRITER
S Index Removing an Open SCSI device 4-4 Renaming an Open SCSI device 4-4 Reports NAMES 5-5 S SAC see SCSI SAC SCF -viii, 1-1, 3-16, 3-17, 4-1, 5-1 SCF DELETE 4-4 SCF DETAIL 4-1 SCF INFO 4-1 SCF NAMES 5-5/5-6 SCF START 5-6 SCF STOP 5-6/5-7 SCSI cables see Cable specifications SCSI ID viewing 4-1 SCSI Interface Module (SIM) queue operations 3-14, 5-4 SCSI-status values 3-21 SIM Queue operations 5-4 SIM queue operations 3-14 Software support for Open SCSI interface 1-1 START command (SCF) 5-6 Starting an O
Index Open SCSI for Fibre Channel Controller Integrator’s Manual for HP Integrity NonStop NS-Series Servers— Index -4 W
