ASPI For NetWare Specification About This Chapter Read this chapter to find out: - An overview of the steps involved in accessing ASPI for NetWare - The SCSI request block and ASPI commands executed by the ASPI manager - Information on running ASPI in file servers with more than 16 MBytes of RAM and NetWare 386’s Scan for New Devices routine ASPI Diagram Accessing ASPI Before creating your NetWare Loadable Module (NLM), you must first create the object file and a definition file. In the definition file, you tell NetWareฎ what routines you wish to export to the operating system, and what routines you wish to import into your NLM. You will need to import one ASPI routine. Sample definition file: . . IMPORT . . ASPI_Entry . . Using the Novell linker, the object and definition files are linked together to create your NLM. During load time, if NetWare 386 does not find this imported routine, it will not load your NLM. You must load the ASPI module before the other modules can access it. ASPI Routine: ASPI_Entry This routine allows you to pass a SCSI Request Block (SRB) to ASPI. Syntax void ASPI_Entry ( void *ASPIRequestBlock ) Return Values Returns nothing Parameters Parameter Description ASPIRequestBlock This field contains a pointer to your SRB. Refer to the request block -definitions found later in this specification. Assembly Example push OFFSET ASPI_ReqBlock ;Push SRB onto the stack call ASPI_Entry ;Call ASPI lea esp,[esp+(1*4)] ;Restore the stack Remarks On entry, interrupts should be disabled. Returns with interrupts disabled. SCSI Request Block (SRB) A SCSI Request Block (SRB) contains the command to be executed by the ASPI -manager and is used by both drivers and application programs. An SRB consists of an SRB header followed by additional fields dependent on the command code. All -request blocks have an eight-byte header: Offset # Bytes Description R/W* 00h (00) 01h (01) Command Code W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 — *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (—). Command Code The Command Code field is used to indicate which of the ASPI services is being accessed. Refer to Valid ASPI Command Codes on page 4-6. Status The Status Byte field is used to post the status of the command. Refer to ASPI Status Bytes on page 4-6. Host Adapter Number The Host Adapter Number field specifies which installed host adapter the request is intended for. Host adapter numbers are always assigned by the SCSI manager layer beginning with zero. SCSI Request Flags The SCSI Request Flags field definition is command code specific. Reserved for Expansion The last four bytes of the header are reserved and must be zero. ASPI Command Codes Valid ASPI Command Codes Command Code Description 00h Host Adapter Inquiry 01h Get Device Type 02h Execute SCSI I/O Command 03h Abort SCSI I/O Command 04h Reset SCSI Device 05h Set Host Adapter Parameters 06h-7Fh Reserved for Future Expansion 80h-FFh Reserved for Vendor Unique ASPI Status Bytes Status Byte Description 00h SCSI Request in Progress 01h SCSI Request Completed Without Error 02h SCSI Request Aborted by Host 04h SCSI Request Completed With Error 80h Invalid SCSI Request 81h Invalid Host Adapter Number 82h SCSI Device Not Installed ASPI Command Code = 0: Host Adapter Inquiry Offset # Bytes Description R/W* 00h (00) 01h (01) Command Code = 0 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 — 08h (08) 01h (01) Number of Host Adapters R 09h (09) 01h (01) Target ID of Host Adapter R 0Ah (10) 10h (16) SCSI Manager ID R 1Ah (26) 10h (16) Host Adapter ID R 2Ah (42) 10h (16) Host Adapter Unique Parameters R *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (—). The status byte always returns with a non-zero status. A SCSI Request Completed Without Error (01h) status indicates that the remaining fields are valid. An Invalid Host Adapter Number (81h) status indicates that the specified host adapter is not -installed. This function is used to get information on the installed host adapter hardware, -including number of host adapters installed. It can be issued once with host adapter zero specified to get the number of host adapters. If further information is desired, it can be issued for each individual host adapter. The SCSI Request Flags field is currently undefined for this command and should be zeroed. The SCSI Manager ID field contains a 16-byte ASCII string describing the SCSI -manager. The Host Adapter ID field contains a 16-byte ASCII string describing the SCSI host adapter. The definition of the Host Adapter Unique Parameters field is left to -implementation notes specific to a particular host adapter. ASPI Command Code = 1: Get Device Type Offset # Bytes Description R/W* 00h (00) 01h (01) Command Code = 1 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 — 08h (08) 01h (01) Target ID W 09h (09) 01h (01) LUN W 0Ah (10) 01h (01) Peripheral Device Type of Target/LUN R *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (—). This command always returns with non-zero status. A SCSI Request Completed Without Error (01h) status indicates that the specified -device is installed and the peripheral device type field is valid. A SCSI Device Not -Installed Error (82h) indicates that the peripheral device type field is not valid. This command is intended for use by various drivers, during initialization, for identifying the targets that they need to support. A CD-ROM driver, for example, can scan each Target/LUN on each installed host adapter looking for the device type corresponding to CD-ROM devices. This eliminates the need for each driver to duplicate the effort of scanning the SCSI bus for devices. The peripheral device type is determined by sending a SCSI Inquiry command to the given target. Refer to any SCSI specification to learn more about the Inquiry -command. The SCSI Request Flags field is currently undefined for this command and should be zeroed. ASPI Command Code = 2: Execute SCSI I/O Command Offset # Bytes Description R/W* 00h (00) 01h (01) Command Code = 2 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 W 08h (08) 01h (01) Target ID — 09h (09) 01h (01) LUN W 0Ah (10) 04h (04) Data Allocation Length W 0Eh (14) 01h (01) Sense Allocation Length (N) W 0Fh (15) 04h (04) Data Buffer Pointer W 13h (19) 04h (04) SRB Link Pointer W 17h (23) 01h (01) SCSI CDB Length (M) W 18h (24) 01h (01) Host Adapter Status R 19h (25) 01h (01) Target Status R 1Ah (26) 04h (04) Post Routine Address W 1Eh (30) 22h (34) Reserved for ASPI Workspace — 40h (64) M SCSI Command Descriptor Block (CDB) W 40h+M N Sense Allocation Area R *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (—). This command usually returns with zero status indicating that the request was queued successfully. Command completion can be determined by polling for non-zero status or through the use of the Post Routine Address field (discussed later). Keep in mind that if you are going to use polling, interrupts must be enabled. The SCSI Request Flags byte is defined as follows: 7 6 5 4 3 2 1 0 Rsvd Rsvd Rsvd Direction Bits Rsvd Link Post The Post bit specifies whether posting is enabled (bit 0 = 1) or disabled (bit 0 = 0). The Link bit specifies whether linking is enabled (bit 1 = 1) or disabled (bit 1 = 0). The Direction Bits specify which direction the transfer is: 00 - Direction determined by SCSI command. Length not checked. 01 - Transfer from SCSI target to host. Length checked. 10 - Transfer from host to SCSI target. Length checked. 11 - No data transfer. The Target ID and LUN fields are used to specify the peripheral device involved in the I/O. The Data Allocation Length field indicates the number of bytes to be transferred. If the SCSI command to be executed does not transfer data (i.e., Rewind, Start Unit, etc.) the Data Allocation Length must be set to zero. The Sense Allocation Length field indicates, in bytes, the number of bytes -allocated at the end of the SRB for sense data. A request sense is automatically -generated if a check condition is presented at the end of a SCSI command. The Data Buffer Pointer field is a pointer to the I/O data buffer. You place the -logical address here. ASPI will convert it to the physical address in the case of a bus master or DMA transfer. The SRB Link Pointer field is a pointer to the next SRB in a chain. See the -discussion on linking for more information. The SCSI CDB Length field establishes the length, in bytes, of the SCSI Command Descriptor Block (CDB). The Host Adapter Status field is used to report the host adapter status as follows: 00h - Host adapter did not detect any error 11h - Selection timeout 12h - Data overrun/underrun 13h - Unexpected bus free 14h - Target bus phase sequence failure The Target Status field is used to report the target's SCSI status, including: 00h - No target status 02h - Check status (sense data is in sense allocation area) 08h - Specified target/LUN is busy 18h - Reservation conflict The POST Routine Address field, if specified, is called when the I/O is completed. See the discussion on posting for more information. The SCSI Command Descriptor Block (CDB) field contains the CDB as defined by the target's SCSI command set. The length of the SCSI CDB is specified in the SCSI - Command Length field. The Sense Allocation Area is filled with sense data on a check condition. The maximum length of this field is specified in the Sense Allocation Length field. Note that the target can return fewer than the number of sense bytes requested. SCSI Command Linking With ASPI ASPI provides the ability to use SCSI linking to guarantee the sequential execution of several commands. Note that the use of this feature requires the involved target(s) to support SCSI linking. To use SCSI linking, a chain of SRBs is built with the SRB link pointer used to link the elements together. The link bit should be set in the SCSI request flags byte of all SRBs except the last in the chain. When a SCSI target returns indicating that the linked command is complete, the next SRB is immediately processed, and the appropriate CDB is dispatched. When using SCSI linking, make sure that the linking flags in the SCSI CDB agree with the link bit in the SCSI request flags. Inconsistencies can cause unpredictable results. For example, setting the CDB up for linking but -failing to set the link bit may result in a random address being used for the next SRB pointer. Any error returned from the target on a linked command will break the chain. Note that if linking without tags is used, as defined in SCSI, posting may not occur on any -elements in the chain until the chain is complete. If you have the post bit set in each SRB's SCSI request flags byte, then each SRB's post routine will be called. Note: It is strongly recommended that you do not use SCSI linking. There are many SCSI targets, as well as SCSI host adapters, which do not handle SCSI linking and will not work with your ASPI module. ASPI Command Posting To use Posting, the Post bit must be set in the SCSI request flags. Posting refers to the SCSI manager making a call to a post routine as specified in the SRB. The post routine is called to indicate that the SRB is complete. The specific SRB completed is indicated by a four-byte SRB pointer on the stack. If your post routine is written in assembly language, it must save the C registers: EBP, EBX, ESI, and EDI. Below is a sample ASPI post handler: ASPI_Post proc near CPush ;Push 'C' required regs mov eax, [esp+20] ;EAX points to SRB . . ;Handle posted SRB . CPop ;Restore registers and ret ; return to ASPI ASPI_Post endp C Example void ASPI_Post ( SRB_Pointer ) void *SRB_Pointer; { . . /* Handle posted SRB */ . } Note: On entry, interrupts will be disabled. You should return with interrupts disabled. You may issue any ASPI command from within your post routine except for an abort command! Your post routing should get in and out as quickly as possible. ASPI Command Code = 3: Abort SCSI I/O Command Offset # Bytes Description R/W* 00h (00) 01h (01) Command Code = 3 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 — 08h (08) 04h (04) SRB Pointer to Abort W *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (—). This command is used to request that an SRB be aborted. It should be issued on any I/O request that has not completed if the driver wishes to timeout on that request. -Success of the Abort command is never assured. This command always returns with SCSI Request Completed Without Error (01h), but the actual failure or success of the abort operation is indicated by the status -eventually returned in the SRB specified! The SCSI Request Flags field is currently undefined for this command and should be zeroed. The SRB Pointer to Abort field contains a pointer to the SRB which is to be aborted. Note: An abort command should not be issued during a post routine. ASPI Command Code = 4: Reset SCSI Device Offset # Bytes Description R/W* 00h (00) 01h (01) Command Code = 4 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 — 08h (08) 01h (01) Target ID W 09h (09) 01h (01) LUN W 0Ah (10) 0Eh (14) Reserved — 18h (24) 01h (01) Host Adapter Status R 19h (25) 01h (01) Target Status R 1Ah (26) 02h (02) POST Routine Address W 1Eh (30) 02h (02) Reserved for ASPI Workspace — *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (—). This command is used to reset a specific SCSI target. Note that the structure passed is nearly identical to the execute SCSI I/O SRB except that some of the fields are not used. This command usually returns with zero status indicating that the request was queued successfully. Command completion can be determined by polling for non-zero status or through the use of posting. The SCSI Request Flags byte is defined as follows: 7 6 5 4 3 2 1 0 Reserved Post The Post bit specifies whether posting is enabled (bit 0 = 1) or disabled (bit 0 = 0). ASPI Command Code = 5: Set Host Adapter Parameters Offset # Bytes Description R/W* 00h (00) 01h (01) Command Code = 5 W 01h (01) 01h (01) Status R 02h (02) 01h (01) Host Adapter Number W 03h (03) 01h (01) SCSI Request Flags W 04h (04) 04h (04) Reserved for Expansion = 0 — 08h (08) 10h (16) Host Adapter Unique Parameters W *The R/W column indicates whether the field is sent to ASPI (W), returned from ASPI (R), or reserved (—). The definition of the host adapter unique parameters is left to implementation notes specific to a particular host adapter. Miscellaneous This section discusses running ASPI in file servers with more than 16 MBytes of RAM and NetWare 386's Scan for New Devices routine. Handling Greater Than 16 MBytes Bus Master ISA SCSI host adapters have a restriction in that they cannot DMA above 16 MBytes of RAM. This is because the ISA bus only receives 24 bits of the -address bus (224 = 16 MBytes). Thus, if you pass a buffer pointer above 16 MBytes to an ASPI -manager/hardware that cannot handle it, you will most likely crash the file server. For these host adapters, you must make sure that both the ASPI SRBs and data buffers are below the first 16 MBytes of RAM. Adaptec's current host adapters handle this -situation as detailed below: Host Adapter - Handling > 16 MBytes AHA-1510 AHA-1520 AHA-1522 AIC-6260 AIC-6360 PIO or 2nd-party DMA, Host Transfers When in PIO mode, there is no restriction. When in Second-Party DMA mode, all ASPI SRBs and all data buffers must be below the first 16 MBytes of RAM. AHA-1540 AHA-1542 Bus Mastering ISA Mode, Host Transfers All ASPI SRBs and all data buffers must be below the first 16 MBytes of RAM. AHA-1640 AHA-1740 (Standard Mode) AHA-1740 (Enhanced Mode) AHA-2740 Series EISA Mode, Host Transfers No restrictions. The AHA-1740 in Enhanced Mode and the AHA-2740 Series Host Adapters can directly access up to 4 GBytes of RAM. For the AHA-1540/1542/1640/1740 (Standard Mode), you will need to run with an ASPI manager which can run with more than 16 MBytes of RAM. You will need aha1540.dsk v2.22 or later, or aha1640.dsk v2.22 or later for this. NetWare 386 v3.11 (and above) has defined some new routines you can use to force a buffer allocation below the first 16 MBytes of RAM. Refer to the NetWare 386 -Technical Specification for more information. Scanning For New Devices Most ASPI managers will not immediately scan the SCSI bus when first loaded. Rather, ASPI managers will wait for NetWare 386 to call its Scan for New Devices routine before the ASPI manager will scan the bus and update its internal ASPI device table. There may be some cases where you use ASPI's Get Device Type routine and your device does not appear although it is really there. In this case, you may want to request -NetWare Force A Scan For New Devices, or you may want to scan the SCSI bus from within your own ASPI module. Again, please refer to the appropriate NetWare 386 -Technical Specification for more information.