ANSI INCITS412-2006 Information technology - SNIA Multipath Management API Specification《信息技术.SNIA多路径管理API规范》.pdf

1、American National StandardDeveloped byfor Information Technology SNIA Multipath Management APISpecificationANSI INCITS 412-2006ANSIINCITS412-2006Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without licen

2、se from IHS-,-,-Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-ANSIINCITS 412-2006American National Standardfor Information Technology SNIA Multipath ManagementAPI Specificatio

3、nSecretariatInformation Technology Industry CouncilApproved August 14, 2006American National Standards Institute, Inc.Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-Approval of

4、 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, substantial agreement has been reached

5、 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 use of American National Standards

6、 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 Standards Institute does not deve

7、lop 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. Requests for interpretations sh

8、ould 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 be taken periodically to reaffirm

9、, 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, Inc.25 West 43rd Street, New York,

10、 NY 10036Copyright 2006 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, DC 20005. Printed in the Unite

11、d 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 patent search in order to identifyw

12、hich, 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 conducted by the de-veloper or

13、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 IHS under license with ANSI Not for ResaleNo reproduction or networking

14、permitted without license from IHS-,-,-iContentsPageForeword vIntroduction vii1 Scope. 12 Normative references. 23 Definitions 34 Document Conventions 65 Background Technical Information 75.1 Overview 75.2 Client Discovery of Optional Behavior . 135.3 Events 175.4 API Programming Concepts 186 Consta

15、nts and Structures 206.1 MP_WCHAR 206.2 MP_CHAR . 206.3 MP_BYTE 206.4 MP_BOOL 206.5 MP_XBOOL . 206.6 MP_UINT32 . 206.7 MP_UINT64 . 206.8 MP_STATUS . 206.9 MP_PATH_STATE 216.10 MP_OBJECT_VISIBILITY_FN. 226.11 MP_OBJECT_PROPERTY_FN. 236.12 MP_OBJECT_TYPE 236.13 MP_OID . 246.14 MP_OID_LIST 256.15 MP_PO

16、RT_TRANSPORT_TYPE 256.16 MP_ACCESS_STATE_TYPE 266.17 MP_LOAD_BALANCE_TYPE 276.18 MP_PROPRIETARY_PROPERTY 286.19 MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES 286.20 MP_LOGICAL_UNIT_NAME_TYPE 296.21 MP_LIBRARY_PROPERTIES. 296.22 MP_AUTOFAILBACK_SUPPORT. 30Copyright American National Standards Institute Prov

17、ided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-iiPage6.23 MP_AUTOPROBING_SUPPORT . 316.24 MP_PLUGIN_PROPERTIES. 316.25 MP_DEVICE_PRODUCT_PROPERTIES . 346.26 MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES 346.27 MP_PATH_LOGICAL_UNIT_PROPER

18、TIES. 376.28 MP_INITIATOR_PORT_PROPERTIES 386.29 MP_TARGET_PORT_PROPERTIES 396.30 MP_TARGET_PORT_GROUP_PROPERTIES 396.31 MP_TPG_STATE_PAIR 407 APIs . 417.1 MP_AssignLogicalUnitToTPG . 437.2 MP_CancelOverridePath . 447.3 MP_CompareOIDs 457.4 MP_DeregisterForObjectPropertyChanges . 467.5 MP_Deregister

19、ForObjectVisibilityChanges 487.6 MP_DeregisterPlugin. 507.7 MP_DisableAutoFailback. 517.8 MP_DisableAutoProbing 527.9 MP_DisablePath 537.10 MP_EnableAutoFailback . 547.11 MP_EnableAutoProbing 557.12 MP_EnablePath. 567.13 MP_FreeOidList. 577.14 MP_GetAssociatedPathOidList . 587.15 MP_GetAssociatedPlu

