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

[Martin Bjorklund <[e-mail]>]

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://www.ietf.org/mailman/listinfo/netmod
>