Subject: [TICTOC] draft-ietf-tictoc-1588v2-yang-05: port-number

From: Rodney Cummings <[email-masked]>
Date: Mon, 2 Oct 2017 17:34:06 +0000

Hi folks,

One of the last topics that we need to resolve for WG Last Call of draft-ietf-tictoc-1588v2-yang-05 is the representation of port-number, which serves as the key to the list of 1588 port data sets (i.e. port-list). I've had some offline discussion with IEEE 1588 WG members, and I'm copying NETMOD members for YANG expertise.

I think we can narrow the possible options to two, so I'm starting a new thread to focus on those.

IEEE Std 1588-2008 is the time sync standard that specifies the information model on which draft-ietf-tictoc-1588v2-yang-05 is based. In IEEE Std 1588-2008, subclause 5.3.5 specifies the following data type to identify each logical port in the 1588 product:
   struct PortIdentity {
      ClockIdentity clockIdentity;
      Uinteger16 portNumber;
   };
IEEE Std 1588-2008 uses this data type as the "portIdentity" of the port in its on-the-wire protocol, state machines, and so on. In other words, in the 1588 standard itself, portIdentity is a "real thing" with real implementation.
 
IEEE Std 1588-2008 also specifies a list of logical ports in each "clock", and portIdentity.portNumber is used as the key to that list of ports.

In the YANG of draft-ietf-tictoc-1588v2-yang-05, we use YANG-style names (e.g. port-list, port-number), but otherwise we've tried to keep consistent to the IEEE Std 1588-2008 information model.

We have a challenge with port-number. If YANG represents port-identity as a container within port-list, YANG does not allow a key to be a leaf within a container, so we cannot use port-identity/port-number as the key to port-list.

It seems that we have two options:

Option 1: Use a leafref
---

YANG summary:

        list port-ds-list {
          key "port-number";
          leaf port-number {
            type uint16;
          }
          container port-identity {
             leaf clock-identity {
                type clock-identity-type;
                config false;
             }
             leaf port-number {
                type leafref{
                   path "../../port-number";
                }
                config false;
             }
          }
        }

This has disadvantages from the YANG perspective, in that port-number is duplicated. The "config false" is intended to mitigate YANG implementation challenges, such that only one value of port-number is provided for configuration.

Option 2: Use a grouping
---

YANG summary:

     grouping port-identity-grouping {
       leaf clock-identity {
         type clock-identity-type;
       }
       leaf port-number {
         type uint16;
       }
     }
     list port-ds-list {
       key "port-number";
       uses port-identity-grouping;
     }

This has disadvantages from the 1588 perspective, in that it is not possible for a 1588-aware management client to "get" portIdentity. We are removing a 1588 "real thing" from the data model in order to accommodate a syntax limitation of YANG. 

Question for NETMOD experts
---

My personal preference is Option 1 (leafref). Nevertheless, if the "config false" does not provide sufficient mitigation for today's YANG implementations, we can go with Option 2. 

Feedback is very much appreciated.

Thanks folks,
Rodney Cummings
Co-author draft-ietf-tictoc-1588v2-yang-05

---

From: Martin Bjorklund <[email-masked]>
Date: Mon, 02 Oct 2017 20:14:30 +0200 (CEST)

