TO: ALL FROM: RON PERRY / SEAGATE DATE: 1/26/89 RE: DOS OSD SPECIFICATION The following outlines some of my thoughts on the DOS OSD. All comments are welcome. ---------------------------------------------------------------- DOS OSD OVERVIEW ---------------------------------------------------------------- The OSD is responsible for the following: 1 . Know the number of SCSI CAMs attached. 2. Know the number of SCSI buses attached. 3. Be able to associate a SCSI bus with a SCSI CAM. 4. Know the entry point of all SCSI CAMs. 5. Provide IOCTL support for the application SCSI I/O LIBRARY. The DOS OSD is provided in the form of a DOS device driver. It supports the following DOS functions: - INIT - IOCTL INPUT - IOCTL OUTPUT These functions are invoked through the normal DOS device driver STRATEGY and INTERRUPT routines. In addition the OSD supports the following OSD/CAM functions: - OSD INIT - OSD EP These functions are invoked through a software interrupt. ---------------------------------------------------------------- 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 | | CAM | |_______________| |_______________| |_______________| | | | | | | | | SCSI | | SCSI | SCSI | | SCSI | | BUS | | BUS | BUS | | BUS | |_______________| |_______|_______| |_______________| ---------------------------------------------------------------- OSD FUCNTIONS ---------------------------------------------------------------- INIT ---- The INIT command is invoked by DOS when the OSD is loaded. During initialization the OSD should - decode the command line and accept parameter information - install the OSD interrupt service routine at the specified software interrupt - allocate memory for the specified number of CAM vectors - set the number of units in the DOS request header to 0 - set the ending address of the resident program code in the DOS request header - set the status word in the DOS request header IOCTL INPUT ----------- The IOCTL INPUT command is invoked by DOS as a result of a IOCTL service request from an application. An IOCTL service request will be generated by the following SCSI I/O LIBRARY functions: - To Be Supplied (TBS) IOCTL OUTPUT ------------ The IOCTL OUTPUT command is invoked by DOS as a result of a IOCTL service request from an application. An IOCTL service request will be generated by the following SCSI LIBRARY functions: - DO_SCSI The TRANSFER ADDRESS in the DOS request header contains a pointer to a CAM command block. During IOCTL OUTPUT, the OSD should pass the CAM control block to the appropriate CAM. On return from the CAM module the OSD must set the return status in the DOS request header. OSD INIT -------- The OSD INIT command is invoked by each CAM driver as it is loaded. Each CAM module is provided in the form of a DOS device driver. During initialization (INIT) each CAM should invoke the OSD INIT function (via the OSD software interrupt) with the following parameters: AX = 1 (OSD INIT function code) ES:BX = pointer to the cam module entry routine CX = number of SCSI buses attached The pointer to the cam module is used by the OSD in building a vector table of CAM module entry points. A CAM command block received by the OSD EP command is vectored to the appropriate CAM module based on the path identifier in the CAM command block. OSD EP ------ The OSD EP command is invoked by device drivers to request processing of a CAM command block. The CAM command block is vectored to the appropriate CAM based on the path identifer in the CAM command block. The OSD EP function is invoked (via the OSD software interrupt) with the following parameters: AX = 0 (OSD EP function code) ES:BX = pointer to CAM command block ----------------------------------------------------------------- DOS CAM OVERVIEW ----------------------------------------------------------------- The CAM is responsible for the following: 1 . Logging on to the DOS OSD 2. Processing a CAM command block. The DOS CAM is provided in the form of a DOS device driver. It supports the following DOS function: - INIT This function is invoked through the normal DOS device driver STRATEGY and INTERRUPT routines. In addition the CAM supports the following CAM function: - CAM EP This function is invoked from the OSD via an intersegment (far) call. ---------------------------------------------------------------- CAM FUCNTIONS ---------------------------------------------------------------- INIT ---- The INIT command is invoked by DOS when the CAM is loaded. During initialization the CAM should - decode the command line and accept parameter information - verify the presence of the DOS OSD - log on to the DOS OSD - invoke OSD INIT - initialize the CAM and HBAs to a ready and idle state - set the number of units in the DOS request header to 0 - set the ending address of the resident program code in the DOS request header - set the status word in the DOS request header During INIT, each CAM module must invoke OSD INIT via the specified software interrupt as follows: AX = 1 (OSD INIT function code) ES:BX = pointer to CAM EP CX = number of SCSI buses supported by this CAM CAM EP ------ CAM EP is invoked by DOS OSD to request processing of a CAM command block. This is an intersegment (far) call with the following parameters: ES:BX = pointer to CAM command block ---------------------------------------------------------------- PHYSICAL CONFIGURATION ---------------------------------------------------------------- _______________________________________________________ | | | INTERRUPT VECTORS | |_______________________________________________________| | | | BIOS DATA AREA | |_______________________________________________________| | | | DOS | |_______________________________________________________| | | | DOS OSD | |_______________________________________________________| | | | CAM | |_______________________________________________________| | | | CAM | |_______________________________________________________| | | | CAM | |_______________________________________________________| | | | DEVICE DRIVER | |_______________________________________________________| | | | DEVICE DRIVER | |_______________________________________________________| | | | APPLICATION | | | |________________ | | SCSI I/O | | | LIBRARY | | |_______________|_______________________________________| | | | SYSTEM ROM | |_______________________________________________________| ---------------------------------------------------------------- IMPLEMENTATION ---------------------------------------------------------------- Under MSDOS, both the DOS OSD and all CAM modules are implemented as pseudo device drivers. Device drivers request CAM services by passing a CAM command block to the DOS OSD which directs the command block to the appropriate CAM module. DOS OSD and CAM modules are specified in the DOS CONFIG.SYS file. Only one DOS OSD module can be present in the system. The number of CAM modules is limited by the size of the PATH variable in the CAM command block (TBS). The DOS OSD must be specified in the CONFIG.SYS file, before any CAM modules. Likewise, all CAM modules must be specified in the CONFIG.SYS file before any device drivers which require CAM services. Command line arguments provide the DOS OSD and the CAM modules with configuration parameters. DOS OSD accepts arguments as follows: /Cn - where n represents the number of CAM modules. /In - where n is the DOS OSD software interrupt number. CAM modules accept arguments as follows: /Pn m - where n represents a logical HBA number (base 0) and m represents the base i/o port for the HBA. /Qn m - where n represents a logical HBA number (base 0) and m represents the IRQ number. /Dn m - where n represents a logical HBA number (base 0) and m represents the DMA channel number. /Hn m - where n represents a logical HBA number (base 0) and m represents the HOST ID number. /In - where n is the DOS OSD software interrupt number. The DOS OSD and all CAM modules must specify the same software interrupt number (/I parameter). The default DOS OSD software interrupt is 58 (hex). The provider of the DOS OSD must use the follow name in the device header name field: _DOS_OSD This allows independent CAM module providers and device driver providers to verify the presence of the DOS OSD prior to invoking the DOS OSD software interrupt.