Subject: [TICTOC] Benjamin Kaduk's Discuss on draft-ietf-tictoc-1588v2-yang-10: (with DISCUSS and COMMENT)

From: Benjamin Kaduk <[email-masked]>
Date: Thu, 11 Oct 2018 06:51:02 -0700

Benjamin Kaduk has entered the following ballot position for
draft-ietf-tictoc-1588v2-yang-10: Discuss

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/

----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

I appreciate that there has been some previous work in this area, but it
seems that there are still many instances of bare integral types with no
indication of what units are used to report a numerical value, whether
larger or smaller priority values indicate a more preferred status, how the
sign of an "offset" measurement should be interpreted, etc.  This leaves
the specification unimplementable in an interoperable way.  A (possibly
incomplete) list of such values includes:

clock-class (is this really more like an enum than an int?)
clock-accuracy (ditto?)
offset-scaled-log-variance
priority1 (are small or large values more-preferred?)
priority2 (ditto)
offset-from-master (interpretation of sign bit)
observed-parent-offset-scaled-log-variance
observed-parent-clock-phase-change-rate
grandmaster-priority1
grandmaster-priority2
current-utc-offset (sign bit)
time-source (is this more like an enum?)
log-min-delay-req-interval (units have to be scaled out before log operation)
log-announce-intervale (ditto)
log-sync-interval (ditto)
log-min-pdelay-req-interval (ditto, two different nodes)

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Section 1

   o  When the IEEE 1588 standard is revised (e.g. the IEEE 1588
   revision in progress at the time of writing this document), it will
   add some new optional features to its data sets.  The YANG module
   of this document MAY be revised and extended to support these new
   features. Moreover, the YANG "revision" SHOULD be used to indicate
   changes to the YANG module under such a circumstance.

It's not clear that a 2119 SHOULD is best here; I would have expected
either an 8174 "should" or a 2119 "MUST".

Section 3

time-interval-type says "units of nanoseconds and multiplied by 2^16".
I assume I'm interperting that wrong, since there doesn't seem to be much
point in claiming a precision in yoctoseconds.

Most "log" values specify the "base-two logarithm", but
offsetScaledLogVariance has a much more vague description.  Lacking access
to IEEE 1588-2008, I can't tell if it is possible to be more precise for
describing this field.  (Also, you can only take the log of a dimensionless
quantity, so the input units need to be specified, per my Discuss.)

> slave-only clock

So we had this long discussion on [email-masked] about potentially offensive
terminology, including "master"/"slave".

We have leap59/leap61; might we need a leap62?

Section 4

(I guess you don't need to talk about sensitive ro nodes when all the nodes
are under the sensitive rw nodes already mentioned.)

---

From: Jiangyuanlong <[email-masked]>
Date: Fri, 12 Oct 2018 14:26:08 +0000

Hi Ben,

I think all the questions on terminologies or units are mainly triggered due to the lack of access to the IEEE 1588-2008 standard. They are defined there (with much more details and explanations) and have been used widely in the industry for quite a long time. 
Perhaps Karen can help to make an arrangement with the IEEE 1588 WG, so that some electronic copies of IEEE 1588-2008 can be sent to the reviewers in the IETF.

Please see my further replies prefixed with [YJ]. 
Thanks much for the review and comments.

Regards,
Yuanlong

----------------Snipped----------------------------
> https://datatracker.ietf.org/doc/draft-ietf-tictoc-1588v2-yang/
[YJ] Are you suggesting to use "must" or "MUST"? Otherwise, I think "should" is similar to "SHOULD".

> terminology, including "master"/"slave".
[YJ] Are you suggesting to change the terminologies? These are well accepted terms in the IEEE 1588, people there will be much confused if terms are changed.

> We have leap59/leap61; might we need a leap62?
[YJ] A leap second is a one-second adjustment that is occasionally applied to Coordinated Universal Time (UTC) in order to keep its time of day close to the mean solar time (UT1). Thus, only 59 or 61 is possible (i.e., 1 second ahead or backward), and we don't need a leap62 or any other bigger leaps.

> are under the sensitive rw nodes already mentioned.)
[YJ] No, we don't talk about any read-only nodes in Section 4.

---

From: Benjamin Kaduk <[email-masked]>
Date: Fri, 12 Oct 2018 09:37:48 -0500

> I think all the questions on terminologies or units are mainly triggered due to the lack of access to the IEEE 1588-2008 standard. They are defined there (with much more details and explanations) a…

Indeed, this topic is quite related to Ben's point about document access.
Though I think generally we still want our documents to be able to stand
alone in some sense, so there's a balance to find.

> Please see my further replies prefixed with [YJ]. 

Thanks.  My apologies for some of the incomplete/incoherent comments;
I had to stop mid-review and forgot to do a cleanup pass before balloting.
Thank you for doing your best to pick out what I was trying to say!

> [YJ] Are you suggesting to use "must" or "MUST"? Otherwise, I think "should" is similar to "SHOULD".

I was suggesting "MUST".

> [YJ] Are you suggesting to change the terminologies? These are well accepted terms in the IEEE 1588, people there will be much confused if terms are changed.

I'm not suggesting to change it, no.  There's a tradeoff to make when the
existing terms are well-known already, and this is not the right place to
start to make a change, especially since we don't have an IETF consensus
position yet.

> [YJ] A leap second is a one-second adjustment that is occasionally applied to Coordinated Universal Time (UTC) in order to keep its time of day close to the mean solar time (UT1). Thus, only 59 or…

I had done some more research after I wrote this note (which was supposed
to just be a note to myself, sorry).  I guess ANSI C has some confusing
text in it (viz.
https://groups.google.com/forum/#!topic/comp.protocols.time.ntp/HvZBLs413ng)
and this confusion has been hard to stamp out.

> [YJ] No, we don't talk about any read-only nodes in Section 4.

Thanks,

Benjamin

---

From: Jiangyuanlong <[email-masked]>
Date: Mon, 15 Oct 2018 16:21:48 +0000

> alone in some sense, so there's a balance to find.
[YJ] I agree with you that there is a balance to find. Actually, there have been quite a few discussions happened in the mailing list of TICTOC WG regarding whether we add more details to the terms in the document, the IEEE 1588 participants strongly advised we refer to the IEEE 1588 terminologies and keep the texts as simple as possible in the draft. Since the targeted readers are mainly implementers and operators of IEEE 1588 community, and the YANG module will be transferred to the IEEE 1588 WG as in our plan, I hope the balance will be somewhat more tilted towards them;) 

> "should" is similar to "SHOULD".
[YJ] How about change "MAY" to "can", and "SHOULD" to "MUST" in the above bullet? Hopefully the new changes indicate a stronger expectation.

Thanks,
Yuanlong

---

From: Benjamin Kaduk <[email-masked]>
Date: Tue, 16 Oct 2018 10:07:22 -0500

> [YJ] I agree with you that there is a balance to find. Actually, there have been quite a few discussions happened in the mailing list of TICTOC WG regarding whether we add more details to the terms…

Ah, thanks for the extra background from the WG.  I am interested to see
how Ben's Discuss gets resolved, which may end up doing enough for me to be
able to resolve mine as a side effect.

> [YJ] How about change "MAY" to "can", and "SHOULD" to "MUST" in the above bullet? Hopefully the new changes indicate a stronger expectation.

They do, thanks!

-Benjamin