Rodney Cummings <[email-masked]> wrote:
> Hi folks,
> 
> One of the last topics that we need to resolve for WG Last Call of
> draft-ietf-tictoc-1588v2-yang-05 is the representation of port-number,
> which serves as the key to the list of 1588 port data sets
> (i.e. port-list). I've had some offline discussion with IEEE 1588 WG
> members, and I'm copying NETMOD members for YANG expertise.
> 
> IEEE Std 1588-2008 is the time sync standard that specifies the
> information model on which draft-ietf-tictoc-1588v2-yang-05 is
> based. In IEEE Std 1588-2008, subclause 5.3.5 specifies the following
> data type to identify each logical port in the 1588 product:
>    struct PortIdentity {
> IEEE Std 1588-2008 uses this data type as the "portIdentity" of the
> port in its on-the-wire protocol, state machines, and so on. In other
> words, in the 1588 standard itself, portIdentity is a "real thing"
> with real implementation.
>  
> IEEE Std 1588-2008 also specifies a list of logical ports in each
> "clock", and portIdentity.portNumber is used as the key to that list
> of ports.
> 
> In the YANG of draft-ietf-tictoc-1588v2-yang-05, we use YANG-style
> names (e.g. port-list, port-number), but otherwise we've tried to keep
> consistent to the IEEE Std 1588-2008 information model.
> 
> We have a challenge with port-number. If YANG represents port-identity
> as a container within port-list, YANG does not allow a key to be a
> leaf within a container, so we cannot use port-identity/port-number as
> the key to port-list.
> 
> This has disadvantages from the YANG perspective, in that port-number
> is duplicated. The "config false" is intended to mitigate YANG
> implementation challenges, such that only one value of port-number is
> provided for configuration.
> 
> Option 2: Use a grouping
> ---
> 
> YANG summary:
> 
> This has disadvantages from the 1588 perspective, in that it is not
> possible for a 1588-aware management client to "get" portIdentity. We
> are removing a 1588 "real thing" from the data model in order to
> accommodate a syntax limitation of YANG.

I think that in general when you go from an information model to a
concrete data model, you need to adapt to the data modelling language
you are using, and this will in most cases mean that there will be
some differences; in some cases the data model structure is different,
and in some cases the data model will result in a more detailed
model.  How keys are specified is one such example.  If you were to
use SMIv2, you'd have to change the names (so that they are unique),
and you'd have to map the structures to conceptual tables.

Clients need to understand the data model in use (not just the
information model behid it).

> My personal preference is Option 1 (leafref). Nevertheless, if the
> "config false" does not provide sufficient mitigation for today's YANG
> implementations, we can go with Option 2.

I don't think any implementation would have any problem supporting
option 1, but it does look a bit odd.  Also, it only "helps" if the
client is getting the data using <get>, but it will not help if it is
using <get-config>.

I think that the cleanest solution is to not try to completely mimic
the structure from the information model, but make sure that the
text in the description statements make it clear that the data model
looks different compared to the information model, in order to help
the readers.

/martin

> _______________________________________________
> netmod mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/netmod
>

---

From: Rodney Cummings <[email-masked]>
Date: Tue, 3 Oct 2017 18:24:17 +0000

Thanks Martin,

Your rationale sounds reasonable to me. We can use the description to
explain differences in the models for the reader. 

Your rationale got me thinking a bit about clock-identity. The 1588
information model and protocol uses clock-identity as a member of
port-identity (along with port-number). Nevertheless, that
instance-list[instance-number]/port-identity/clock-identity 
is equivalent to instance-list[instance-number]/clock-identity
(part of grouping default-ds-entry in draft-ietf-tictoc-1588v2-yang-05).
So... we are currently repeating clock-identity as we repeated
port-number. If we apply your rationale, we can remove that
repetition as well.

I propose that we go with Option 2, but without using a grouping,
and use the same approach for clock-identity. 

This would look like:

list port-ds-list {
   key "port-number";
   leaf port-number {
      description 
         "Port number.
          
         The data sets (i.e. information model) of IEEE Std 1588-2008
         specify a member portDS.portIdentity, which uses a typed 
         struct with members clockIdentity and portNumber.

         In this YANG data model, portIdentity is not provided as
         a container, but both of its members are provided as a leaf.
         portIdentity.portNumber is provided as this port-number leaf
         in YANG. portIdentity.clockIdentity is provided as the
         clock-identity leaf in the instance (i.e. ../../clock-identity).";
      type uint16;
   }
}

Rodney

> -----Original Message-----
> From: Martin Bjorklund [mailto:[email-masked]]
> Sent: Monday, October 2, 2017 1:15 PM
> To: Rodney Cummings <[email-masked]>
> Cc: [email-masked]; [email-masked]
> Subject: Re: [netmod] draft-ietf-tictoc-1588v2-yang-05: port-number
> 
> > https://urldefense.proofpoint.com/v2/url?u=https-
> 3A__www.ietf.org_mailman_listinfo_netmod&d=DwICAg&c=I_0YwoKy7z5LMTVdyO6YCi
> E2uzI1jjZZuIPelcSjixA&r=WA71sf2o7Dw7CbYhFt24DPjt3lJuupswWYdnboKbZ8k&m=HQ-
> S1mMpOcwPGLxrc9fTcSPc3vMBTRPINVlW5icLVhI&s=vW2fbaZlyBrALsCxc0EC961aVU3t5gm
> DrURSXdnPR8A&e=
> >