ANSI INCITS 428-2007 for Information technology - Storage Management Host Bus Adapter Application Programming Interface (SM-HBA).pdf

1、American National StandardDeveloped byfor Information Technology Storage Management Host Bus AdapterApplication Programming Interface(SM-HBA)ANSI INCITS 428-2007ANSIINCITS428-2007ANSIINCITS 428-2007American National Standardfor Information Technology Storage ManagementHost Bus AdapterApplication Pro

2、gramming Interface(SM-HBA)SecretariatInformation Technology Industry CouncilApproved February 1, 2007 American National Standards Institute, Inc.AbstractA standard Application Programming Interface defines a scope within which and a grammar by which it ispossible to write application software withou

3、t attention to vendor-specific infrastructure behavior. Thisstandard defines a standard Application Programming Interface the scope of which is management ofFibre Channel and Serial Attached SCSI Host Bus Adapters and use of specific Fibre Channel and SerialAttached SCSI facilities for the discovery

4、 and management of the components of Fibre Channel StorageArea Network and Serial Attached SCSI domain. This standard is to be used in conjunction with the Fibre Channel, Serial Attached SCSI and SCSIfamilies of standards.Approval of an American National Standard requires review by ANSI that therequ

5、irements 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, substantial agreement has been reached by directly andmaterially affected interests. Substantial agreemen

6、t 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 use of American National Standards is completely voluntary; theirexistence does not in any respect pr

7、eclude 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 Standards Institute does not develop standards andwill in no circumstances give an interpretation of

8、 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. Requests for interpretations should beaddressed to the secretariat or sponsor whose name appears o

9、n 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 be taken periodically to reaffirm, revise, orwithdraw this standard. Purchasers of American National

10、 Standards mayreceive current information on all standards by calling or writing the AmericanNational Standards Institute.American National StandardPublished byAmerican National Standards Institute, Inc.25 West 43rd Street, New York, NY 10036Copyright 2007 by Information Technology Industry Council

