ISO/IEC 11002:2008

Information technology — Multipath management API

ISO/IEC 11002:2008(E) is an Application Programming Interface (API) which provides management interfaces as defined in ISO/IEC 14776-453 (Information technology - Small computer system interface (SCSI) - Part 453: Primary commands-3 (SPC-3)) and common vendor-specific extensions to the standard capabilities. ISO/IEC 11002 relates to SCSI multipathing features and excludes multipathing between interconnect devices (such as Fibre Channel switches) and transport specific multipathing (such as iSCSI multiple connections per session).

Technologies de l'information — API de gestion des trajets multiples

General Information

• Status: Published
• Publication Date: 03-Aug-2008
• ICS: 35.200 - Interface and interconnection equipment
• Technical Committee: ISO/IEC JTC 1/SC 25 - Interconnection of information technology equipment
• Drafting Committee: ISO/IEC JTC 1/SC 25 - Interconnection of information technology equipment
• Current Stage: 9093 - International Standard confirmed
• Completion Date: 13-Jul-2018

Standards Content (Sample)

ISO/IEC 11002
Edition 1.0 2008-07
INTERNATIONAL
STANDARD


Information technology – Multipath management (API)




ISO/IEC 11002:2008(E)

---------------------- Page: 1 ----------------------
THIS PUBLICATION IS COPYRIGHT PROTECTED
Copyright © 2008 ISO/IEC, Geneva, Switzerland

All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized in any form
or by any means, electronic or mechanical, including photocopying and microfilm, without permission in writing from
either IEC or IEC's member National Committee in the country of the requester.
If you have any questions about ISO/IEC copyright or have an enquiry about obtaining additional rights to this
publication, please contact the address below or your local IEC member National Committee for further information.

IEC Central Office
3, rue de Varembé
CH-1211 Geneva 20
Switzerland
Email: [e-mail]
Web: www.iec.ch

About the IEC
The International Electrotechnical Commission (IEC) is the leading global organization that prepares and publishes
International Standards for all electrical, electronic and related technologies.

About IEC publications
The technical content of IEC publications is kept under constant review by the IEC. Please make sure that you have the
latest edition, a corrigenda or an amendment might have been published.
ƒ Catalogue of IEC publications: www.iec.ch/searchpub
The IEC on-line Catalogue enables you to search by a variety of criteria (reference number, text, technical committee,…).
It also gives information on projects, withdrawn and replaced publications.
ƒ IEC Just Published: www.iec.ch/online_news/justpub
Stay up to date on all new IEC publications. Just Published details twice a month all new publications released. Available
on-line and also by email.
ƒ Electropedia: www.electropedia.org
The world's leading online dictionary of electronic and electrical terms containing more than 20 000 terms and definitions
in English and French, with equivalent terms in additional languages. Also known as the International Electrotechnical
Vocabulary online.
ƒ Customer Service Centre: www.iec.ch/webstore/custserv
If you wish to give us your feedback on this publication or need further assistance, please visit the Customer Service
Centre FAQ or contact us:
Email: [e-mail]
Tel.: [phone]
Fax: [phone]

---------------------- Page: 2 ----------------------
ISO/IEC 11002
Edition 1.0 2008-07
INTERNATIONAL
STANDARD


Information technology – Multipath management (API)



INTERNATIONAL
ELECTROTECHNICAL
COMMISSION
PRICE CODE
W
ICS 35.200 ISBN 2-8318-9908-7

---------------------- Page: 3 ----------------------
– 2 – 11002 © ISO/IEC:2008(E)
CONTENTS
FOREWORD.6
INTRODUCTION.7
1 Scope.8
2 Normative references .8
3 Terms, definitions and abbreviations .8
3.1 Terms and definitions .8
3.2 Abbreviations .10
4 Document conventions .11
5 Background technical information .12
5.1 Overview .12
5.2 Target port groups.12
5.3 Relationship between target port groups in SCSI and in this API .13
5.3.1 General .13
5.3.2 Symmetric and asymmetric multipath access .14
5.3.3 Logical unit affinity groups.15
5.3.4 Load balancing .15
5.3.5 Model overview .16
5.4 Client discovery of optional behavior .18
5.4.1 General .18
5.4.2 Discovery of load balancing behavior.18
5.4.3 Client discovery of failover/failback capabilities .20
5.4.4 Client discovery of a driver’s OS device file name behavior .20
5.4.5 Client discovery of auto-failback capabilities.20
5.4.6 Client discovery of auto-probing capabilities .21
5.4.7 Client discovery of support for LU assignment to target port groups.21
5.5 Events.21
5.6 API concepts .22
5.6.1 Library and plugins .22
5.6.2 OS-independent implementation.22
5.6.3 Object ID .22
5.6.4 Object ID list.23
6 Constants and structures.23
6.1 MP_WCHAR.23
6.2 MP_CHAR.23
6.3 MP_BYTE .23
6.4 MP_BOOL .24
6.5 MP_XBOOL.24
6.6 MP_UINT32.24
6.7 MP_UINT64.24
6.8 MP_STATUS .24
6.9 MP_PATH_STATE .25
6.10 MP_OBJECT_VISIBILITY_FN .26
6.11 MP_OBJECT_PROPERTY_FN .26
6.12 MP_OBJECT_TYPE .27
6.13 MP_OID .27
6.14 MP_OID_LIST .28