20、ginOid 597.16 MP_GetAssociatedTPGOidList . 607.17 MP_GetDeviceProductOidList . 617.18 MP_GetDeviceProductProperties 627.19 MP_GetInitiatorPortOidList 637.20 MP_GetInitiatorPortProperties. 647.21 MP_GetLibraryProperties 657.22 MP_GetMPLuOidListFromTPG . 667.23 MP_GetMPLogicalUnitProperties 677.24 MP_

21、GetMultipathLus . 687.25 MP_GetObjectType . 69Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-iiiPage7.26 MP_GetPathLogicalUnitProperties 707.27 MP_GetPluginOidList. 717.28 MP_G

22、etPluginProperties 727.29 MP_GetProprietaryLoadBalanceOidList 737.30 MP_GetProprietaryLoadBalanceProperties . 747.31 MP_GetTargetPortGroupProperties. 757.32 MP_GetTargetPortOidList 767.33 MP_GetTargetPortProperties. 777.34 MP_RegisterForObjectPropertyChanges. 787.35 MP_RegisterForObjectVisibilityCha

23、nges . 807.36 MP_RegisterPlugin 827.37 MP_SetLogicalUnitLoadBalanceType 837.38 MP_SetOverridePath . 847.39 MP_SetPathWeight 857.40 MP_SetPluginLoadBalanceType . 867.41 MP_SetFailbackPollingRate. 877.42 MP_SetProbingPollingRate 887.43 MP_SetProprietaryProperties 897.44 MP_SetTPGAccess . 908 Implement

24、ation Compliance. 929 Implementation Notes 939.1 Backwards Compatibility 939.2 Client Usage Notes 939.3 Library Implementation Notes 939.4 Plugin Implementation Notes . 94Figures1 Asymmetric Array Example 82 API Instances Corresponding to Asymmetric Array Example 93 Relationship between Various Obje

25、cts in the Multipath World. 124 Driver Representation of a Logical Unit with Multiple Paths 135 APIs Relative to Objects from Figure 1 42Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from

26、IHS-,-,-ivPageAnnexesA Device Names . 95A.1 Initiator Port osDeviceName 95A.2 Logical Unit osDeviceName. 95B Synthesizing Target Port Groups. 96C Transport Layer Multipathing . 98D Coding Examples. 100D.1 Example of Getting Library Properties. 100D.2 Example of Getting Plugin Properties 100D.3 Examp

27、le of Discovering path LUs associated with an MP LU . 101E Library/Plugin API 103Copyright American National Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-vForeword (This foreword is not part of American

28、 National Standard ANSI INCITS 412-2006.)This standard documents an API that allows a management application to discoverthe multipath devices on the current system and to discover the associated local anddevice ports. An implementation of the API may optionally include active manage-ment (failover,

29、load balancing, manual path overrides). The API uses an architecturethat allows multiple MP drivers installed on a system to provide a common interfaceto clients of the library. The vendor implementations may support multipath driversbundled with an OS, or drivers associated with an HBA, target devi

30、ce, or volumemanager. This API can be used by host-based management applications and willalso be used in ANSI INCITS 388 for enterprise-wide multipath discovery and man-agement. A client of the API should be able to move between platforms by simply re-compiling.This standard includes five informativ

31、e annexes.Requests for interpretation, suggestions for improvement and addenda, or defect re-ports are welcome. They should be sent to the INCITS Secretariat, National Commit-tee for Information Technology Standards, Information Technology Institute, 1250Eye Street, NW, Suite 200, Washington, DC 200

32、05-3922. This standard was processed and approved for submittal to ANSI by the InterNation-al Committee for Information Technology Standards (INCITS). Committee approvalof the standard does not necessarily imply that all committee members voted for itsapproval. At the time it approved this standard,

33、 INCITS had the following members:Karen Higginbottom, ChairJennifer Garner, SecretaryOrganization Represented Name of RepresentativeAIM Global Dan MullenCharles Biss (Alt.)Apple Computer, Inc. David MichaelElectronic Industries Alliance Edward Mikoski, Jr.Henry Cuschieri (Alt.)EMC Corporation Gary R

