CommsDSL Specification v6.1

It can also contain definition of various common fields that can be referenced by multiple messages. Such fields are defined as children of <fields> node.

There can be multiple <fields> elements in the same schema definition file. The fields are described in detail in Fields chapter.

The definition of a single message is done using <message> node (described in detail in Messages chapter).

Multiple messages can (but don’t have to) be bundled together as children of <messages> node.

Transport framing is defined using <frame> node (described in detail in Frames chapter).

Multiple frames can (but don’t have to) be bundled together as children of <frames> node.

There are protocols that put some information, common to all the messages, such as protocol version and/or extra flags, into the framing information instead of message payload. This information needs to be accessible when message payload is being read or message object is being handled by the application. The COMMS Library handles these cases by having a common interface class for all the messages, which contains this extra information. In order to support such cases, the CommsDSL introduces optional node <interface> (described in detail in Interfaces chapter) for description of such common interfaces.

Multiple interfaces can (but don’t have to) be bundled together as children of <interfaces> node.

All the nodes described above are allowed to appear in any order.

Many schema elements have properties (described in details later) which can contain an actual value or a reference to other field’s value. In most cases it is clear which one it is.

In the example above defaultValue of the I1 is 0. The assignment of the defaultValue of the I2 is referencing value V1 of the E1 <enum> field, which is 10.

However, there can be a case when such distinction is not clear (happens for the <string> field). In such case the reference to external field needs to be prefixed with ^ character.

In the example above both S1 and S2 have the same defaultValue which is hello.

In case of multiple schemas, referencing a field defined in another schema requires prefixing the reference string with @ and schema name:

It is allowed (but not required) to use @ with schema name prefix when referencing fields in the same schema.

In case of using <optional> field conditions the referenced fields are not global ones, but a siblings. Such sibling reference needs to be prefixed with $ character.

Some properties support references to the member fields of an <interface> . Such reference needs to be prefixed with % character.

Use prefix table for future references.

Every field must define it’s name, which is expected to be used by a code generator when defining a relevant class. The name is defined using name property.

It is possible to provide a description of the field about what it is and how it is expected to be used. This description is only for documentation purposes and may find it’s way into the generated code as a comment for the generated class. The property is description.

Sometimes two different fields are very similar, but differ in one particular aspect. CommsDSL allows copying all the properties from previously defined field (using reuse property) and change some of them after the copy. For example:

In the example above member of the bitfield Member1 copies all the properties from SomeIntField field, then overrides its name and adds bitLength one to specify its length in bits.

The reuse is allowed only from the field of the same kind. For example, it is NOT allowed for <enum> field to reuse definition of <int> , only other <enum> .

By default the code generator is expected not to generate code for fields that are not referenced by any message or any other field to reduce amount of generated code. However, there may be cases when a field releated definitions are expected to find their way into the generated code even the field itself is not referenced anywhere. To help with such forcing the forceGen property has been introduced with boolean value.

CommsDSL supports generation of not only field’s serialization and value access functionality, but also of various GUI protocol visualization, debugging and analysis tools. There are some allowed properties, that indicate how the field is expected to be displayed by such tools.

The displayName property is there to specify proper string of the field’s name, with spaces, dots and other characters that are not allowed to exist in the name.

If displayName is not specified, the code generator must use value of property name instead. In order to force empty displayName, use "_" (underscore) value.

Sometimes the values of some fields may be controlled by other fields. In this case, it could be wise to disable manual update of such fields. To enable/disable such behavior use displayReadOnly property with boolean value.

Also sometimes it can be desirable to completely hide some field from being displayed in the protocol analysis GUI application. In this case use displayHidden property with boolean value.

CommsDSL allows providing an information in what version the field was added to a particular message, as well as in what version it was deprecated, and whether it was removed from being serialized after deprecation.

To specify the version in which field was introduced, use sinceVersion property. To specify the version in which the field was deprecated, use deprecated property. To specify whether the field was removed after being deprecated use removed property in addition to deprecated.

In the example above:

NOTE, that all the specified versions mustn’t be greater that the version of the schema. Also value of sinceVersion must be less than value of deprecated.

