---------------------------------------------------------------- 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 and TRANSPORT MODULE isolate 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 called directly (OSD EP). The entry point address is obtained via the IOCTL INPUT function. The OSD is responsible for the following: 1. Load OSD configuration file. 2. Locate / load Scsi Interface Modules (SIMs). 3. Initialize all SIMs. 4. Provide an Interrupt Service Routine for all IRQ lines used by SIM HBAs 5. Provide IOCTL support for device driver and application initialization. 6. Transfer CAM command blocks to the specified SIM or Transport Module. 7. Inform device drivers if a SIM supports a device that is also configured by the system bios (Interrupt 13). 8. Initialize Transport Module. The OSD must be specified in the CONFIG.SYS file, before any device drivers which require CAM services. ---------------------------------------------------------------- DATA STRUCTURES ---------------------------------------------------------------- DOS DEVICE DRIVER HEADER ------------------------ A DOS device driver requires a device header at the beginning of the file. The DOS device header is defined as follows: Offset Length Pointer to next header 00H 4 Attribute 04H 2 Offset of strategy routine 06H 2 Offset of interrupt routine 08H 2 Name 0AH 8 With the exception of the Name field, all fields in the DOS device header are implementation specific. All DOS OSD providers must use the name _DOS_OSD in the DOS device header. This allows device drivers and applications to issue an IOCTL to a known device independent of the DOS OSD provider. 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 OSD Vendor ID 14H 16 OSD Product ID 24H 16 OSD Product Revision 34H 4 OSD Sims 38H 2 Interrupt 13 Device 0 Sim 3AH 1 Interrupt 13 Device 0 Path 3BH 1 Interrupt 13 Device 0 Target ID 3CH 1 Interrupt 13 Device 0 Lun 3DH 1 Interrupt 13 Device 1 Sim 3EH 1 Interrupt 13 Device 1 Path 3FH 1 Interrupt 13 Device 1 Target ID 40H 1 Interrupt 13 Device 1 Lun 41H 1 OSD EP is the software 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. All calls to this entry point are FAR calls. To obtain the address of the OSD software header, device drivers or applications must first issue an IOCTL INPUT. OSD Signature identifies a valid OSD module. OSD Vendor ID is an ASCII field that identifies the OSD vendor. OSD Product ID is an ASCII field that identifies the product name. OSD Product Revision identifies the product revision level. OSD Sims identifes the number of SIM modules attached to the OSD. Interrupt 13 Device 0 Sim identifies a SIM module with an interrupt 13 boot device attached. This area will be initialized to 0FFFFh if the boot device is not a CAM device. Interrupt 13 Device 0 Path identifies the Sim Control Block PATH of the boot device. This area will be initialized to 0FFFFh if the boot device is not a CAM device. Interrupt 13 Device 0 Target ID identifies the Sim Control Block TARGET ID of the boot device. This area will be initialized to 0FFFFh if the boot device is not a CAM device. Interrupt 13 Device 0 Lun identifies the Sim Control Block LUN of the boot device. This area will be initialized to 0FFFFh if the boot device is not a CAM device. Interrupt 13 Device 1 Sim identifies a SIM module with a second interrupt 13 device. This area will be initialized to 0FFFFh if the second interrupt 13 device is not a CAM device. Interrupt 13 Device 1 Path identifies the Sim Control Block PATH of a second interrupt 13 device. This area will be initialized to 0FFFFh if the second interrupt 13 device is not a CAM device. Interrupt 13 Device 1 Target ID identifies the Sim Control Block TARGET ID of a second interrupt 13 device. This area will be initialized to 0FFFFh if the the second interrupt 13 device is not a CAM device. Interrupt 13 Device 1 Lun identifies the Sim Control Block LUN of a second interrupt 13 device. This area will be initialized to 0FFFFh if the second interrupt 13 device is not a CAM device. 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 SIM NUMBER 01H 02 OSD ADDITIONAL SERVICE POINTER 03H 04 OSD STATUS BYTE 07H 01 OSD FUNCTION DATA 08H 24 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 RETURN SIM INITIALIZATION TABLE 02 OSD SIM NUMBER represents the logical path number of the destination SIM. OSD ADDITIONAL SERVICE POINTER contains the address of a routine to call when the transaction is complete. A null pointer signifies 'no additional service' required. OSD STATUS BYTE contains the OSDs returned status code. The following return codes (hex) are defined: 00 = NOT USED 01 = NO ERRORS - normal completion status 02-88 = reserved 89 = BAD COMMAND - invalid FUNCTION CODE specified 8A = reserved 8B = INVALID LINK NUMBER - invalid SIM NUMBER specified 8C-FF = reserved (The above status codes are specified to be consistent with the SIM working document proposal.) OSD FUNCTION DATA is an area that varies depending on the operation to be performed. See specific OSD functions for definition. NON OSD AREA is the area of the CAM control block that is specific to the SIMs or Transport Module. Configuration File ------------------ The configuration file allows the user to specify the SIMs to be loaded by the OSD. The CAM configuration file is a command file (similiar to DOS configuration files CONFIG.SYS ) which accepts the following commands: CAM - This command specifies the filename of a SIM to be loaded by the the OSD. --------------------------------------------------------------- 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 - install interrupt service routines for SIM irqs - find / load and initialize the TRANSPORT module - complete the DOS request header - locate interrupt 13 devices that are also CAM devices 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. 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. If the OSD locates any rom resident SIMs, the OSD issues interrupt 13 requests to determine if any SIM units are also configured into interrupt 13. The OSD issues an interrupt 13 request with the following parameters: AX = 0AA55h DL = Interrupt 13 unit number (80H or 81H) ES:BX = Transfer Address If the specified unit can not be identified as a SIM unit, the interrupt 13 request will be rejected with a BAD COMMAND status (01H). If the specified unit is identified as a SIM unit, the following information will be returned at the transfer address: Field Offset Length Sim Signature (6A6A6A6AH) 00 04 Vendor ID 04 16 Product ID 20 16 Product Revision 36 04 Logical ID of Interrupt 13 SIM 40 01 Target ID of Interrupt 13 device 41 01 Lun of Interrupt 13 device 42 01 ----------------------------------------------------------------- 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 SIM INITIALIZATION TABLE INIT ---- The INIT function is described by the INITIALIZATION section above. IOCTL INPUT ----------- Device drivers (or applications) must make an IOCTL request to determine the OSD entry point. Specific OSD services are then available through the calls to the OSD entry point. The IOCTL request is made using DOS service 44H (I/O Control for Devices), function 02H (Read from device). DOS is called with the following parameters: AX = Dos service and function value (4402H) BX = Device handle CX = Number of bytes to read (04H) DS:DX = Transfer address The OSD will return the address of the Software Header at the Transfer Address. PASS REQUEST TO SIM ------------------- The PASS REQUEST TO SIM function directs the OSD to transfer the Sim Control Block (equivalent to the NON OSD AREA) to the Start Routine of the SIM designated by the OSD SIM NUMBER. The OSD is called with the following parameters: ES:BX = pointer to OSD command block The OSD command block is structured as follows: FIELD OFFSET LENGTH ----- ------ ------ OSD FUNCTION CODE 00H 01 OSD SIM NUMBER 01H 02 OSD ADDITIONAL SERVICE POINTER 03H 04 OSD STATUS BYTE 07H 01 RESERVED 08H 24 SIM CONTROL BLOCK 20H ? PASS REQUEST TO TRANSPORT MODULE -------------------------------- The PASS REQUEST TO TRANSPORT MODULE function directs the OSD to transfer the Transport Control Block (eqivalent to the NON OSD AREA) to the Transport Module Start Routine. The OSD is called with the following parameters: ES:BX = pointer to OSD command block The OSD command block is structured as follows: FIELD OFFSET LENGTH ----- ------ ------ OSD FUNCTION CODE 00H 01 OSD SIM NUMBER 01H 02 OSD ADDITIONAL SERVICE POINTER 03H 04 OSD STATUS BYTE 07H 01 RESERVED 08H 24 TRANSPORT CONTROL BLOCK 20H ? RETURN SIM INITIALIZATION TABLE ------------------------------- The RETURN SIM INITIALIZATION TABLE function directs the OSD to return a pointer to the INITIALIZATION TABLE of the SIM designated by the OSD SIM NUMBER. ES:BX = pointer to OSD command block The OSD command block is structured as follows: FIELD OFFSET LENGTH ----- ------ ------ OSD FUNCTION CODE 00H 01 OSD SIM NUMBER 01H 02 OSD ADDITIONAL SERVICE POINTER 03H 04 OSD STATUS BYTE 07H 01 SIM INITIALIZATION TABLE ADDRESS 08H 04 RESERVED 0CH 20 The address of the SIM INITIALIZATION TABLE is returned as a double word pointer in the OSD FUNCTION DATA area of the OSD command block. ---------------------------------------------------------------- LOGICAL CONFIGURATION ---------------------------------------------------------------- _______________________________________________________ | | | APPLICATION | | | |---------------| | | SCSI I/O | | ___| LIBRARY | | | |_______________|_______________________________________| | | | | INT 21 | ___________________________|___________________________ | | | | | DOS |___ | | | | | |_______________________________________________________| | FAR | | FAR | FAR | CALL | | CALL | CALL | | ___________|____________ ___________|___________ |(INIT) | | | | | |(IOCTL) | | DEVICE DRIVER | | DEVICE DRIVER | | | |_______________________| |_______________________| | | | | | | | FAR CALL | | |______________|________________________________| | | | | (OSD_EP) | ___________________________|___________________________ | | | | | OSD |___| |_______________________________________________________| | FAR | FAR | FAR | CALL | CALL | CALL _______|_______ _______|_______ _______|_______ | | | | | | | CAM | | CAM | | ROM CAM | |_______________| |_______________| |_______________| | | | | | | | | SCSI | | SCSI | SCSI | | SCSI | | BUS | | BUS | BUS | | BUS | |_______________| |_______|_______| |_______________|