Skip to content

Latest commit

 

History

History
282 lines (265 loc) · 10 KB

enum.adoc

File metadata and controls

282 lines (265 loc) · 10 KB

<enum> Field

This field stores and abstracts away value of integral enumerated type, where every valid value has its name. The <enum> field has all the common properties as well as extra properties and elements described below.

Underlying Type

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

  • int8 - 1 byte signed integer.

  • uint8 - 1 byte unsigned integer.

  • int16 - 2 bytes signed integer.

  • uint16 - 2 bytes unsigned integer.

  • int32 - 4 bytes signed integer.

  • uint32 - 4 bytes unsigned integer.

  • int64 - 8 bytes signed integer.

  • uint64 - 8 bytes unsigned integer.

  • intvar - up to 8 bytes variable length signed integer

  • uintvar - up to 8 bytes variable length unsigned integer

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <enum name="SomeEnumField" type="uint8">
            ...
        </enum>
    </fields>
</schema>

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

Valid Values

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

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <enum name="SomeEnumField" type="uint8">
            <validValue name="Val1" val="0" />
            <validValue name="Val2" val="5" />
            <validValue name="Val3" val="0x1b" />
        </enum>
    </fields>
</schema>

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:

  • description - Extra description and documentation on how to use the value.

  • displayName - Human readable name of the value.

  • sinceVersion - Version of the protocol when the value was introduced.

  • deprecated - Version of the protocol when the value was deprecated.

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

Default Value

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

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <enum name="SomeEnumField" type="uint8" defaultValue="5">
            <validValue name="Val1" val="0" />
            <validValue name="Val2" val="5" />
            <validValue name="Val3" val="0x1b" />
        </enum>
    </fields>
</schema>

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

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <enum name="SomeEnumField" type="uint8" defaultValue="Val2">
            <validValue name="Val1" val="0" />
            <validValue name="Val2" val="5" />
            <validValue name="Val3" val="0x1b" />
        </enum>
    </fields>
</schema>

Endian

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.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    <fields>
        <enum name="SomeEnumField" type="uint16" endian="little">
            <validValue name="Val1" val="0" />
            <validValue name="Val2" val="5" />
            <validValue name="Val3" val="0x1b" />
        </enum>
    </fields>
</schema>

Serialization Length

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.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    <fields>
        <enum name="SomeEnumField" type="uint32" length="3">
            <validValue name="Val1" val="0x0" />
            <validValue name="Val2" val="0x0a0b0c" />
            <validValue name="Val3" val="0xffffff" />
        </enum>
    </fields>
</schema>

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.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    <fields>
        <enum name="SomeEnumField" type="uint32" availableLengthLimit="true">
            <validValue name="Val1" val="0x0" />
            <validValue name="Val2" val="0x0a0b" />
            <validValue name="Val3" val="0xffffff" />
        </enum>
    </fields>
</schema>

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

Length in Bits

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

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    <fields>
        <bitfield name="SomeBitfield">
            <enum name="SomeEnumMember" type="uint8" bitLength="3">
                <validValue name="Val1" val="0" />
                <validValue name="Val2" val="1" />
                <validValue name="Val3" val="2" />
            </enum>

            <enum name="SomeOtherEnumMember" type="uint8" bitLength="5">
                <validValue name="Val1" val="5" />
                <validValue name="Val2" val="12" />
                <validValue name="Val3" val="20" />
            </enum>
        </bitfield>
    </fields>
</schema>

Hex Assignment

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.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    <fields>
        <enum name="SomeEnumField" type="uint8" hexAssign="true">
            <validValue name="Val1" val="0" />
            <validValue name="Val2" val="5" />
            <validValue name="Val3" val="0x1b" />
        </enum>
    </fields>
</schema>

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

enum class SomeEnumFieldVal
{
    Val1 = 0x00,
    Val2 = 0x05,
    Val3 = 0x1b
};

instead of

enum class SomeEnumFieldVal
{
    Val1 = 0,
    Val2 = 5,
    Val3 = 27
};

Allow Non-Unique Values

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.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    <fields>
        <enum name="SomeEnumField" type="uint8" nonUniqueAllowed="true">
            <validValue name="Val1" val="0" />
            <validValue name="Val2" val="5" />
            <validValue name="OtherNameForVal2" val="5" />
        </enum>
    </fields>
</schema>

Version Based Validity

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.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big" version="5">
    <fields>
        <enum name="SomeEnumField" type="uint8" validCheckVersion="true">
            <validValue name="Val1" val="0" />
            <validValue name="Val2" val="5" />
            <validValue name="Val3" val="10" sinceVersion="2" />
            <validValue name="Val4" val="15" sinceVersion="3" deprecated="4"/>
        </enum>
    </fields>
</schema>

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.