---------------------- Page: 4 ----------------------
11002 © ISO/IEC:2008(E) – 3 –
6.15 MP_PORT_TRANSPORT_TYPE .28
6.16 MP_ACCESS_STATE_TYPE.29
6.17 MP_LOAD_BALANCE_TYPE.29
6.18 MP_PROPRIETARY_PROPERTY .30
6.19 MP_PROPRIETARY_LOAD_BALANCE_PROPERTIES .31
6.20 MP_LOGICAL_UNIT_NAME_TYPE .31
6.21 MP_LIBRARY_PROPERTIES.32
6.22 MP_AUTOFAILBACK_SUPPORT .32
6.23 MP_AUTOPROBING_SUPPORT .33
6.24 MP_PLUGIN_PROPERTIES.33
6.25 MP_DEVICE_PRODUCT_PROPERTIES .35
6.26 MP_MULTIPATH_LOGICAL_UNIT_PROPERTIES.36
6.27 MP_PATH_LOGICAL_UNIT_PROPERTIES.38
6.28 MP_INITIATOR_PORT_PROPERTIES .39
6.29 MP_TARGET_PORT_PROPERTIES .39
6.30 MP_TARGET_PORT_GROUP_PROPERTIES .40
6.31 MP_TPG_STATE_PAIR.40
7 APIs .41
7.1 API overview .41
7.2 MP_AssignLogicalUnitToTPG.42
7.3 MP_CancelOverridePath .43
7.4 MP_CompareOIDs .44
7.5 MP_DeregisterForObjectPropertyChanges .44
7.6 MP_DeregisterForObjectVisibilityChanges .45
7.7 MP_DeregisterPlugin.46
7.8 MP_DisableAutoFailback.47
7.9 MP_DisableAutoProbing.47
7.10 MP_DisablePath.48
7.11 MP_EnableAutoFailback.49
7.12 MP_EnableAutoProbing.49
7.13 MP_EnablePath .50
7.14 MP_FreeOidList .51
7.15 MP_GetAssociatedPathOidList.51
7.16 MP_GetAssociatedPluginOid.52
7.17 MP_GetAssociatedTPGOidList .52
7.18 MP_GetDeviceProductOidList .53
7.19 MP_GetDeviceProductProperties .54
7.20 MP_GetInitiatorPortOidList.55
7.21 MP_GetInitiatorPortProperties.56
7.22 MP_GetLibraryProperties .56
7.23 MP_GetMPLuOidListFromTPG .57
7.24 MP_GetMPLogicalUnitProperties.57
7.25 MP_GetMultipathLus .58
7.26 MP_GetObjectType .59
7.27 MP_GetPathLogicalUnitProperties.60
7.28 MP_GetPluginOidList .60
7.29 MP_GetPluginProperties .61
7.30 MP_GetProprietaryLoadBalanceOidList.62
7.31 MP_GetProprietaryLoadBalanceProperties.62

---------------------- Page: 5 ----------------------
– 4 – 11002 © ISO/IEC:2008(E)
7.32 MP_GetTargetPortGroupProperties .63
7.33 MP_GetTargetPortOidList.64
7.34 MP_GetTargetPortProperties .64
7.35 MP_RegisterForObjectPropertyChanges .65
7.36 MP_RegisterForObjectVisibilityChanges.66
7.37 MP_RegisterPlugin.67
7.38 MP_SetLogicalUnitLoadBalanceType .68
7.39 MP_SetOverridePath.69
7.40 MP_SetPathWeight .70
7.41 MP_SetPluginLoadBalanceType.70
7.42 MP_SetFailbackPollingRate .71
7.43 MP_SetProbingPollingRate .72
7.44 MP_SetProprietaryProperties .72
7.45 MP_SetTPGAccess .73
8 Implementation compliance .74
9 Implementations .75
9.1 Backwards compatibility .75
9.2 Client usage notes .75
9.2.1 Reserved fields.75
9.2.2 Event notification within a single client .75
9.2.3 Event notification and multi-threading .75
9.3 Library implementation notes.75
9.3.1 Multi-threading support.75
9.3.2 Event notification and multi-threading .75
9.3.3 Structure packing .75
9.3.4 Calling conventions .76
9.4 Plugin implementation notes.76
9.4.1 Reserved fields.76
9.4.2 Multi-threading support.76
9.4.3 Event notification to different clients .76
9.4.4 Event notification and multi-threading .76
9.4.5 Event overhead conservation.76
9.4.6 Function names .76
Annex A (informative) Device names .77
A.1 General .77
A.2 Initiator port osDeviceName .77
A.3 Logical unit osDeviceName .77
Annex B (informative) Synthesizing target port groups .79
Annex C (informative) Transport layer multipathing.80
Annex D (informative) Coding examples .81
D.1 General .81
D.2 Example of getting library properties .81
D.3 Example of getting plugin properties.81
D.4 Example of discovering path LUs associated with an MP LU .82
Annex E (informative) Library/plugin API.84
Bibliography.85

