--- 1/draft-ietf-tictoc-1588v2-yang-00.txt 2016-11-25 01:13:08.592040260 -0800 +++ 2/draft-ietf-tictoc-1588v2-yang-01.txt 2016-11-25 01:13:08.644041505 -0800 @@ -1,20 +1,27 @@ Internet Working Group Y. Jiang, Ed. X. Liu -Internet Draft J. Xu +Internet-Draft J. Xu Huawei Intended status: Standards Track R. Cummings, Ed. National Instruments -Expires: April 2017 October 20, 2016 +Expires: May 2017 November 25, 2016 YANG Data Model for IEEE 1588v2 - draft-ietf-tictoc-1588v2-yang-00 + draft-ietf-tictoc-1588v2-yang-01 + +Abstract + + This document defines a YANG data model for the configuration of + IEEE 1588-2008 devices and clocks, and also retrieval of the + configuration information, data set and running states of IEEE + 1588-2008 clocks. Status of this Memo This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. @@ -24,109 +31,104 @@ documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html - This Internet-Draft will expire on April 20, 2017. + This Internet-Draft will expire on May 25, 2017. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. -Abstract - - This document defines a YANG data model for the configuration of - IEEE 1588-2008 devices and clocks, and also retrieval of the - configuration information, data set and running states of IEEE - 1588-2008 clocks. - Table of Contents 1. Introduction .............................................. 2 1.1. Conventions used in this document ...................... 4 1.2. Terminology ............................................ 4 2. IEEE 1588-2008 YANG Model hierarchy ....................... 5 - 2.1. Interpretations from IEEE 1588 Working Group ........... 7 - 3. IEEE 1588-2008 YANG Module ................................ 8 - 4. Security Considerations .................................. 20 - 5. IANA Considerations ...................................... 20 - 6. References ............................................... 21 - 6.1. Normative References .................................. 21 - 6.2. Informative References ................................ 21 - 7. Acknowledgments .......................................... 22 + 2.1. Interpretations from IEEE 1588 Working Group ........... 8 + 3. IEEE 1588-2008 YANG Module ................................ 9 + 4. Security Considerations .................................. 21 + 5. IANA Considerations ...................................... 22 + 6. References ............................................... 22 + 6.1. Normative References .................................. 22 + 6.2. Informative References ................................ 22 + 7. Acknowledgments .......................................... 23 Appendix A Transferring YANG Work to IEEE 1588 WG (Informational) - ............................................................... 22 - A.1. Assumptions for the Transfer .......................... 23 - A.2. Intellectual Property Considerations .................. 24 - A.3. Namespace and Module Name ............................. 24 - A.4. IEEE 1588 YANG Modules in ASCII Format ................ 25 + ................................................................. 23 + A.1. Assumptions for the Transfer .......................... 24 + A.2. Intellectual Property Considerations .................. 25 + A.3. Namespace and Module Name ............................. 25 + A.4. IEEE 1588 YANG Modules in ASCII Format ................ 26 1. Introduction As a synchronization protocol, IEEE 1588-2008 (also known as IEEE 1588v2) [IEEE1588] is widely supported in the carrier networks, industrial networks, automotive networks, and many other applications. It can provide high precision time synchronization as - high as nano-seconds. The protocol depends on a Precision Time - Protocol (PTP) engine to decide its state automatically, and a PTP - transportation layer to carry the PTP timing and various quality - messages. The configuration parameters and state data sets of IEEE - 1588-2008 are numerous. + fine as nano-seconds. The protocol depends on a Precision Time + Protocol (PTP) engine to decide its own state automatically, and a + PTP transportation layer to carry the PTP timing and various + quality messages. The configuration parameters and state data sets + of IEEE 1588-2008 are numerous. According to the concepts described in [RFC3444], IEEE 1588-2008 itself provides an information model in its normative specifications for the data sets (in IEEE 1588-2008 clause 8). Some standardization organizations including the IETF have specified data models in MIBs (Management Information Bases) for IEEE 1588- - 2008 data sets (e.g. [PTP-MIB], [IEEE8021AS]). Since these MIBs are + 2008 data sets (e.g. [PTP-MIB], [IEEE8021AS]). These MIBs are typically focused on retrieval of state data using the Simple - Network Management Protocol (SNMP), configuration is not considered. + Network Management Protocol (SNMP), while configuration of PTP data + sets is not considered. Some service providers and applications require that the management of the IEEE 1588-2008 synchronization network be flexible and more Internet-based (typically overlaid on their transport networks). - Software Defined Network (SDN) is another driving factor which + Software Defined Network (SDN) is another driving factor, which demands an improved configuration capability of synchronization networks. YANG [RFC6020] is a data modeling language used to model configuration and state data manipulated by network management protocols like the Network Configuration Protocol (NETCONF) [RFC6241]. A small set of built-in data types are defined in [RFC6020], and a collection of common data types are further defined in [RFC6991]. Advantages of YANG include Internet based - configuration capability, validation, roll-back and so on. All of + configuration capability, validation, rollback and so on. All of these characteristics make it attractive to become another candidate modeling language for IEEE 1588-2008. This document defines a YANG [RFC6020] data model for the - configuration of IEEE 1588-2008 devices and clocks, and also - retrieval of the state data of IEEE 1588-2008 clocks. The data - model is based on the PTP data sets as specified in [IEEE1588]. The - router specific IEEE 1588-2008 information is out of scope of this - document. + configuration of IEEE 1588-2008 devices and clocks, and retrieval + of the state data of IEEE 1588-2008 clocks. The data model is based + on the PTP data sets as specified in [IEEE1588]. The technology + specific IEEE 1588-2008 information, e.g., those specifically + implemented by a bridge, a router or a telecom profile, is out of + scope of this document. When used in practice, network products in support of synchronization typically conform to one or more IEEE 1588-2008 profiles. Each profile specifies how IEEE 1588-2008 is used in a given industry (e.g. telecom, automotive) and application. A profile can require features that are optional in IEEE 1588-2008, and it can specify new features that use IEEE 1588-2008 as a foundation. It is expected that the IEEE 1588-2008 YANG module will be used as @@ -155,22 +157,22 @@ specific enhancements. 1.1. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 1.2. Terminology - Terminologies used in this document are extracted from [IEEE1588] - and [PTP-MIB]. + Most terminologies used in this document are extracted from + [IEEE1588]. BC Boundary Clock DS Data Set E2E End-to-End EUI Extended Unique Identifier. GPS Global Positioning System @@ -189,53 +191,61 @@ PTP Precision Time Protocol TAI International Atomic Time TC Transparent Clock UTC Coordinated Universal Time 2. IEEE 1588-2008 YANG Model hierarchy - This section describes the hierarchy of IEEE 1588-2008 YANG module. - Query and configuration of device wide or port specific + This section describes the hierarchy of an IEEE 1588-2008 YANG + module. Query and configuration of device wide or port specific configuration information and clock data set is described for this version. Query and configuration of clock information include: - Clock data set attributes in a clock node, including: current-ds, - parent-ds, default-ds, time-properties-ds, and transparentClock- + parent-ds, default-ds, time-properties-ds, and transparent-clock- default-ds. - - Port specific data set attributes, including: port-ds and - transparentClock-port-ds. + - Port-specific data set attributes, including: port-ds and + transparent-clock-port-ds. + + The readers are assumed to be familiar with IEEE 1588-2008. As all + PTP terminologies and PTP data set attributes are described in + details in IEEE 1588-2008 [IEEE1588], this document only outlines + each of them in the YANG module. A simplified graphical representation of the data model is typically used by YANG modules as described in [REST-CONF]. This document uses the same representation and the meaning of the symbols in these diagrams is as follows: o Brackets "[" and "]" enclose list keys. o Abbreviations before data node names: "rw" means configuration data (read-write) and "ro" state data (read-only). o Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. o Parentheses enclose choice and case nodes, and case nodes are also marked with a colon (":"). o Ellipsis ("...") stands for contents of subtrees that are not shown. + o Arrow ("->") stands for a reference to a particular leaf + instance in the tree. + module: ietf-ptp-dataset +--rw instance-list* [instance-number] | +--rw instance-number uint8 | +--rw default-ds | | +--rw two-step-flag? boolean | | +--rw clock-identity? binary | | +--rw number-ports? uint16 | | +--rw clock-quality | | | +--rw clock-class? uint8 | | | +--rw clock-accuracy? uint8 @@ -314,68 +324,68 @@ multiple PTP domains was not clear in the data sets of IEEE Std 1588-2008. This document introduces the concept of PTP instance as described in the new revision of IEEE 1588. The instance concept is used exclusively to allow for optional support of multiple domains. The instance number has no usage within PTP messages. Based on statements in IEEE 1588-2008 subclauses 8.3.1. and 10.1, most transparent clock products have interpreted the transparent clock data sets to reside as a singleton at the root level of the managed product. Since 1588-2008 transparent clocks are domain - independent, the instance concept is not applicable for them. + independent, the instance concept is not applicable for domains. 3. IEEE 1588-2008 YANG Module - file "ietf-ptp-dataset@2016-10-20" + file "ietf-ptp-dataset@2016-11-25" module ietf-ptp-dataset{ namespace "urn:ietf:params:xml:ns:yang:ietf-ptp-dataset"; prefix "ptp-dataset"; organization "IETF TICTOC WG"; contact "WG Web: http://tools.ietf.org/wg/tictoc/ WG List: WG Chair: Karen O'Donoghue WG Chair: Yaakov Stein Editor: Yuanlong Jiang Editor: Rodney Cummings "; description "This YANG module defines a data model for the configuration - of IEEE 1588-2008 clocks, and also retrieval of the state + of IEEE 1588-2008 clocks, and also for retrieval of the state data of IEEE 1588-2008 clocks."; - revision "2016-10-20" { - description "Original version."; + + revision "2016-10-25" { + description "Version 1.0"; reference "draft-ietf-tictoc-1588v2-yang"; } grouping default-ds-entry { description "Collection of members of the default data set."; leaf two-step-flag { type boolean; description - "The flag indicates whether the Two Step process is - used."; + "When set, the clock is a two-step clock; otherwise, + the clock is a one-step clock."; } leaf clock-identity { type binary { length "8"; } description "The clockIdentity of the local clock"; } - leaf number-ports { type uint16; description "The number of PTP ports on the device."; } container clock-quality { description "The clockQuality of the local clock. It contains clockClass, clockAccuracy and offsetScaledLogVariance."; @@ -416,22 +426,21 @@ leaf domain-number { type uint8; description "The domain number of the current syntonization domain."; } leaf slave-only { type boolean; description - "Indicates whether the clock is a slave-only clock."; - + "When set, the clock is a slave-only clock."; } } grouping current-ds-entry { description "Collection of members of current data set."; leaf steps-removed { type uint16; default 0; @@ -449,54 +458,54 @@ current value of the time difference between a master and a slave clock as computed by the slave."; } leaf mean-path-delay { type binary { length "1..255"; } description "An implementation-specific representation of the current value of the mean propagation time between a - master and slave clock as computed by the slave."; + master and a slave clock as computed by the slave."; } } grouping parent-ds-entry { description "Collection of members of the parent data set."; container parent-port-identity { description - "The portIdentity of the port on the master. - It contains two members: clockIdentity and portNumer."; + "The portIdentity of the port on the master, which + contains two members: clockIdentity and portNumber."; leaf clock-identity { type binary { length "8"; } description "The clockIdentity of the master clock."; } leaf port-number { type uint16; description "The portNumber for the port on the specific master."; } } leaf parent-stats { type boolean; default false; description - "Indicates whether the values of + "When set, the values of observedParentOffsetScaledLogVariance and observedParentClockPhaseChangeRate of parentDS have been measured and are valid."; } leaf observed-parent-offset-scaled-log-variance { type uint16; default 0xFFFF; description "An estimate of the parent clock's PTP variance as observed by the slave clock."; @@ -556,59 +564,59 @@ } grouping time-properties-ds-entry { description "Collection of members of the timeProperties data set."; leaf current-utc-offset-valid { type boolean; description - "Indicates whether current UTC offset is valid."; + "When set, the current UTC offset is valid."; } leaf current-utc-offset { type uint16; description "The offset between TAI and UTC when the epoch of the PTP system is the PTP epoch, otherwise the value has no meaning."; } leaf leap59 { type boolean; description - "Indicates whether the last minute of the current UTC - day contains 59 seconds."; + "When set, the last minute of the current UTC day + contains 59 seconds."; } leaf leap61 { type boolean; description - "Indicates whether the last minute of the current UTC - day contains 61 seconds."; + "When set, the last minute of the current UTC day + contains 61 seconds."; } leaf time-traceable { type boolean; description - "Indicates whether the timescale and the - currentUtcOffset are traceable to a primary - reference."; + "When set, the timescale and the currentUtcOffset are + traceable to a primary reference."; } leaf frequency-traceable { type boolean; description - "Indicates whether the frequency determining the - timescale is traceable to a primary reference."; + "When set, the frequency determining the timescale + is traceable to a primary reference."; } - leaf PTP-timescale { + leaf ptp-timescale { type boolean; description - "Indicates whether the clock timescale - of the grandmaster clock is PTP."; + "When set, the clock timescale of the grandmaster + clock is PTP; otherwise the timescale is ARB + (arbitrary)."; } leaf time-source { type uint8; description "The source of time used by the grandmaster clock."; } } grouping port-ds-entry { @@ -640,24 +648,25 @@ leaf port-state { type uint8; default 1; description "Current state associated with the port."; } leaf log-min-delay-req-interval { type int8; description - "The logarithm to the base 2 of the minDelayReqInterval + "The base-two logarithm of the minDelayReqInterval (the minimum permitted mean time interval between successive Delay_Req messages)."; } + leaf peer-mean-path-delay { type int64; default 0; description "An estimate of the current one-way propagation delay on the link when the delayMechanism is P2P, otherwise it is zero."; } leaf log-announce-interval { @@ -656,41 +665,41 @@ default 0; description "An estimate of the current one-way propagation delay on the link when the delayMechanism is P2P, otherwise it is zero."; } leaf log-announce-interval { type int8; description - "The logarithm to the base 2 of the of the mean + "The base-two logarithm of the mean announceInterval (mean time interval between successive Announce messages)."; } leaf announce-receipt-timeout { type uint8; description "The number of announceInterval that have to pass - without receipt of an announce message before the + without receipt of an Announce message before the occurrence of the event ANNOUNCE_RECEIPT_TIMEOUT_ EXPIRES."; } leaf log-sync-interval { type int8; description - "The logarithm to the base 2 of the mean SyncInterval + "The base-two logarithm of the mean SyncInterval for multicast messages. The rates for unicast transmissions are negotiated separately on a per port - basis."; + basis and are not constrained by this attribute."; } leaf delay-mechanism { type enumeration { enum E2E { value 01; description "The port uses the delay request-response mechanism."; } @@ -691,38 +700,37 @@ enum E2E { value 01; description "The port uses the delay request-response mechanism."; } enum P2P { value 02; description "The port uses the peer delay mechanism."; - } enum DISABLED { value 254; description - "The port does not implement the delay + "The port does not implement any delay mechanism."; } } description "The propagation delay measuring option used by the port in computing meanPathDelay."; } - leaf log-min-Pdelay-req-interval { + leaf log-min-pdelay-req-interval { type int8; description - "The logarithm to the base 2 of the + "The base-two logarithm of the minPdelayReqInterval (minimum permitted mean time interval between successive Pdelay_Req messages)."; } leaf version-number { type uint8; description "The PTP version in use on the port."; } @@ -754,21 +762,21 @@ mechanism."; } enum P2P { value 2; description "The port uses the peer delay mechanism."; } enum DISABLED { value 254; description - "The port does not implement the delay + "The port does not implement any delay mechanism."; } } description "The propagation delay measuring option used by the transparent clock."; } leaf primary-domain { type uint8; default 0; @@ -807,21 +816,21 @@ type int8; description "The logarithm to the base 2 of the minPdelayReqInterval (minimum permitted mean time interval between successive Pdelay_Req messages)."; } leaf faulty-flag { type boolean; default false; description - "Indicates whether the port is faulty."; + " When set, the port is faulty."; } leaf peer-mean-path-delay { type int64; default 0; description "An estimate of the current one-way propagation delay on the link when the delayMechanism is P2P, otherwise it is zero."; } } @@ -947,21 +958,21 @@ [IEEE8021AS] IEEE, "Timing and Synchronizations for Time-Sensitive Applications in Bridged Local Area Networks", IEEE 802.1AS-2001, 2011 [PTP-MIB] Shankarkumar, V., Montini, L., Frost, T., and Dowd, G., "Precision Time Protocol Version 2 (PTPv2) Management Information Base", draft-ietf-tictoc-ptp-mib-11, Work in progress [REST-CONF] Bierman, A., Bjorklund, M., and Watsen, K., "RESTCONF - protocol", draft-ietf-netconf-restconf-17, Work in + protocol", draft-ietf-netconf-restconf-18, Work in progress [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between Information Models and Data Models", RFC 3444, January 2003 [RFC4663] Harrington, D., "Transferring MIB Work from IETF Bridge MIB WG to IEEE 802.1 WG", RFC 4663, September 2006 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. @@ -970,22 +981,22 @@ [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure Shell (SSH)", RFC 6242, June 2011 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration Protocol (NETCONF) Access Control Model", RFC 6536, March 2012 7. Acknowledgments - The authors would like to thank reviews and suggestions from Mahesh - Jethanandani and Tal Mizrahi. + The authors would like to thank Joe Gwinn, Mahesh Jethanandani and + Tal Mizrahi for their valuable reviews and suggestions. Appendix A Transferring YANG Work to IEEE 1588 WG (Informational) This appendix describes a future plan to transition responsibility for IEEE 1588 YANG modules from the IETF TICTOC Working Group (WG) to the IEEE 1588 WG, which develops the time synchronization technology that the YANG modules are designed to manage. This appendix is forward-looking with regard to future standardization roadmaps in IETF and IEEE. Since those roadmaps