+/* 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
projects / osm / IM.git / commitdiff