《ANSI-INCITS-412-2006.pdf》由会员分享，可在线阅读，更多相关《ANSI-INCITS-412-2006.pdf（114页珍藏版）》请在三一文库上搜索。
1、American National Standard Developed by for Information Technology SNIA Multipath Management API Specification ANSI INCITS 412-2006 ANSI INCITS 412-2006 Copyright American National Standards Institute Provided by IHS under license with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice No
2、t for Resale, 04/29/2007 13:18:12 MDTNo reproduction or networking permitted without license from IHS -,-,- Copyright American National Standards Institute Provided by IHS under license with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resale, 04/29/2007 13:18:12 MDTNo repro
3、duction or networking permitted without license from IHS -,-,- ANSI INCITS 412-2006 American National Standard for Information Technology SNIA Multipath Management API Specification Secretariat Information Technology Industry Council Approved August 14, 2006 American National Standards Institute, In
4、c. Copyright American National Standards Institute Provided by IHS under license with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resale, 04/29/2007 13:18:12 MDTNo reproduction or networking permitted without license from IHS -,-,- Approval of an American National Standard
5、requires review by ANSI that the requirements for due process, consensus, and other criteria for approval have been met by the standards developer. Consensus is established when, in the judgement of the ANSI Board of Standards Review, substantial agreement has been reached by directly and materially
6、 affected interests. Substantial agreement means much more than a simple majority, but not necessarily unanimity. Consensus requires that all views and objections be considered, and that a concerted effort be made towards their resolution. The use of American National Standards is completely volunta
7、ry; their existence does not in any respect preclude anyone, whether he has approved the standards or not, from manufacturing, marketing, purchasing, or using products, processes, or procedures not conforming to the standards. The American National Standards Institute does not develop standards and
8、will in no circumstances give an interpretation of any American National Standard. Moreover, no person shall have the right or authority to issue an interpretation of an American National Standard in the name of the American National Standards Institute. Requests for interpretations should be addres
9、sed to the secretariat or sponsor whose name appears on the title page of this standard. CAUTION NOTICE: This American National Standard may be revised or withdrawn at any time. The procedures of the American National Standards Institute require that action be taken periodically to reaffirm, revise,
10、 or withdraw this standard. Purchasers of American National Standards may receive current information on all standards by calling or writing the American National Standards Institute. American National Standard Published by American National Standards Institute, Inc. 25 West 43rd Street, New York, N
11、Y 10036 Copyright 2006 by Information Technology Industry Council (ITI) All rights reserved. No part of this publication may be reproduced in any form, in an electronic retrieval system or otherwise, without prior written permission of ITI, 1250 Eye Street NW, Washington, DC 20005. Printed in the Un
12、ited States of America CAUTION: The developers of this standard have requested that holders of patents that may be required 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 ide
13、ntify which, if any, patents may apply to this standard. As of the date of publication of this standard and following calls for the identification of patents that may be required for the implementation of the standard, no such claims have been made. No further patent search is conducted by the de- v
14、eloper or publisher in respect to any standard it processes. No representation is made or implied that 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 Licensee=IHS Employees/111111100
15、1, User=OConnor, Maurice Not for Resale, 04/29/2007 13:18:12 MDTNo reproduction or networking permitted without license from IHS -,-,- i Contents Page Foreword v Introduction vii 1Scope. 1 2Normative references. 2 3Definitions 3 4Document Conventions 6 5Background Technical Information 7 5.1Overview
16、 7 5.2Client Discovery of Optional Behavior . 13 5.3Events 17 5.4API Programming Concepts 18 6Constants and Structures 20 6.1MP_WCHAR 20 6.2MP_CHAR . 20 6.3MP_BYTE 20 6.4MP_BOOL 20 6.5MP_XBOOL. 20 6.6MP_UINT32. 20 6.7MP_UINT64. 20 6.8MP_STATUS . 20 6.9MP_PATH_STATE 21 6.10MP_OBJECT_VISIBILITY_FN. 22
17、 6.11MP_OBJECT_PROPERTY_FN. 23 6.12MP_OBJECT_TYPE 23 6.13MP_OID. 24 6.14MP_OID_LIST 25 6.15MP_PORT_TRANSPORT_TYPE 25 6.16MP_ACCESS_STATE_TYPE 26 6.17MP_LOAD_BALANCE_TYPE 27 6.18MP_PROPRIETARY_PROPERTY 28 6.19MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES 28 6.20MP_LOGICAL_UNIT_NAME_TYPE 29 6.21MP_LIBRARY_PR
18、OPERTIES. 29 6.22MP_AUTOFAILBACK_SUPPORT. 30 Copyright American National Standards Institute Provided by IHS under license with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resale, 04/29/2007 13:18:12 MDTNo reproduction or networking permitted without license from IHS -,-,-
19、ii Page 6.23MP_AUTOPROBING_SUPPORT . 31 6.24MP_PLUGIN_PROPERTIES. 31 6.25MP_DEVICE_PRODUCT_PROPERTIES. 34 6.26MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES 34 6.27MP_PATH_LOGICAL_UNIT_PROPERTIES. 37 6.28MP_INITIATOR_PORT_PROPERTIES 38 6.29MP_TARGET_PORT_PROPERTIES 39 6.30MP_TARGET_PORT_GROUP_PROPERTIES 39 6.
20、31MP_TPG_STATE_PAIR 40 7APIs . 41 7.1MP_AssignLogicalUnitToTPG . 43 7.2MP_CancelOverridePath. 44 7.3MP_CompareOIDs 45 7.4MP_DeregisterForObjectPropertyChanges. 46 7.5MP_DeregisterForObjectVisibilityChanges 48 7.6MP_DeregisterPlugin. 50 7.7MP_DisableAutoFailback. 51 7.8MP_DisableAutoProbing 52 7.9MP_
21、DisablePath 53 7.10MP_EnableAutoFailback . 54 7.11MP_EnableAutoProbing 55 7.12MP_EnablePath. 56 7.13MP_FreeOidList. 57 7.14MP_GetAssociatedPathOidList . 58 7.15MP_GetAssociatedPluginOid 59 7.16MP_GetAssociatedTPGOidList . 60 7.17MP_GetDeviceProductOidList. 61 7.18MP_GetDeviceProductProperties 62 7.1
22、9MP_GetInitiatorPortOidList 63 7.20MP_GetInitiatorPortProperties. 64 7.21MP_GetLibraryProperties 65 7.22MP_GetMPLuOidListFromTPG . 66 7.23MP_GetMPLogicalUnitProperties 67 7.24MP_GetMultipathLus . 68 7.25MP_GetObjectType . 69 Copyright American National Standards Institute Provided by IHS under licen
23、se with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resale, 04/29/2007 13:18:12 MDTNo reproduction or networking permitted without license from IHS -,-,- iii Page 7.26MP_GetPathLogicalUnitProperties 70 7.27MP_GetPluginOidList.71 7.28MP_GetPluginProperties72 7.29MP_GetPropri
24、etaryLoadBalanceOidList73 7.30MP_GetProprietaryLoadBalanceProperties.74 7.31MP_GetTargetPortGroupProperties.75 7.32MP_GetTargetPortOidList76 7.33MP_GetTargetPortProperties.77 7.34MP_RegisterForObjectPropertyChanges.78 7.35MP_RegisterForObjectVisibilityChanges.80 7.36MP_RegisterPlugin 82 7.37MP_SetLo
25、gicalUnitLoadBalanceType83 7.38MP_SetOverridePath.84 7.39MP_SetPathWeight85 7.40MP_SetPluginLoadBalanceType .86 7.41MP_SetFailbackPollingRate.87 7.42MP_SetProbingPollingRate88 7.43MP_SetProprietaryProperties 89 7.44MP_SetTPGAccess .90 8Implementation Compliance.92 9Implementation Notes93 9.1Backward
26、s Compatibility93 9.2Client Usage Notes93 9.3Library Implementation Notes93 9.4Plugin Implementation Notes.94 Figures 1Asymmetric Array Example8 2API Instances Corresponding to Asymmetric Array Example9 3Relationship between Various Objects in the Multipath World.12 4Driver Representation of a Logic
27、al Unit with Multiple Paths 13 5APIs Relative to Objects from Figure 142 Copyright American National Standards Institute Provided by IHS under license with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resale, 04/29/2007 13:18:12 MDTNo reproduction or networking permitted wit
28、hout license from IHS -,-,- iv Page Annexes ADevice Names . 95 A.1Initiator Port osDeviceName 95 A.2Logical Unit osDeviceName. 95 BSynthesizing Target Port Groups. 96 CTransport Layer Multipathing. 98 DCoding Examples. 100 D.1Example of Getting Library Properties. 100 D.2Example of Getting Plugin Pr
29、operties 100 D.3Example of Discovering path LUs associated with an MP LU. 101 ELibrary/Plugin API 103 Copyright American National Standards Institute Provided by IHS under license with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resale, 04/29/2007 13:18:12 MDTNo reproductio
30、n or networking permitted without license from IHS -,-,- v Foreword (This foreword is not part of American National Standard ANSI INCITS 412-2006.) This standard documents an API that allows a management application to discover the multipath devices on the current system and to discover the associat
31、ed local and device ports. An implementation of the API may optionally include active manage- ment (failover, load balancing, manual path overrides). The API uses an architecture that allows multiple MP drivers installed on a system to provide a common interface to clients of the library. The vendor
32、 implementations may support multipath drivers bundled with an OS, or drivers associated with an HBA, target device, or volume manager. This API can be used by host-based management applications and will also be used in ANSI INCITS 388 for enterprise-wide multipath discovery and man- agement. A clie
33、nt 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 Commit- tee
34、for Information Technology Standards, Information Technology Institute, 1250 Eye 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 approval of the
35、standard does not necessarily imply that all committee members voted for its approval. At the time it approved this standard, INCITS had the following members: Karen Higginbottom, Chair Jennifer Garner, Secretary Organization Represented Name of Representative AIM GlobalDan Mullen Charles Biss (Alt.
36、) Apple Computer, Inc.David Michael Electronic Industries AllianceEdward Mikoski, Jr. Henry Cuschieri (Alt.) EMC CorporationGary Robinson Farance, IncFrank Farance GS1 US Frank Sharkey James Chronowski (Alt.) Mary Wilson (Alt.) Hewlett-Packard Company.Karen Higginbottom Steve Mills (Alt.) Scott Jame
37、son (Alt.) IBM Corporation .Ronald F. Silletti Peter Schirling (Alt.) IEEE .Judith Gorman Terry DeCourcelle (Alt.) Jodi Haasz (Alt.) Bob Labelle (Alt.) Robert Pritchard (Alt.) Intel.Philip Wennblom Dave Thewlis (Alt.) Jesse Walker (Alt.) Grace Wei (Alt.) Lexmark International.Don Wright Dwight Lewis
38、 (Alt.) Paul Menard (Alt.) Microsoft Corporation .Jim Hughes Don Stanwyck (Alt.) Mike Ksar (Alt.) Isabelle Valet-Harper (Alt.) Copyright American National Standards Institute Provided by IHS under license with ANSI Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resale, 04/29/2007 1
39、3:18:12 MDTNo reproduction or networking permitted without license from IHS -,-,- vi Organization RepresentedName of Representative National Institute of Standards using #defines rather than enums helps assure client code is interoperable across platforms and compilers especially if used in C+ appli
40、cations. 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 a C function prototype and
41、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 an input and an output parame
42、ter. 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 is important to note that t
43、his 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 particular, this subclause conta
44、ins 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 can rely on the API function
45、ing 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. Otherwise a client should assume t
46、hat 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 Licensee=IHS Employees/1111111001, User=OConnor, Maurice Not for Resal
47、e, 04/29/2007 13:18:12 MDTNo 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 devi
48、ces. 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 device 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 d