ANSI INCITS386-2004 Information technology - Fibre Channel HBA API (FC-HBA)《信息技术.光纤信道HBA API (FC-HBA)》.pdf

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