---------------------- Page: 6 ----------------------
11002 © ISO/IEC:2008(E) – 5 –

Figure 1 – Asymmetric array example .13
Figure 2 – API Instances corresponding to asymmetric array example .14
Figure 3 – Relationship between various objects in the multipath model .17
Figure 4 – Driver representation of a logical unit with multiple paths .18
Figure 5 – APIs relative to the objects from Figure 1.42
Figure B.1 – Synthetic target port groups.79

Table A.1 – Names for the osDeviceName field .77
Table A.2 – Names for the osDeviceName.78

---------------------- Page: 7 ----------------------
– 6 – 11002 © ISO/IEC:2008(E)

INFORMATION TECHNOLOGY –
MULTIPATH MANAGEMENT (API)

FOREWORD
1) ISO (International Organization for Standardization) and IEC (International Electrotechnical Commission) form the
specialized system for worldwide standardization. National bodies that are members of ISO or IEC participate in
the development of International Standards. Their preparation is entrusted to technical committees; any ISO and
IEC member body interested in the subject dealt with may participate in this preparatory work. International
governmental and non-governmental organizations liaising with ISO and IEC also participate in this preparation.
2) In the field of information technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.
Draft International Standards adopted by the joint technical committee are circulated to national bodies for voting.
Publication as an International Standard requires approval by at least 75 % of the national bodies casting a vote.
3) The formal decisions or agreements of IEC and ISO on technical matters express, as nearly as possible, an
international consensus of opinion on the relevant subjects since each technical committee has representation
from all interested IEC and ISO member bodies.
4) IEC, ISO and ISO/IEC publications have the form of recommendations for international use and are accepted
by IEC and ISO member bodies in that sense. While all reasonable efforts are made to ensure that the
technical content of IEC, ISO and ISO/IEC publications is accurate, IEC or ISO cannot be held responsible for
the way in which they are used or for any misinterpretation by any end user.
5) In order to promote international uniformity, IEC and ISO member bodies undertake to apply IEC, ISO and
ISO/IEC publications transparently to the maximum extent possible in their national and regional publications.
Any divergence between any ISO/IEC publication and the corresponding national or regional publication
should be clearly indicated in the latter.
6) ISO and IEC provide no marking procedure to indicate their approval and cannot be rendered responsible for
any equipment declared to be in conformity with an ISO/IEC publication.
7) All users should ensure that they have the latest edition of this publication.
8) No liability shall attach to IEC or ISO or its directors, employees, servants or agents including individual experts
and members of their technical committees and IEC or ISO member bodies for any personal injury, property
damage or other damage of any nature whatsoever, whether direct or indirect, or for costs (including legal fees)
and expenses arising out of the publication of, use of, or reliance upon, this ISO/IEC publication or any other IEC,
ISO or ISO/IEC publications.
9) Attention is drawn to the normative references cited in this publication. Use of the referenced publications is
indispensable for the correct application of this publication.
10) Attention is drawn to the possibility that some of the elements of this International Standard may be the subject of
patent rights. ISO and IEC shall not be held responsible for identifying any or all such patent rights.
International Standard ISO/IEC 11002 was prepared by the Information Technology Industry
Council and was adopted under the fast track procedure by subcommittee 25: Interconnection
of information technology equipment, of ISO/IEC joint technical committee 1: Information
technology.
This International Standard has been approved by vote of the member bodies, and the voting
results may be obtained from the address given on the second title page.
This publication has been drafted in accordance with the ISO/IEC Directives, Part 2.

---------------------- Page: 8 ----------------------
11002 © ISO/IEC:2008(E) – 7 –

INTRODUCTION
The Multipath Management application programming interface (API) provides management
interfaces to standard capabilities defined in ISO/IEC 14776-453 (SPC-3) and common
vendor-specific extensions to the standard capabilities. The intended audience is vendors that
deliver drivers that provide these capabilities. This standard relates to SCSI multipathing
features and excludes multipathing between interconnect devices (such as Fibre Channel
switches) and transport specific multipathing (such as iSCSI multiple connections per
session).

