1 /* STANDARD_RIFT_IO_COPYRIGHT */
5 * @author Tim Mortsolf, Anil Gunturu, Tom Seidenberg
7 * @brief RiftWare yang to protobuf conversion extensions
12 namespace "http://riftio.com/ns/riftware-1.0/rw-pb-ext";
19 "RIFT yang extensions for converting yang files to Google
20 Protocol Buffers (protobuf) using rift protoc-c extensions.";
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.
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.";
40 "Change the name of an embedded protobuf message type for this
41 container or list. Allowed values are valid C identifiers.
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
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.";
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.
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.";
68 extension msg-tag-base {
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
75 // ATTN: would really like to specify field-relative in uses!
79 extension msg-tag-reserve {
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.";
89 extension msg-proto-max-size {
92 "Specify the maximum size of this message in the C structure or
93 so in bytes. Allowed values are positive decimal integers.";
96 extension msg-typedef {
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.
103 typename will be appended to the mangeled protobuf package name
104 and an underscore, to ensure name uniqueness across the global
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.";
113 extension field-name {
114 argument "fieldname";
116 "Change the name of the element to fieldname, when converting the
117 object to protobuf. Allowed values are valid C identifiers.
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.";
126 extension field-inline {
127 argument "selection";
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
135 When applied to a container or list statement, this extension is
136 inherited by all enclosed objects, unless overridden.";
139 extension field-inline-max {
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:
150 If 'none' is specified, then the inline_max protobuf extension
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'.
157 If a decimal integer is specified, that number is used as the
160 If this extension is not specified, the behavior defaults to
161 'yang'. Descendant list and leaf-list objects do not inherit
165 extension field-string-max {
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:
183 If 'none' is specified, then the string_max protobuf extension
184 will not be used. 'none' cannot be combined with 'octet' or
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'.
192 If a decimal integer is specified, that number is used as the
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.
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.
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.";
214 extension field-tag {
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.
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
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.
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.
239 If this extension is not specified, the default behavior is
243 extension field-type {
246 "Override the default protobuf field type mapping for a leaf or
247 leaf-list type, and use the specified protobuf type instead.
249 Allowed values are any of the Protobuf scalar types, as
250 restricted by the yang leaf type:
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 |
271 | instance-identifier, | |
273 +---------------------------+-------------------------------+
274 | bits, binary | bytes, auto |
275 +---------------------------+-------------------------------+
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
285 extension field-c-type {
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.";
292 /* ATTN: Stop using this extension? */
293 extension package-name {
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";
303 extension application-request-point {
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
311 extension enum-name {
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.";
321 extension enum-type {
322 argument "enumtypename";
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.";
331 extension file-pbc-include {
332 argument "pathstring";
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.";
340 extension field-merge-behavior {
343 "An extension for controlling the merge done for listy types
344 during upacking of protobuf. It can take 3 different value:
346 1) default: The default is whatever protobuf-c does today
347 (for keyed lists, the default is equivalent to by-keys).
349 2) by-keys: allowed on keyed lists (and leaf-lists): merge
350 elements with matching key.
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.";