The version information on the field in global <fields> area or inside some namespace does NOT make sense and should be ignored by the code generator. It is allowed when field is a member of a <message> or a <bundle> field.

Some fields may specify what values are considered to be valid, and there may be a need to fail the read operation in case the received value is invalid.

To achieve this failOnInvalid property with boolean value can be used. There are two main scenarios that may require usage of this property. One is the protocol being implemented requires such behavior in its specification. The second is when there are multiple forms of the same message which are differentiated by the value of some specific field in its payload. For example:

The example above defined 3 variants of the message with numeric ID equals to 1. When new message with this ID comes in, the framing code is expected to try reading all of the variants and choose one, on which read operation doesn’t fail. The order property of the message specifies in what order the messages with the same ID must be read. It described in more detail in Messages chapter.

Sometimes there may be a need to have "psuedo" fields, which are implemented using proper field abstration, and are handled as any other field, but not actually getting serialized when written (or deserialized when read). It can be achieved using pseudo property with boolean value.

The code generator is expected to allow some level of compile time customization of the generated code, such as choosing different data structures and/or adding/replacing some runtime logic. The code generator is also expected to provide command line options to choose required level of customization. Sometimes it may be required to allow generated field abstraction to be customizable regardless of the customization level requested from the code generator. CommsDSL provides customizable property with boolean value to force any field being customizable at compile time.

Sometimes code generator may generate a bit different (or better) code for fields that are used for some particular purpose. To specify such purpose use semanticType property.

Available semantic types are:

In some cases the CommsDSL may be insufficient to express the the protocol definition in correct way. To handle such cases the code generator is expected to allow injection of the custom / overriding code to fix / replace the default implementation produced by the code generator.

The code generator is expected to generate the default code for the following operations:

To ensure visibility and/or help with forcing the injection of the correcting code, the CommsDSL provides the following properties.

The value of the properties above can be one of the following:

In some cases different fields may have the same overriding or any other extra code that needs to be injected. In order to minimize the copy-paste of the code, the CommsDSL introduces the copyCodeFrom property with a reference value indicating another field, overriding code of which needs to be applied to the field being defined.

Note, that copyCodeFrom property is applied before any xOverride ones described in previous section. It means that some portion of copied code can be cleared.

In case of reusing other field definition, only the field definition properties are copied. The extra code that the original field might inject is NOT included in such copy by default. The copying of injected code must be specified explicitly using copyCodeFrom property descirbed above, or to avoid repetition of the reference string, another reuseCode property with boolean value can be used in addition to reuse one.

Use properties table for future references.

Every <enum> field must provide its underlying storage type using type property. Available values are:

The variable length types are encoded using Base-128 form, such as LEB128 for little endian or similar for big endian.

All the valid values must be listed as <validValue> child of the <enum> XML element.

Every <validValue> must define a valid name (using name property) as well as numeric value (using val property), that fits chosen underlying type. The <validValue>-es may be listed in any order, not necessarily sorted.

Every <validValue> has extra optional properties:

All these extra properties are described in detail in Common Properties of Fields.

The default value of the <enum> field when constructed can be specified using defaultValue property. If not specified, defaults to 0.

The default value can also be specified using the name of one of the <validValue>-es:

The default serialization endian of the protocol is specified in endian property of the schema. It is possible to override the default endian value with extra endian property.

The underlying type dictates the serialization length of the <enum> field. However, there may be protocols that limit serialization length of the field to non-standard lengths, such as 3 bytes. In this case use length property to specify custom serialization length.

IMPORTANT: When length property is used with variable length underlying type (intvar and uintvar), it means maximum allowed length.

Some protocols allow (de)serialization of the <enum> field value having less bytes in the buffer than is required by its underlying type serialization. Usually the length of such an <enum> field is specified externally, by the preceding "length" field in TLV (type-length-value) triplet (explained in detail in <variant> Field section). In order to allow code generator to handle such cases use availableLengthLimit property with boolean value.

Note, that the code generator is responsible to allow external limiting serialization length for such fields before write operation takes place.

<enum> field can be a member of <bitfield> field. In this case the serialization length may be specified in bits using bitLength property.

