ANSI INCITS 412-2006 for Information Technology C SNIA Multipath Management API Specification.pdf

1、American National StandardDeveloped byfor Information Technology SNIA Multipath Management APISpecificationANSI INCITS 412-2006ANSIINCITS412-2006ANSIINCITS 412-2006American National Standardfor Information Technology SNIA Multipath ManagementAPI SpecificationSecretariatInformation Technology Industr

2、y CouncilApproved August 14, 2006American National Standards Institute, Inc.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

3、 judgement of the 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

4、concerted effort 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

5、not conforming 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 i

6、n the name of the 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 Ame

7、rican National 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 Standa

8、rdPublished byAmerican National Standards Institute, Inc.25 West 43rd Street, New York, 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 wr

9、itten permission 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

10、 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 publication of this standardand following calls for the identification of patents that may be required for the implementation ofthe standard, no

11、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 representation is made or impliedthat licenses are not required to avoid infringement in the use of this standard.iContentsPageForeword vIntroduction vii1 Scop

12、e. 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 Constants and Structures 206.1 MP_WCHAR 206.2 MP_CHAR . 206.3 MP_BYTE 206.4 MP_BOOL 206.5

13、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_PORT_TRANSPORT_TYPE 256.16 MP_ACCESS_STATE_TYPE 266.17 MP_LOAD_BALANCE_TYPE 276.18 MP_

14、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. 30iiPage6.23 MP_AUTOPROBING_SUPPORT . 316.24 MP_PLUGIN_PROPERTIES. 316.25 MP_DEVICE_PRODUCT_PROPERTIES . 346.26 MP_MULTIPATH_LOGICAL_UNIT_

15、PROPERTIES 346.27 MP_PATH_LOGICAL_UNIT_PROPERTIES. 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_DeregisterF

16、orObjectPropertyChanges . 467.5 MP_DeregisterForObjectVisibilityChanges 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_GetAssoc

17、iatedPathOidList . 587.15 MP_GetAssociatedPluginOid 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 . 66

18、7.23 MP_GetMPLogicalUnitProperties 677.24 MP_GetMultipathLus . 687.25 MP_GetObjectType . 69iiiPage7.26 MP_GetPathLogicalUnitProperties 707.27 MP_GetPluginOidList. 717.28 MP_GetPluginProperties 727.29 MP_GetProprietaryLoadBalanceOidList 737.30 MP_GetProprietaryLoadBalanceProperties . 747.31 MP_GetTar

19、getPortGroupProperties. 757.32 MP_GetTargetPortOidList 767.33 MP_GetTargetPortProperties. 777.34 MP_RegisterForObjectPropertyChanges. 787.35 MP_RegisterForObjectVisibilityChanges . 807.36 MP_RegisterPlugin 827.37 MP_SetLogicalUnitLoadBalanceType 837.38 MP_SetOverridePath . 847.39 MP_SetPathWeight 85

20、7.40 MP_SetPluginLoadBalanceType . 867.41 MP_SetFailbackPollingRate. 877.42 MP_SetProbingPollingRate 887.43 MP_SetProprietaryProperties 897.44 MP_SetTPGAccess . 908 Implementation Compliance. 929 Implementation Notes 939.1 Backwards Compatibility 939.2 Client Usage Notes 939.3 Library Implementation

21、 Notes 939.4 Plugin Implementation Notes . 94Figures1 Asymmetric Array Example 82 API Instances Corresponding to Asymmetric Array Example 93 Relationship between Various Objects in the Multipath World. 124 Driver Representation of a Logical Unit with Multiple Paths 135 APIs Relative to Objects from

22、Figure 1 42ivPageAnnexesA 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 Ex

