/* STANDARD_RIFT_IO_COPYRIGHT */ /** * @file rw-pb-ext.yang * @author Tim Mortsolf, Anil Gunturu, Tom Seidenberg * @date 2013/03/21 * @brief RiftWare yang to protobuf conversion extensions */ module rw-pb-ext { namespace "http://riftio.com/ns/riftware-1.0/rw-pb-ext"; prefix "rwpb"; revision 2014-03-28 { description "Initial revision."; reference "RIFT yang extensions for converting yang files to Google Protocol Buffers (protobuf) using rift protoc-c extensions."; } extension msg-new { argument "typename"; description "Generate an equivalent, top-level, protobuf message for this container, list, rpc input, rpc output, or notification. The argument is the name of the protobuf message type. Allowed values are valid C identifiers. The protobuf definition will only be generated when processing the same module that defines the yang object - a duplicate will not be generated when importing reusing a yang object via uses, or when importing the module."; } extension msg-name { argument "typename"; description "Change the name of an embedded protobuf message type for this container or list. Allowed values are valid C identifiers. In lieu of this extension, embedded protobuf message typenames are based on the fieldname, and further mangled by removing underscores and CamelCased at underscore boundaries. This extension allows the automatic mangling procedure to be overridden. This extension is incompatible with msg-new, which already defines the typename for top-level messages. Use this extension solely for embedded messages."; } extension msg-flat { argument "selection"; description "Set the protobuf message rw_msgopts flat option on a container or list statement. Allowed values are 'true', 'false', and 'auto'. The default is 'false' for top-level messages, and 'auto' for embedded messages. If 'auto' is specified, the behavior is the same as the enclosing container or list. Unless overridden, this extension effectively applies to all enclosed descendent container and list statements. Flatness will be required by the protobuf compilation step."; } extension msg-tag-base { argument "value"; description "Specify a base tag value for a container, list, grouping, or uses statement. Field tags may be specified relative to this base. Allowed values are positive decimal integers."; // ATTN: would really like to specify field-relative in uses! } /* extension msg-tag-reserve { argument "value"; description "Reserve space in the tag numbering for future expansion of the enclosing grouping, container, or choice. Must be a positive decimal integer. Choose carefully, as you cannot increase the value at a later time."; } */ extension msg-proto-max-size { argument "value"; description "Specify the maximum size of this message in the C structure or so in bytes. Allowed values are positive decimal integers."; } extension msg-typedef { argument "typename"; description "Create a prototbuf-c message typedef for the original, base definition of the container, list, grouping, rpc input, rpc output, or notification. Allowed values are valid C identifiers. typename will be appended to the mangeled protobuf package name and an underscore, to ensure name uniqueness across the global schema. The typedef will only be generated when processing the same module that defines the yang object - a duplicate will not be generated when importing reusing a yang object via uses, or when importing the module."; } extension field-name { argument "fieldname"; description "Change the name of the element to fieldname, when converting the object to protobuf. Allowed values are valid C identifiers. In lieu of this extension, element names will be used as-is, if possible, or mangled to fit in the C identifier character space (invalid C identifier characters will be replaced with underscore). This extension allows the automatic mangling procedure to be overridden."; } extension field-inline { argument "selection"; description "Set the protobuf field 'inline' option on a container, list, leaf-list, or leaf statement. Allowed values are 'true', 'false', and 'auto'. If 'auto' is specified, the behavior is controlled by the enclosing container or list's protobuf-msg-flat setting. When applied to a container or list statement, this extension is inherited by all enclosed objects, unless overridden."; } extension field-inline-max { argument "limit"; description "Set the protobuf field 'inline_max' option for list and leaf-list statements. Allowed values are a positive decimal integer, 'yang', or 'none'. Example limits: '64' 'yang' 'none' If 'none' is specified, then the inline_max protobuf extension will not be used. If 'yang' is specified, then the number of elements specified in the yang 'max-elements' statement is used. If there is no 'max-elements' statement, the behavior defaults to 'none'. If a decimal integer is specified, that number is used as the maximum length. If this extension is not specified, the behavior defaults to 'yang'. Descendant list and leaf-list objects do not inherit this extension."; } extension field-string-max { argument "limit"; description "Set the protobuf field 'string_max' option for a leaf or leaf-list of type string, binary, leafref, identityref, or instance-identifier. Allowed values are a positive decimal integer, 'yang', or 'none'. An optional encoding specifier may also be specified, as octet or utf8, which specifies how characters are counted. If specified, the encoding must come first. Example limits: 'octet 64' 'utf8 20' 'utf8 yang' 'utf8' '128' 'none' If 'none' is specified, then the string_max protobuf extension will not be used. 'none' cannot be combined with 'octet' or 'utf8'. If 'yang' is specified, the yang type must be string or binary. If the yang type includes the length statement, then the statements maximum length is used as the length. Otherwise, behavior defaults to 'none'. If a decimal integer is specified, that number is used as the length. The encoding specifiers are used to determine the actual number of bytes used in the protobuf extension. If the 'octet' specifier is used, then the maximum length is used literally as the byte length. If the 'utf8' specified is used, then the maximum length is considered to be in terms of worst-case UTF-8 characters, in which case the protobuf byte length will actually be 4 times the specified length. For string and binary types, the default encoding is 'octet'. For the remaining types, the default encoding is 'utf8', reflecting those types fundemental description as XML entities assumed to be encoded in UTF-8. If this extension is not specified, then the default is 'yang' for string and binary, and 'none' for the other types. This extension cannot be specified on aggregate objects, and so it cannot be inherited."; } extension field-tag { argument "value"; description "Set the protobuf field tag. Allowed values are a positive decimal integer, 'auto', a base-relative addition expression, or a field-relative addition expression. If a decimal integer is specified, then the tag is set to the specified number. You should avoid using this form in a grouping, because you may not be able to guarantee uniqueness across all the uses of the group. However, the syntax will be allowed. A base-relative addition expression allows the tag of a field to be defined in terms of the base tag of an enclosing grouping, container, list, or uses statement. The expression has the form '+NUMBER', where NUMBER is the value to add to the base to derive the current field's tag. A field-relative addition expression allows the tag of one field to be defined in terms of another field. The expression has the form 'NAME+NUMBER', where NAME is the name of the other field, and NUMBER is the value to add to the other fields tag to derive the current field's tag. If this extension is not specified, the default behavior is 'auto'."; } extension field-type { argument "type"; description "Override the default protobuf field type mapping for a leaf or leaf-list type, and use the specified protobuf type instead. Allowed values are any of the Protobuf scalar types, as restricted by the yang leaf type: +---------------------------+-------------------------------+ | (pseudo) yang leaf type | (pseudo) protobuf scalar type | |---------------------------+-------------------------------+ | int8, int16, int32 | int32, sint32, sfixed32, auto | +---------------------------+-------------------------------+ | int64 | int64, sint64, sfixed64, auto | +---------------------------+-------------------------------+ | uint8, uint16, uint32 | uint32, fixed32, auto | +---------------------------+-------------------------------+ | uint64 | uint64, fixed64, auto | +---------------------------+-------------------------------+ | decimal | uint64, sint64, int64, | | | fixed64, sfixed64, | | | float, double, auto | +---------------------------+-------------------------------+ | empty, boolean | bool, auto | +---------------------------+-------------------------------+ | string, leafref, | string, auto | | identityref, | | | instance-identifier, | | | anyxml | | +---------------------------+-------------------------------+ | bits, binary | bytes, auto | +---------------------------+-------------------------------+ If 'auto' is specified, the default conversion will be used. The protobuf pseudo-type utf8 is equivalent to string, except that length limits will be adjusted in protobuf extentions to allow the string to be composed entirely of the maximum sized UTF-8 multibyte characters (byte length is 4 times larger than the character length)."; } extension field-c-type { argument "type"; description "Override the default protoc-c C-language type mapping for a leaf or leaf-list type, and use the specified C type instead."; } /* ATTN: Stop using this extension? */ extension package-name { argument "pkgname"; description "Specifies the name of the package name in the generated .proto file on a module statement The argument is the name of the package-name. Allowed values are valid C identifiers When package-name is not specified the generated package name defaults to the Yang module name"; } extension application-request-point { description "This extension is used temporarily until the config and data portions are split into different namespaces and keyspecs. This allows applications to provide data at a keyspec, and request config at a different level"; } extension enum-name { argument "enumname"; description "Use the specified name for the enum enumerator in the .proto instead of the default mangled name of the yang identifer. If there is a name conflict with other enum name either specified explicitly or generated one, the yangpbc conversion will fail. Allowed values are valid C identifiers."; } extension enum-type { argument "enumtypename"; description "Use the specified name for the enum type in the .proto instead of the default mangled name of the yang identifier. If there is a name conflict with another enum type, either auto-generated or explicitly specified one, the yangpbc conversion will fail. Allowed values are valid C identifiers."; } extension file-pbc-include { argument "pathstring"; description "A module level extension to specify the include files for pb-c.h when any rift specific c-types are used. This extension can occur multiple times as a child of module statement. The value should be a valid path string."; } extension field-merge-behavior { argument "value"; description "An extension for controlling the merge done for listy types during upacking of protobuf. It can take 3 different value: 1) default: The default is whatever protobuf-c does today (for keyed lists, the default is equivalent to by-keys). 2) by-keys: allowed on keyed lists (and leaf-lists): merge elements with matching key. 3) none: allowed on keyed lists (and leaf-lists): do not attempt to merge elements. This must ONLY be used when it is known or expected that the proto message would contain large number of list items."; } } // rw-pb-ext