Merge "Feature 5651: support of MAC address specification in VNFD"
[osm/IM.git] / 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