models/yang/rw-pb-ext.yang

   1 /* STANDARD_RIFT_IO_COPYRIGHT */
   2
   3 /**
   4  * @file rw-pb-ext.yang
   5  * @author Tim Mortsolf, Anil Gunturu, Tom Seidenberg
   6  * @date 2013/03/21
   7  * @brief RiftWare yang to protobuf conversion extensions
   8  */
   9
  10 module rw-pb-ext
  11 {
  12   namespace "http://riftio.com/ns/riftware-1.0/rw-pb-ext";
  13   prefix "rwpb";
  14
  15   revision 2014-03-28 {
  16     description
  17       "Initial revision.";
  18     reference
  19       "RIFT yang extensions for converting yang files to Google
  20       Protocol Buffers (protobuf) using rift protoc-c extensions.";
  21   }
  22
  23   extension msg-new {
  24     argument "typename";
  25     description
  26       "Generate an equivalent, top-level, protobuf message for this
  27       container, list, rpc input, rpc output, or notification.  The
  28       argument is the name of the protobuf message type.  Allowed
  29       values are valid C identifiers.
  30
  31       The protobuf definition will only be generated when processing
  32       the same module that defines the yang object - a duplicate will
  33       not be generated when importing reusing a yang object via uses,
  34       or when importing the module.";
  35   }
  36
  37   extension msg-name {
  38     argument "typename";
  39     description
  40       "Change the name of an embedded protobuf message type for this
  41       container or list.  Allowed values are valid C identifiers.
  42
  43       In lieu of this extension, embedded protobuf message typenames
  44       are based on the fieldname, and further mangled by removing
  45       underscores and CamelCased at underscore boundaries.  This
  46       extension allows the automatic mangling procedure to be
  47       overridden.
  48
  49       This extension is incompatible with msg-new, which already
  50       defines the typename for top-level messages.  Use this extension
  51       solely for embedded messages.";
  52   }
  53
  54   extension msg-flat {
  55     argument "selection";
  56     description
  57       "Set the protobuf message rw_msgopts flat option on a container
  58       or list statement.  Allowed values are 'true', 'false', and
  59       'auto'.  The default is 'false' for top-level messages, and
  60       'auto' for embedded messages.  If 'auto' is specified, the
  61       behavior is the same as the enclosing container or list.
  62
  63       Unless overridden, this extension effectively applies to all
  64       enclosed descendent container and list statements.  Flatness will
  65       be required by the protobuf compilation step.";
  66   }
  67
  68   extension msg-tag-base {
  69     argument "value";
  70     description
  71       "Specify a base tag value for a container, list, grouping, or
  72       uses statement.  Field tags may be specified relative to this
  73       base.  Allowed values are positive
  74       decimal integers.";
  75     // ATTN:  would really like to specify field-relative in uses!
  76   }
  77
  78 /*
  79   extension msg-tag-reserve {
  80     argument "value";
  81     description
  82       "Reserve space in the tag numbering for future expansion of the
  83       enclosing grouping, container, or choice.  Must be a positive
  84       decimal integer.  Choose carefully, as you cannot increase the
  85       value at a later time.";
  86   }
  87 */
  88
  89   extension msg-proto-max-size {
  90     argument "value";
  91     description
  92       "Specify the maximum size of this message in the C structure or
  93       so in bytes.  Allowed values are positive decimal integers.";
  94   }
  95
  96   extension msg-typedef {
  97     argument "typename";
  98     description
  99       "Create a prototbuf-c message typedef for the original, base
 100       definition of the container, list, grouping, rpc input, rpc
 101       output, or notification.  Allowed values are valid C identifiers.
 102
 103       typename will be appended to the mangeled protobuf package name
 104       and an underscore, to ensure name uniqueness across the global
 105       schema.
 106
 107       The typedef will only be generated when processing
 108       the same module that defines the yang object - a duplicate will
 109       not be generated when importing reusing a yang object via uses,
 110       or when importing the module.";
 111   }
 112
 113   extension field-name {
 114     argument "fieldname";
 115     description
 116       "Change the name of the element to fieldname, when converting the
 117       object to protobuf.  Allowed values are valid C identifiers.
 118
 119       In lieu of this extension, element names will be used as-is, if
 120       possible, or mangled to fit in the C identifier character space
 121       (invalid C identifier characters will be replaced with
 122       underscore).  This extension allows the automatic mangling
 123       procedure to be overridden.";
 124   }
 125
 126   extension field-inline {
 127     argument "selection";
 128     description
 129       "Set the protobuf field 'inline' option on a container, list,
 130       leaf-list, or leaf statement.  Allowed values are 'true',
 131       'false', and 'auto'.  If 'auto' is specified, the behavior is
 132       controlled by the enclosing container or list's protobuf-msg-flat
 133       setting.
 134
 135       When applied to a container or list statement, this extension is
 136       inherited by all enclosed objects, unless overridden.";
 137   }
 138
 139   extension field-inline-max {
 140     argument "limit";
 141     description
 142       "Set the protobuf field 'inline_max' option for list and
 143       leaf-list statements.  Allowed values are a positive decimal
 144       integer, 'yang', or 'none'.  Example limits:
 145
 146         '64'
 147         'yang'
 148         'none'
 149
 150       If 'none' is specified, then the inline_max protobuf extension
 151       will not be used.
 152
 153       If 'yang' is specified, then the number of elements specified in
 154       the yang 'max-elements' statement is used.  If there is no
 155       'max-elements' statement, the behavior defaults to 'none'.
 156
 157       If a decimal integer is specified, that number is used as the
 158       maximum length.
 159
 160       If this extension is not specified, the behavior defaults to
 161       'yang'.  Descendant list and leaf-list objects do not inherit
 162       this extension.";
 163   }
 164
 165   extension field-string-max {
 166     argument "limit";
 167     description
 168       "Set the protobuf field 'string_max' option for a leaf or
 169       leaf-list of type string, binary, leafref, identityref, or
 170       instance-identifier.  Allowed values are a positive decimal
 171       integer, 'yang', or 'none'.  An optional encoding specifier may
 172       also be specified, as octet or utf8, which specifies how
 173       characters are counted.  If specified, the encoding must come
 174       first.  Example limits:
 175
 176         'octet 64'
 177         'utf8 20'
 178         'utf8 yang'
 179         'utf8'
 180         '128'
 181         'none'
 182
 183       If 'none' is specified, then the string_max protobuf extension
 184       will not be used.  'none' cannot be combined with 'octet' or
 185       'utf8'.
 186
 187       If 'yang' is specified, the yang type must be string or binary.
 188       If the yang type includes the length statement, then the
 189       statements maximum length is used as the length.  Otherwise,
 190       behavior defaults to 'none'.
 191
 192       If a decimal integer is specified, that number is used as the
 193       length.
 194
 195       The encoding specifiers are used to determine the actual number
 196       of bytes used in the protobuf extension.  If the 'octet'
 197       specifier is used, then the maximum length is used literally as
 198       the byte length.  If the 'utf8' specified is used, then the
 199       maximum length is considered to be in terms of worst-case UTF-8
 200       characters, in which case the protobuf byte length will actually
 201       be 4 times the specified length.
 202
 203       For string and binary types, the default encoding is 'octet'.
 204       For the remaining types, the default encoding is 'utf8',
 205       reflecting those types fundemental description as XML entities
 206       assumed to be encoded in UTF-8.
 207
 208       If this extension is not specified, then the default is 'yang'
 209       for string and binary, and 'none' for the other types.  This
 210       extension cannot be specified on aggregate objects, and so it
 211       cannot be inherited.";
 212   }
 213
 214   extension field-tag {
 215     argument "value";
 216     description
 217       "Set the protobuf field tag.  Allowed values are a positive
 218       decimal integer, 'auto', a base-relative addition expression, or
 219       a field-relative addition expression.
 220
 221       If a decimal integer is specified, then the tag is set to the
 222       specified number.  You should avoid using this form in a
 223       grouping, because you may not be able to guarantee uniqueness
 224       across all the uses of the group.  However, the syntax will be
 225       allowed.
 226
 227       A base-relative addition expression allows the tag of a field to
 228       be defined in terms of the base tag of an enclosing grouping,
 229       container, list, or uses statement.  The expression has the form
 230       '+NUMBER', where NUMBER is the value to add to the base to derive
 231       the current field's tag.
 232
 233       A field-relative addition expression allows the tag of one field
 234       to be defined in terms of another field.  The expression has the
 235       form 'NAME+NUMBER', where NAME is the name of the other field,
 236       and NUMBER is the value to add to the other fields tag to derive
 237       the current field's tag.
 238
 239       If this extension is not specified, the default behavior is
 240       'auto'.";
 241   }
 242
 243   extension field-type {
 244     argument "type";
 245     description
 246       "Override the default protobuf field type mapping for a leaf or
 247       leaf-list type, and use the specified protobuf type instead.
 248
 249       Allowed values are any of the Protobuf scalar types, as
 250       restricted by the yang leaf type:
 251
 252       +---------------------------+-------------------------------+
 253       | (pseudo) yang leaf type   | (pseudo) protobuf scalar type |
 254       |---------------------------+-------------------------------+
 255       | int8, int16, int32        | int32, sint32, sfixed32, auto |
 256       +---------------------------+-------------------------------+
 257       | int64                     | int64, sint64, sfixed64, auto |
 258       +---------------------------+-------------------------------+
 259       | uint8, uint16, uint32     | uint32, fixed32, auto         |
 260       +---------------------------+-------------------------------+
 261       | uint64                    | uint64, fixed64, auto         |
 262       +---------------------------+-------------------------------+
 263       | decimal                   | uint64, sint64, int64,        |
 264       |                           | fixed64, sfixed64,            |
 265       |                           | float, double, auto           |
 266       +---------------------------+-------------------------------+
 267       | empty, boolean            | bool, auto                    |
 268       +---------------------------+-------------------------------+
 269       | string, leafref,          | string, auto                  |
 270       | identityref,              |                               |
 271       | instance-identifier,      |                               |
 272       | anyxml                    |                               |
 273       +---------------------------+-------------------------------+
 274       | bits, binary              | bytes, auto                   |
 275       +---------------------------+-------------------------------+
 276
 277       If 'auto' is specified, the default conversion will be used.  The
 278       protobuf pseudo-type utf8 is equivalent to string, except that
 279       length limits will be adjusted in protobuf extentions to allow
 280       the string to be composed entirely of the maximum sized UTF-8
 281       multibyte characters (byte length is 4 times larger than the
 282       character length).";
 283   }
 284
 285   extension field-c-type {
 286     argument "type";
 287     description
 288       "Override the default protoc-c C-language type mapping for a leaf
 289       or leaf-list type, and use the specified C type instead.";
 290   }
 291
 292   /* ATTN: Stop using this extension? */
 293   extension package-name {
 294     argument "pkgname";
 295     description
 296       "Specifies the name of the package name in the generated .proto
 297       file on a module statement The argument is the name of the
 298       package-name.  Allowed values are valid C identifiers When
 299       package-name is not specified the generated package name defaults
 300       to the Yang module name";
 301   }
 302
 303   extension application-request-point {
 304     description
 305       "This extension is used temporarily until the config and data portions
 306        are split into different namespaces and keyspecs. This allows
 307        applications to provide data at a keyspec, and request config at a
 308        different level";
 309   }
 310
 311   extension enum-name {
 312     argument "enumname";
 313     description
 314       "Use the specified name for the enum enumerator in the .proto
 315       instead of the default mangled name of the yang identifer.
 316       If there is a name conflict with other enum name either specified
 317       explicitly or generated one, the yangpbc conversion will fail.
 318       Allowed values are valid C identifiers.";
 319   }
 320
 321   extension enum-type {
 322     argument "enumtypename";
 323     description
 324       "Use the specified name for the enum type in the .proto instead
 325       of the default mangled name of the yang identifier.  If there is
 326       a name conflict with another enum type, either auto-generated or
 327       explicitly specified one, the yangpbc conversion will fail.
 328       Allowed values are valid C identifiers.";
 329   }
 330
 331   extension file-pbc-include {
 332     argument "pathstring";
 333     description
 334       "A module level extension to specify the include files for pb-c.h
 335       when any rift specific c-types are used.  This extension can
 336       occur multiple times as a child of module statement.  The value
 337       should be a valid path string.";
 338   }
 339
 340   extension field-merge-behavior {
 341     argument "value";
 342     description
 343       "An extension for controlling the merge done for listy types
 344        during upacking of protobuf. It can take 3 different value:
 345
 346        1) default: The default is whatever protobuf-c does today
 347           (for keyed lists, the default is equivalent to by-keys).
 348
 349        2) by-keys: allowed on keyed lists (and leaf-lists): merge
 350           elements with matching key.
 351
 352        3) none: allowed on keyed lists (and leaf-lists): do not
 353           attempt to merge elements. This must ONLY be used when it
 354           is known or expected that the proto message would contain
 355           large number of list items.";
 356   }
 357
 358 } // rw-pb-ext