The code generator is expected to generate appropriate enum types using decimal values assigned to enumeration names. However, some protocol specifications may list valid values using hexadecimal format. To make the reading of the generated code more convenient, use hexAssign property with boolean value to force code generator make the assignments using hexadecimal values.

The generated enum type is expected to look something like this:

instead of

By default, non-unqiue values are not allowed, the code generator must report an error if two different <validValue>-es use the same value of the val property. It is done as protection against copy-paste errors. However, CommsDSL allows usage of non-unique values in case nonUniqueAllowed property has been set to true.

The code generator is expected to generate functionality checking that <enum> field contains a valid value. By default any specified <validValue> is considered to be valid regardless of version it was introduced and/or deprecated. However, it is possible to force code generator to generate validity check code that takes into account reported version of the protocol by using validCheckVersion property, which is set to true.

In the example above values 0 and 5 will always be considered valid. However value 10 will be considered valid only if reported protocol version is greater than or equal to 2. The value 15 will be considered valid only for protocol version 3.

Use properties table for future references.

Every <int> field must provide its underlying storage type using type property. Available values are:

The variable length types are encoded using Base-128 form, such as LEB128 for little endian or similar for big endian.

Some protocol may assign a special meaning for some values. For example, some field specifies configuration of some timer duration, when 0 value means infinite. Such values (if exist) must be listed as <special> child of the <int> XML element.

The code generator is expected to generate extra convenience functions that check whether field has special value as well as updating the stored value with special one.

Every <special> must define a valid name (using name property) as well as numeric value (using val property), that fits chosen underlying type. The <special>-s may be listed in any order, not necessarily sorted.

Every <special> has extra optional properties:

All these extra properties are described in detail in Common Properties of Fields.

By default, non-unqiue special values (different name for the same value) are not allowed, the code generator must report an error if two different <special>-es use the same value of the val property. It is done as protection against copy-paste errors. However, CommsDSL allows usage of non-unique values in case nonUniqueSpecialsAllowed property has been set to true.

The default value of the <int> field when constructed can be specified using defaultValue property. If not specified, defaults to 0.

The default value can also be specified using the name of one of the <special>-s:

The default serialization endian of the protocol is specified in endian property of the schema. It is possible to override the default endian value with extra endian property.

The underlying type dictates the serialization length of the <int> field. However there may be protocols, that limit serialization length of the field to non-standard lengths, such as 3 bytes. In this case use length property to specify custom serialization length.

IMPORTANT: When length property is used with variable length underlying types (intvar and uintvar), it means maximum allowed length.

Some protocols allow (de)serialization of the <int> field value having less bytes in the buffer than is required by its underlying type serialization. Usually the length of such an <int> field is specified externally, by the preceding "length" field in TLV (type-length-value) triplet (explained in detail in <variant> Field section). In order to allow code generator to handle such cases use availableLengthLimit property with boolean value.

Note, that the code generator is responsible to allow external limiting serialization length for such fields before write operation takes place.

<int> field can be a member of <bitfield> field. In this case the serialization length may be specified in bits using bitLength property.

Some protocols may require adding/subtracting some value before serialization, and performing the opposite operation when the field is deserialized. Such operation can be forced using serOffset property with numeric value. The classic example would be defining a year field that is being serialized using 1 byte as offset from year 2000. Although it is possible to define such field as 1 byte integer

it is quite inconvenient to work with it in a client code. The client code needs to be aware what offset needs to be added to get the proper year value. It is much better to use serOffset property to manipulate value before and after serialization.

NOTE, that value of serOffset property must fit into the underlying type defined using type property.

When limiting serialization length using length property, the performed read operation is expected to sign extend read signed value. However, such default behavior may be incorrect for some cases, especially when serialization offset is also used. There are protocols that disallow serialization of a negative value. Any signed integer must add predefined offset to make it non-negative first, and only then serialize. The deserialization procedure is the opposite, first deserialize the non-negative value, and then subtract predefined offset to get the real value.

For example, there is an integer field with expected valid values between -8,000,000 and +8,000,000. This range fits into 3 bytes, which are used to serialize such field. Such field is serialized using the following math:

In order to implement such example correctly there is a need to switch off the automatic sign extension when value is deserialized.

