Messages

Every message is defined using <message> XML element.

Message Name

Every message definition must specify its name using name property.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" ...>
        ...
    </message>
</schema>

Numeric ID

Every message definition must specify its numeric ID using id property.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" id="0x1">
        ...
    </message>
</schema>

It is highly recommended to define "message ID" numeric values as external <enum> field and reuse its values.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <enum name="MsgId" type="uint8" semanticType="messageId">
            <validValue name="Msg1" val=0x1" />
            <validValue name="Msg2" val=0x2" />
        </enum>
    </fields>

    <message name="Msg1" id="MsgId.Msg1">
        ...
    </message>

    <message name="Msg2" id="MsgId.Msg2">
        ...
    </message>
</schema>

Description

It is possible to provide a description of the message 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.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" id="1">
        <description>
            Some long
            multiline
            description
        </description>
        ...
    </message>
</schema>

Display Name

When various analysis tools display message details, the preference is to display proper space separated name (which is defined using displayName property) rather than using a name.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" id="1" displayName="Message 1">
        ...
    </message>
</schema>

In case displayName is empty, the analysis tools are expected to use value of name property instead.

It is recommended to share the displayName with relevant <validValue> of <enum> that lists numeric IDs of the messages:

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <string name="Msg1Name" defaultValue="Message 1" />
        <string name="Msg2Name" defaultValue="Message 2" />

        <enum name="MsgId" type="uint8" semanticType="messageId">
            <validValue name="Msg1" val="1" displayName="^Msg1Name" />
            <validValue name="Msg2" val="2" displayName="^Msg2Name" />
        </enum>

        <message name="Msg1" id="MsgId.Msg1" displayName="^Msg1Name">
            ...
        </message>

        <message name="Msg2" id="MsgId.Msg2" displayName="^Msg2Name">
            ...
        </message>
    </fields>
</schema>

Fields

Every <message> has zero or more fields that can be specified as child XML elements.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <int name="SomeCommonField" type="uint16" defaultValue="10" />
    </fields>

    <message name="Msg1" id="1">
        <int name="F1" type="uint8" />
        <enum name="F2" type="uint8">
            ...
        </enum>
        <ref field="SomeCommonField" name="F3" />
        <string name="F4" length="8" />
        ...
    </message>
</schema>

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

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big">
    <message name="Msg1" id="1">
        <displayName value="Message 1" />
        <fields>
            <int name="F1" type="uint8" />
        </fields>
    </message>
</schema>

Sometimes different messages have the same fields. In order to avoid duplication, use copyFieldsFrom property to specify original message.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" id="1">
        <int name="F1" type="uint32" />
    </message>

    <message name="Msg2" id="2" copyFieldsFrom="Msg1" />
</schema>

In the example above Msg2 will have the same fields as Msg1.

After copying fields from other message, all other defined fields will be appended to copied ones.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" id="1">
        <int name="F1" type="uint32" />
    </message>

    <message name="Msg2" id="2" copyFieldsFrom="Msg1">
        <float name="F2" type="float" />
    </message>
</schema>

In the example above Msg2 will have 2 fields: F1 and F2.

Ordering

There are protocols that may define various forms of the same message, which share the same numeric ID, but are differentiated by a serialization length or value of some particular field inside the message. It can be convenient to define such variants as separate classes. In case there are multiple <message>-es with the same numeric ID, it is required to specify order in which they are expected to be processed (read). The ordering is specified using order property with unsigned numeric value. The message object with lower order value gets created and its read operation attempted before message object with higher value.

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" nonUniqueMsgIdAllowed="true">
    <message name="Msg1Form1" id="1" order="0" >
        ...
    </message>

    <message name="Msg1Form2" id="1" order="1">
        ...
    </message>    
</schema>

NOTE that there is a need to set nonUniqueMsgIdAllowed property of the schema to true to allow multiple message objects with the same numeric ID.

All the order values for the same numeric ID must be unique, but not necessarily sequential.

Versioning

CommsDSL allows providing an information in what version the message was added to the protocol, as well as in what version it was deprecated, and whether it was removed (not supported any more) after deprecation.

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

<?xml version="1.0" encoding="UTF-8"?>
<schema name="MyProtocol" endian="big" version="5" >
    <message name="SomeMessage" id="100" sinceVersion="2" >
        ...
    </message>

    <message name="SomeOtherMessage" id="101" sinceVersion="3" deprecated="4" removed="true">
        ...
    </message>

</schema>

In the example above SomeMessage was introduced in version 2, and SomeOtherMessage was introduced in version 3, but deprecated and removed in version 4.

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 code generator is expected to be able to generate support for specific versions and include / exclude support for some messages based on their version information.

Platforms

Some protocols may be used in multiple independent platforms, while having some platform-specific messages. The CommsDSL allows listing of the supported platforms using <platform> XML nodes. Every message may list platforms in which it must be supported using platforms property. In case the property's value is empty (default), the message is supported in all the available platforms (if any defined). The platforms property value is coma-separated list of platform names with preceding + if the listed platforms are the one supported, or - if the listed platforms need to be excluded from all available ones.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <platform name="Plat1" />
    <platform name="Plat2" />
    <platform name="Plat3" />
    <platform name="Plat4" />

    <message name="Msg1" id="1" platforms="+Plat1,Plat4">
        ...
    </message>

    <message name="Msg2" id="2" platforms="-Plat1, Plat2">
        ...
    </message>
</schema>

In the example above Msg1 is supported only for platforms Plat1 and Plat4, while Msg2 is NOT supported in Plat1, and Plat2 (i.e. supported in Plat3 and Plat4).

The main consideration for what format to choose should be whether the platforms support for the message should or should NOT be added automatically when new <platform> is defined.

Sender

In most protocols there are uni-directional messages. The CommsDSL allows definition of entity that sends a particular message using sender property. Available values are both (default), server, and client. The code generator may use provided information and generate some auxiliary code and/or data structures to be used for client and/or server implementation.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" id="1" sender="client">
        ...
    </message>

    <message name="Msg2" id="2" sender="server">
        ...
    </message>

    <message name="Msg3" id="2">
        ...
    </message>
</schema>

In the example above Msg1 and Msg2 are uni-directional messages, while Msg3 is bi-directional.

Customization

The code generator is expected to allow some level of compile time customization of the generated code, such as enable/disable generation of particular virtual functions. 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 message class to be customizable regardless of the customization level requested from the code generator. CommsDSL provides customizable property with boolean value to force any message to being customizable at compile time.

<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <message name="Msg1" id="1" customizable="true">
        ...
    </message>
</schema>

Use properties table for future references.

results matching ""

    No results matching ""