TO: ALL FROM: RON PERRY DATE: 3/31/89 RE: DOS OSD SPECIFICATION The following is an amended outline of the DOS OSD. If anyone has comments please leave a message on the BBS or contact me at (408) 439-2310. ---------------------------------------------------------------- DOS OSD OVERVIEW ---------------------------------------------------------------- The SCSI Common Access Method (CAM) provides a common interface to SCSI devices independent of the operating environment. CAM has three components: - OPERATING SYSTEM DEPENDENCIES MODULE (OSD) - TRANPORT MODULE - SCSI INTERFACE MODULES (SIM) The OSD isolates the TRANSPORT MODULE and SIMs from the operating system. It allows SIMs to provide functional services to device drivers independent of the operating system. This document proposes an initialization and operating procedures for the MSDOS or PCDOS (DOS) operating system. Throughout this document OSD refers to the Operating System Dependent Module implemented in the MSDOS or PCDOS operating environment. The OSD is a single tasking software component operating within the addressing constraints of real mode. It is implemented in the form of a DOS device driver and supports the following device driver functions: - INIT - IOCTL INPUT These functions are invoked through the normal DOS device driver STRATEGY and INTERRUPT routines. The OSD also supports a CAM entry point that is invoked by software interrupt (OSD EP). The OSD is responsible for the following: 1. Load OSD configuration file. 2. Locate / load Scsi Interface Modules (SIMs). 3. Initialize all SIMs. 4. Initialize the OSD device tables. 5. Provide an Interrupt Service Routine for all IRQ lines used by SIM HBAs 6. Provide IOCTL support for the application SCSI I/O LIBRARY. 7. Transfer CAM command blocks to the specified SIM or Transport Module. x. Provide interrupt 13 to SIM translation if the boot device is attached to a SIM HBA. x. Initialize Transport Module. The OSD must be specified in the CONFIG.SYS file, before any device drivers which require CAM services. ---------------------------------------------------------------- DATA STRUCTURES ---------------------------------------------------------------- OSD SOFTWARE HEADER ------------------- In addition to the DOS device driver header, the OSD contains a CAM software header defined as follows: Offset Length OSD EP 00H 16 OSD Signature = 06B6B6B6BH 10H 4 Vendor ID 14H 16 Product ID 24H 16 Product Revision 34H 4 OSD EP is the software interrupt entry point through which users request CAM services. The OSD EP is the first field of the OSD header with 16 bytes reserved for the entry code. A 'CALL' or 'JMP' instruction is required to re-vector the request beyond the OSD header. The other fields in the Osd Software Header are analagous to those defined in the Initialization & Interrupt Processing Algorithms And Associated Structure Definitions document. CAM COMMAND BLOCK ----------------- The CAM command block is the data structure used to request CAM services and receive status. The CAM command block is structured as follows: FIELD OFFSET LENGTH ----- ------ ------ OSD FUNCTION CODE 00H 01 OSD PATH (or device type) 01H 02 OSD ADDITIONAL SERVICE POINTER 03H 04 OSD RESERVED 07H 25 NON OSD AREA 20H variable OSD FUNCTION CODE is the command code that qualifies the processing of the CAM command block. The following command codes are defined: FUNCTION CODE -------- ---- PASS REQUEST TO SIM 00 PASS REQUEST TO TRANSPORT MODULE 01 GET DEVICE TABLE ADDRESS 02 OSD PATH normally represents the logical path number of the destination device as supplied in the OSD DEVICE TABLE. If the OSD FUNCTION CODE is 'GET DEVICE TABLE ADDRESS', then this area contains the peripheral device type of the requested device table. OSD ADDITIONAL SERVICE POINTER normally contains the address of a routine to call when the transaction is complete. If the OSD FUNCTION CODE is 'GET DEVICE TABLE ADDRESS', then this area contains the address of the requested device table. (A null pointer signifies 'no further service' or 'no such device' depending on the OSD FUNCTION CODE.) OSD RESERVED is an undefined area. (This area is reserved for device unique data such as dma channel, base i/o port, and any OSD support functions that may be required for compatability with other operating systems. The size requirement for this area is unknown. It is presumed to be in the range of 0 to 25 bytes.) NON OSD AREA is the area of the CAM control block that is specific to the SIMs or Transport Module. OSD Device Table ---------------- The device table translates the physical scsi bus configurations to logical configurations by device type. A SIM identifies the destination of a Cam Command Block (CCB) from the Scsi Link, Target Id and Target Lun. The OSD identifies the destination SIM from the Path Id. This information is conveyed to the device drivers by the OSD device table. OSD device table Offset Length ---------------- ------ ------ Device Type 0 1 Number of Devices 1 2 Device 0 Path 3 1 Device 0 Scsi Link 4 1 Device 0 Id 5 1 Device 0 Lun 6 1 Device 0 State 7 1 Device 0 CAM Start Routine 8 4 Device 0 CAM Device Block 12 4 . . . Device n Path y 1 (y = 3+(n * 13)) Device n Scsi Link y+1 1 Device n Id y+2 1 Device n Lun y+3 1 Device n State y+4 1 Device n CAM Start Routine y+5 4 Device n CAM Device Block y+9 4 Device Type is the SCSI peripheral device type. Number of Devices is the total number of 'Device Type' peripherals supported under CAM services. Device Path is the logical path number (OSD PATH) of the device. This number is assigned by the OSD during initialization. Device Scsi Link is the SIM logical bus number of the device. Device Id is the scsi bus target id of the device. Device Lun is the scsi bus target lun of the device. Device State is a boolean value that represents the state of the the device as reported during SIM initialization (present or not present). CAM Start Routine is the entry point address of the SIM that provides service for the device. CAM Device Block is the data area address of the SIM that provides service for the device. Configuration File ------------------ The configuration file allows the user to specify the OSD resources, SIM resources, and SIM bus configurations. It eliminates timeout and command processing delays associated with multiple device drivers scanning multiple scsi buses for devices or luns. The CAM configuration file is a command file (similiar to DOS configuration files CONFIG.SYS ) which accepts the following commands: SWINT - This command allows the user to declare the software interrupt to be used by OSD. OSDID - This command allows the user to assign a multiplex identifier to the OSD for sharing of a software interrupt. OSDNAME - This command allows the user to specify the name assigned to the OSD in the DOS device header. CAM - This command specifies the filename of a SIM to be loaded by the the OSD. ROMCAM - This command specifes the segment address of a ROM resident SIM. HBA - This command assigns a SCSI id to the HBA. IOPORT - This command assigns the base i/o port to the HBA. DMA - This command assigns a dma channel to the HBA. IRQ - This command assigns an irq to the HBA. TYPE - This command specifies the SCSI device type of a device on the bus. ID - This command specifies the SCSI target id of a device on the bus. LUN - This command specifies the SCSI lun of a device on the bus. --------------------------------------------------------------- INITIALIZATION --------------------------------------------------------------- OSD initialization occurs when DOS invokes the device driver INIT function. During initialization the OSD should: - decode the command line and accept parameters - load the cam configuration file - find / load and initialize specified SIMs - initialize OSD device table - install interrupt service routines for SIM irqs - install the OSD (software) interrupt service routine - complete the DOS request header By default, the OSD uses the configuration file "\CONFIG.CAM" to obtain OSD and SIM configuration details. The command line argument "/F " allows a user to specify an alternate filename for OSD and SIM configuration detail. In addition to providing flexiblity to the configuration process, this also allows multiple OSD modules to be loaded. Based on the configuration file, the OSD loads ram resident SIMs or locates rom resident SIMs and initializes all SIMs. See the Initialization and Interrupt Processing Algorithms and Associated Structure Definitions document for SIM initialization procedures. From the SIM Initialization Tables and OSD configuration file, the OSD builds the OSD device table for each scsi device type. ----------------------------------------------------------------- OSD FUNCTIONS ----------------------------------------------------------------- The OSD supports five functions. Two functions are invoked through DOS: - INIT - IOCTL INPUT and the others through the OSD software interrupt. - PASS REQUEST TO SIM - PASS REQUEST TO TRANSPORT MODULE - GET DEVICE TABLE ADDRESS INIT ---- The INIT function is described in the INITIALIZATION section above. IOCTL INPUT ----------- Applications that link to the SCSI I/O library must make an IOCTL request to determine which software interrupt the OSD is using. Specific OSD services are then available through the software interrupt (OSD EP). PASS REQUEST TO SIM ------------------- The CAM command block is vectored to the appropriate SIM based on the path identifer in the command block. The OSD software interrupt is invoked with the following parameters: AX = OSD multiplex identifier ES:BX = pointer to CAM command block PASS REQUEST TO TRANSPORT MODULE -------------------------------- (tbs) GET DEVICE TABLE ADDRESS ------------------------ This command allows the device driver to determine the address of the OSD device table. The OSD software interrupt is invoked with the following parameters: AX = OSD multiplex identifier ES:BX = pointer to CAM command block ---------------------------------------------------------------- TRANSFER CONVENTIONS ---------------------------------------------------------------- The CAM Control Block is the method by which device drivers communicate with SIMs. Device drivers can use either of two methods for transfering requests to SIMS. - OSD transfer convention - Direct transfer convention In the OSD transfer convention, the device driver invokes a software interrupt to enter the OSD. The OSD calls the appropriate CAM start routine based on the OSD PATH field in the CAM Control Block. The Direct Transfer method allows the device driver to invoke the appropriate CAM start routine based on the OSD device table. (The functional requirements of the OSD are very limited. As currently proposed, the majority of the processing involves initialization. Assuming that the OSD functionality requirements don't increase, then the Direct Transfer method provides device drivers an opportunity to improve the transfer performance when requesting CAM services. This method may not be viable with increased OSD functional requirements.) ---------------------------------------------------------------- LOGICAL CONFIGURATION ---------------------------------------------------------------- _______________________________________________________ | | | APPLICATION | | | |---------------| | | SCSI I/O | | ___| LIBRARY | | | |_______________|_______________________________________| | | INT 21 | INT 21 | | (IOCTL) | | ______|____________________|___________________________ | | | | | DOS |___ | | | | | |_______________________________________________________| | FAR | | FAR | FAR | CALL | | CALL | CALL | | ___________|____________ ___________|___________ | | | | | | | | | DEVICE DRIVER | | DEVICE DRIVER | | | |_______________________| |_______________________| | | | | | | | S/W INT | | |______________|________________________________| | | | ___________________________|___________________________ | | | | | OSD |___| |_______________________________________________________| | FAR | FAR | FAR | CALL | CALL | CALL _______|_______ _______|_______ _______|_______ | | | | | | | CAM | | CAM | | ROM CAM | |_______________| |_______________| |_______________| | | | | | | | | SCSI | | SCSI | SCSI | | SCSI | | BUS | | BUS | BUS | | BUS | |_______________| |_______|_______| |_______________| ---------------------------------------------------------------- OPEN ISSUES ---------------------------------------------------------------- 1. Initialization and interface with Transport Module. 2. Interrupt 13. If boot device is also CAM device, then unit will be configured twice. Once as interrupt 13 device, and once as CAM device. 3. HBA specific information passed to SIM. (DMA channel, base i/o port). 4. Additional OSD functionality to make CAM consistent across multiple operating systems.