NOTE, that signExt property is relevant only for signed types with non-default serialization length.

Some protocols may not support serialization of floating point values, and use scaling instead. It is done by multiplying the original floating point value by some number, dropping the fraction part and serializing the value as integer. Upon reception, the integer value is divided by predefined number to get a proper floating point value.

For example, there is a distance measured in millimeters with precision of 4 digits after decimal point. The value is multiplied by 10,000 and serialized as <int> field. Such scenario is supported by CommsDSL via introduction of scaling property.

NOTE, that format of scaling value is "numerator / denominator". The code generator is expected to define such field like any other <int>, but also provide functions that allow set / get of scaled floating point value.

It is possible to omit the denominator value.

In the example above it is equivalent to having scaling="4/1" defined.

Protocols quite often specify what units are being transfered. The CommsDSL provides units property to specify this information. The code generator may use this information to generate a functionality that allows retrieval of proper value for requested units, while doing all the conversion math internally. Such behavior will allow developers, that use generated protocol code, to focus on their business logic without getting into details on how value was transfered and what units are used by default.

For list of supported units values, refer to appended units table.

Quite often, units and scaling need to be used together. For example

The code generator may generate code that allows retrieval of proper (floating point) value of either degrees or radians, while all the scaling and conversion math is done automatically.

Many protocols specify ranges of values the field is allowed to have and how client code is expected to behave on reception of invalid values. The code generator is expected to generate code that checks whether field’s value is valid. The CommsDSL provides multiple properties to help with such task.

One of such properties if validRange. The format of it’s value is "[min_value, max_value]".

It is possible to have multiple valid ranges for the same field. However XML does NOT allow having multiple attributes with the same name. As the result it is required to put extra valid ranges as <validRange> children elements.

Another property is validValue, which adds single value (not range) to already defined valid ranges / values. Just like with validRange, multiple values need to be added as XML children elements.

There are also validMin and validMax, which specify single numeric value and are equivalent to having
validRange="[provided_min_value, max_value_allowed_by_type]" and
validRange="[min_value_allowed_by_type, provided_max_value]" respectively.

The specified valid ranges and values are allowed to intersect. The code generator may warn about such cases and/or unify them to limit number of if conditions in the generated code for better performance.

If none of the mentioned above validity related options has been used, the whole range of available values is considered to be valid.

All the validity related properties mentioned in this section (validRange, validValue, validMin, and validMax) may also add information about version they were introduced / deprecated in. Adding such information is possible only when the property is defined as XML child element.

The sinceVersion and deprecated properties are described in detail as Common Properties of Fields.

The code generator is expected to generate functionality checking that <int> field contains a valid value. By default if the field’s value is within any of the specified ranges / values, then the it is considered to be valid regardless of version the containing range was introduced and/or deprecated. However, it is possible to force code generator to generate validity check code that takes into account reported version of the protocol by using validCheckVersion property, which is set to true.

Sometimes the <int> field has only one valid value and it must be initialized with it. The defaultValidValue property can be used as a replacement to the combination of defaultValue and validValue ones having to specify the same value:

When scaling information is specified, it is possible to notify GUI analysis tools that value of <int> field should be displayed as scaled floating point number. To do so, use displayDecimals property with numeric value of how many digits need to be displayed after decimal point.

Also when serialization offset is provided, sometimes it may be desirable to display the value in the GUI analysis tool(s) with such offset.

For example, many protocols define some kind of remaining length field when defining a transport frame or other places. Sometimes the value of such field should also include its own length. However, it is much more convenient to work with it, when the retrieved value shows only remaining length of subsequent fields, without worrying whether the value needs to be reduced by the serialization length of holding field, and what exactly this length is. Such field can be defined like this:

In the example above, the field is expected to hold only remaining length, excluding the length of itself, but adding it when value is serialized.

However, when such field is displayed in GUI analysis tool(s), it is desirable to display the value with serialization offset as well. It can be achieved using displayOffset property with numeric value.

When <special> values are specified the protocol analysis tools are expected to display them next to actual numeric value of the field. The displaySpecials property with boolean value is there to control this default behavior.

