SCSI-2 CAM Working Document Proposal INTRODUCTION The goal of this document is to provide a significant starting point for the SCSI-2 CAM Committee. It is not meant to be the final word on CAM. This document is the result of merging several proposals put forth by the following companies (left column) who jointly put forth this proposal. This proposal was reviewed in a meeting on 1/11/89. The companies listed in the right column also attended this meeting. Adaptec Apple Ballard Synergy AT&T Columbia Data Products ENDL NCR Corporation IBM Quantum LMS/OSD Western Digital Optotech OVERVIEW The basis for this proposal is to have a well defined, structure-based service embedded in the operating system. This service, which we refer to as the "CAM Layer", provides services that frees any driver-level software from the details involved with communication with the Host Bus Adapter (HBA). This layer, then, will hide all of the details regarding the SCSI hardware so that device drivers only have to be written once for each Operating System. As we see it, the CAM effort should be initially directed toward the following activities: 1) Define the structure to be passed to the CAM Layer software from the device drivers. This structure should contain all of the parameters needed by the CAM Layer to perform its services. 2) Define the programming interface between the device drivers and the CAM Layer. This interface is probably different for each Operating System because of the differences in machine and Operating System architecture. 3) Define the set of services that are provided by the CAM Layer software along with guidelines for their use by device drivers. 4) Define a set of access routines that will provide a "library" of routines that will be used when accessing the services provided by the CAM Layer software. 5) Resolve any other issues related to the use of SCSI peripherals on machines that may wish to exchange media, host bus adapters, and/or drives. CAM LAYER The CAM Layer is a system service which provides generic SCSI functionality. The basic idea is to be able to send arbitrary SCSI command descriptor blocks (CDBs) and selected messages. There is CAM Layer software associated with each SCSI Host Bus Adapter (HBA). It is invoked by passing a pointer to a standardized data structure to the CAM Layer software. This section describes the services provided by the CAM Layer software for each SCSI HBA. Rudimentary coordination of multiple SCSI HBAs is also supported in the CAM structure. There will be features which are mandatory across all Operating System implementations and they are presented first. Features which are optional for certain Operating Systems are presented next. Finally, features which are optional for all Operating Systems are presented. Every implementation must allow the sending of SCSI CDBs. The SCSI CDB is contained in the CAM Command Block whose address is passed to the CAM Layer. CAM Layer Functions Upon invocation of the CAM Layer, the actual function which is being requested is denoted by the CAM Function Code. If a restricted version of the CAM Layer is desired, the legal function codes can be filtered to prevent unwanted access to dangerous functions. Any arguments to these functions or results from these functions will be passed in the CAM Command Block or in buffers pointed to by fields in this structure. The following paragraphs describe the complete set of CAM Layer functions. SEND SCSI COMMAND This function sends the SCSI CDB found in the CAM Command Block to the specified target on the specified SCSI link. This will be the most often used function provided by the CAM Layer. This is an initiator mode function. INITIATE SCSI ABORT MESSAGE This function will issue a SCSI "Abort" message to the specified target device on the specified SCSI link. This is an initiator mode function. INITIATE SCSI BUS DEVICE RESET This function will issue a SCSI "Bus Device Reset" message to the specified target device on the specified SCSI link. This is an initiator mode function. RETURN HOST ADAPTER SCSI ID This function will return the SCSI ID that is used by the Host Bus Adapter associated with the specified SCSI link. The SCSI ID will be returned in the "Target Status" field in the CAM Command Block. GET DEVICE TABLE INFORMATION This function will return an array of bytes which are the "peripheral device type" bytes returned during an INQUIRY command. The first byte of this array corresponds to the device at SCSI id 0/lun 0. The next byte is for id 0/lun 1. This continues up to id 7/lun 7. A value of 7F (hex) indicates that there is no peripheral attached at that id/lun. This array is returned in the data buffer specified in the CAM Command Block for the specified SCSI link. GET NUMBER OF SCSI LINKS SUPPORTED This function returns the number of SCSI links supported by the CAM Layer driver. The value is returned in the "Target Status" field in the CAM Command Block. ALLOW TARGET MODE This function causes the CAM Layer to set up the HBA associated with the specified SCSI link so that it may be selected as a target. The specified SCSI id must match that returned by the "RETURN HOST ADAPTER SCSI ID" function. The specified lun will be the one that is enabled for selection. This is a target mode function. GET SCSI CDB This function causes the CAM Layer driver to hold this request until the specified SCSI id/lun is selected on the specified link. At that point, it will request the SCSI CDB from the initiator and place it into the CDB field in the CAM Command Block. Then it will notify the requester via the interrupt routine address field contained in the CAM Command Block. This is a target mode function. RECEIVE DATA This function causes the CAM Layer driver to request a data out phase to get data from the current initiator. The data will be placed in the data buffer. The number of bytes transferred is specified by the data buffer length field in the CAM Command Block. This is a target mode function. SEND DATA This function causes the CAM Layer driver to request a data in phase to transmit data to the current initiator. The data will be transmitted from the data buffer. The number of bytes transferred is specified by the data buffer length field in the CAM Command Block. This is a target mode function. DISCONNECT This function causes the CAM Layer to send a DISCONNECT message to the current initiator. It then disconnects from the SCSI link. This is a target mode function. RESELECT This function causes the CAM Layer to reselect the specified initiator and send the appropriate IDENTIFY message. This is a target mode function. SEND STATUS This function causes the CAM Layer to send the status byte specified in the "Target Status" field to the current initiator and then send the COMMAND COMPLETE message. It will then disconnect from the SCSI link. This is a target mode function. SEND MESSAGE This function causes the CAM Layer to send the specified message byte(s) to the current initiator. This is a target mode function. INITIALIZE HOST BUS ADAPTER This function causes the CAM Layer to (re)initialize the specified HBA. All pending commands for that HBA are terminated and all appropriate initialization is performed. This function might be one of the commands that a restricted CAM Layer might want to disallow. SCSI BUS RESET This function issues a SCSI Bus Reset. This function might be one of the commands that a restricted CAM Layer might want to disallow. CAM COMMAND BLOCK DEFINITION This section defines the CAM Command Block and the fields contained within this structure. Following the structure definition is a detailed description of each field within the CAM Command Block. OFFSET DATA TYPE LENGTH FIELD DESCRIPTION 00 UNSIGNED CHAR 1 Function Code 01 UNSIGNED CHAR 1 Function Flags 02 UNSIGNED CHAR 1 Path 03 UNSIGNED CHAR 1 Target ID 04 UNSIGNED CHAR 1 Target LUN 05 UNSIGNED CHAR 1 Status Code 06 UNSIGNED CHAR 1 SCSI Status 07 UNSIGNED CHAR 1 CDB Length 08 UNSIGNED CHAR 16 SCSI Command Descriptor Block 24 UNSIGNED LONG 4 Data Buffer Pointer 28 UNSIGNED LONG 4 Data Buffer Length 32 UNSIGNED LONG 4 Sense Data Buffer Pointer 36 UNSIGNED INT 2 Sense Data Allocation Length 38 UNSIGNED INT 2 Priority / Ordering / ? 40 UNSIGNED LONG 4 Next CCB Pointer 44 UNSIGNED LONG 4 Private Information Pointer 48 UNSIGNED CHAR 48 Scratchpad Area In addition, an Operating System Dependent (OSD) structure will be defined that contains a field defined as "Transaction Completion Pointer". FIELD DEFINITIONS Function Code - This field specifies the actual function which is being requested. If a restricted version of the CAM Layer is wanted, the legal function codes can be filtered to prevent unwanted access to dangerous functions. 0 = send SCSI command to specified target (CDB fully specified). 1 = initiate SCSI ABORT message. 2 = initiate SCSI Bus Device Reset. 3 = return Host adapter SCSI ID. 4 = get device table information. 5 = get number of SCSI links supported. 6 = allow target mode. 7 = get SCSI CDB. 8 = receive data. 9 = send data. 10 = disconnect. 11 = reselect. 12 = send status. 13 = send message. 14 = initialize Host Bus Adapter 15 = SCSI Bus Reset (NOT recommended!) 16-255 = RESERVED. FIELD DEFINITIONS (continued) Function Flags - This field contains flags that are used to indicate special handling of the requested function. These bits are defined as follows: Bit 0 = direction flag - This bit is an indicator that tells the generic driver the direction of data movement during the data transfer phase. A value of zero (0) indicates a "read" operation (data from target to initia tor). A value of one (1) indicates a "write" operation (data from initiator to target). Bit 1 = polling flag - When set to one, this bit causes the driver to return to the caller as soon as the command block has been "registered" with the driver. This will allow the calling software to "poll" the driver return code field to determine when the command is completed. A non-zero value will indicate completion or termination. When this bit is reset (0), the driver will suspend the caller until the command is completed. Bit 2 = physical address bit - When set to one, this bit indicates that the physical address fields in the CAM Command Block are valid. Bit 3 = logical address bit - When set to one, this bit indicates that the logical address fields in the CAM Command Block are valid. Bit 4 = scatter/gather enable bit - When set to one, this bit allows the CAM driver to perform scatter/gather operations on this command. Bit 5 = auto sense flag - When set to one, this bit causes the driver to retrieve sense data on a check condition in the target completion status byte. When the check condition occurs, the driver constructs a 6-byte SCSI CDB with the "Request Sense" command to send to the same target. The loca tion and amount of the sense data is as specified in the command block. On return, the driver return code field contains the status of the original command. The target status contains the target completion status of the original command. (This feature should be mandatory! This would eliminate the need for this bit.) Bit 6 = disconnect flag - When set to one, this bit causes the driver to set bit 6 in the SCSI IDENTIFY message to one. Bit 6 in the SCSI IDENTIFY message indicates that the initiator has the ability to accommodate disconnection and reconnection. If this feature is made mandatory, it would eliminate the need for this bit. Bit 7 = RESERVED FIELD DEFINITIONS (continued) Path - This field contains the logical link number of the SCSI link on which this command is to operate. Link numbers are zero-based so that the first link supported by the CAM Layer is link number zero. Link numbers are successively numbered up to the number of links supported without any gaps in the numbers. Target ID and Target LUN - These fields contains the SCSI ID and Logical Unit Number (LUN) of the target for this command. SCSI Status - This field is the status byte returned by the target after the command is completed. CDB Length - This field contains the length, in bytes, of the CDB contained in the SCSI Command Descriptor Block field. The value contained in this field must be between 6 and 12. SCSI Command Descriptor Block - This 12-byte field will contain the CDB for the command that is to be performed. Data Buffer Pointer - This field contain a pointer to the data buffer used in connection with this request. Data Buffer Length - This field contains the length (in bytes) of the data buffer. Sense Data Buffer Pointer - This field contains a pointer to the data buffer for the "request sense" data. This buffer (and pointer) will only be used if the sense data control bit is set and a "check condition" occurs while performing the specified command. Sense Data Allocation length - This field contains the length (in bytes) of the request sense data buffer. Priority / Ordering / ? - This field is used to allow the driver software to specify the relative priority and/or ordering of this request in relation to the other requests pending at the CAM Layer. Next CCB Pointer - This field provides a pointer to the next command block in a chain of command blocks. A value of zero (0) in this field indicates the last command block on the chain. These fields allow for linked commands. Private Information Pointer - This field is used by the driver/application that calls the CAM Layer to point to an area of memory that it has allocated to store private information related to this request. FIELD DEFINITIONS (continued) Scratchpad Area - This field is used by the CAM Layer to store temporary data while it processes this request. CAM driver status code - This field contains the CAM Layer driver's returned status code. The values returned have the following meanings: 00 = NOT USED - command in progress or still queued. 01 = NO ERRORS - normal completion status. 02 = BUFFER OVERFLOW ERROR - Either the target asked for more than 12 bytes of command, or the target tried to send or receive more bytes of data than the buffer can hold. 03-7F = RESERVED. 80 = COMMAND TIMEOUT - the specified command did not complete within the timer value specified. 81 = SCSI BUS BUSY - The CAM Layer driver failed to win arbitration for the SCSI Bus during several different bus free phases. 82 = TARGET SELECTION TIMEOUT - The target failed to respond to selection. 83 = SCSI BUS RESET SENT/RECEIVED - The SCSI operation was terminated at some point because the SCSI bus was reset. 84 = UNEXPECTED DISCONNECTION/INVALID BUS PHASE - The target terminates a SCSI operation prematurely by releasing the SCSI bus. The target does this by dropping the BSY signal prior to sending a "Command Complete" or "Disconnect" message. 85 = TRANSFER INCOMPLETE - This code indicates that the SCSI operation ended normally, but the total number of bytes transferred successfully was less than the initial number of bytes to be transferred. 86 = UNCORRECTABLE PARITY ERROR DETECTED - This code indicates that an uncorrectable SCSI bus parity error was detected. When this occurs, the CAM Layer driver sends the ABORT message to the target. FIELD DEFINITIONS (continued) 87 = SENSE DATA OPERATION FAILED - The CAM Layer driver attempted to obtain sense data and failed. 88 = MESSAGE REJECT RECEIVED - This code is returned when the CAM Layer driver receives the MESSAGE REJECT message. 89 = BAD COMMAND - This code is returned when an invalid command code is specified. 8A = INVALID BUS PHASE - This code is returned when an invalid bus phase is detected on the SCSI link. 8B = INVALID LINK NUMBER - This code is returned when an invalid SCSI link number is specified. 8C-8F = RESERVED. 90 = TARGET SELECTED - This code is returned when the SCSI HBA has been selected by an initiator. 91 = CDB RECEIVED - This code is returned along with the CDB sent by the initiator to indicate that the CDB has been successfully received. 92-FF = RESERVED. OSD FIELD DEFINITIONS Transaction Completion Pointer - This field provides a pointer to the routine to be called by the CAM Layer when the requested function completes. OPEN ISSUES 1) Arguments for the different function codes can be in one of three places: A) memory referenced by the data buffer pointer, B) a dedicated field in the CAM Command Block, or C) sharing another field in the CAM Command Block. The appropriate place will depend on exactly how many arguments are needed and their field size. 2) How to handle Asynchronous Event Notification. 3) Completion of the definition of the Target mode interface. 4) How to handle SCSI-2 command queuing and priorities in a cohesive way. 5) For each Operating System, we need to define the interface method used to pass the CAM Command Block to the CAM Layer from both a device driver and an application program. 6) The specification of the functions to be included into the Standard SCSI I/O Library needs to be defined. 7) A standard algorithm for conversion of Head/Sector/Cylinder to/from Logical Block Address needs to be defined.