ANSI INCITS 386-2004 Information Technology - Fibre Channel HBA API (FC-HBA).pdf

1、American National StandardDeveloped byfor Information Technology Fibre Channel HBA API(FC-HBA)ANSI INCITS 386-2004ANSIINCITS386-2004ANSIINCITS 386-2004American National Standardfor Information Technology Fibre Channel HBA API (FC-HBA)SecretariatInformation Technology Industry CouncilApproved August

2、3, 2004American National Standards Institute, Inc.AbstractA standard Application Programming Interface (API) defines a scope within which, and a grammar bywhich, it is possible to write application software without attention to vendor-specific infrastructurebehavior. This standard defines a standard

3、 Application Programming Interface the scope of which ismanagement of Fibre Channel Host Bus Adapters (HBAs) and use of certain Fibre Channel facilities fordiscovery and management of the components of a Fibre Channel Storage Area Network. This standardis to be used with the Fibre Channel and SCSI f

4、amilies of standards.Approval of an American National Standard requires review by ANSI that therequirements for due process, consensus, and other criteria for approval havebeen met by the standards developer.Consensus is established when, in the judgement of the ANSI Board ofStandards Review, substa

5、ntial agreement has been reached by directly andmaterially affected interests. Substantial agreement means much more thana simple majority, but not necessarily unanimity. Consensus requires that allviews and objections be considered, and that a concerted effort be madetowards their resolution.The us

6、e of American National Standards is completely voluntary; theirexistence does not in any respect preclude anyone, whether he has approvedthe standards or not, from manufacturing, marketing, purchasing, or usingproducts, processes, or procedures not conforming to the standards.The American National S

7、tandards Institute does not develop standards andwill in no circumstances give an interpretation of any American NationalStandard. Moreover, no person shall have the right or authority to issue aninterpretation of an American National Standard in the name of the AmericanNational Standards Institute.

8、 Requests for interpretations should beaddressed to the secretariat or sponsor whose name appears on the titlepage of this standard.CAUTION NOTICE: This American National Standard may be revised orwithdrawn at any time. The procedures of the American National StandardsInstitute require that action b

9、e taken periodically to reaffirm, revise, orwithdraw this standard. Purchasers of American National Standards mayreceive current information on all standards by calling or writing the AmericanNational Standards Institute.American National StandardPublished byAmerican National Standards Institute, In

10、c.25 West 43rd Street, New York, NY 10036Copyright 2004 by Information Technology Industry Council (ITI)All rights reserved.No part of this publication may be reproduced in anyform, in an electronic retrieval system or otherwise,without prior written permission of ITI, 1250 Eye Street NW, Washington

11、, DC 20005. Printed in the United States of AmericaCAUTION: The developers of this standard have requested that holders of patents that may berequired for the implementation of the standard disclose such patents to the publisher. However,neither the developers nor the publisher have undertaken a pat

12、ent search in order to identifywhich, if any, patents may apply to this standard. As of the date of publication of this standardand following calls for the identification of patents that may be required for the implementation ofthe standard, no such claims have been made. No further patent search is

13、 conducted by the de-veloper or publisher in respect to any standard it processes. No representation is made or impliedthat licenses are not required to avoid infringement in the use of this standard.iContentsPageFroeword.xviIntroduction xxii1 Scope 12 Normative References. . 32.1 Normative referenc

14、es. . 32.2 Approved references. 32.3 References under development. . 32.4 IETF references. 42.5 InfiniBandtmTrade Organization references 43 Definitions, symbols, abbreviations, and conventions. . 53.1 Definitions 53.2 Symbols and abbreviations. 93.3 Keywords. 103.4 Conventions. 113.5 Notation for P

15、rocedures and Functions. 124 General Constraints. . 134.1 Software Structure. 134.2 C language. . 144.3 Operating System Dependencies 154.4 FC-MI Common HBA API 155 Software Structure and Behavior. 165.1 Overview 165.2 Software Structure. 165.2.1 OS specific structure 165.2.2 OS independent structur

