diff --git a/CMakeLists.txt b/CMakeLists.txt index 13b8f40..2163036 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,7 +11,7 @@ if (NOT ASCIIDOCTOR_PDF_EXE) message(FATAL_ERROR "asciidoctor-pdf is not found") endif () -set (VERSION "v5.0") +set (VERSION "v6.0") set (MAIN_FILE "${PROJECT_SOURCE_DIR}/commsdsl_spec.adoc") add_custom_target("pdf" ALL diff --git a/appendix/alias.adoc b/appendix/alias.adoc index 25c13d8..83d57d1 100644 --- a/appendix/alias.adoc +++ b/appendix/alias.adoc @@ -8,7 +8,7 @@ Introduced in DSL version **3**. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|3|yes||Name of the alias. |**description**|string|3|no||Human readable description of the alias. |**field**|relative <> string|3|yes||Reference to the aliased field, must start with `$` character. +|**name**|<> string|3|yes||Name of the alias. |=== diff --git a/appendix/bundle.adoc b/appendix/bundle.adoc index 6ddb328..ddaa2b1 100644 --- a/appendix/bundle.adoc +++ b/appendix/bundle.adoc @@ -18,7 +18,7 @@ Extra child XML elements allowed: |=== |XML Element|DSL Version ^.^|Description -|**<members>**|1|Wraps member fields. |**<alias>**|3|Alias names for other member fields. See <> for more info. +|**<members>**|1|Wraps member fields. |**<replace>**|5|Wraps replacing member fields after copying using **reuse** property. |=== diff --git a/appendix/custom.adoc b/appendix/custom.adoc index 9db2fb2..eed2bae 100644 --- a/appendix/custom.adoc +++ b/appendix/custom.adoc @@ -8,9 +8,9 @@ for detailed description. [cols="^.^27,^.^11,^.^8,^.^10,^.^10,34", options="header"] |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description +|**checksumFrom**|<> string|5|no (unless **semanticLayerType** is "checksum" and **checksumUntil** is empty)||Name of the frame layer, from which the checksum calculation starts. Applicable only when `semanticLayerType="checksum"`. +|**checksumUntil**|<> string|5|no (unless **semanticLayerType** is "checksum" and **checksumFrom** is empty)||Name of the frame layer, until (and including) which the checksum calculation is executed. Applicable only when `semanticLayerType="checksum"`. |**[.line-through]#idReplacement#**|<>|1|no|false|Mark the layer as one replacing <>. + **Deprecated**, use `semanticLayerType="id"` instead. |**semanticLayerType**|"payload", "id", "size", "sync", "checksum", "value", "custom"|5|no|custom|Specify what other layer **<custom>** one is replacing. -|**checksumFrom**|<> string|5|no (unless **semanticLayerType** is "checksum" and **checksumUntil** is empty)||Name of the frame layer, from which the checksum calculation starts. Applicable only when `semanticLayerType="checksum"`. -|**checksumUntil**|<> string|5|no (unless **semanticLayerType** is "checksum" and **checksumFrom** is empty)||Name of the frame layer, until (and including) which the checksum calculation is executed. Applicable only when `semanticLayerType="checksum"`. |=== diff --git a/appendix/enum.adoc b/appendix/enum.adoc index 5c5d169..450fd9b 100644 --- a/appendix/enum.adoc +++ b/appendix/enum.adoc @@ -9,15 +9,15 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**type**|"int8", "uint8", "int16", "uint16", "int32", "uint32", "int64", "uint64", "intvar", "uintvar"|1|yes||Underlying primitive type. +|**availableLengthLimit**|<>|4|no|false|Allow having less bytes in the buffer than required by the **type** when performing (de)serialization. +|**bitLength**|<>|1|no|length of **type** in bits|Serialization length in bits, applicable only to a member of <>. |**defaultValue**|<> or <>|1|no|0|Default value. Must fit the underlying **type**. |**endian**|"big" or "little"|1|no|endian of <>|Endian of the field. -|**length**|<>|1|no|length of **type**|Forced serialization length. -|**bitLength**|<>|1|no|length of **type** in bits|Serialization length in bits, applicable only to a member of <>. |**hexAssign**|<>|1|no|false|Force generated code to assign enum values using hexadecimal numbers. +|**length**|<>|1|no|length of **type**|Forced serialization length. |**nonUniqueAllowed**|<>|1|no|false|Allow non unique **<validValue>**-es. +|**type**|"int8", "uint8", "int16", "uint16", "int32", "uint32", "int64", "uint64", "intvar", "uintvar"|1|yes||Underlying primitive type. |**validCheckVersion**|<>|1|no|false|Take into account protocol version when generating code for field's value validity check. -|**availableLengthLimit**|<>|4|no|false|Allow having less bytes in the buffer than required by the **type** when performing (de)serialization. |=== ==== Properties of <validValue> Child Element of <enum> Field ==== @@ -25,12 +25,12 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the value. -|**val**|<>|1|yes||Numeric value. +|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which value was deprecated. + +Must be greater than value of **sinceVersion**. |**description**|string|1|no||Human readable description of the value. |**displayName**|string|1|no||Human readable name of the value to display in various analysis tools. +|**name**|<> string|1|yes||Name of the value. |**sinceVersion**|<>|1|no|0|Version of the protocol in which value was introduced. -|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which value was deprecated. + -Must be greater than value of **sinceVersion**. +|**val**|<>|1|yes||Numeric value. |=== diff --git a/appendix/fields.adoc b/appendix/fields.adoc index cfc3702..4df3e78 100644 --- a/appendix/fields.adoc +++ b/appendix/fields.adoc @@ -8,31 +8,31 @@ Refer to <> chapter for detailed des |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the field. +|**copyCodeFrom**|<> string|5|no||Specify field, overriding or other extra code of which needs to be copied. +|**customizable**|<>|1|no|false|Mark the field to allow compile time customization regardless of code generator's level of customization. +|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which field was deprecated. + +Must be greater than value of **sinceVersion**. + +Applipable only to members of the <> or <>. |**description**|string|1|no||Human readable description of the field. -|**reuse**|<> string|1|no||Field, definition of which to copy. +|**displayHidden**|<>|1|no|false|Don't display field at all in visual analysis tool(s). |**displayName**|string|1|no||Name of the field to display. If empty, the code generator must use value of property **name** instead. In order to force empty name to display, use "_" (underscore). |**displayReadOnly**|<>|1|no|false|Disable modification of the field in visual analysis tool(s). -|**displayHidden**|<>|1|no|false|Don't display field at all in visual analysis tool(s). -|**sinceVersion**|<>|1|no|0|Version of the protocol in which field was introduced. + -Applicable only to members of the <> or <>. -|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which field was deprecated. + -Must be greater than value of **sinceVersion**. + -Applipable only to members of the <> or <>. -|**removed**|<>|1|no|false|Indicates whether deprecated field has been removed from being serialized. + -Applicable only to members of the <> or <>. |**failOnInvalid**|<>|1|no|false|Fail *read* operation if read value is invalid. -|**pseudo**|<>|1|no|false|In case of **true**, don't serialize/deserialize this field. -|**customizable**|<>|1|no|false|Mark the field to allow compile time customization regardless of code generator's level of customization. -|**semanticType**|"none", "messageId", "version", "length"|1|no|none|Specify semantic type of the field. It allows code generator to generate special code for special cases. Value "length" was introduced in **v2** of this specification. |**forceGen**|<>|3|no|false|Force generation of field's code regardless of it's being referenced or not. -|**valueOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **value** operation. -|**readOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **read** operation. -|**writeOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **write** operation. -|**refreshOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **refresh** operation. |**lengthOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **length** retrieval. -|**validOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **valid** retrieval. +|**name**|<> string|1|yes||Name of the field. |**nameOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **name** retrieval. -|**copyCodeFrom**|<> string|5|no||Specify field, overriding or other extra code of which needs to be copied. +|**pseudo**|<>|1|no|false|In case of **true**, don't serialize/deserialize this field. +|**readOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **read** operation. +|**refreshOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **refresh** operation. +|**removed**|<>|1|no|false|Indicates whether deprecated field has been removed from being serialized. + +Applicable only to members of the <> or <>. +|**reuse**|<> string|1|no||Field, definition of which to copy. |**reuseCode**|<>|5|no|false|In case of **reuse** apply **copyCodeFrom** with the same <> string. +|**semanticType**|"none", "messageId", "version", "length"|1|no|none|Specify semantic type of the field. It allows code generator to generate special code for special cases. Value "length" was introduced in **v2** of this specification. +|**sinceVersion**|<>|1|no|0|Version of the protocol in which field was introduced. + +Applicable only to members of the <> or <>. +|**validOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **valid** retrieval. +|**valueOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **value** operation. +|**writeOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **write** operation. |=== diff --git a/appendix/float.adoc b/appendix/float.adoc index bec64c4..0bec3ab 100644 --- a/appendix/float.adoc +++ b/appendix/float.adoc @@ -9,32 +9,31 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**type**|"float", "double"|1|yes||Underlying primitive type |**defaultValue**|floating point value, **nan**, **inf**, **-inf**|1|no|0.0|Default value. Must fit the underlying **type**. +|**displayDecimals**|<>|1|no|0|Indicates to GUI analysis how many digits need to be displayed after the fraction point. +|**displaySpecials**|<>|2|no|true|Control displaying **<special>** values in analysis tools. |**endian**|"big" or "little"|1|no|endian of <>|Endian of the field. +|**nonUniqueSpecialsAllowed**|<>|2|no|false|Allow non unique **<special>**-s. +|**type**|"float", "double"|1|yes||Underlying primitive type |**units**|<>|1|no||Units of the value. +|**validCheckVersion**|<>|1|no|false|Take into account protocol version when generating code for field's value validity check. +|**validFullRange**|<>|1|no|false|Mark all the range of existing FP values to be valid, excluding **nan**, **inf**, and **-inf**. +|**validMax**|floating point value|1|no||Valid maximal value. All the numbers below it are considered to be valid. +|**validMin**|floating point value|1|no||Valid minimal value. All the numbers above it are considered to be valid. |**validRange**|"[ fp_value, fp_value ]"|1|no||Range of valid values. |**validValue**|floating point value, **nan**, **inf**, **-inf**|1|no||Valid value. -|**validMin**|floating point value|1|no||Valid minimal value. All the numbers above it are considered to be valid. -|**validMax**|floating point value|1|no||Valid maximal value. All the numbers below it are considered to be valid. -|**validFullRange**|<>|1|no|false|Mark all the range of existing FP values to be valid, excluding **nan**, **inf**, and **-inf**. -|**validCheckVersion**|<>|1|no|false|Take into account protocol version when generating code for field's value validity check. -|**displayDecimals**|<>|1|no|0|Indicates to GUI analysis how many digits need to be displayed after the fraction point. -|**nonUniqueSpecialsAllowed**|<>|2|no|false|Allow non unique **<special>**-s. -|**displaySpecials**|<>|2|no|true|Control displaying **<special>** values in analysis tools. |=== - ==== Properties of <special> Child Element of <float> Field ==== [cols="^.^28,^.^10,^.^8,^.^8,^.^10,36", options="header"] |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the value. -|**val**|floating point value, **nan**, **inf**, **-inf**|1|yes||Numeric value. -|**description**|string|1|no||Human readable description of the value. -|**sinceVersion**|<>|1|no|0|Version of the protocol in which value was introduced. -|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which value was deprecated. + +|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which value was deprecated. + Must be greater than value of **sinceVersion**. +|**description**|string|1|no||Human readable description of the value. |**displayName**|string|2|no||Name to display in various analysis tools. +|**name**|<> string|1|yes||Name of the value. +|**sinceVersion**|<>|1|no|0|Version of the protocol in which value was introduced. +|**val**|floating point value, **nan**, **inf**, **-inf**|1|yes||Numeric value. |=== diff --git a/appendix/frame.adoc b/appendix/frame.adoc index fdab4c8..f6bb56f 100644 --- a/appendix/frame.adoc +++ b/appendix/frame.adoc @@ -8,8 +8,8 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the frame. |**description**|string|1|no||Human readable description of the frame. +|**name**|<> string|1|yes||Name of the frame. |=== Extra child XML elements allowed: diff --git a/appendix/int.adoc b/appendix/int.adoc index 4b9ee34..3937e50 100644 --- a/appendix/int.adoc +++ b/appendix/int.adoc @@ -9,26 +9,26 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**type**|"int8", "uint8", "int16", "uint16", "int32", "uint32", "int64", "uint64", "intvar", "uintvar"|1|yes||Underlying primitive type. +|**availableLengthLimit**|<>|4|no|false|Allow having less bytes in the buffer than required by the **type** when performing (de)serialization. +|**bitLength**|<>|1|no|length of **type** in bits|Serialization length in bits, applicable only to a member of <>. +|**defaultValidValue**|<> or <>|4|no||Convenience bunding of the **defaultValue** and **validValue** into a single property. |**defaultValue**|<> or <>|1|no|0|Default value. Must fit the underlying **type**. +|**displayDecimals**|<>|1|no|0|Indicates to GUI analysis tools to display this field as floating point value with specified number of digits after the fraction point. +|**displayOffset**|<>|1|no|0|Indicates to GUI analysis tools to add specified offset value to a field's value when displaying it. +|**displaySpecials**|<>|2|no|true|Control displaying **<special>** values in analysis tools. |**endian**|"big" or "little"|1|no|endian of <>|Endian of the field. |**length**|<>|1|no|length of **type**|Forced serialization length. -|**bitLength**|<>|1|no|length of **type** in bits|Serialization length in bits, applicable only to a member of <>. +|**nonUniqueSpecialsAllowed**|<>|2|no|false|Allow non unique **<special>**-s. |**serOffset**|<>|1|no|0|Extra value that needs to be added to the field's value when the latter is being serialized. |**signExt**|<>|1|no|true|Enable / Disable sign extension of the signed value when **length** property is used to reduce the default serialization length. |**scaling**|"<> / <>"|1|no|1/1|Scaling ratio. +|**type**|"int8", "uint8", "int16", "uint16", "int32", "uint32", "int64", "uint64", "intvar", "uintvar"|1|yes||Underlying primitive type. |**units**|<>|1|no||Units of the value. +|**validCheckVersion**|<>|1|no|false|Take into account protocol version when generating code for field's value validity check. +|**validMax**|<>|1|no||Valid maximal value. All the numbers below it are considered to be valid. +|**validMin**|<>|1|no||Valid minimal value. All the numbers above it are considered to be valid. |**validRange**|"[ <>, <> ]"|1|no||Range of valid values. |**validValue**|<>|1|no||Valid value. -|**validMin**|<>|1|no||Valid minimal value. All the numbers above it are considered to be valid. -|**validMax**|<>|1|no||Valid maximal value. All the numbers below it are considered to be valid. -|**validCheckVersion**|<>|1|no|false|Take into account protocol version when generating code for field's value validity check. -|**displayDecimals**|<>|1|no|0|Indicates to GUI analysis tools to display this field as floating point value with specified number of digits after the fraction point. -|**displayOffset**|<>|1|no|0|Indicates to GUI analysis tools to add specified offset value to a field's value when displaying it. -|**nonUniqueSpecialsAllowed**|<>|2|no|false|Allow non unique **<special>**-s. -|**displaySpecials**|<>|2|no|true|Control displaying **<special>** values in analysis tools. -|**defaultValidValue**|<> or <>|4|no||Convenience bunding of the **defaultValue** and **validValue** into a single property. -|**availableLengthLimit**|<>|4|no|false|Allow having less bytes in the buffer than required by the **type** when performing (de)serialization. |=== ==== Properties of <special> Child Element of <int> Field ==== @@ -36,12 +36,11 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the value. -|**val**|<>|1|yes||Numeric value. -|**description**|string|1|no||Human readable description of the value. -|**sinceVersion**|<>|1|no|0|Version of the protocol in which value was introduced. |**deprecated**|<>|1|no|max unsigned|Version of the protocol in which value was deprecated. + Must be greater than value of **sinceVersion**. +|**description**|string|1|no||Human readable description of the value. |**displayName**|string|2|no||Name to display in various analysis tools. +|**name**|<> string|1|yes||Name of the value. +|**sinceVersion**|<>|1|no|0|Version of the protocol in which value was introduced. +|**val**|<>|1|yes||Numeric value. |=== - diff --git a/appendix/interface.adoc b/appendix/interface.adoc index dc7ce15..32a3fa0 100644 --- a/appendix/interface.adoc +++ b/appendix/interface.adoc @@ -8,10 +8,10 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the interface. -|**description**|string|1|no||Human readable description of the interface. -|**copyFieldsFrom**|<> string|1|no||Interface or bundle field definition from which fields need to be copied. |**copyFieldsAliases**|<>|3|no|true|Control copy of the defined <> when **copyFieldsFrom** property is used to copy fields from the other <> or <>. +|**copyFieldsFrom**|<> string|1|no||Interface or bundle field definition from which fields need to be copied. +|**description**|string|1|no||Human readable description of the interface. +|**name**|<> string|1|yes||Name of the interface. |=== @@ -21,6 +21,6 @@ Extra child XML elements allowed: |=== |XML Element|DSL Version ^.^|Description +|**copyFieldsAliases**|<>|3|no|true|Control copy of the defined <> when **copyFieldsFrom** property is used to copy fields from the other <> or <>. |**<fields>**|1|Wraps member fields. -|**<alias>**|3|Alias names for other member fields. See <> for more info. |=== diff --git a/appendix/layers.adoc b/appendix/layers.adoc index 84371d7..87e48df 100644 --- a/appendix/layers.adoc +++ b/appendix/layers.adoc @@ -7,7 +7,7 @@ Refer to <> chapter for detailed des |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the layer. |**description**|string|1|no||Human readable description of the layer. |**field**|<> or <> to it|1|yes (except for <>)||Wrapped field definition. +|**name**|<> string|1|yes||Name of the layer. |=== diff --git a/appendix/list.adoc b/appendix/list.adoc index 3522c2f..46b39dd 100644 --- a/appendix/list.adoc +++ b/appendix/list.adoc @@ -9,12 +9,12 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**element**|<> or <>|1|yes||Element of the field. |**count**|<>|1|no|0|Fixed number of elements in the list. Cannot be used tegether with **lengthPrefix** or **countPrefix**. |**countPrefix**|<> or <>|1|no||Prefix field containing number of elements in the list. Cannot be used tegether with **count** or **lengthPrefix**. -|**lengthPrefix**|<> or <>|1|no||Prefix field containing serialization length of the list. Cannot be used tegether with **count** or **countPrefix**. -|**elemLengthPrefix**|<>|1|no||Prefix field containing serialization length of the list **element**. +|**element**|<> or <>|1|yes||Element of the field. |**elemFixedLength**|<>|1|no|false|Indication of whether list has and will allways have fixed length element, so **elemLengthPrefix** prefixes only the first element and not the rest. +|**elemLengthPrefix**|<>|1|no||Prefix field containing serialization length of the list **element**. +|**lengthPrefix**|<> or <>|1|no||Prefix field containing serialization length of the list. Cannot be used tegether with **count** or **countPrefix**. |**termSuffix**|<>|5|no||Suffix field terminating the list. |=== diff --git a/appendix/message.adoc b/appendix/message.adoc index e993baa..eabbb97 100644 --- a/appendix/message.adoc +++ b/appendix/message.adoc @@ -8,27 +8,33 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the message. -|**id**|<>|1|yes||Numeric ID of the message. -|**description**|string|1|no||Human readable description of the message. -|**displayName**|string|1|no||Name of the message to display. If empty, the code generator must use value of property **name** instead. +|**construct**|string|6|no||Construction requirement. +|**constructAsReadCond**|bool|6|no|false|Copy **construct** value(s) to **readCond**. +|**constructAsValidCond**|bool|6|no|false|Copy **construct** value(s) to **validCond**. +|**copyCodeFrom**|<> string|5|no||Specify message, overriding or other extra code of which needs to be copied. +|**copyFieldsAliases**|<>|3|no|true|Control copy of the defined <> when **copyFieldsFrom** property is used to copy fields from the other <> or <>. |**copyFieldsFrom**|<> string|1|no||Message or bundle field definition from which fields need to be copied. -|**order**|<>|1|no|0|Relative order of the messages with the same **id**. -|**sinceVersion**|<>|1|no|0|Version of the protocol in which message was introduced. +|**customizable**|<>|1|no|false|Mark the message to allow compile time customization regardless of code generator's level of customization. |**deprecated**|<>|1|no|max unsigned|Version of the protocol in which message was deprecated. + Must be greater than value of **sinceVersion**. +|**description**|string|1|no||Human readable description of the message. +|**displayName**|string|1|no||Name of the message to display. If empty, the code generator must use value of property **name** instead. +|**failOnInvalid**|<>|6|no|false|Fail *read* operation if any of the fields have invalid value or **validCond** conditions are not true. +|**id**|<>|1|yes||Numeric ID of the message. +|**lengthOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **length** retrieval. +|**name**|<> string|1|yes||Name of the message. +|**nameOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **name** retrieval. +|**order**|<>|1|no|0|Relative order of the messages with the same **id**. +|**readCond**|string|6|no||Extra read operation condition. +|**readOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **read** operation. +|**refreshOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **refresh** operation. |**removed**|<>|1|no|false|Indicates whether deprecated message has been removed from being supported. |**sender**|"both", "client", "server"|1|no|both|Endpoint that sends the message. -|**customizable**|<>|1|no|false|Mark the message to allow compile time customization regardless of code generator's level of customization. -|**copyFieldsAliases**|<>|3|no|true|Control copy of the defined <> when **copyFieldsFrom** property is used to copy fields from the other <> or <>. +|**sinceVersion**|<>|1|no|0|Version of the protocol in which message was introduced. |**validateMinLength**|<>|4|no||Specify expected minimal serialization length of the message fields. -|**readOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **read** operation. |**writeOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **write** operation. -|**refreshOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **refresh** operation. -|**lengthOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **length** retrieval. +|**validCond**|string|6|no||Extra validity check operation condition. |**validOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **valid** retrieval. -|**nameOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **name** retrieval. -|**copyCodeFrom**|<> string|5|no||Specify message, overriding or other extra code of which needs to be copied. |=== Extra child XML elements allowed: @@ -37,7 +43,10 @@ Extra child XML elements allowed: |=== |XML Element|DSL Version ^.^|Description -|**<fields>**|1|Wraps member fields. |**<alias>**|3|Alias names for other member fields. See <> for more info. +|**<construct>**|6|Multiple construction requirements. +|**<fields>**|1|Wraps member fields. +|**<readCond>**|6|Multiple extra read operation conditions. |**<replace>**|5|Wraps replacing fields after copying using **copyFieldsFrom** property. +|**<validCond>**|6|Multiple extra validity check operation conditions. |=== diff --git a/appendix/optional.adoc b/appendix/optional.adoc index 3381795..9b790da 100644 --- a/appendix/optional.adoc +++ b/appendix/optional.adoc @@ -9,12 +9,12 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**field**|<>|1|no||Wrapped field. -|**defaultMode**|"tentative", "missing", "exist"|1|no|tentative|Default mode of the field. See also <> below. |**cond**|string|1|no||Condition when the field exists. +|**defaultMode**|"tentative", "missing", "exist"|1|no|tentative|Default mode of the field. See also <> below. |**displayExtModeCtrl**|<>|1|no|false|Disable manual update of the mode in GUI analysis tools. -|**missingOnReadFail**|<>|5|no|false|Mark the field as "missing" if its read operation fails. +|**field**|<>|1|no||Wrapped field. |**missingOnInvalid**|<>|5|no|false|Mark the field as "missing" if the field's value is invalid. +|**missingOnReadFail**|<>|5|no|false|Mark the field as "missing" if its read operation fails. |=== Inner field must be specified using **field** property or as @@ -25,9 +25,9 @@ Extra child XML elements allowed: [cols="^.^28,^.^10,62", options="header"] |=== |XML Element|DSL Version ^.^|Description -|**<field>**|1|Wraps member field. -|**<cond>**|1|Condition when field exists. |**<and>**|1|Logical "and" of conditions. +|**<cond>**|1|Condition when field exists. +|**<field>**|1|Wraps member field. |**<or>**|1|Logical "or" of conditions. |=== @@ -37,8 +37,8 @@ Extra child XML elements allowed: |=== |Mode ^.^|Accepted Values (case insensitive) -|Tentative|"tentative", "tent", "t" -|Missing|"missing", "miss", "m" |Exist|"exist", "exists", "e" +|Missing|"missing", "miss", "m" +|Tentative|"tentative", "tent", "t" |=== diff --git a/appendix/ref.adoc b/appendix/ref.adoc index 50ef87c..e0e1745 100644 --- a/appendix/ref.adoc +++ b/appendix/ref.adoc @@ -9,7 +9,7 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**field**|<>|1|yes||Reference to other field. |**bitLength**|<>|2|no|length in bits|Serialization length in bits, applicable only to a member of <> and when referencing a field that can be a member of <>. +|**field**|<>|1|yes||Reference to other field. |=== diff --git a/appendix/reference.adoc b/appendix/reference.adoc index 19c28f0..81aa148 100644 --- a/appendix/reference.adoc +++ b/appendix/reference.adoc @@ -10,5 +10,6 @@ Lists available prefixes allowing distinction of different <>. |=== diff --git a/appendix/schema.adoc b/appendix/schema.adoc index 02a315b..28af0b7 100644 --- a/appendix/schema.adoc +++ b/appendix/schema.adoc @@ -7,11 +7,11 @@ Refer to <> chapter for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|string|1|yes||Name of the protocol. Allowed to have spaces. -|**endian**|"big" or "little"|1|no|little|Endian of the protocol. |**description**|string|1|no||Human readable description of the protocol. -|**version**|<>|1|no|0|Version of the protocol. |**dslVersion**|<>|1|no|0|Version of the used DSL. +|**endian**|"big" or "little"|1|no|little|Endian of the protocol. +|**name**|string|1|yes||Name of the protocol. Allowed to have spaces. |**nonUniqueMsgIdAllowed**|<>|1|no|false|Allow non-unique numeric message IDs. +|**version**|<>|1|no|0|Version of the protocol. |=== diff --git a/appendix/set.adoc b/appendix/set.adoc index 3655dff..0838c50 100644 --- a/appendix/set.adoc +++ b/appendix/set.adoc @@ -9,15 +9,15 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**type**|"uint8", "uint16", "uint32", "uint64"|1|yes (no if **length** is specified)||Underlying primitive type. -|**length**|<>|1|yes (no if **type** is specifed)|length of **type**|Serialization length. -|**bitLength**|<>|1|no|length of **type** in bits|Serialization length in bits, applicable only to a member of <>. +|**availableLengthLimit**|<>|4|no|false|Allow having less bytes in the buffer than required by the **type** or **length** when performing (de)serialization. |**defaultValue**|<>|1|no|false|Default initialization value of every bit. -|**reservedValue**|<>|1|no|false|Expected value of every reserved bit. |**endian**|"big" or "little"|1|no|endian of <>|Endian of the field. +|**bitLength**|<>|1|no|length of **type** in bits|Serialization length in bits, applicable only to a member of <>. +|**length**|<>|1|yes (no if **type** is specifed)|length of **type**|Serialization length. |**nonUniqueAllowed**|<>|1|no|false|Allow non unique **<bit>**-s. +|**reservedValue**|<>|1|no|false|Expected value of every reserved bit. +|**type**|"uint8", "uint16", "uint32", "uint64"|1|yes (no if **length** is specified)||Underlying primitive type. |**validCheckVersion**|<>|1|no|false|Take into account protocol version when generating code for field's value validity check. -|**availableLengthLimit**|<>|4|no|false|Allow having less bytes in the buffer than required by the **type** or **length** when performing (de)serialization. |=== ==== Properties of <bit> Child Element of <set> Field ==== @@ -25,14 +25,14 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**name**|<> string|1|yes||Name of the value. -|**idx**|<>|1|yes||Index of the specified bit. Counting starts from least significant bit. +|**defaultValue**|<>|1|no|**defaultValue** of the **<set>** field|Default value of the bit (when constructed). +|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which bit was deprecated (became reserved). + +Must be greater than value of **sinceVersion**. |**description**|string|1|no||Human readable description of the bit. |**displayName**|string|1|no||Human readable name of the bit to display in various analysis tools. -|**defaultValue**|<>|1|no|**defaultValue** of the **<set>** field|Default value of the bit (when constructed). -|**reservedValue**|<>|1|no|**reservedValue** of the **<set>** field|Expected value of the bit if it is reserved. +|**idx**|<>|1|yes||Index of the specified bit. Counting starts from least significant bit. +|**name**|<> string|1|yes||Name of the value. |**reserved**|<>|1|no|false|Mark / Unmark the bit as being reserved. +|**reservedValue**|<>|1|no|**reservedValue** of the **<set>** field|Expected value of the bit if it is reserved. |**sinceVersion**|<>|1|no|0|Version of the protocol in which bit was introduced (became non-reserved). -|**deprecated**|<>|1|no|max unsigned|Version of the protocol in which bit was deprecated (became reserved). + -Must be greater than value of **sinceVersion**. |=== diff --git a/commsdsl_spec.adoc b/commsdsl_spec.adoc index 5d5347e..fe732ff 100644 --- a/commsdsl_spec.adoc +++ b/commsdsl_spec.adoc @@ -1,6 +1,6 @@ -= CommsDSL Specification v5.0 += CommsDSL Specification v6.0 Alex Robenko -v5.0, 2022-08 +v6.0, 2023-03 :doctype: article :toc: left :source-highlighter: rouge diff --git a/fields/optional.adoc b/fields/optional.adoc index 5f02133..f646a00 100644 --- a/fields/optional.adoc +++ b/fields/optional.adoc @@ -99,7 +99,7 @@ using **cond** <>. that is a member of a <> or a <>. The **cond** expression specifies condition when the **<optional>** field exists, and must always -reference other **sibling** field. Such reference is always prefixed with **$** character +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. @@ -157,6 +157,40 @@ Deep (nested) conditions are also expected to be supported by the code generator ---- +Since **v6.0** of this specification referencing of the member fields of an <> +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. +[source,xml] +---- + + + + + + + + + + + + + + + + + + + + + +---- +**WARNING**: The **CommsDSL** specification supports multiple interfaces and doesn't impose any restriction +on how they are used in the end application. The schema parser is responsible to do +a check that **any** (not all) of the previously encountered **<interface>**-es contains +the referenced field. The code generator may also not impose many restrictions on such references. +Usage of the wrong **<interface>** class with the missing referenced +field in the end application may result in compilation errors. + [[fields-optional-multiple-existence-conditions]] ==== Multiple Existence Conditions ==== The **CommsDSL** also allows usage of multiple existence condition statements. However, diff --git a/intro/references.adoc b/intro/references.adoc index 33311dc..a66cef1 100644 --- a/intro/references.adoc +++ b/intro/references.adoc @@ -141,4 +141,28 @@ referenced fields are not global ones, but a siblings. Such sibling reference ne ---- +[[intro-references-to-interface-fields]] +==== References to Interface Fields ==== +Some properties support references to the member fields of an <>. +Such reference needs to be prefixed with `%` character. + +[source,xml] +---- + + + + + + + + + + + + + + + +---- + Use <> for future references. diff --git a/intro/schema_def.adoc b/intro/schema_def.adoc index 91854e7..bbaa3f8 100644 --- a/intro/schema_def.adoc +++ b/intro/schema_def.adoc @@ -114,7 +114,7 @@ There are protocols that put some information, common to all the messages, such 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 -https://github.com/commschamp/comms_champion#comms-library[COMMS Library] +https://github.com/commschamp/comms[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 diff --git a/messages/messages.adoc b/messages/messages.adoc index 2186939..5ff3c6b 100644 --- a/messages/messages.adoc +++ b/messages/messages.adoc @@ -418,7 +418,9 @@ In the example above *Msg1* and *Msg2* are uni-directional messages, while Many protocol specifications provide expected serialization length of the message. In order to prevent various typos or copy-paste errors, the **CommsDSL** provides an ability to validate the specified message length during the schema file parsing. To perform such a -check use **validateMinLength** <>. +check use **validateMinLength** <> with <> value. +It can help to avoid some copy-paste or typo errors +at the time of schema parsing rather than debugging generated incorrect code. [source,xml] ---- @@ -443,28 +445,6 @@ customizable at compile time. [source,xml] ---- - - - ... - - ----- - -[[messages-alias-to-fields]] -=== Alias Names to Member Fields === -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 <> chapter for more details. - -[[messages-ensuring-serialization-length]] -=== Ensuring Serialization Length === -Many protocol specifications indicate the expected message serialization length, especially -when message has fixed length. The **CommsDSL** allows specifying expected minimal length -using **validateMinLength** property with <> value to help avoid some copy-paste or typo errors -at the time of schema parsing rather than debugging generated incorrect code. -[source,xml] ----- - @@ -478,9 +458,15 @@ at the time of schema parsing rather than debugging generated incorrect code. Note, that <> field is always expected to have 0 minimal length regardless of its <>. -Also note, that the value of **validateMinLength** is the expected serialization length of +Also note, that the value of **validateMinLength** is the expected serialization length of message fields __without__ the fields of the <>. +[[messages-alias-to-fields]] +=== Alias Names to Member Fields === +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 <> chapter for more details. + [[messages-ensuring-overriding-code-injection]] === Ensuring Overriding Code Injection === Similar to <> the default code @@ -532,7 +518,6 @@ It means that some portion of copied code can be cleared. ---- - ... @@ -543,5 +528,343 @@ It means that some portion of copied code can be cleared. ---- +[[messages-construct-requirements]] +=== Extra Construction Requirements === +In some cases the message object construction may require updating +fields in its <>. The +**CommsDSL** provides such an ability using the **construct** property. +The reference to the interface field is performed using the same syntax +as with the <> field's <>, +i.e. using `%` prefix. +[source,xml] +---- + + + + + + + + + + + + + + ... + + + + ... + + + +---- + +In the example above `Msg1` constructor must set `Flags.Bits.B0` bit, while `Msg2` +constructor must assign `2` to the `Flags.Extra` field. + +To perform multiple updates to the interface fields the `` child node with its single `` child node must be used. +[source,xml] +---- + + + + + + + + + + + + + + + + + + + + + + ... + + + +---- +The `` nodes are very similar to the `` ones used to describe multiple +<> of the <> +field, but with some limitations: + +- Only bit sets and equality statements are supported. +- Only `` nodes are supported. + +**WARNING**: The **CommsDSL** specification supports multiple interfaces and doesn't impose any restriction +on how they are used in the end application. The schema parser is responsible to do +a check that **any** (not all) of the previously encountered **<interface>**-es contains +the referenced field. The code generator may also not impose many restrictions on such references. +Usage of the wrong **<interface>** class with the missing referenced +field in the end application may result in compilation errors. + +[[messages-read-conditions]] +=== Extra Read Conditions === +The **read** operation of every <> means invoking +the **read** operation for every one of its member fields. However, there may be cases +when preliminary evaluation of the <> fields +needs to be performed. To do so the **readCond** property referencing appropriate +<> fields can be used. The syntax is +the same as with the <> field's <>. +[source,xml] +---- + + + + + + + + + + + + + + ... + + + + + + + + + + + + + + ... + + + +---- +In case of multiple conditions the **readCond** needs to be specified +as the `` child node with a single `` or `` immediate child. +Nested `` and/or `` conditions are allowed in the same way as with the +<> field's <>. +The only difference is that the inner child nodes must be named `readCond` instead of `cond`. + +Quite often the <> (**readCond**) are the same as the <> (**construct**). +To avoid unnecessary statements duplication there is **constructAsReadCond** property with +<> value to force copying **construct** value(s) to the **readCond**. +[source,xml] +---- + + + + + + + + + + + + + + + + + + + + + + ... + + + +---- +It is equivalent to +[source,xml] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + + +---- + +[[messages-valid-conditions]] +=== Extra Validity Conditions === +The **valid** operation of every <> means invoking +the **valid** operation for every one of its member fields. However, the valid values +of fields may be interdependent. There may be a need to introduce extra validity checks +on the message contents. To do so the **validCond** property referencing appropriate +<> fields and/or fields of the +<> itself can be used. The syntax is +the same as with the <> field's +<>. + +[source,xml] +---- + + + + + + + + + + + + + + + ... + + +---- + +In case of multiple conditions the **validCond** needs to be specified +as the `` child node with a single `` or `` immediate child. +Nested `` and/or `` conditions are allowed in the same way as with the +<> field's <>. +The only difference is that the inner child nodes must be named `validCond` instead of `cond`. + +[source,xml] +---- + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +---- + +Quite often the <> (**validCond**) are the same as the <> (**construct**). +To avoid unnecessary statements duplication there is **constructAsValidCond** property with +<> value to force copying **construct** value(s) to the **validCond**, similar +to the **constructAsReadCond** property described <>. + +[source,xml] +---- + + + + + + + + + + + + + + + ... + + + ... + + + +---- + +[[messages-fail-read-on-invalid]] +=== Failing Read on Invalid Contents === +In the <> it was shown that the `` +can have extra conditions for its payload to be valid. Sometimes these extra conditions are +required to be taken into account during the **read** operation and the latter should +fail in case the message contents are invalid. To support such case the +**failOnInvalid** <> with boolean value should be used +(the same way as with <>). + +[source,xml] +---- + + + + + + + + + + + + + + + +---- + +The **failOnInvalid** property for the `` can also be used to fail the **read** operation in +case any of the member fields has an invalid value. + + +[source,xml] +---- + + + + + + +---- + Use <> for future references.