23、ample of Discovering path LUs associated with an MP LU . 101E Library/Plugin API 103vForeword (This foreword is not part of American 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

24、to discover the associated local anddevice ports. An implementation of the API may optionally include active manage-ment (failover, 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

25、 library. The vendor implementations may support multipath driversbundled with an OS, or drivers associated with an HBA, target device, 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

26、-agement. A client of the API should be able to move between platforms by simply re-compiling.This standard includes five informative annexes.Requests for interpretation, suggestions for improvement and addenda, or defect re-ports are welcome. They should be sent to the INCITS Secretariat, National

27、Commit-tee for Information Technology Standards, Information Technology Institute, 1250Eye Street, NW, Suite 200, Washington, DC 20005-3922. This standard was processed and approved for submittal to ANSI by the InterNation-al Committee for Information Technology Standards (INCITS). Committee approva

28、lof the standard does not necessarily imply that all committee members voted for itsapproval. At the time it approved this standard, INCITS had the following members:Karen Higginbottom, ChairJennifer Garner, SecretaryOrganization Represented Name of RepresentativeAIM Global Dan MullenCharles Biss (A

29、lt.)Apple Computer, Inc. David MichaelElectronic Industries Alliance Edward Mikoski, Jr.Henry Cuschieri (Alt.)EMC Corporation Gary RobinsonFarance, Inc Frank FaranceGS1 US Frank SharkeyJames Chronowski (Alt.)Mary Wilson (Alt.)Hewlett-Packard Company. Karen HigginbottomSteve Mills (Alt.)Scott Jameson

30、 (Alt.)IBM Corporation . Ronald F. SillettiPeter Schirling (Alt.)IEEE . Judith GormanTerry DeCourcelle (Alt.)Jodi Haasz (Alt.)Bob Labelle (Alt.)Robert Pritchard (Alt.)Intel. Philip WennblomDave Thewlis (Alt.)Jesse Walker (Alt.)Grace Wei (Alt.)Lexmark International . Don WrightDwight Lewis (Alt.)Paul

31、 Menard (Alt.)Microsoft Corporation . Jim HughesDon Stanwyck (Alt.)Mike Ksar (Alt.)Isabelle Valet-Harper (Alt.)viOrganization Represented Name of RepresentativeNational Institute of Standards using #defines rather than enums helps assure client code is interoperable across platforms and compilers es

32、pecially 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 function in a format that is a combination of

33、 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 parameter, output parameter, or both a

34、n 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 particular return value would be returned. It

35、 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 that may be useful to the reader. In part

36、icular, 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 is mandatory to be supported a client

37、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 the specified conditions are met. Otherw

38、ise 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. ANSI INCITS 412-2006 7 5 Background Technical Information 5.1 Overview Open system platforms give applications access to physical

39、devices by presenting a special set of file names that represent the devices. Although end 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 dev

40、ice files have a hierarchical organization, either by using files and directories or by naming 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 exploi

41、ted to allow different drivers to operate on different parts of the device tree. When the 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 repres

42、ent paths to the same device will overwrite each others data. As storage products (typically 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. Dev

43、ice 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

44、 files that represent multipath devices. Storage applications like file systems can use these multipath device files the same way they would use a single-path device file, but benefit from improved reliability and performance. In addition, the multipath drivers provide some management capabilities f

45、or example, failover or load balancing that only apply to multipath devices. This standard focuses on devices accesses through SCSI commands. SCSI commands are sent to a target device by an initiator. The target may consist of multiple logical units. For example, a RAID array exposes virtual disk as

46、 separate logical units. A target device supporting multiple paths and attached hosts will nearly always have multiple ports. Each permutation of initiator port, target port, and logical unit is commonly referred to as a path. With no multipath support in place, the OS would see each path as separat

47、e logical units. The function of multipath drivers is then to create a virtual multipath device the aggregates all these path logical units. 5.1.1 Target Port Groups A logical unit may only be accessible through certain target ports. If the device supports asymmetric access (see 5.1.2, Symmetric and

48、 Asymmetric Multipath Access), certain ports may be preferred for access (sometimes this is referred to as affinity. ANSI INCITS 408-2005 (SPC-3) has introduced Target Port Groups as a way for target devices to represent access characteristics for logical units. A target port group is a collection o

49、f ports; all the logical units associated with that target port group share the same access state (active/optimized, active/non-optimized, standby, or unavailable). Target Port Groups are abstract elements that may or may not equate to an element of the target system (such as a controller). The concept of target port groups can be applied to all devices even if they dont actually implement the SCSI standard interfaces. This API does not require an SPC-3-compliant array; it includes target port groups and uses the terminology of ANSI INCITS 408-2005 (SPC-3) as a s