16、e. 165.3 Names, Handles and Their Usage. . 175.4 HBA Configuration Rediscovery Effect on the API. . 185.4.1 Introduction. 185.4.2 HBA_STATUS_ERROR_STALE_DATA 185.4.3 Semistatic table model . 195.5 Multiuse considerations. 196 Attributes and Data Structures. . 206.1 Basic Attribute Types. 206.2 Statu

17、s Return Values. 206.3 HBA Attributes. 236.3.1 HBA Attribute Data Declarations 236.3.2 HBA Attribute Specifications. 236.3.2.1 Compliance 236.3.2.2 Manufacturer . 236.3.2.3 SerialNumber. 236.3.2.4 Model. 236.3.2.5 ModelDescription. 246.3.2.6 NodeWWN. 24Pageii6.3.2.7 NodeSymbolicName. 246.3.2.8 Hardw

18、areVersion. 246.3.2.9 DriverVersion. 246.3.2.10 OptionROMVersion . 246.3.2.11 FirmwareVersion . 246.3.2.12 VendorSpecificID. 246.3.2.13 NumberOfPorts 256.3.2.14 DriverName . 256.4 FC_Port Attributes. 256.4.1 FC_Port Attribute Data Declarations 256.4.1.1 Port Type . 256.4.1.2 Port State. 256.4.1.3 Po

19、rt Speed. 266.4.1.4 Class of Service. 266.4.1.5 FC-4 Types 266.4.1.6 FC_Port Attributes . 266.4.2 FC_Port Attribute Specifications. 276.4.2.1 Compliance 276.4.2.2 NodeWWN. 276.4.2.3 PortWWN. 276.4.2.4 PortSymbolicName 276.4.2.5 PortFcId . 276.4.2.6 PortType 276.4.2.7 PortState 286.4.2.8 PortSupporte

20、dClassofService . 286.4.2.9 PortSupportedFc4Types 286.4.2.10 PortActiveFc4Types 286.4.2.11 PortSupportedSpeed . 286.4.2.12 PortSpeed 286.4.2.13 PortMaxFrameSize 286.4.2.14 OSDeviceName. 296.4.2.15 NumberofDiscoveredPorts 296.4.2.16 FabricName . 296.5 End Port Statistics. 306.5.1 End Port Statistics

21、Data Declarations. 306.5.2 End Port Statistics Attribute Specifications. 306.5.2.1 Compliance 306.5.2.2 SecondsSinceLastReset . 306.5.2.3 TxFrames 306.5.2.4 RxFrames 316.5.2.5 TxWords 316.5.2.6 RxWords 316.5.2.7 LIPCount 316.5.2.8 NOSCount . 316.5.2.9 ErrorFrames 316.5.2.10 DumpedFrames. 316.5.2.11

22、LinkFailureCount . 316.5.2.12 LossOfSyncCount 316.5.2.13 LossOfSignalCount 316.5.2.14 PrimitiveSeqProtocolErrCount. 316.5.2.15 InvalidTxWordCount 326.5.2.16 Invalid CRC Count. 326.5.2.17 InputRequests . 326.5.2.18 OutputRequests. 32Pageiii6.5.2.19 ControlRequests 326.5.2.20 InputMegabytes . 326.5.2.

23、21 OutputMegabytes 326.6 FCP_Port Attributes (see FCP-2). . 326.6.1 FCP_Port Attribute Data Declarations 326.6.1.1 HBA_FCPBINDINGTYPE 326.6.1.2 HBA_BIND_CAPABILITY 326.6.1.3 HBA_BIND_TYPE . 336.6.1.4 HBA_LUID . 336.6.1.5 HBA_ScsiId . 336.6.1.6 HBA_FcpId 336.6.1.7 Composite types 336.6.2 Target Mappi