Use properties table for future references.

The underlying type of the <set> field can be provided its underlying storage type using type property. Available values are:

NOTE that the available types are all fixed length unsigned ones.

The underlying type specification may be omitted if serialization length (in number of bytes) is specified using length property. In this case underlying type is automatically selected based on the provided serialization length.

Some protocols allow (de)serialization of the <set> field value having less bytes in the buffer than is required by its underlying type serialization. Usually the length of such an <set> field is specified externally, by the preceding "length" field in TLV (type-length-value) triplet (explained in detail in <variant> Field section). In order to allow code generator to handle such cases use availableLengthLimit property with boolean value.

Note, that the code generator is responsible to allow external limiting serialization length for such fields before write operation takes place.

<set> field can be a member of <bitfield> field. In this case the serialization length may be specified in bits using bitLength property.

NOTE that the underlying type information can be omitted when bitLength property is in use, just like with length.

The <set> field may list its bits as <bit> XML child elements. Every such element must specify its name using name property as well as its index using idx property.

The bit indexing starts from least significant bit, and mustn’t exceed number of bits allowed by the underlying type. The <bit>-s may be listed in any order, not necessarily sorted.

The code generator is expected to generate convenience functions (or other means) to set / get the value of every listed bit.

Every <bit> element may also define extra properties listed below for better readability:

These properties are described in detail in Common Properties of Fields.

When the <set> field object is default constructed, all bits are initialized to false, i.e. 0. Such default behavior can be modified using defaultValue property with boolean value.

The SomeSetField field from the example above is expected to be initialized to 0xff when default constructed.

The defaultValue may also be specified per-bit, which overrides the defaultValue specified for the whole field.

The SomeSetField field from the example above is expected to be initialized to 0xfe when default constructed.

All the bits that aren’t listed as <bit> XML child elements are considered to be reserved. By default every reserved bit is expected to be zeroed when field is checked to have a valid value. Such expectation can be changed using reservedValue property.

The SomeSetField field from the example above is expected to be initialized to 0xfc and all the reserved (non-listed) bits are expected to remain true.

Reserved bits can also be specified as <bit> XML child element with usage of reserved property with boolean value.

The example above marks bit 2 to be reserved, that is initialized to true and must always stay true.

The SomeSetField field from the example above is expected to be initialized to 0x04 when default constructed.

The default serialization endian of the protocol is specified in endian property of the schema. It is possible to override the default endian value with extra endian property.

By default, having multiple names for the same bit is not allowed, the code generator must report an error if two different <bit>-s use the same value of idx property. It is done as protection against copy-paste errors. However, CommsDSL allows usage of multiple names for the same bit in case nonUniqueAllowed property has been set to true.

In addition to mentioned earlier properties, every <bit> element supports extra ones for versioning:

These extra properties are described in detail in Common Properties of Fields.

The code generator is expected to generate functionality checking that <set> field contains a valid value. Any specified non-reserved bit can have any value, while reserved bits (implicit or explicit) must have value specified by reservedValue property (either of the field or the bit itself). By default, the validity check must ignore the version in which particular bit became reserved / non-reserved, and check only values of the bits that have always stayed reserved. However, it is possible to force code generator to generate validity check code that takes into account reported version of the protocol by using validCheckVersion property, which is set to true.

In the example above bits 0 and 5 will always have valid values. However bit 10 will be considered valid only if it is cleared before version 2, and may have any value after. The bit 15 will be allowed any value when version 3 of the protocol is reported, and must be cleared for any other version.

Use properties table for future references.

Member fields need to be listed as children XML elements of the <bitfield>. Every such member is expected to use bitLength property to specify its serialization length in bits. If it is not specified, then length in bits is calculated automatically as length in bytes multiplied by 8.

NOTE that summary of all the lengths in bits of all the members must be divisible by 8 and mustn’t exceed 64 bits, otherwise the code generator must report an error.

The members of <bitfield> must be listed in order starting from the least significant bit. In the example above SomeIntMember occupies bits [0 - 2], SomeSetMember occupies bits [3 - 5], and SomeEnumMember occupies bits [6 -7].