11、(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, DC 20005. Printed in the United States of AmericaCAUTION: The developers of this standard have re

12、quested 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 patent search in order to identifywhich, if any, patents may apply to this standard. As of the date of

13、 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 conducted by the de-veloper or publisher in respect to any standard it processes. No representatio

14、n is made or impliedthat licenses are not required to avoid infringement in the use of this standard.iContentsPageForeword xxviiIntroduction xxxiii1 Scope. 12 Normative References . 32.1 Normative references. 32.2 Approved references 32.3 References under development. 42.4 IETF references . 42.5 Inf

15、iniBandtmTrade Organization references 42.6 Other references 43 Definitions, symbols, abbreviations, and conventions . 63.1 Definitions 63.2 Symbols and abbreviations 113.3 Keywords . 113.4 Conventions. 123.5 Notation for Procedures and Functions . 134 General Constraints. 144.1 Software Structure .

16、 144.2 Backwards Compatibility with FC-HBA 154.3 C language. 154.4 Operating System Dependencies 165 Software Structure and Behavior. 175.1 Overview 175.2 Software Structure . 175.2.1 OS specific structure 175.2.2 OS independent structure 175.3 Names, Handles and Their Usage. 185.4 HBA Configuration

17、 Rediscovery Effect on the API. . 195.4.1 Introduction . 195.4.2 HBA_STATUS_ERROR_STALE_DATA . 195.4.3 Semistatic table model. 205.5 Multiuse considerations. 206 Attributes and Data Structures. 216.1 Basic Attribute Types. 216.2 Status Return Values. 21iiPage6.3 SM-HBA Adapter Attributes. 246.3.1 Ge

18、neric Adapter Attribute 246.3.2 Generic Adapter Attribute Specifications . 246.3.2.1 Compliance 246.3.2.2 Manufacturer 246.3.2.3 SerialNumber. 246.3.2.4 Model . 256.3.2.5 ModelDescription . 256.3.2.6 HardwareVersion . 256.3.2.7 DriverVersion . 256.3.2.8 OptionROMVersion 256.3.2.9 FirmwareVersion 256

19、.3.2.10 VendorSpecificID . 256.3.2.11 DriverName 256.3.2.12 HBASymbolicName . 266.3.2.13 RedundantOptionROMVersion 266.3.2.14 RedundantFirmwareVersion 266.4 SM-HBA Port Attributes. . 266.4.1 Generic Port Attribute Data Declarations. 266.4.1.1 Port Type . 266.4.1.2 Port State. 276.4.2 Generic Port At

20、tributes 276.4.3 Generic Port Attribute Specifications . 276.4.3.1 Compliance 276.4.3.2 PortType 276.4.3.3 PortState 276.4.3.4 OSDeviceName . 276.4.3.5 PortSpecificAttribute 286.4.4 SMHBA FC Port Attribute Data Declarations. 286.4.4.1 Class of Service. 286.4.4.2 FC-4 Types 296.4.5 SMHBA FC Port Attr

21、ibutes 296.4.6 SMHBA FC Port Attribute Specifications . 296.4.6.1 Compliance 296.4.6.2 NodeWWN. 296.4.6.3 PortWWN. 296.4.6.4 FcId 296.4.6.5 PortSupportedClassofService 296.4.6.6 PortSupportedFc4Types 306.4.6.7 PortActiveFc4Types. 306.4.6.8 FabricName . 306.4.6.9 PortSymbolicName 306.4.6.10 NumberofD

22、iscoveredPorts. 306.4.6.11 NumberofPhys . 306.4.7 SMHBA SAS Port Attribute Data Declarations 316.4.7.1 HBA_SASPortProtocol 316.4.8 SMHBA SAS Port Attributes 316.4.9 SMHBA SAS Port Attribute Specifications. 316.4.9.1 Compliance 316.4.9.2 PortProtocol . 316.4.9.3 LocalSASAddress 31iiiPage6.4.9.4 Attac

23、hedSASAddress. 316.4.9.5 NumberofDiscoveredPorts . 316.4.9.6 NumberofPhys . 326.5 SM-HBA Phy Attributes 326.5.1 SM-HBA FC Phy Attribute Data Declaration 326.5.1.1 FC Phy Speed 326.5.1.2 SM-HBA FC Phy Type . 326.5.2 SM-HBA FC Phy Attributes 326.5.3 SM-HBA FC Phy Attribute Specifications. 326.5.3.1 Co

24、mpliance 326.5.3.2 PhySupportedSpeed 336.5.3.3 PhySpeed. 336.5.3.4 PhyType. 336.5.3.5 MaxFrameSize. 336.5.4 SM-HBA SAS PHY Attribute Data Declaration 336.5.5 SM-HBA SAS Phy Attribute . 336.5.6 SM-HBA SAS Phy Attribute Specifications 346.5.6.1 Compliance 346.5.6.2 PhyIdentifier . 346.5.6.3 Negotiated

25、LinkRate 346.5.6.4 ProgrammedMinLinkRate 346.5.6.5 HardwareMinLinkRate 346.5.6.6 ProgrammedMaxLinkRate . 346.5.6.7 HardwareMaxLinkRate. 346.5.6.8 domainPortWWN . 346.6 SM-HBA Statistics 346.6.1 SM-HBA Protocol Statistics 346.6.1.1 SM-HBA Protocol Statistics Data Declarations 346.6.1.2 SM-HBA Protoco

26、l Statistics Attribute Specifications 356.6.1.2.1 Compliance 356.6.1.2.2 SecondsSinceLastReset 356.6.1.2.3 InputRequests 356.6.1.2.4 OutputRequests . 356.6.1.2.5 ControlRequests 356.6.1.2.6 InputMegabytes 356.6.1.2.7 OutputMegabytes. 356.6.2 SM-HBA Phy Statistics. 366.6.2.1 SM-HBA Phy Statistics Dat

27、a Declaration. 366.6.2.2 SM-HBA SAS Phy Statistics Data Declaration. 366.6.2.3 SM-HBA SAS Phy Statistics Attribute Specifications. 366.6.2.3.1 Compliance 366.6.2.3.2 SecondsSinceLastReset 366.6.2.3.3 TxFrames. 366.6.2.3.4 TxWords. 366.6.2.3.5 RxFrames. 366.6.2.3.6 RxWords 376.6.2.3.7 InvalidDwordCou

28、nt. 376.6.2.3.8 RunningDisparityErrorCount 376.6.2.3.9 LossofDwordSynchronizationCount. 376.6.2.3.10 PhyResetProblemCount 376.6.2.4 SM-HBA FC Phy Statistics Data Declaration . 38ivPage6.6.2.5 SM-HBA FC Phy Statistics Attribute Specifications. 386.6.2.5.1 Compliance 386.6.2.5.2 SecondsSinceLastReset

29、386.6.2.5.3 TxFrames. 386.6.2.5.4 RxFrames 386.6.2.5.5 TxWords 386.6.2.5.6 RxWords 396.6.2.5.7 LIPCount 396.6.2.5.8 NOSCount . 396.6.2.5.9 ErrorFrames. 396.6.2.5.10 DumpedFrames 396.6.2.5.11 LinkFailureCount. 396.6.2.5.12 LossOfSyncCount . 396.6.2.5.13 LossOfSignalCount . 396.6.2.5.14 PrimitiveSeqPr

30、otocolErrCount 396.6.2.5.15 InvalidTxWordCount 396.6.2.5.16 Invalid CRC Count 406.7 SM-HBA Target Port Attributes 406.7.1 Target Port Attribute Data Declaration. 406.7.1.1 SMHBA_BIND_CAPABILITY. 406.7.1.2 SMHBA_BIND_TYPE 406.7.1.3 SMHBA_ScsiId 406.7.1.4 SMHBA_LUID 406.7.1.5 SMHBA_PORTLUN. 406.7.1.6

31、Composite types 416.7.2 Target Mapping and Persistent Binding Attribute Specifications 416.7.2.1 Overview 416.7.2.2 SMHBA_BIND_CAPABILITY. 416.7.2.3 SMHBA_BIND_TYPE 426.7.2.4 SMHBA_SCSIID 426.7.2.5 SMHBA_LUID 426.7.2.6 PortWWN. 426.7.2.7 domainPortWWN . 436.7.2.8 TargetLun 436.7.2.9 OSDeviceName . 4

32、36.7.2.10 ScsiBusNumber . 446.7.2.11 ScsiTargetNumber. 456.7.2.12 ScsiOSLun. 456.7.3 Persistent Binding Capabilities 456.7.3.1 Persistent Binding Capability: SMHBA_CAN_BIND_TO_WWPN 456.7.3.2 Persistent Binding Capability: SMHBA_CAN_BIND_TO_LUID456.7.3.3 Persistent Binding Capability: SMHBA_CAN_BIND_

33、ANY_LUNS 456.7.3.4 Persistent Binding Capability: SMHBA_CAN_ BIND_AUTOMAP 466.7.4 Persistent Binding Setting Types. 466.7.4.1 Persistent Binding Type: SMHBA_BIND_TO_WWPN. 466.7.4.2 Persistent Binding Type: SMHBA_BIND_TO_LUID 466.8 SM-HBA Asynchronous Event Notification Attributes 466.8.1 Asynchronou

34、s Event Data Declarations 466.8.1.1 Callback Handle. 466.8.1.2 HBA Add Category Event Type . 466.8.1.3 HBA Category Event Types. 47vPage6.8.1.4 Port Category Event Types 476.8.1.5 Port Statistics Category Event Types. 476.8.1.6 Phy Statistics Category Event Types. 476.8.1.7 Target Category Event Typ

35、es 476.8.1.8 Link Category Event Types 476.8.2 Asynchronous Event Attribute Specifications. 486.8.2.1 EventType 486.9 SM-HBA Library Attributes. 496.9.1 Library Attribute Data Declarations 496.9.2 SM-HBA Function Prototypes 496.9.3 SM-HBA Entry Point Data Declarations . 516.9.4 SM-HBA Entry Point Sp

36、ecifications . 526.9.5 SM-HBA Library Attribute Data Declarations . 526.9.6 SM-HBA Library Attribute Specifications 526.9.6.1 Compliance 526.9.6.2 LibPath. 526.9.6.3 VName . 536.9.6.4 VVersion. 536.9.6.5 build_date. 536.10 FC-HBA HBA Attributes. 536.10.1 HBA Attribute Data Declarations 536.10.2 HBA

37、Attribute Specifications 536.10.2.1 Compliance 536.10.2.2 Manufacturer 536.10.2.3 SerialNumber . 546.10.2.4 Model . 546.10.2.5 ModelDescription . 546.10.2.6 NodeWWN . 546.10.2.7 NodeSymbolicName 546.10.2.8 HardwareVersion . 546.10.2.9 DriverVersion . 546.10.2.10 OptionROMVersion 556.10.2.11 Firmware

38、Version 556.10.2.12 VendorSpecificID . 556.10.2.13 NumberOfPorts 556.10.2.14 DriverName 556.11 FC-HBA FC_Port Attributes. 556.11.1 FC_Port Attribute Data Declarations 556.11.1.1 Port Type 556.11.1.2 Port State . 566.11.1.3 Port Speed . 566.11.1.4 Class of Service . 566.11.1.5 FC-4 Types 566.11.1.6 F

39、C_Port Attributes 576.11.2 FC_Port Attribute Specifications 576.11.2.1 Compliance 576.11.2.2 NodeWWN . 576.11.2.3 PortWWN . 576.11.2.4 PortSymbolicName 576.11.2.5 PortFcId 57viPage6.11.2.6 PortType 576.11.2.7 PortState 586.11.2.8 PortSupportedClassofService 586.11.2.9 PortSupportedFc4Types 586.11.2.

40、10 PortActiveFc4Types. 586.11.2.11 PortSupportedSpeed . 586.11.2.12 PortSpeed 586.11.2.13 PortMaxFrameSize 586.11.2.14 OSDeviceName . 596.11.2.15 NumberofDiscoveredPorts. 596.11.2.16 FabricName . 596.12 FC-HBA End Port Statistics. . 606.12.1 End Port Statistics Data Declarations 606.12.2 End Port St

41、atistics Attribute Specifications 606.12.2.1 Compliance 606.12.2.2 SecondsSinceLastReset 606.12.2.3 TxFrames. 606.12.2.4 RxFrames 616.12.2.5 TxWords 616.12.2.6 RxWords 616.12.2.7 LIPCount 616.12.2.8 NOSCount . 616.12.2.9 ErrorFrames. 616.12.2.10 DumpedFrames . 616.12.2.11 LinkFailureCount 616.12.2.1

42、2 LossOfSyncCount 616.12.2.13 LossOfSignalCount 616.12.2.14 PrimitiveSeqProtocolErrCount . 616.12.2.15 InvalidTxWordCount 626.12.2.16 Invalid CRC Count . 626.12.2.17 InputRequests 626.12.2.18 OutputRequests. 626.12.2.19 ControlRequests 626.12.2.20 InputMegabytes . 626.12.2.21 OutputMegabytes 626.13

43、FC-HBA FCP_Port Attributes (see FCP-3) 626.13.1 FCP_Port Attribute Data Declarations . 626.13.1.1 HBA_FCPBINDINGTYPE 626.13.1.2 HBA_BIND_CAPABILITY 626.13.1.3 HBA_BIND_TYPE . 636.13.1.4 HBA_LUID . 636.13.1.5 HBA_ScsiId 636.13.1.6 HBA_FcpId 636.13.1.7 Composite types 636.13.2 Target Mapping and Persi

44、stent Binding Attribute Specifications 646.13.2.1 Overview 646.13.2.2 HBA_FCPBINDINGTYPE 656.13.2.3 HBA_BIND_CAPABILITY 656.13.2.4 HBA_BIND_TYPE . 656.13.2.5 HBA_LUID . 656.13.2.6 HBA_SCSIID . 65viiPage6.13.2.7 HBA_FCPID. 666.13.2.8 NodeWWN . 666.13.2.9 PortWWN . 666.13.2.10 FcId 666.13.2.11 FcpLun

45、. 666.13.2.12 OSDeviceName . 666.13.2.13 ScsiBusNumber . 676.13.2.14 ScsiTargetNumber . 686.13.2.15 ScsiOSLun . 686.13.3 Persistent Binding Capabilities. 686.13.3.1 Persistent Binding Capability: HBA_CAN_BIND_TO_D_ID. 686.13.3.2 Persistent Binding Capability: HBA_CAN_BIND_TO_WWPN . 686.13.3.3 Persis

46、tent Binding Capability: HBA_CAN_BIND_TO_WWNN. 686.13.3.4 Persistent Binding Capability: HBA_CAN_BIND_TO_LUID. 686.13.3.5 Persistent Binding Capability: HBA_CAN_BIND_ANY_LUNS. 686.13.3.6 Persistent Binding Capability: HBA_CAN_BIND_TARGETS. 696.13.3.7 Persistent Binding Capability: HBA_CAN_ BIND_AUTO

47、MAP . 696.13.3.8 Persistent Binding Capability: HBA_CAN_BIND_CONFIGURED 696.13.4 Persistent Binding Setting Types . 696.13.4.1 Persistent Binding Type: HBA_BIND_TO_D_ID 696.13.4.2 Persistent Binding Type: HBA_BIND_TO_WWPN 706.13.4.3 Persistent Binding Type: HBA_BIND_TO_WWNN 706.13.4.4 Persistent Bin

48、ding Type: HBA_BIND_TO_LUID 706.13.4.5 Persistent Binding Type: HBA_BIND_TARGETS 706.14 FC-HBA SB Attributes 706.14.1 SB Attribute Data Declarations 706.14.2 SB Statistics Attribute Specifications . 716.14.2.1 Compliance 716.14.2.2 SSCHRSCHCount . 716.14.2.3 SampleCount . 726.14.2.4 DeviceConnectTim

49、e. 726.14.2.5 FunctionPendingTime 726.14.2.6 DeviceDisconnectTime 726.14.2.7 ControlUnitQueuingTime 726.14.2.8 DeviceActiveOnlyTime. 726.15 FC-3 Management Attributes. 726.15.1 FC-3 Management Data Declarations 726.15.2 FC-3 Management Attribute Overview. 736.15.3 FC-3 Management Attribute Specifications 736.15.3.1 SM-HBA Compliance . 736.15.3.2 FC-HBA Compliance 736.15.3.3 WWN 736.15.3.4 unittype. 736.15.3.5 PortId 736.15.3.6 NumberOfAttachedNodes 736.15.3.7 IPVersion 736.15.3.8 UDPPort . 746.15.3.9 IPAddress. 746.15.3.10 TopologyDiscoveryFlags 746.16 FC-HBA Polled Event Notificat