24、ng and Persistent Binding Attribute Specifications 346.6.2.1 HBA_FCPBINDINGTYPE 346.6.2.2 HBA_BIND_CAPABILITY 356.6.2.3 HBA_BIND_TYPE . 356.6.2.4 HBA_LUID . 356.6.2.5 HBA_SCSIID . 356.6.2.6 HBA_FCPID 356.6.2.7 NodeWWN. 366.6.2.8 PortWWN. 366.6.2.9 FcId 366.6.2.10 FcpLun. 366.6.2.11 OSDeviceName. 366

25、.6.2.12 ScsiBusNumber. 376.6.2.13 ScsiTargetNumber. 376.6.2.14 ScsiOSLun. 376.6.3 Persistent Binding Capabilities . 386.6.3.1 Persistent Binding Capability: HBA_CAN_BIND_TO_D_ID 386.6.3.2 Persistent Binding Capability: HBA_CAN_BIND_TO_WWPN 386.6.3.3 Persistent Binding Capability: HBA_CAN_BIND_TO_WWN

26、N 386.6.3.4 Persistent Binding Capability: HBA_CAN_BIND_TO_LUID 386.6.3.5 Persistent Binding Capability: HBA_CAN_BIND_ANY_LUNS 386.6.3.6 Persistent Binding Capability: HBA_CAN_BIND_TARGETS 386.6.3.7 Persistent Binding Capability: HBA_CAN_ BIND_AUTOMAP 396.6.3.8 Persistent Binding Capability: HBA_CAN

27、_BIND_CONFIGURED . 396.6.4 Persistent Binding Setting Types 396.6.4.1 Persistent Binding Type: HBA_BIND_TO_D_ID . 396.6.4.2 Persistent Binding Type: HBA_BIND_TO_WWPN396.6.4.3 Persistent Binding Type: HBA_BIND_TO_WWNN396.6.4.4 Persistent Binding Type: HBA_BIND_TO_LUID . 396.6.4.5 Persistent Binding T

28、ype: HBA_BIND_TARGETS 406.7 SB Attributes 406.7.1 SB Attribute Data Declarations. 406.7.2 SB Statistics Attribute Specifications 416.7.2.1 Compliance 416.7.2.2 SSCHRSCHCount. 416.7.2.3 SampleCount. 416.7.2.4 DeviceConnectTime 416.7.2.5 FunctionPendingTime 416.7.2.6 DeviceDisconnectTime 416.7.2.7 Con

29、trolUnitQueuingTime . 426.7.2.8 DeviceActiveOnlyTime 426.8 FC-3 Management Attributes. . 42Pageiv6.8.1 FC-3 Management Data Declarations 426.8.2 FC-3 Management Attribute Overview . 426.8.3 FC-3 Management Attribute Specifications 426.8.3.1 Compliance 426.8.3.2 WWN . 426.8.3.3 unittype 436.8.3.4 Por

30、tId . 436.8.3.5 NumberOfAttachedNodes . 436.8.3.6 IPVersion . 436.8.3.7 UDPPort 436.8.3.8 IPAddress 436.8.3.9 TopologyDiscoveryFlags . 436.9 Polled Event Notification Attributes. 446.9.1 Polled Event Data Declarations 446.9.1.1 Polled Event Codes. 446.9.1.2 Polled Event Data Structure Declarations .

31、 446.9.2 Polled Event Attribute Specifications 446.9.2.1 EventCode. 446.10 Asynchronous Event Notification Attributes. 446.10.1 Asynchronous Event Data Declarations . 446.10.1.1 Callback Handle 446.10.1.2 HBA Add Category Event Type . 456.10.1.3 HBA Category Event Types. 456.10.1.4 Port Category Eve

32、nt Types . 456.10.1.5 Port Statistics Category Event Types 456.10.1.6 Target Category Event Types 456.10.1.7 Link Category Event Types . 456.10.2 Asynchronous Event Attribute Specifications . 466.10.2.1 EventType . 466.11 Library Attributes. 466.11.1 Library Attribute Data Declarations. 466.11.2 Lib

