Re: [netmod] draft-ietf-tictoc-1588v2-yang-05: port-number

[Rodney Cummings <[e-mail]>]

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:[e-mail]]
> Sent: Monday, October 2, 2017 1:15 PM
> To: Rodney Cummings <[e-mail]>
> Cc: [e-mail]; [e-mail]
> Subject: Re: [netmod] draft-ietf-tictoc-1588v2-yang-05: port-number
> 
> Rodney Cummings <[e-mail]> 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.
> >
> > 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.
> 
> 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).
> 
> > 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.
> 
> 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
> 
> 
> 
> >
> > Feedback is very much appreciated.
> >
> > Thanks folks,
> > Rodney Cummings
> > Co-author draft-ietf-tictoc-1588v2-yang-05
> >
> > _______________________________________________
> > netmod mailing list
> > [e-mail]
> > 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=
> >