int Field
Last updated
Was this helpful?
Last updated
Was this helpful?
This field stores and abstracts away value of integral type. The <int> field has all the properties as well as extra properties and elements described below.
Every <int> field must provide its underlying storage type using type . 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
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> has extra optional properties:
description - Extra description and documentation on how to use the value.
sinceVersion - Version of the protocol when the special name / meaning was introduced.
deprecated - Version of the protocol when the special name / meaning was deprecated.
displayName - Readable name to display for the special value in protocol debugging and visualization tools.
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:
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.
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:
Add 8,000,000 to the field's value to get non-negative number.
Serialize the result using only 3 bytes.
In order to implement such example correctly there is a need to switch off the automatic sign extension when value is deserialized.
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.
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.
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.
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.
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.
The variable length types are encoded using Base-128 form, such as for little endian or similar for big endian.
Every <special> must define a valid (using name ) as well as value (using val ), that fits chosen . The <special>-s may be listed in any order, not necessarily sorted.
All these extra properties are described in detail in .
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 has been set to true.
The default serialization endian of the protocol is specified in endian property of the . It is possible to override the default endian value with extra endian property.
The 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 (intvar and uintvar), it means maximum allowed length.
<int> field can be a member of field. In this case the serialization length may be specified in bits using bitLength .
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 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
When limiting 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 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.
NOTE, that signExt property is relevant only for signed types with non-default .
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 .
Protocols quite often specify what units are being transfered. The CommsDSL provides units 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 table.
There are also validMin and validMax, which specify single 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.
All the validity related 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 .
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 , which is set to true.
When 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 with numeric value of how many digits need to be displayed after decimal point.
Also when 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 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:
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 with 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 with value is there to control this default behavior.
Use for future references.