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
Current Stage
9093 - International Standard confirmed
Start Date
13-Jul-2018
Completion Date
13-Jul-2018
Ref Project

Buy Standard

Standard
ISO/IEC 11002:2008 - Information technology -- Multipath management API
English language
78 pages
sale 15% off
Preview
sale 15% off
Preview

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: inmail@iec.ch
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: csc@iec.ch
Tel.: +41 22 919 02 11
Fax: +41 22 919 03 00
---------------------- Page: 2 ----------------------
ISO/IEC 11002
Edition 1.0 2008-07
INTERNATIONAL
STANDARD
Information technology – Multipath management (API)
INTERNATIONAL
ELECTROTECHNICAL
COMMISSION
PRICE CODE
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
...

Questions, Comments and Discussion

Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.