If there is any other property defined as XML child of the <bitfield>, then all the members must be wrapped in <members> XML element for separation.

When serializing, the <bitfield> object needs to combine the values of all the members into single unsigned raw value of appropriate length, and write the received value using appropriate endian. By default endian of the schema is used, unless it is overridden using extra endian property of the <bitfield> field.

It is possible to replace some of the copied member fields after reuse using <replace> child node, which wraps the replacing fields.

The replacing field must have the same name as the reused member field it is replacing. The <replace> child node may have multiple member fields replacing the copied ones. The order of the fields inside the <replace> child node is not important, the order of the fields is determined by the original <bitfield> field, which was reused.

The example above is equivalent to defining SomeOtherBitfield <bitfield> field in the following way.

Use properties table for future references.

Member fields need to be listed as children XML elements of the <bundle>.

If there is any other property defined as XML child of the <bundle>, then all the members must be wrapped in <members> XML element for separation.

Like any other field, <bundle> supports reuse of any other <bundle>. Such reuse copies all the fields from original <bundle> in addition to all the properties. Any new defined member field gets appended to the copied ones.

In the example above SomeOtherBundle has 3 member fields: F1, F2, and F3.

It is possible to replace some of the copied member fields after reuse using <replace> child node, which wraps the replacing fields.

The replacing field must have the same name as the reused member field it is replacing. The <replace> child node may have multiple member fields replacing the copied ones. The order of the fields inside the <replace> child node is not important, the order of the fields is determined by the original <bundle> field, which was reused.

It is possible to combine <replace>-ing copied member fields and extending the <bundle> with new fields.

The example above is equivalent to defining SomeOtherBundle <bundle> field in the following way.

Sometimes an existing member field may be renamed and/or moved. It is possible to create alias names for the fields to keep the old client code being able to compile and work. Please refer to Aliases chapter for more details.

Use properties table for future references.

The default value of the <string> field when constructed can be specified using defaultValue property. If not specified, defaults to empty string.

In case the string value needs to be serialized using predefined fixed length, use length property to specify the required value.

Many protocols prefix string with its length. The CommsDSL allows definition of such prefix using lengthPrefix child element, which must define prefix as <int> field.

In case the prefix field is defined as external field, CommsDSL allows usage of lengthPrefix as property, value of which contains name of the referenced field.

The CommsDSL also supports detached length prefix, when there are several other fields in the <message> or in the <bundle> between the length field and the <string>.

NOTE, the existence of $ prefix when specifying lengthPrefix value. It indicates that the referenced field is a sibling in the containing <message> or the <bundle> field.

The code generator is expected to take the existence of such detached prefix into account and generate correct code for various field operations (read, write, etc…​).

Some protocols may terminate strings with 0 (zero) byte. The CommsDSL support such cases with existence of zeroTermSuffix property with boolean value.

NOTE, that length, lengthPrefix and zeroTermSuffix properties are mutually exclusive, i.e. cannot be used together.

Use properties table for future references.

