Advanced SCSI Programming Interface

SCSI BBS: (719) 574-0424 In addition, it is highly recommended that you acquire the technical reference manuals for any SCSI hardware which your ASPI module intends to support. These manuals can be obtained from the hardware manufacturer, and they provide detailed information on which SCSI commands are supported and how they are implemented. November 6, 2001 4 Adaptec Programming Conventions This specification contains function prototypes and structure definitions with the following data types: Type Size (Bytes) Description VOID N/A Indicates lack of a return value or lack of function arguments. BYTE 1 Unsigned 8-bit value. WORD 2 Unsigned 16-bit value. DWORD 4 Unsigned 32-bit value. LPVOID 4 Generic pointer. Used in SRB fields which require either a pointer to a function or a Win32 handle (for example, SRB PostProc). LPBYTE 4 Pointer to an array of BYTEs. Mainly used as a buffer pointer. LPSRB 4 Generic pointer to one of the SRB structures defined below. Unless otherwise noted, all multibyte fields follow Intel& 39;s byte order of low byte first and end with the high byte. For example, if there is a 2-byte offset field, the first byte is the low byte of the offset while the second byte is the high byte of the offset. All structure fields marked reserved must be set to zero, and structures must be packed! Packed means that byte alignment is used on all structure definitions. Microsoft compilers allow byte packing to be set through the use of “ pragma pack(1)” while Borland compilers allow packing to be set with “ pragma option -a1”. See your compiler documentation for more information. Failure to pack structures and zero reserved fields can cause system instability, including crashes. All ASPI for Win32 functions are exported from WNASPI32.DLL using the ‘C’ calling convention (specifically, cdecl as implemented by Microsoft’s compilers). With the ‘C’ calling convention the caller pushes the last function argument on the stack first (the first argument has the lowest memory address), and the caller is responsible for popping arguments from the stack. Programming Guidelines The following are some general guidelines to keep in mind while reading this specification and while writing ASPI for Win32 applications: ∑ If you are using explicit dynamic linking, remember that the ASPI for Win32 DLL is named WNASPI32.DLL and not WINASPI.DLL. Make sure to call LoadLibrary appropriately. ∑ ASPI for Win32 is fully re-entrant and permits overlapped, asynchronous I/O. ASPI modules can send additional ASPI requests while others are pending completion. Be sure to use separate SRBs for each ASPI request. ∑ For requests requiring data transfers, the direction bits in the SRB Flags field must be set correctly. Direction bits are no longer optional for data transfers. This means that SRB DIR SCSI is no longer a valid setting. For requests not requiring data transfers, the direction bits are ignored. ∑ Be sure that buffers are aligned according to the buffer alignment mask returned by the SC HA INQUIRY command. ∑ ASPI SCSI Request Blocks (SRBs) and data buffers do not need to be in page-locked memory. The ASPI manager takes care of locking buffers and SRBs. ∑ If an error SS BUFFER TOO BIG is returned by the SendASPI32Command routine, you should break the transfer down into multiple 64KByte transfers or less. Another alternative is to use the GetASPI32Buffer/FreeASPI32Buffer calls to allocate large transfer buffers. ∑ If you send an ASPI request with posting (callbacks) enabled, the post procedure will always be called. November 6, 2001 5 Adaptec ∑ The CDB area has been fixed in length at 16. Therefore, the sense data area no longer shifts location depending on command length as in ASPI for Win16. If you are developing an application targeted only at Win32, you no longer need to account for the “floating” sense buffer. ∑ When scanning for devices, the SendASPI32Command may also return the status SS NO DEVICE in the SRB Status field. Check for this e