---------------------- Page: 9 ----------------------
– 8 – 11002 © ISO/IEC:2008(E)
INFORMATION TECHNOLOGY –
MULTIPATH MANAGEMENT API

1 Scope
This International Standard provides management interfaces to standard capabilities defined
in ISO/IEC 14776-453 (SPC-3) and common vendor-specific extensions to the standard
capabilities. The intended audience is vendors that deliver drivers that provide these
capabilities. This standard relates to SCSI multipathing features and excludes multipathing
between interconnect devices (such as Fibre Channel switches) and transport specific
multipathing (such as iSCSI multiple connections per session).
2 Normative references
The following referenced documents are indispensable for the application of this document.
For dated references, only the edition cited applies. For undated references, the latest edition
of the referenced document (including any amendments) applies.
The provisions of the referenced specifications other than ISO/IEC, IEC, ISO and ITU
documents, as identified in this clause, are valid within the context of this International
Standard. The reference to such a specification within this International Standard does not
give it any further status within ISO or IEC. In particular, it does not give the referenced
specification the status of an International Standard.
ISO/IEC 9899:1999, Programming languages – C
ISO/IEC 14165-133, Information technology – Fibre channel – Part 133: Switch fabric-3
(FC-SW-3)
ISO/IEC 14165-251, Information technology – Fibre channel – Part 251: Framing and
signalling (FC-FS)
ISO/IEC 14776-115, Information technology – Small computer system interface (SCSI) –
Part 115: Parallel interface-5 (SPI-5)
ISO/IEC 14776-150, Information technology – Small computer system interface (SCSI) –
Part 150: Serial attached SCSI (SAS)
ISO/IEC 14776-413, Information technology – Small computer system interface (SCSI) –
Part 413: Architecture model-3 (SAM-3)
ISO/IEC 14776-453, Information technology – Small computer system interface (SCSI) –
Part 453: Primary commands-3 (SPC-3)
RFC 3720, Internet Small Computer Systems Interface (iSCSI)
NOTE Copies of IETF standards such as RFC 3720 may be obtained through the Internet Engineering Task Force
(IETF) at http://www.ietf.org.

3 Terms, definitions and abbreviations
3.1 Terms and definitions
For the purposes of this document the following terms and definitions apply.
3.1.1
auto-failback
capability of some multipath drivers to resume use of a path when the path transitions from
unavailable to available

---------------------- Page: 10 ----------------------
11002 © ISO/IEC:2008(E) – 9 –
3.1.2
auto-probing
capability of some multipath drivers to validate operational paths that are not currently being
used
3.1.3
available paths
set of paths for a logical unit that may be considered for routing I/O requests
NOTE For symmetric access devices, all paths are considered available. For asymmetric access devices, all paths
in active target port groups are considered available.
3.1.4
device file
operating system files (for instance UNIX, Linux etc.,) that facilitate communication with the
system’s hardware and peripherals
3.1.5
device identification VPD page
VPD page that provides the means to retrieve identification information about the SCSI
device, logical unit, and SCSI port
3.1.6
hexadecimal-encoded binary data
ASCII character string used to denote the hexadecimal encoding of a binary string of octets
NOTE It may only contain the ASCII characters 0-9, A-F, and a-f. Two hexadecimal characters represent each byte
of binary data.
3.1.7
host
compute node connected to the SAN
3.1.8
initiator
SCSI device that initiates requests; also known as a client
NOTE In this document, initiator refers to an initiator port.
3.1.9
logical unit
addressable entity within a SCSI target
NOTE For example, RAID arrays expose each virtual disk volume as a logical unit. When the term “logical unit: is
used in this standard and is not qualified as a “multipath logical unit” or “path logical unit”, it refers to a logical unit
in a target device.
3.1.10
multipath logical unit
an object type of this API representing a “virtual “logical unit that coalesces multiple path
logical units for the same underlying device logical unit
3.1.11
object ID
unique identifier assigned to any object within the MP API
NOTE Objects sometimes represent physical entities, e.g. initiator ports. At other times, objects represent logical
entities, e.g. target port groups.
3.1.12
path
association between an initiator port, target port and logical unit, see 3.1.13
3.1.13
path logical unit
an object type of this API providing access to a single logical unit through a single initiator
port and single device port

---------------------- Page: 11 ----------------------
– 10 – 11002 © ISO/IEC:2008(E)
NOTE Within this API, each path (see 3.1.12) is modelled as a path logical unit. The result of multipath drivers is
a single OS device file representing a multipath logical unit aggregating multiple path logical units.
3.1.14
persistent
quality of something being n
...