33、rary Attribute Specifications . 536.11.2.1 Compliance 536.11.2.2 Final. 536.11.2.3 LibPath 536.11.2.4 VName. 536.11.2.5 VVersion 536.11.2.6 build_date 547 Function Calls. 557.1 Overview 557.2 Library Control Functions. . 577.2.1 HBA_GetVersion 577.2.1.1 Format . 577.2.1.2 Description. 577.2.1.3 Argu

34、ments . 577.2.1.4 Return Values 577.2.2 HBA_LoadLibrary . 577.2.2.1 Format . 577.2.2.2 Description. 587.2.2.3 Arguments . 587.2.2.4 Return Values 587.2.3 HBA_FreeLibrary 587.2.3.1 Format . 58Pagev7.2.3.2 Description. 597.2.3.3 Arguments . 597.2.3.4 Return Values 597.2.4 HBA_RegisterLibrary 597.2.4.1

35、 Format . 597.2.4.2 Description. 597.2.4.3 Arguments . 597.2.4.4 Return Values 607.2.5 HBA_RegisterLibraryV2 . 607.2.5.1 Format . 607.2.5.2 Description. 607.2.5.3 Arguments . 607.2.5.4 Return Values 617.2.6 HBA_GetWrapperLibraryAttributes 617.2.6.1 Format . 617.2.6.2 Description. 617.2.6.3 Arguments

36、 . 617.2.6.4 Return Values 627.2.7 HBA_GetVendorLibraryAttributes. 627.2.7.1 Format . 627.2.7.2 Description. 627.2.7.3 Arguments . 627.2.7.4 Return Values 637.2.8 HBA_GetNumberOfAdapters . 637.2.8.1 Format . 637.2.8.2 Description. 637.2.8.3 Arguments . 637.2.8.4 Return Values 637.2.9 HBA_RefreshInfo

37、rmation 637.2.9.1 Format . 637.2.9.2 Description. 647.2.9.3 Arguments . 647.2.9.4 Return Values 647.2.10 HBA_RefreshAdapterConfiguration 647.2.10.1 Format . 647.2.10.2 Description. 647.2.10.3 Arguments . 657.2.10.4 Return Values 657.2.11 HBA_ResetStatistics 657.2.11.1 Format . 657.2.11.2 Description

38、. 657.3 HBA and Port Information Functions. 657.3.1 HBA_GetAdapterName 657.3.1.1 Format . 657.3.1.2 Description. 657.3.1.3 Arguments . 667.3.1.4 Return Values 667.3.2 HBA_OpenAdapter. 667.3.2.1 Format . 667.3.2.2 Description. 667.3.2.3 Arguments . 677.3.2.4 Return Values 677.3.3 HBA_OpenAdapterByWWN

39、 . 677.3.3.1 Format . 67Pagevi7.3.3.2 Description. 677.3.3.3 Arguments . 677.3.3.4 Return Values 687.3.4 HBA_CloseAdapter 687.3.4.1 Format . 687.3.4.2 Description. 687.3.4.3 Arguments . 687.3.4.4 Return Values 687.3.5 HBA_GetAdapterAttributes. 697.3.5.1 Format . 697.3.5.2 Description. 697.3.5.3 Argu

40、ments . 697.3.5.4 Return Values 697.3.6 HBA_GetAdapterPortAttributes 707.3.6.1 Format . 707.3.6.2 Description. 707.3.6.3 Arguments . 707.3.6.4 Return Values 707.3.7 HBA_GetDiscoveredPortAttributes. 717.3.7.1 Format . 717.3.7.2 Description. 717.3.7.3 Arguments . 717.3.7.4 Return Values 727.3.8 HBA_Ge

41、tPortAttributesByWWN . 727.3.8.1 Format . 727.3.8.2 Description. 737.3.8.3 Arguments . 737.3.8.4 Return Values 737.3.9 HBA_GetPortStatistics . 737.3.9.1 Format . 737.3.9.2 Description. 747.3.9.3 Arguments . 747.3.9.4 Return Values 747.3.10 HBA_GetFC4Statistics . 757.3.10.1 Format . 757.3.10.2 Descri

