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.