34、obinsonFarance, Inc Frank FaranceGS1 US Frank SharkeyJames Chronowski (Alt.)Mary Wilson (Alt.)Hewlett-Packard Company. Karen HigginbottomSteve Mills (Alt.)Scott Jameson (Alt.)IBM Corporation . Ronald F. SillettiPeter Schirling (Alt.)IEEE . Judith GormanTerry DeCourcelle (Alt.)Jodi Haasz (Alt.)Bob La

35、belle (Alt.)Robert Pritchard (Alt.)Intel. Philip WennblomDave Thewlis (Alt.)Jesse Walker (Alt.)Grace Wei (Alt.)Lexmark International . Don WrightDwight Lewis (Alt.)Paul Menard (Alt.)Microsoft Corporation . Jim HughesDon Stanwyck (Alt.)Mike Ksar (Alt.)Isabelle Valet-Harper (Alt.)Copyright American Na

36、tional Standards Institute Provided by IHS under license with ANSI Not for ResaleNo reproduction or networking permitted without license from IHS-,-,-viOrganization Represented Name of RepresentativeNational Institute of Standards using #defines rather than enums helps assure client code is interope

37、rable across platforms and compilers especially if used in C+ applications. API Description Format Each APIs description is divided into seven subclauses. 1. Synopsis This subclause gives a brief description of what action the API performs. 2. Prototype This subclause gives a prototype of the functi

38、on in a format that is a combination of a C function prototype and an Interface Definition Language (IDL) prototype. The prototypes show the following: The name of the API The return type of the API Each of the parameters of the API, the type of each parameter, and whether that parameter is an input

39、 parameter, output parameter, or both an input and an output parameter. 3. Parameters This subclause lists each parameter along with an explanation of what the parameter represents. 4. Typical Return Values This subclause lists the Typical Return Values of the API with an explanation of why a partic

40、ular return value would be returned. It is important to note that this list is not a comprehensive list of all of the possible return values. There are certain errors, e.g. MP_STATUS_INSUFFICIENT_MEMORY, which might be returned by any API. 5. Remarks This subclause contains comments about the API th

41、at may be useful to the reader. In particular, this subclause contains extra information about the information returned by the API. 6. Support This subclause states that if an API is mandatory to be supported, optional to be supported, or mandatory to be supported under certain conditions. If an API

42、 is mandatory to be supported a client can rely on the API functioning under all circumstances. If the API is optional to be supported then a client cannot rely on the API functioning. If the API is mandatory to be supported under certain conditions then a client can rely on the API functioning if t

43、he specified conditions are met. Otherwise a client should assume that the API is not supported. 7. See Also This subclause lists other related APIs or related code examples that the reader might find useful. Copyright American National Standards Institute Provided by IHS under license with ANSI Not

44、 for ResaleNo reproduction or networking permitted without license from IHS-,-,-ANSI INCITS 412-2006 7 5 Background Technical Information 5.1 Overview Open system platforms give applications access to physical devices by presenting a special set of file names that represent the devices. Although end

45、 users typically dont use these special device files, knowledgeable applications (file systems, databases, backup software) operate on these device files and provide familiar user interfaces to storage. The device files have a hierarchical organization, either by using files and directories or by na

46、ming conventions. This hierarchy of device files (sometimes called a device tree) provides an effective interface for simpler, desktop device configurations. Inside open systems kernels, the hierarchy is exploited to allow different drivers to operate on different parts of the device tree. When the

47、OS discovers connected devices and builds the device tree, multiple paths to the same device may show up as separate device files in the device tree. Separate storage applications using device files that represent paths to the same device will overwrite each others data. As storage products (typical

48、ly disk arrays) strove for better reliability and performance, they added multipath support. For OSes that lacked multipath support, the device and logical volume manager vendors provided multipath drivers. Device standards lacked standard interfaces for identifying multipath devices; so multipath drivers are often limited to specific device products. Recently standards have been defined and OS vendors have started integrating multipath support in their bundled drivers. These drivers create special device files that represent multipath devices. Storage applications like file syst