42、ption. 757.3.10.3 Arguments . 757.3.10.4 Return Values 757.4 FCP Information Functions 767.4.1 HBA_GetBindingCapability. 767.4.1.1 Format . 767.4.1.2 Description. 767.4.1.3 Arguments . 767.4.1.4 Return Values 767.4.2 HBA_GetBindingSupport 777.4.2.1 Format . 777.4.2.2 Description. 777.4.2.3 Arguments

43、 . 777.4.2.4 Return Values 777.4.3 HBA_SetBindingSupport 787.4.3.1 Format . 787.4.3.2 Description. 787.4.3.3 Arguments . 787.4.3.4 Return Values 79Pagevii7.4.4 HBA_GetFcpTargetMapping 797.4.4.1 Format . 797.4.4.2 Description. 797.4.4.3 Arguments . 797.4.4.4 Return Values 807.4.5 HBA_GetFcpTargetMapp

44、ingV2 807.4.5.1 Format . 807.4.5.2 Description. 807.4.5.3 Arguments . 817.4.5.4 Return Values 817.4.6 HBA_GetFcpPersistentBinding 827.4.6.1 Format . 827.4.6.2 Description. 827.4.6.3 Arguments . 827.4.6.4 Return Values 827.4.7 HBA_GetPersistentBindingV2 837.4.7.1 Format . 837.4.7.2 Description. 837.4

45、.7.3 Arguments . 837.4.7.4 Return Values 847.4.8 HBA_SetPersistentBindingV2 847.4.8.1 Format . 847.4.8.2 Description. 847.4.8.3 Arguments . 857.4.8.4 Return Values 857.4.9 HBA_RemovePersistentBinding. 857.4.9.1 Format . 857.4.9.2 Description. 867.4.9.3 Arguments . 867.4.9.4 Return Values 867.4.10 HB

46、A_RemoveAllPersistentBindings . 877.4.10.1 Format . 877.4.10.2 Description. 877.4.10.3 Arguments . 877.4.10.4 Return Values 877.4.11 HBA_GetFCPStatistics. 887.4.11.1 Format . 887.4.11.2 Description. 887.4.11.3 Arguments . 887.4.11.4 Return Values 887.5 SCSI Information Functions. 897.5.1 HBA_SendScs

47、iInquiry 897.5.1.1 Format . 897.5.1.2 Description. 897.5.1.3 Arguments . 897.5.1.4 Return Values 907.5.2 HBA_ScsiInquiryV2 907.5.2.1 Format . 907.5.2.2 Description. 917.5.2.3 Arguments . 917.5.2.4 Return Values 927.5.3 HBA_SendReportLUNs 937.5.3.1 Format . 937.5.3.2 Description. 93Pageviii7.5.3.3 Ar

48、guments . 937.5.3.4 Return Values 947.5.4 HBA_ScsiReportLunsV2 947.5.4.1 Format . 947.5.4.2 Description. 947.5.4.3 Arguments . 957.5.4.4 Return Values 967.5.5 HBA_SendReadCapacity . 977.5.5.1 Format . 977.5.5.2 Description. 977.5.5.3 Arguments . 977.5.5.4 Return Values 987.5.6 HBA_ScsiReadCapacityV2

49、 987.5.6.1 Format . 987.5.6.2 Description. 987.5.6.3 Arguments . 997.5.6.4 Return Values 1007.6 SB Information Functions. . 1017.6.1 HBA_GetSBTargetMapping . 1017.6.1.1 Format . 1017.6.1.2 Description. 1017.6.1.3 Arguments . 1017.6.1.4 Return Values 1017.6.2 HBA_GetSBStatistics . 1027.6.2.1 Format . 1027.6.2.2 Description. 1027.6.2.3 Arguments . 1027.6.2.4 Return Values 1027.7 SB Disk Device Information Functions. . 1037.7.1 HBA_SBDskGetCapacity . 1037.7.1.1 Format . 1037.7.1.2 Description. 1037.7.1.3 Arguments . 1037.7.1.4 Return Values 1047.8 Fabric Management Functions. . 1047.8.1 HBA