Advanced SCSI Programming Interface

November6,20011AdaptecAdvancedSCSIProgrammingInterfaceASPIforWin32TechnicalReferenceNovember6,2001åNovember6,20012AdaptecCopyrightCopyright©1989-2001Adaptec,Inc.Allrightsreserved.Nopartofthispublicationmaybereproduced,storedinaretrievalsystem,ortransmittedinanyformorbyanymeans,electronic,mechanical,photocopying,recordingorotherwise,withoutthepriorwrittenconsentofAdaptec,Inc.,691SouthMilpitasBlvd.,Milpitas,CA95035.TrademarksAdaptec,theAdapteclogo,andAHAaretrademarksofAdaptec,Inc.whichmayberegisteredinsomejurisdictions.Allothertrademarksareownedbytheirrespectiveowners.ChangesThematerialinthisdocumentisforinformationonlyandissubjecttochangewithoutnotice.Whilereasonableeffortshavebeenmadeinthepreparationofthisdocumenttoassureitsaccuracy,Adaptec,Inc.assumesnoliabilityresultingfromerrorsoromissionsinthisdocument,orfromtheuseoftheinformationcontainedherein.Adaptecreservestherighttomakechangesintheproductdesignwithoutreservationandwithoutnotificationtoitsusers.AdaptecWarranties,TechnicalSupportandServicesTHEADAPTECSOFTWAREISPROVIDEDASIS.THEREARENOWARRANTIESANDADAPTECEXPRESSLYDISCLAIMSANYIMPLIEDWARRANTYOFMERCHANTABILITYORFITNESSFORPARTICULARPURPOSE.Adaptechasnoobligationtoprovideanymodifications,improvements,updates,trainingorsupportrelatingtotheAdaptecSoftware.Anysuchmatters,ifapplicable,shallbesubjecttomutualwrittenagreementbetweentheparties.Forlicensinginformation,pleasecontactAdaptec'sDianeMcGeeat(408)[e-mail]6,20013AdaptecASPIforWin32OverviewThearchitectureofSCSImakesitpossibletoaccessawidevarietyofdevicesusingasinglebuslinkedtoahostcomputerwithaSCSIhostadapter.SupportforperipheraldevicesinWindows(98,ME,NT,2000andWindowsXP(32-bit))isnormallyachievedthroughdevicespecificdriverslayeredontopoftheoperatingsystems’nativeSCSIsupport.BecauseofthetremendousdiversityofSCSIdevices,nodrivercansupportallSCSIperipherals.Instead,separatedriversareneededforeachmajorclassofinstalledSCSIdevice.Thesedriverssharethehostadapterhardwarethroughtheoperatingsystems’nativeSCSIsupport.ThenativeSCSIlayersaredifferentbetweenWindows98/MEandWindowsNT/2000/XP(32-bit).Inaddition,developmentanddebuggingofVxDsorkernelmodedriverscanbeverydifficult.TheneedforastandardSCSIprogramminginterfacetosimplifySCSIapplicationdevelopmentandeasetheportingofSCSIapplicationsfromoneWin32platformtoanotherbroughtASPIforWin32intoexistence.TheAdvancedSCSIProgrammingInterface(ASPI)forWin32wasdesignedtoincreasecompatibilityandsimplifytheconnectionofSCSIperipheraldevicesliketape,CD-ROM,WORM,magneto-optical,scanners,andotherdevices.ItdefinesaprotocolforSCSIapplications(calledASPImodules)tosubmitI/Orequeststoasingleoperatingsystemdriver(calledtheASPImanager).AccesstotheoperatingsystemdriverismadethroughaDynamicLinkLibrarynamedWNASPI32.DLL.BeforeBeginningBeforeyoubeginyourASPIforWin32developmenteffort,besurethatyouhaveasolidunderstandingoftheSCSIspecifications.MuchofyoursuccessindevelopinganASPImoduleisdependentonyourunderstandingofthesespecifications.Herearesourcesforthespecifications:SCSI-1andCCS:AmericanNationalStandardsInstitute25West43rdStreet,4thFl.NY,NY10036Phone:[phone]Fax:[phone]SCSI-2andSCSI-3:GlobalEngineeringDocumentsWorldHeadquarters15IvernessWayEastEnglewood,CO80112-5776Phone:[phone]Phone:[phone]Fax:[phone]:[phone]Inaddition,itishighlyrecommendedthatyouacquirethetechnicalreferencemanualsforanySCSIhardwarewhichyourASPImoduleintendstosupport.Thesemanualscanbeobtainedfromthehardwaremanufacturer,andtheyprovidedetailedinformationonwhichSCSIcommandsaresupportedandhowtheyareimplemented.November6,20014AdaptecProgrammingConventionsThisspecificationcontainsfunctionprototypesandstructuredefinitionswiththefollowingdatatypes:TypeSize(Bytes)DescriptionVOIDN/AIndicateslackofareturnvalueorlackoffunctionarguments.BYTE1Unsigned8-bitvalue.WORD2Unsigned16-bitvalue.DWORD4Unsigned32-bitvalue.LPVOID4Genericpointer.UsedinSRBfieldswhichrequireeitherapointertoafunctionoraWin32handle(forexample,SRB_PostProc).LPBYTE4PointertoanarrayofBYTEs.Mainlyusedasabufferpointer.LPSRB4GenericpointertooneoftheSRB_*structuresdefinedbelow.Unlessotherwisenoted,allmultibytefieldsfollowIntel'sbyteorderoflowbytefirstandendwiththehighbyte.Forexample,ifthereisa2-byteoffsetfield,thefirstbyteisthelowbyteoftheoffsetwhilethesecondbyteisthehighbyteoftheoffset.Allstructurefieldsmarkedreservedmustbesettozero,andstructuresmustbepacked!Packedmeansthatbytealignmentisusedonallstructuredefinitions.Microsoftcompilersallowbytepackingtobesetthroughtheuseof“#pragmapack(1)”whileBorlandcompilersallowpackingtobesetwith“#pragmaoption-a1”.Seeyourcompilerdocumentationformoreinformation.Failuretopackstructuresandzeroreservedfieldscancausesysteminstability,includingcrashes.AllASPIforWin32functionsareexportedfromWNASPI32.DLLusingthe‘C’callingconvention(specifically,__cdeclasimplementedbyMicrosoft’scompilers).Withthe‘C’callingconventionthecallerpushesthelastfunctionargumentonthestackfirst(thefirstargumenthasthelowestmemoryaddress),and