The default value of the <data> field when constructed can be specified using defaultValue property. The value of the property must be case-insestive string of hexadecimal values with even number of characters. The allowed ranges of the characters are: [`0' - `9'], and [`a' - `f']. The ' ' (space) character is also allowed for convenient separation of the bytes. If not specified, defaults to empty data.

The example above is expected to create approprate raw data abstracting field, containing 8 bytes: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef] when default constructed.

In case the data value needs to be serialized using predefined fixed length, use length property to specify the required value.

Many protocols prefix raw binary data with its length. The CommsDSL allows definition of such prefix using lengthPrefix child element, which must define prefix as <int> field.

In case the prefix field is defined as external field, CommsDSL allows usage of lengthPrefix as property, value of which contains name of the referenced field.

The CommsDSL also supports detached length prefix, when there are several other fields in the <message> or in the <bundle> between the length field and the <data>.

NOTE, the existence of $ prefix when specifying lengthPrefix value. It indicates that the referenced field is a sibling in the containing <message> or the <bundle> field.

The code generator is expected to take the existence of such detached prefix into account and generate correct code for various field operations (read, write, etc…​).

NOTE, that length and lengthPrefix properties are mutually exclusive, i.e. cannot be used together.

Use properties table for future references.

Every <list> must specify its element field. The element field can be defined as XML child of the <list> definition.

If a list element contains multiple fields, they must be bundled as members of the <bundle> field.

In case other properties of the <list> field are defined as child XML elements, then the element field definition needs to be wrapped by <element> XML child.

The CommsDSL also allows reference of externally defined field to be an element using element property.

If the defined list must contain predefined number of elements, use count property to provide the required information.

Most protocols prefix the variable length lists with number of elements that are going to follow, use countPrefix child XML element to specify a field that is going to be used as such prefix.

In case the count prefix field is defined as external field, CommsDSL allows usage of countPrefix as property, value of which contains name of the referenced field.

The CommsDSL also supports detached count prefix, when there are several other fields in the <message> or in the <bundle> between the count field and the <list>.

NOTE, the existence of $ prefix when specifying countPrefix value. It indicates that the referenced field is a sibling in the containing <message> or the <bundle> field.

The code generator is expected to take the existence of such detached prefix into account and generate correct code for various field operations (read, write, etc…​).

There are protocols that prefix a list with serialization length rather than number of elements. In this case use lengthPrefix instead of countPrefix. The allowed usage scenarios are exactly the same as described above in the Count Prefix section.

There are protocols that use special byte(s) to terminate a list instead of prefixing it with number of elements or serialization length. Specifying termination suffix field is supported using termSuffix property. Just like with countPrefix, and lengthPrefix, the termination suffix can be specified as a child XML node or referenced when defined externally.

The termination suffix is determined by the successful read attempt before attempting to read the list element. It means that the termination suffix field needs to fail its read operation if it’s not encountered. In most cases specifying valid value(s) in conjunction with the failOnInvalid property is sufficient.

NOTE that count, countPrefix, lengthPrefix, and termSuffix properties are mutually exclusive, i.e. cannot be used together.

Some protocols prefix every element with its serialization length for the forward / backward compatibility of the protocol. If there is such need, use elemLengthPrefix to specify a field that will prefix every element of the list.

In case every list element has fixed length and protocol specification doesn’t allow adding extra variable length fields to the element in the future, some protocols prefix only first element in the list with its serialization length. CommsDSL supports such lists with elemFixedLength property, that has boolean value.

The code generator must report an error when element of such list (with elemFixedLength property set to true) has variable length.

Use properties table for future references.

Every <float> field must provide its underlying storage type using type property. Available values are:

Some protocol may set a special meaning for some values. Such values (if exist) must be listed as <special> child of the <float> XML element.

The code generator is expected to generate extra convenience functions that check whether field has special value as well as updating the stored value with special one.

Every <special> must define a valid name (using name property) as well as floating point value (using val property), that fits chosen underlying type. The <special>-s may be listed in any order, not necessarily sorted.

In addition to floating point numbers, the val property may also cantain the following case-insensitive strings.

Every <special> has extra optional properties:

All these extra properties are described in detail in Common Properties of Fields.

By default, non-unqiue special values (different name for the same value) are not allowed, the code generator must report an error if two different <special>-es use the same value of the val property. It is done as protection against copy-paste errors. However, CommsDSL allows usage of non-unique values in case nonUniqueSpecialsAllowed property has been set to true.

The default value of the <float> field when constructed can be specified using defaultValue property. If not specified, defaults to 0.0.

The default value can also be specified using the name of one of the <special>-s:

Just like with special values, the value of the defaultValue property can also be either nan, inf or -inf.

The default serialization endian of the protocol is specified in endian property of the schema. It is possible to override the default endian value with extra endian property.

Protocols quite often specify what units are being transfered. The CommsDSL provides units property to specify this information. The code generator may use this information to generate a functionality that allows retrieval of proper value for requested units, while doing all the conversion math internally. Such behavior will allow developers, that use generated protocol code, to focus on their business logic without getting into details on how value was transfered.

For list of supported units values, refer to appended units table.

Many protocols specify ranges of values the field is allowed to have and how client code is expected to behave on reception of invalid values. The code generator is expected to generate code that checks whether field’s value is valid. The CommsDSL provides multiple properties to help with such task.

One of such properties is validRange. The format of it’s value is "[min_value, max_value]".

It is possible to have multiple valid ranges for the same field. However XML does NOT allow having multiple attributes with the same name. As the result it is required to put extra valid ranges as <validRange> children elements.

Another property is validValue, which adds single value (not range) to already defined valid ranges / values. Just like with validRange, multiple values need to be added as XML children elements.

The validValue property allows adding special values (nan, inf, and -inf) to available valid values / ranges.

There are also validMin and validMax, which specify single floating point value and are equivalent to having
validRange="[provided_min_value, max_value_allowed_by_type]" and
validRange="[min_value_allowed_by_type, provided_max_value]" respectively.

The specified valid ranges and values are allowed to intersect. The code generator may warn about such cases and/or unify them to limit number of if conditions in the generated code for better performance.

If none of the mentioned above validity related options has been used, the whole range of available values is considered to be valid, including extra values nan, inf, and -inf.

In case nan, inf, and -inf need to be excluded from a range of valid values, but all the available floating point values are considered to be valid, then validFullRange property with boolean value needs to be used.

All the validity related properties mentioned in this section (validRange, validValue, validMin, validMax) may also add information about version they were introduced / deprecated in. Adding such information is possible only when the property is defined as XML child element.

The sinceVersion and deprecated properties are described in detail as Common Properties of Fields.

The code generator is expected to generate functionality checking that <float> field contains a valid value. By default if the field’s value is within any of the specified ranges / values, then the it is considered to be valid regardless of version the containing range was introduced and/or deprecated. However, it is possible to force code generator to generate validity check code that takes into account reported version of the protocol by using validCheckVersion property, which is set to true.

When displaying the floating point value, held by the <float> field, GUI analysis tools require knowledge on how many digits after decimal point need to be displayed. To provide this information, use displayDecimals property with numeric value.

If value of displayDecimals is 0, then it is up to the GUI tool to choose how many digits after decimal point to display.

When <special> values are specified the protocol analysis tools are expected to display them next to actual numeric value of the field. The displaySpecials property with boolean value is there to control this default behavior.

Use properties table for future references.

The only extra property the <ref> field has is field to specify a reference to other field.

Since v2 of this specification it is allowed to use <ref> field as member of the <bitfield> field while referencing one of the allowed member types. In such case it is required to use bitLength property to specify length in bits.

Use properties table for future references.

Every <optional> must specify its inner field. The wrapped field can be defined as XML child of the <optional> definition.

In case other properties of the <optional> field are defined as child XML elements, then the element field definition needs to be wrapped by <field> XML child.

The CommsDSL also allows reference of externally defined field to be specified as inner (wrapped) field type using field property.

Every <optional> field has 3 modes: tenative (default), exist, and missing. The exist and missing modes are self explanatory. The tentative mode is there to perform read operation on the inner field only if there are non-consumed bytes left in the input buffer. This mode can be useful with protocols that just add fields at the end of the message in the new version, but the protocol itself doesn’t report its version in any other way.

The default mode of the newly constructed <optional> field can be specified using defaultMode property.

Many protocols introduce optional fields, and the existence of such fields depends on the value of some other field. Classic example would be having some kind of flags field (see <set> ) where some bit specifies whether other field that follows exists or not. Such conditions can be expressed using cond property.

NOTE, that cond property can be used only for <optional> field that is a member of a <bundle> or a <message> . The cond expression specifies condition when the <optional> field exists, and is expected to reference other sibling field. Such reference is always prefixed with $ character to indicate that the field is a sibling of the <optional> and not some external field.

The allowed cond expressions are:

NOTE, that XML doesn’t allow usage of < or > symbols in condition values directly. They need to be substituted with < and > strings respectively.

For example:

The F3 above exists, only if value of F1 is less than value of F2

Deep (nested) conditions are also expected to be supported by the code generator:

When referencing the member of another <optional> field in the existence condition, a check that the wrapping <optional> field exists in addition to the actual specified condition is automatically implied.

Since v6.0 of this specification referencing of the member fields of an <interface> is also supported. Such reference is prefixed with the % character and it works in exactly the same way as the reference to a sibling field described above.