1、American National StandardDeveloped byfor Information Technology Fibre Channel HBA API(FC-HBA)ANSI INCITS 386-2004ANSIINCITS386-2004Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo reproduction or networking permitted without license from IHS-,-
2、,-ANSIINCITS 386-2004American National Standardfor Information Technology Fibre Channel HBA API (FC-HBA)SecretariatInformation Technology Industry CouncilApproved August 3, 2004American National Standards Institute, Inc.AbstractA standard Application Programming Interface (API) defines a scope withi
3、n which, and a grammar bywhich, it is possible to write application software without attention to vendor-specific infrastructurebehavior. This standard defines a standard Application Programming Interface the scope of which ismanagement of Fibre Channel Host Bus Adapters (HBAs) and use of certain Fi
4、bre 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 families of standards.Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo repro
5、duction or networking permitted without license from IHS-,-,-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 t
6、he ANSI Board ofStandards Review, substantial 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 effor
7、t be madetowards their resolution.The use 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
8、to the standards.The American National Standards 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 t
9、he AmericanNational Standards Institute. 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
10、StandardsInstitute require that action be 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 byA
11、merican National Standards Institute, Inc.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 permissio
12、n of ITI, 1250 Eye Street NW, Washington, 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
13、 nor the publisher have undertaken a patent 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 hav
14、e been made. No further patent search is 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.Copyright American National Standards Institute Provided by
15、IHS under license with ANSINot for ResaleNo reproduction or networking permitted without license from IHS-,-,-iContentsPageFroeword.xviIntroduction xxii1 Scope 12 Normative References. . 32.1 Normative references. . 32.2 Approved references. 32.3 References under development. . 32.4 IETF references.
16、 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 Procedures and Functions. 124 General Constraints. . 134.1 Software Structure. 134.2 C lang
17、uage. . 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 structure. 165.3 Names, Handles and Their Usage. . 175.4 HBA Configuration Rediscovery Effect on t
18、he 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 Status Return Values. 206.3 HBA Attributes. 236.3.1 HBA Attribute Data Declarations 236.3.2 HBA
19、 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. 24Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo reproduction or networking permit
20、ted without license from IHS-,-,-Pageii6.3.2.7 NodeSymbolicName. 246.3.2.8 HardwareVersion. 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 Attr
21、ibute Data Declarations 256.4.1.1 Port Type . 256.4.1.2 Port State. 256.4.1.3 Port 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 27
22、6.4.2.5 PortFcId . 276.4.2.6 PortType 276.4.2.7 PortState 286.4.2.8 PortSupportedClassofService . 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
23、 296.4.2.16 FabricName . 296.5 End Port Statistics. 306.5.1 End Port Statistics 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
24、 316.5.2.8 NOSCount . 316.5.2.9 ErrorFrames 316.5.2.10 DumpedFrames. 316.5.2.11 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 Output
25、Requests. 32Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo reproduction or networking permitted without license from IHS-,-,-Pageiii6.5.2.19 ControlRequests 326.5.2.20 InputMegabytes . 326.5.2.21 OutputMegabytes 326.6 FCP_Port Attributes (see
26、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 Mapping and Persistent Binding Attribute Specifications
27、 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.6.2.12 ScsiBusNumber. 376.6.2.13 ScsiTargetNumber
28、. 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_WWNN 386.6.3.4 Persistent Binding Capability: HBA_CAN
29、_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_BIND_CONFIGURED . 396.6.4 Persistent Binding Sett
30、ing 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 Type: HBA_BIND_TARGETS 406.7 SB Attributes 406.7.1
31、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 ControlUnitQueuingTime . 426.7.2.8 DeviceActiveOnlyTi
32、me 426.8 FC-3 Management Attributes. . 42Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo reproduction or networking permitted without license from IHS-,-,-Pageiv6.8.1 FC-3 Management Data Declarations 426.8.2 FC-3 Management Attribute Overview
33、. 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 PortId . 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. 4
34、46.9.1 Polled Event Data Declarations 446.9.1.1 Polled Event Codes. 446.9.1.2 Polled Event Data Structure Declarations . 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 Ca
35、llback Handle 446.10.1.2 HBA Add Category Event Type . 456.10.1.3 HBA Category Event Types. 456.10.1.4 Port Category Event 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 Speci
36、fications . 466.10.2.1 EventType . 466.11 Library Attributes. 466.11.1 Library Attribute Data Declarations. 466.11.2 Library 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 Ove
37、rview 557.2 Library Control Functions. . 577.2.1 HBA_GetVersion 577.2.1.1 Format . 577.2.1.2 Description. 577.2.1.3 Arguments . 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
38、Format . 58Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo reproduction or networking permitted without license from IHS-,-,-Pagev7.2.3.2 Description. 597.2.3.3 Arguments . 597.2.3.4 Return Values 597.2.4 HBA_RegisterLibrary 597.2.4.1 Format .
39、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 . 617.2.6
40、.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_RefreshInformation 63
41、7.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. 657.3 HB
42、A 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 . 677.3.3
43、.1 Format . 67Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo reproduction or networking permitted without license from IHS-,-,-Pagevi7.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 .
44、 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 Arguments . 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
45、.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_GetPortAttributesByWWN . 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
46、 . 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 Description. 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 .
47、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 . 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 Va
48、lues 79Copyright American National Standards Institute Provided by IHS under license with ANSINot for ResaleNo reproduction or networking permitted without license from IHS-,-,-Pagevii7.4.4 HBA_GetFcpTargetMapping 797.4.4.1 Format . 797.4.4.2 Description. 797.4.4.3 Arguments . 797.4.4.4 Return Value
49、s 807.4.5 HBA_GetFcpTargetMappingV2 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.7.3 Arguments . 837.4.7.4 Return Values 847.4.8 HBA_SetPersistent
