From 21657fba1ffc2eaa9eb573f88303cd00f6f9c8cd Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Fri, 6 Dec 2024 08:16:02 +1000 Subject: [PATCH 01/20] Updated next release version to be v7.0 --- CMakeLists.txt | 4 +++- commsdsl_spec.adoc | 4 ++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 8fa9cf9..a8928b6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -11,8 +11,10 @@ if (NOT ASCIIDOCTOR_PDF_EXE) message(FATAL_ERROR "asciidoctor-pdf is not found") endif () -set (VERSION "v6.1") set (MAIN_FILE "${PROJECT_SOURCE_DIR}/commsdsl_spec.adoc") +file (READ "${MAIN_FILE}" main_file_contents) +string (REGEX MATCH "v([0-9\.]*)\," _ ${main_file_contents}) +set (VERSION "v${CMAKE_MATCH_1}") add_custom_target("pdf" ALL COMMAND ${ASCIIDOCTOR_PDF_EXE} ${MAIN_FILE} diff --git a/commsdsl_spec.adoc b/commsdsl_spec.adoc index c5200b4..48e40b9 100644 --- a/commsdsl_spec.adoc +++ b/commsdsl_spec.adoc @@ -1,6 +1,6 @@ -= CommsDSL Specification v6.1 += CommsDSL Specification v7.0 Alex Robenko -v6.1, 2023-06 +v7.0, 2024-12 :doctype: article :toc: left :source-highlighter: rouge From 1c5e288ed8808804f8f939883a4780eed8ddd03d Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Fri, 6 Dec 2024 08:35:54 +1000 Subject: [PATCH 02/20] Added description of the "validValue" and "defaultValidValue" properties of the field. --- appendix/string.adoc | 2 ++ fields/string.adoc | 81 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) diff --git a/appendix/string.adoc b/appendix/string.adoc index b9943f1..8522782 100644 --- a/appendix/string.adoc +++ b/appendix/string.adoc @@ -10,8 +10,10 @@ for detailed description. |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description |**defaultValue**|string|1|no||Default value. +|**defaultValidValue**|string|7|no||Default valid value. |**length**|<>|1|no|0|Fixed serialization length. **0** means no length limit. Cannot be used tegether with **lengthPrefix** or **zeroTermSuffix**. |**lengthPrefix**|<> or <>|1|no||Prefix field containing length of the string. Cannot be used tegether with **length** or **zeroTermSuffix**. +|**validValue**|string|7|no||Valid value. |**zeroTermSuffix**|<>|1|no|false|Terminate string with **0**. Cannot be used tegether with **length** or **lengthPrefix**. |=== diff --git a/fields/string.adoc b/fields/string.adoc index 7d80518..3f4bb4e 100644 --- a/fields/string.adoc +++ b/fields/string.adoc @@ -19,6 +19,7 @@ input buffer. Note, that the __available__ bytes may be bound by the other means. It does NOT necessarily mean that all the bytes received from the I/O link will be consumed. +[[fields-string-default-value]] ==== Default Value ==== The default value of the **<string>** field when constructed can be specified using **defaultValue** <>. If not specified, defaults to empty string. @@ -32,6 +33,7 @@ using **defaultValue** <>. If not specified, default ---- +[[fields-string-fixed-length]] ==== Fixed Length ==== In case the string value needs to be serialized using predefined fixed length, use **length** property to specify the required value. @@ -45,6 +47,7 @@ use **length** property to specify the required value. ---- +[[fields-string-length-prefix]] ==== Length Prefix ==== Many protocols prefix string with its length. The **CommsDSL** allows definition of such prefix using **lengthPrefix** child element, which must define prefix as @@ -106,6 +109,7 @@ 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...). +[[fields-string-zero-term-suffix]] ==== Zero Termination Suffix ==== Some protocols may terminate strings with **0** (zero) byte. The **CommsDSL** support such cases with existence of **zeroTermSuffix** <> @@ -123,4 +127,81 @@ with <> value. **NOTE**, that **length**, **lengthPrefix** and **zeroTermSuffix** properties are mutually exclusive, i.e. cannot be used together. +[[fields-string-valid-values]] +==== Valid Values ==== +Some protocols may specify a narrow range of possible valid string values that +the field is expected to have. To specify such a valid value use **validValue** +<>. +[source,xml] +---- + + + + + + +---- + +It is possible to provide a list of multiple valid values using child nodes. +[source,xml] +---- + + + + + + + + ... + + + +---- + +It is also possible to combine a single XML attribute with other child nodes: +[source,xml] +---- + + + + + + ... + + + +---- + +When the protocol specification demands haveing a specific string value, then it is possible to +combine it with the <> +property. +[source,xml] +---- + + + + + + +---- + +[[fields-string-single-valid-value]] +==== Single Valid Value ==== +Sometimes the **<string>** field has only one valid value and it must be initialized with it. The +**defaultValidValue** <> can be used as a replacement to the combination of +**defaultValue** and **validValue** ones having to specify the same value: +[source,xml] +---- + + + + + + + + +---- + Use <> for future references. From 1b22440b33057b7cfbea1a61cdf6f00e942116fe Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Fri, 6 Dec 2024 08:45:11 +1000 Subject: [PATCH 03/20] Added description of the "validValue" and "defaultValidValue" properties of the field. --- appendix/data.adoc | 2 ++ fields/data.adoc | 78 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) diff --git a/appendix/data.adoc b/appendix/data.adoc index 3c46919..7cde649 100644 --- a/appendix/data.adoc +++ b/appendix/data.adoc @@ -10,8 +10,10 @@ for detailed description. |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description |**defaultValue**|string|1|no||Default value. Case-insensitive hexadecimal string. +|**defaultValidValue**|string|7|no||Default valid value. Case-insensitive hexadecimal string. |**length**|<>|1|no|0|Fixed serialization length. **0** means no length limit. Cannot be used tegether with **lengthPrefix**. |**lengthPrefix**|<> or <>|1|no||Prefix field containing length of the data. Cannot be used tegether with **length**. +|**validValue**|string|7|no||Valid value. Case-insensitive hexadecimal string. |=== diff --git a/fields/data.adoc b/fields/data.adoc index 286e03d..dba5b94 100644 --- a/fields/data.adoc +++ b/fields/data.adoc @@ -116,4 +116,82 @@ into account and generate correct code for various field operations **NOTE**, that **length** and **lengthPrefix** properties are mutually exclusive, i.e. cannot be used together. + +[[fields-data-valid-values]] +==== Valid Values ==== +Some protocols may specify a narrow range of possible valid data values that +the field is expected to have. To specify such a valid value use **validValue** +<>. +[source,xml] +---- + + + + + + +---- + +It is possible to provide a list of multiple valid values using child nodes. +[source,xml] +---- + + + + + + + + ... + + + +---- + +It is also possible to combine a single XML attribute with other child nodes: +[source,xml] +---- + + + + + + ... + + + +---- + +When the protocol specification demands haveing a specific data value, then it is possible to +combine it with the <> +property. +[source,xml] +---- + + + + + + +---- + +[[fields-data-single-valid-value]] +==== Single Valid Value ==== +Sometimes the **<data>** field has only one valid value and it must be initialized with it. The +**defaultValidValue** <> can be used as a replacement to the combination of +**defaultValue** and **validValue** ones having to specify the same value: +[source,xml] +---- + + + + + + + + +---- + Use <> for future references. From 3f36ff2827a3ac4717e29ed10295d344fca789e8 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Fri, 6 Dec 2024 08:51:39 +1000 Subject: [PATCH 04/20] Added usage of the "sinceVersion" and "deprecated" properties to the "validValue" for the and fields. --- fields/data.adoc | 17 +++++++++++++++++ fields/string.adoc | 17 +++++++++++++++++ 2 files changed, 34 insertions(+) diff --git a/fields/data.adoc b/fields/data.adoc index dba5b94..64cc9ee 100644 --- a/fields/data.adoc +++ b/fields/data.adoc @@ -148,6 +148,23 @@ It is possible to provide a list of multiple valid values using child nodes. ---- +When using child nodes to specify the valid values, it is possible (but not necessary) to specify the versions of +the protocol when the valid value was introduced and when it got deprecated. +[source,xml] +---- + + + + + + + + ... + + + +---- + It is also possible to combine a single XML attribute with other child nodes: [source,xml] ---- diff --git a/fields/string.adoc b/fields/string.adoc index 3f4bb4e..128c0ce 100644 --- a/fields/string.adoc +++ b/fields/string.adoc @@ -158,6 +158,23 @@ It is possible to provide a list of multiple valid values using child nodes. ---- +When using child nodes to specify the valid values, it is possible (but not necessary) to specify the versions of +the protocol when the valid value was introduced and when it got deprecated. +[source,xml] +---- + + + + + + + + ... + + + +---- + It is also possible to combine a single XML attribute with other child nodes: [source,xml] ---- From 17f0145e6242d41b156b193daa7c347bf4e601fe Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Fri, 6 Dec 2024 08:54:40 +1000 Subject: [PATCH 05/20] Added some anchors to the field paragraphs. --- fields/data.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/fields/data.adoc b/fields/data.adoc index 64cc9ee..a7bdecf 100644 --- a/fields/data.adoc +++ b/fields/data.adoc @@ -19,6 +19,7 @@ input buffer. Note, that the __available__ bytes may be bound by the other means. It does NOT necessarily mean that all the bytes received from the I/O link will be consumed. +[[fields-data-default-value]] ==== Default Value ==== The default value of the **<data>** field when constructed can be specified using **defaultValue** <>. The value of the @@ -39,6 +40,7 @@ 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. +[[fields-data-fixed-length]] ==== Fixed Length ==== In case the data value needs to be serialized using predefined fixed length, use **length** property to specify the required value. @@ -52,6 +54,7 @@ use **length** property to specify the required value. ---- +[[fields-data-length-prefix]] ==== Length Prefix ==== 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 From d66154baf0f1bc94cb6d35fdf8c39f1683349285 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Fri, 6 Dec 2024 08:59:13 +1000 Subject: [PATCH 06/20] Cosmetic update to the semanticType="length" description. --- fields/common.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/fields/common.adoc b/fields/common.adoc index 57ea365..eaf1f41 100644 --- a/fields/common.adoc +++ b/fields/common.adoc @@ -303,9 +303,9 @@ an <>). ---- -* **length** - Introduced in **v2.0** of **CommsDSL** specification. -Used to specify that the field holds total serialization length -of the **subsequent** fields. Usually applicable to <> field +* **length** - Used to specify that the field holds total serialization length +of the **subsequent** fields (excluding the length of the field itself). +Usually applicable to <> field (or <> referencing an <>). Since **v5.0** of **CommsDSL**, the **length** semantic type can be set for other complex fields, such as <> or <>. From 824c6e2c072be66ae6642f0776a27731af0d23b3 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Sun, 8 Dec 2024 13:50:36 +1000 Subject: [PATCH 07/20] Deprecated and removed "displayHidden" and "displayReadOnly" properties of fields. --- appendix/fields.adoc | 2 -- appendix/float.adoc | 2 +- appendix/int.adoc | 4 ++-- fields/common.adoc | 35 +---------------------------------- fields/float.adoc | 4 ++-- fields/int.adoc | 16 +++++++--------- fields/variant.adoc | 12 ++++++------ 7 files changed, 19 insertions(+), 56 deletions(-) diff --git a/appendix/fields.adoc b/appendix/fields.adoc index 4df3e78..da7f558 100644 --- a/appendix/fields.adoc +++ b/appendix/fields.adoc @@ -14,9 +14,7 @@ Refer to <> chapter for detailed des Must be greater than value of **sinceVersion**. + Applipable only to members of the <> or <>. |**description**|string|1|no||Human readable description of the field. -|**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). |**failOnInvalid**|<>|1|no|false|Fail *read* operation if read value is invalid. |**forceGen**|<>|3|no|false|Force generation of field's code regardless of it's being referenced or not. |**lengthOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **length** retrieval. diff --git a/appendix/float.adoc b/appendix/float.adoc index 0bec3ab..45e234d 100644 --- a/appendix/float.adoc +++ b/appendix/float.adoc @@ -10,7 +10,7 @@ for detailed description. |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description |**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. +|**displayDecimals**|<>|1|no|0|Specifies number of digits 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. diff --git a/appendix/int.adoc b/appendix/int.adoc index 3937e50..f3ebabf 100644 --- a/appendix/int.adoc +++ b/appendix/int.adoc @@ -13,8 +13,8 @@ for detailed description. |**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. +|**displayDecimals**|<>|1|no|0|Use specified number of digits after the fraction point when displaying the field's value as floating point. +|**displayOffset**|<>|1|no|0|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. diff --git a/fields/common.adoc b/fields/common.adoc index eaf1f41..15a883a 100644 --- a/fields/common.adoc +++ b/fields/common.adoc @@ -87,12 +87,7 @@ has been introduced with <> value. ---- [[fields-common-display-properties]] -==== Display Properties ==== -**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. - +==== Display Name ==== 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 <>. @@ -118,34 +113,6 @@ If **displayName** is not specified, the code generator must use value of proper ---- -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 <> -value. -[source,xml] ----- - - - - - - ----- - -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 <> -value. -[source,xml] ----- - - - - - - ----- - [[fields-common-versioning]] ==== Versioning ==== **CommsDSL** allows providing an information in what version the field was added diff --git a/fields/float.adoc b/fields/float.adoc index 15a47b1..c69ff84 100644 --- a/fields/float.adoc +++ b/fields/float.adoc @@ -308,7 +308,7 @@ is set to **true**. ==== Extra Display Properties ==== When displaying the floating point value, held by the **<float>** field, -GUI analysis tools require knowledge on how many digits after decimal point +it may be required to specify amount of digits after decimal point need to be displayed. To provide this information, use **displayDecimals** <> with numeric value. [source,xml] @@ -320,7 +320,7 @@ with numeric value. ---- -If value of **displayDecimals** is **0**, then it is up to the GUI tool +If value of **displayDecimals** is **0**, then it is up to the displaying application to choose how many digits after decimal point to display. When **<special>** values are specified the protocol analysis tools are diff --git a/fields/int.adoc b/fields/int.adoc index c9b53c2..3e36839 100644 --- a/fields/int.adoc +++ b/fields/int.adoc @@ -464,9 +464,8 @@ Sometimes the **<int>** field has only one valid value and it must be init [[fields-int-extra-display-properties]] ==== Extra Display Properties ==== -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** <> +When <> information is specified and the field's value needs to be displayed +somewhere as a floating point one, use **displayDecimals** <> with numeric value of how many digits need to be displayed after decimal point. [source,xml] ---- @@ -478,8 +477,9 @@ 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. +Also when <> is provided it can +be added to the displayed value by using the **displayOffset** <> with +<> value. For example, many protocols define some kind of remaining length field when defining a transport <> or other places. Sometimes @@ -500,10 +500,8 @@ 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** <> with -<> value. +However, when such field is displayed it is desirable +to display the value with serialization offset as well. [source,xml] ---- diff --git a/fields/variant.adoc b/fields/variant.adoc index c88c010..5b65590 100644 --- a/fields/variant.adoc +++ b/fields/variant.adoc @@ -16,7 +16,7 @@ field, member fields need to be listed as children XML elements of the **<var - + @@ -72,7 +72,7 @@ TLV (type / length / value) triplets. - + @@ -108,7 +108,7 @@ preserving forward / backward compatibility of the protocol. For example: - + @@ -135,7 +135,7 @@ introduced in the future versions of the protocol while still operating correctl - + ... @@ -165,7 +165,7 @@ to all the properties. Any new defined member field gets **appended** to the cop - + @@ -204,7 +204,7 @@ child node, which wraps the replacing fields. - + From 11bd3c0c88c2e3196551fd4e07891dc44b277f4f Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Sun, 8 Dec 2024 14:09:55 +1000 Subject: [PATCH 08/20] Deprecated and removed "displaySpecials" property of and fields. --- appendix/float.adoc | 1 - appendix/int.adoc | 1 - fields/float.adoc | 17 ----------------- fields/int.adoc | 18 ------------------ 4 files changed, 37 deletions(-) diff --git a/appendix/float.adoc b/appendix/float.adoc index 45e234d..baa39db 100644 --- a/appendix/float.adoc +++ b/appendix/float.adoc @@ -11,7 +11,6 @@ for detailed description. |**defaultValue**|floating point value, **nan**, **inf**, **-inf**|1|no|0.0|Default value. Must fit the underlying **type**. |**displayDecimals**|<>|1|no|0|Specifies number of digits 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 diff --git a/appendix/int.adoc b/appendix/int.adoc index f3ebabf..2d843c4 100644 --- a/appendix/int.adoc +++ b/appendix/int.adoc @@ -15,7 +15,6 @@ for detailed description. |**defaultValue**|<> or <>|1|no|0|Default value. Must fit the underlying **type**. |**displayDecimals**|<>|1|no|0|Use specified number of digits after the fraction point when displaying the field's value as floating point. |**displayOffset**|<>|1|no|0|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. |**nonUniqueSpecialsAllowed**|<>|2|no|false|Allow non unique **<special>**-s. diff --git a/fields/float.adoc b/fields/float.adoc index c69ff84..e9df6df 100644 --- a/fields/float.adoc +++ b/fields/float.adoc @@ -323,21 +323,4 @@ with numeric value. If value of **displayDecimals** is **0**, then it is up to the displaying application 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** -<> with <> value -is there to control this default behavior. -[source,xml] ----- - - - - - - - - - ----- - Use <> for future references. diff --git a/fields/int.adoc b/fields/int.adoc index 3e36839..07cea40 100644 --- a/fields/int.adoc +++ b/fields/int.adoc @@ -512,22 +512,4 @@ to display the value with serialization offset as well. ---- -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. -[source,xml] ----- - - - - - - - - - ----- - - Use <> for future references. From 0a695456e32fdef40bb538f488d0aa17f99172ab Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Sun, 8 Dec 2024 14:32:53 +1000 Subject: [PATCH 09/20] Deprecated and removed "displayExtModeCtrl" property of field. --- appendix/optional.adoc | 1 - fields/optional.adoc | 25 ------------------------- 2 files changed, 26 deletions(-) diff --git a/appendix/optional.adoc b/appendix/optional.adoc index 9b790da..20b34fc 100644 --- a/appendix/optional.adoc +++ b/appendix/optional.adoc @@ -11,7 +11,6 @@ for detailed description. |**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. |**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. diff --git a/fields/optional.adoc b/fields/optional.adoc index d57ccfa..d234225 100644 --- a/fields/optional.adoc +++ b/fields/optional.adoc @@ -347,30 +347,5 @@ operation of the **<optional>** field didn't take place. ---- -[[fields-optional-extra-display-property]] -==== Extra Display Property ==== -By default GUI protocol analysis tools should allow manual update of the -**<optional>** field mode. However, if the mode is controlled by the -values of other fields, it is possible to disable manual update of the -mode by using **displayExtModeCtrl** -(stands for "display external mode control") <> -with <> value. -[source,xml] ----- - - - - - - - - - - - - - - ----- Use <> for future references. From 4cdf9b32b8800c6fcc8b659a6be1443367000dcf Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Sun, 8 Dec 2024 14:42:26 +1000 Subject: [PATCH 10/20] Deprecated and removed "displayIdxReadOnlyHidden" property of field. --- appendix/variant.adoc | 1 - fields/variant.adoc | 21 --------------------- 2 files changed, 22 deletions(-) diff --git a/appendix/variant.adoc b/appendix/variant.adoc index 59d44f2..e304938 100644 --- a/appendix/variant.adoc +++ b/appendix/variant.adoc @@ -10,7 +10,6 @@ for detailed description. |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description |**defaultMember**|<> or <> index|1|no|-1|Default member. Negative number means no member selected. -|**displayIdxReadOnlyHidden**|<>|1|no|false|Hide active index of the member when field displayed in read-only mode. |=== diff --git a/fields/variant.adoc b/fields/variant.adoc index 5b65590..020c4a6 100644 --- a/fields/variant.adoc +++ b/fields/variant.adoc @@ -288,26 +288,5 @@ name. Negative number as value of **defaultMember** property will force the **<variant>** field not to have a default member. -==== Extra Display Property ==== -By default GUI protocol analysis tools should display the index of the -held member when displaying **<variant>** field in "read only" mode. -However, for some occasions this information may be irrelevant. To hide -display of index use **displayIdxReadOnlyHidden** -<> with <> value. -[source,xml] ----- - - - - - - ... - - ... - - - ----- - Use <> for future references. From 281afc5a40a181c2a277ca6e0578b63f93465145 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Sun, 8 Dec 2024 14:51:12 +1000 Subject: [PATCH 11/20] Cosmetic wording updates. --- appendix/enum.adoc | 2 +- appendix/float.adoc | 2 +- appendix/int.adoc | 2 +- appendix/set.adoc | 2 +- fields/enum.adoc | 2 +- fields/float.adoc | 2 +- fields/int.adoc | 2 +- fields/set.adoc | 2 +- messages/messages.adoc | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/appendix/enum.adoc b/appendix/enum.adoc index 450fd9b..cd22059 100644 --- a/appendix/enum.adoc +++ b/appendix/enum.adoc @@ -28,7 +28,7 @@ for detailed description. |**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. +|**displayName**|string|1|no||Human readable name of the value. |**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/float.adoc b/appendix/float.adoc index baa39db..4567e27 100644 --- a/appendix/float.adoc +++ b/appendix/float.adoc @@ -31,7 +31,7 @@ for detailed description. |**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. +|**displayName**|string|2|no||Human readable name of the value. |**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/int.adoc b/appendix/int.adoc index 2d843c4..c32c567 100644 --- a/appendix/int.adoc +++ b/appendix/int.adoc @@ -38,7 +38,7 @@ for detailed description. |**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. +|**displayName**|string|2|no||Human readable name of the value. |**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/set.adoc b/appendix/set.adoc index 0838c50..835f017 100644 --- a/appendix/set.adoc +++ b/appendix/set.adoc @@ -29,7 +29,7 @@ for detailed description. |**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. +|**displayName**|string|1|no||Human readable name of the bit. |**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. diff --git a/fields/enum.adoc b/fields/enum.adoc index 3980871..14665b8 100644 --- a/fields/enum.adoc +++ b/fields/enum.adoc @@ -63,7 +63,7 @@ in any order, not necessarily sorted. Every **<validValue>** has extra optional properties: * **description** - Extra description and documentation on how to use the value. -* **displayName** - String specifying how to name the value in various analysis tools. +* **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. diff --git a/fields/float.adoc b/fields/float.adoc index e9df6df..20f2bad 100644 --- a/fields/float.adoc +++ b/fields/float.adoc @@ -77,7 +77,7 @@ 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. +* **displayName** - Human readable name of the value. All these extra properties are described in detail in <>. diff --git a/fields/int.adoc b/fields/int.adoc index 07cea40..8eea3d7 100644 --- a/fields/int.adoc +++ b/fields/int.adoc @@ -67,7 +67,7 @@ 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. +* **displayName** - Human readable name of the value. All these extra properties are described in detail in <>. diff --git a/fields/set.adoc b/fields/set.adoc index 7ac4d85..e767d46 100644 --- a/fields/set.adoc +++ b/fields/set.adoc @@ -114,7 +114,7 @@ Every **<bit>** element may also define extra <>. diff --git a/messages/messages.adoc b/messages/messages.adoc index 5ff3c6b..cab17e1 100644 --- a/messages/messages.adoc +++ b/messages/messages.adoc @@ -81,7 +81,7 @@ generated class. The <> is **description**. [[messages-display-name]] === Display Name === When various analysis tools display message details, the preference is to -display proper space separated name (which is defined using **displayName** +display proper human readable and space separated name (which is defined using **displayName** <>) rather than using a <>. [source,xml] ---- From 43dadb608df10af027b9fbce3038d07c242106d0 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Mon, 9 Dec 2024 09:58:03 +1000 Subject: [PATCH 12/20] Added description of the "fixedValue" property of fields. --- appendix/fields.adoc | 1 + fields/common.adoc | 17 +++++++++++++++++ fields/variant.adoc | 24 ++++++++++++++---------- 3 files changed, 32 insertions(+), 10 deletions(-) diff --git a/appendix/fields.adoc b/appendix/fields.adoc index da7f558..212037d 100644 --- a/appendix/fields.adoc +++ b/appendix/fields.adoc @@ -16,6 +16,7 @@ Applipable only to members of the <> or <>|1|no|false|Fail *read* operation if read value is invalid. +|**fixedValue**|<>|7|no|false|Remove an ability to update field's value after the object construction. |**forceGen**|<>|3|no|false|Force generation of field's code regardless of it's being referenced or not. |**lengthOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **length** retrieval. |**name**|<> string|1|yes||Name of the field. diff --git a/fields/common.adoc b/fields/common.adoc index 15a883a..1c3d969 100644 --- a/fields/common.adoc +++ b/fields/common.adoc @@ -210,6 +210,23 @@ value. ---- +[[fields-common-fixed-value-fields]] +==== Fixed Value (Constant) Fields ==== +It is possible to disallow modification of the field's value by the client application +using **fixedValue** property with <> value. +[source,xml] +---- + + + + + ... + + +---- +In the example above the code generator must remove an ability to explicitly modify the field's value +after its construction. The field's value can still be updated by the **read** operation though. + [[fields-common-customizable-fields]] ==== Customizable Fields ==== The code generator is expected to allow some level of compile time customization of the diff --git a/fields/variant.adoc b/fields/variant.adoc index 020c4a6..c6b5ecc 100644 --- a/fields/variant.adoc +++ b/fields/variant.adoc @@ -16,7 +16,7 @@ field, member fields need to be listed as children XML elements of the **<var - + @@ -36,7 +36,9 @@ field, member fields need to be listed as children XML elements of the **<var The example above defines every *key-value* pair as <> field, where first field (*key*) reuses external definition of *Key* field and adds its default construction value as well as what value considered to be valid. -**NOTE**, that every *key* member sets **failOnInvalid** property to **true**. + +**NOTE** that every *key* member sets +<> property to **true**. The code generator is expected to generate code that attempts *read* operation of every defined member field in the order of their definition. Once the *read* operation is successful, the right member has been found and the *read* operation @@ -44,6 +46,10 @@ needs to terminate. The *in-order* read is high level logic, the code generator is allowed to introduce optimizations as long as the outcome of detecting the right member is the same. +Also **note** that the <> property +is set to **true** to prevent the application from explicitly updating the **Key** field +after the element is constructed. + If there is any other <> defined as XML child of the **<variant>**, then all the members must be wrapped in **<members>** XML element for separation. @@ -72,7 +78,7 @@ TLV (type / length / value) triplets. - + @@ -95,9 +101,7 @@ TLV (type / length / value) triplets. Please **note** assigning **semanticType** property to be **length** for the *Length* field in every bundle. It specifies that the field contains remaining length of all the subsequent fields in the **<bundle>** and -allows the code generator to produce correct code. The support for -**length** value of **semanticType** has been introduced in **v2** of this -specification. +allows the code generator to produce correct code. Quite often the developers wonder why there is a need to use *remaining length* information for the fields, length of which is constant and known and compile time. @@ -108,7 +112,7 @@ preserving forward / backward compatibility of the protocol. For example: - + @@ -135,7 +139,7 @@ introduced in the future versions of the protocol while still operating correctl - + ... @@ -165,7 +169,7 @@ to all the properties. Any new defined member field gets **appended** to the cop - + @@ -204,7 +208,7 @@ child node, which wraps the replacing fields. - + From 3409efcb01a9aa6bbb44cb5963ac7d0a75e53865 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Tue, 10 Dec 2024 08:51:10 +1000 Subject: [PATCH 13/20] Added support for "validateMinLength" property for all the fields. --- appendix/fields.adoc | 1 + appendix/message.adoc | 2 +- fields/common.adoc | 32 ++++++++++++++++++++++++++++++++ intro/multiple_files.adoc | 5 ++++- 4 files changed, 38 insertions(+), 2 deletions(-) diff --git a/appendix/fields.adoc b/appendix/fields.adoc index 212037d..befeeac 100644 --- a/appendix/fields.adoc +++ b/appendix/fields.adoc @@ -31,6 +31,7 @@ Applicable only to members of the <> or <>|1|no|0|Version of the protocol in which field was introduced. + Applicable only to members of the <> or <>. +|**validateMinLength**|<>|7|no||Specify expected minimal serialization length of the field. |**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/message.adoc b/appendix/message.adoc index eabbb97..38acda9 100644 --- a/appendix/message.adoc +++ b/appendix/message.adoc @@ -32,9 +32,9 @@ Must be greater than value of **sinceVersion**. |**sender**|"both", "client", "server"|1|no|both|Endpoint that sends the message. |**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. -|**writeOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **write** operation. |**validCond**|string|6|no||Extra validity check operation condition. |**validOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **valid** retrieval. +|**writeOverride**|"any", "replace", "extend", "none"|4|no|any|Control the overriding code for **write** operation. |=== Extra child XML elements allowed: diff --git a/fields/common.adoc b/fields/common.adoc index 1c3d969..b0176d1 100644 --- a/fields/common.adoc +++ b/fields/common.adoc @@ -425,4 +425,36 @@ boolean value can be used in addition to **reuse** one. ---- +[[fields-common-length-validation]] +=== Field Length Validation === +Many protocol specifications provide expected serialization length of the message or selected fields. In order to +prevent various typos or copy-paste errors, the **CommsDSL** provides an ability to +validate the specified field (minimal) length during the schema file parsing. It can be quite useful for the +composite fields like <>. To perform such a +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] +---- + + + + + + + ... + + + ... + + + + + + + + + +---- + Use <> for future references. diff --git a/intro/multiple_files.adoc b/intro/multiple_files.adoc index 10f5346..cac639f 100644 --- a/intro/multiple_files.adoc +++ b/intro/multiple_files.adoc @@ -2,7 +2,10 @@ === Multiple Files === For big protocols it is possible and even recommended to split schema definition into multiple files. The code generator **must** accept a list of schema files to -process and **must** process them in the requested order. +process and **must** process them in the requested order. Note there are no +**include** (or similar) statements in the **CommsDSL** specification. The +code generator is expected to process the listed DSL files in the provided order +and being able to reuse any definition that has already been encountered. Every subsequently processed schema file must **NOT** change any properties of the **<schema>** node with the same **name** that was defined in the From 6a2f9a6950f745c07528843a43a37b43747e309e Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Fri, 13 Dec 2024 08:16:14 +1000 Subject: [PATCH 14/20] Added "reuse" and "reuseCode" properties to and definitions. --- appendix/interface.adoc | 4 ++-- appendix/message.adoc | 2 ++ fields/common.adoc | 2 +- fields/optional.adoc | 3 +++ interfaces/interfaces.adoc | 41 +++++++++++++++++++++++++++++++++ messages/messages.adoc | 46 ++++++++++++++++++++++++++++++++++++++ schema/schema.adoc | 2 +- 7 files changed, 96 insertions(+), 4 deletions(-) diff --git a/appendix/interface.adoc b/appendix/interface.adoc index 32a3fa0..a6b483c 100644 --- a/appendix/interface.adoc +++ b/appendix/interface.adoc @@ -12,6 +12,8 @@ for detailed description. |**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. +|**reuse**|<> string|7|no||Interface definition of which to copy. +|**reuseCode**|<>|7|no|false|In case of **reuse** apply **copyCodeFrom** with the same <> string. |=== @@ -20,7 +22,5 @@ Extra child XML elements allowed: [cols="^.^28,^.^10,62", options="header"] |=== |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. |=== diff --git a/appendix/message.adoc b/appendix/message.adoc index 38acda9..f3e9b45 100644 --- a/appendix/message.adoc +++ b/appendix/message.adoc @@ -28,6 +28,8 @@ Must be greater than value of **sinceVersion**. |**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. +|**reuse**|<> string|7|no||Message definition of which to copy. +|**reuseCode**|<>|7|no|false|In case of **reuse** apply **copyCodeFrom** with the same <> string. |**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. |**sinceVersion**|<>|1|no|0|Version of the protocol in which message was introduced. diff --git a/fields/common.adoc b/fields/common.adoc index b0176d1..4a4e4e2 100644 --- a/fields/common.adoc +++ b/fields/common.adoc @@ -399,7 +399,7 @@ It means that some portion of copied code can be cleared. In case of <> 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 +**copyCodeFrom** property described above, or to avoid repetition of the <> string, another **reuseCode** property with boolean value can be used in addition to **reuse** one. [source,xml] diff --git a/fields/optional.adoc b/fields/optional.adoc index d234225..da96e39 100644 --- a/fields/optional.adoc +++ b/fields/optional.adoc @@ -59,6 +59,9 @@ 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 <> in the new version, but the protocol itself doesn't report its version in any other way. +When the *read* operation is complete, the mode of the field is expected to be +changed automatically to either **exist** or **missing** depending on whether +the relevant data was read or not. The default mode of the newly constructed **<optional>** field can be specified using **defaultMode** <>. diff --git a/interfaces/interfaces.adoc b/interfaces/interfaces.adoc index 474bb73..d2cd797 100644 --- a/interfaces/interfaces.adoc +++ b/interfaces/interfaces.adoc @@ -28,6 +28,7 @@ message object and will contain required extra information. These fields are there to hold extra values delivered as part of message <>. +[[interfaces-name]] === Interface Name === Every interface definition must specify its <> using **name** <>. @@ -41,6 +42,7 @@ Every interface definition must specify its <> using ---- +[[interfaces-description]] === Description === It is possible to provide a description of the interface about what it is and how it is expected to be used. This description is only for documentation @@ -61,6 +63,7 @@ generated class. The <> is **description**. ---- +[[interfaces-fields]] === More About Fields === Similar to **<message>** every **<interface>** has zero or more <> that can be specified as child XML elements. If there is any other @@ -131,9 +134,47 @@ having "version" value as **semanticType** property, will be considered for fields that, were introduced and/or deprecated at some stage, i.e. use **sinceVersion** and/or **derecated** + **removed** properties. +[[interfaces-alias-names]] === Alias Names to Fields === Sometimes a contained 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. +[[interfaces-reusing-other-fields]] +=== Reusing Other Interfaces === +Sometimes two different interfaces are very similar but differ in one or two particular aspects. It is possible +to reuse the other interface definition using **reuse** property (similar to <> +and <>). +[source,xml] +---- + + + + ... + + + + + ... + + +---- +Similar to using the <> property any new fields defined are added to ones +copied from the **reuse**-d interface. + +In case of reusing other interface definition, only the interface +definition properties are copied. The extra code that the original interface might inject is **NOT** included +in such copy by default. To include injected code use **reuseCode** property with +boolean value can be used in addition to **reuse** one. +[source,xml] +---- + + + + ... + + +---- + + Use <> for future references. diff --git a/messages/messages.adoc b/messages/messages.adoc index cab17e1..bab9ceb 100644 --- a/messages/messages.adoc +++ b/messages/messages.adoc @@ -866,5 +866,51 @@ case any of the member fields has an invalid value. ---- +[[messages-reusing-other-fields]] +=== Reusing Other Messages === +Sometimes two different messages are very similar but differ in one or two particular aspects. It is possible +to reuse the other message definition using **reuse** property (similar to <>), +especially when things like <>, +<>, and <> need +to be copied. +[source,xml] +---- + + + + + + + + + ... + + + + + + ... + + +---- +Similar to using the <> property any new fields defined are added to ones +copied from the **reuse**-d message. + +In case of reusing other message definition, only the message +definition properties are copied. The extra code that the original message might inject is **NOT** included +in such copy by default. The copying of injected code must be specified explicitly using +<> property described above, or to avoid repetition of the +<> string, another **reuseCode** property with +boolean value can be used in addition to **reuse** one. +[source,xml] +---- + + + + ... + + +---- + Use <> for future references. diff --git a/schema/schema.adoc b/schema/schema.adoc index eaa74aa..625045d 100644 --- a/schema/schema.adoc +++ b/schema/schema.adoc @@ -99,7 +99,7 @@ property or other construct. [source,xml] ---- - + ... ---- From 114401e14f6360ae85dd81282e122d2ddcbf4daa Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Tue, 17 Dec 2024 08:55:07 +1000 Subject: [PATCH 15/20] Added description of "validCond" and "copyValidCondFrom" properties of the field. --- appendix/bundle.adoc | 3 ++ fields/bundle.adoc | 73 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+) diff --git a/appendix/bundle.adoc b/appendix/bundle.adoc index ddaa2b1..c73bf04 100644 --- a/appendix/bundle.adoc +++ b/appendix/bundle.adoc @@ -9,7 +9,9 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description +|**copyValidCondFrom**|<> string|7|no||Bundle field definition from which extra validity condition needs to be copied. |**reuseAliases**|<>|3|no|true|Control copy of the defined <> from reused other <> when **reuse** property is used. +|**validCond**|string|7|no||Extra validity check operation condition. |=== Extra child XML elements allowed: @@ -21,4 +23,5 @@ Extra child XML elements allowed: |**<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. +|**<validCond>**|7|Multiple extra validity check operation conditions. |=== diff --git a/fields/bundle.adoc b/fields/bundle.adoc index ec4a524..f1ae288 100644 --- a/fields/bundle.adoc +++ b/fields/bundle.adoc @@ -170,4 +170,77 @@ Sometimes an existing member field may be renamed and/or moved. It is possible t 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. + +[[fields-bundle-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 <bundle> contents. To do so the **validCond** property referencing appropriate +member fields of the <> itself can be used. The syntax is +the same as with the <> field's +<> (described later). + +[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] +---- + + + + + + + + + + + + + + + + + +---- + +In case some other <> have similar fields and the same extra validity conditions apply to +the <> field being defined, it is possible to copy the conditions using **copyValidCondFrom** +property. +[source,xml] +---- + + + + + + + + + + + + + + + +---- + Use <> for future references. From 6e35a4aa938dd0c311077609f1b277e8713a9178 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Tue, 17 Dec 2024 09:04:50 +1000 Subject: [PATCH 16/20] Added description of "validCond" and "copyValidCondFrom" properties of the field. --- appendix/bitfield.adoc | 5 ++- appendix/bundle.adoc | 2 +- fields/bitfield.adoc | 73 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 78 insertions(+), 2 deletions(-) diff --git a/appendix/bitfield.adoc b/appendix/bitfield.adoc index 0ad9e03..cd48d12 100644 --- a/appendix/bitfield.adoc +++ b/appendix/bitfield.adoc @@ -9,7 +9,9 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**endian**|"big" or "little"|1|no|endian of <>|Endian of the field.| +|**copyValidCondFrom**|<> string|7|no||<> field definition from which extra validity condition needs to be copied. +|**endian**|"big" or "little"|1|no|endian of <>|Endian of the field. +|**validCond**|string|7|no||Extra validity check operation condition. |=== Extra child XML elements allowed: @@ -20,4 +22,5 @@ Extra child XML elements allowed: |**<members>**|1|Wraps member fields. |**<replace>**|5|Wraps replacing member fields after copying using **reuse** property. +|**<validCond>**|7|Multiple extra validity check operation conditions. |=== diff --git a/appendix/bundle.adoc b/appendix/bundle.adoc index c73bf04..c53c674 100644 --- a/appendix/bundle.adoc +++ b/appendix/bundle.adoc @@ -9,7 +9,7 @@ for detailed description. |=== |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description -|**copyValidCondFrom**|<> string|7|no||Bundle field definition from which extra validity condition needs to be copied. +|**copyValidCondFrom**|<> string|7|no||<> field definition from which extra validity condition needs to be copied. |**reuseAliases**|<>|3|no|true|Control copy of the defined <> from reused other <> when **reuse** property is used. |**validCond**|string|7|no||Extra validity check operation condition. |=== diff --git a/fields/bitfield.adoc b/fields/bitfield.adoc index 1134112..d1eebe9 100644 --- a/fields/bitfield.adoc +++ b/fields/bitfield.adoc @@ -143,4 +143,77 @@ in the following way. ---- +[[fields-bitfield-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 <bitfield> contents. To do so the **validCond** property referencing appropriate +member fields of the <> itself can be used. The syntax is +the same as with the <> field's +<> (described later). + +[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] +---- + + + + + + + + + + + + + + + + + +---- + +In case some other <> have similar fields and the same extra validity conditions apply to +the <> field being defined, it is possible to copy the conditions using **copyValidCondFrom** +property. +[source,xml] +---- + + + + + + + + + + + + + + + +---- + + Use <> for future references. From 43b414d20f6c0363b2bae3342b624235da90d817 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Wed, 18 Dec 2024 08:32:16 +1000 Subject: [PATCH 17/20] Updated documentation to clarify that $ prefix is relevant to siblings and member fields. --- appendix/reference.adoc | 2 +- intro/references.adoc | 16 +++++++++++++++- 2 files changed, 16 insertions(+), 2 deletions(-) diff --git a/appendix/reference.adoc b/appendix/reference.adoc index 81aa148..f26e9c3 100644 --- a/appendix/reference.adoc +++ b/appendix/reference.adoc @@ -7,7 +7,7 @@ Lists available prefixes allowing distinction of different <>. diff --git a/intro/references.adoc b/intro/references.adoc index a66cef1..f532f80 100644 --- a/intro/references.adoc +++ b/intro/references.adoc @@ -122,7 +122,7 @@ 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. [[intro-references-to-siblings]] -==== References to Sibling Elements ==== +==== References to Sibling or Member Elements ==== In case of using <> field <> the referenced fields are not global ones, but a siblings. Such sibling reference needs to be prefixed with `$` character. @@ -141,6 +141,20 @@ referenced fields are not global ones, but a siblings. Such sibling reference ne ---- +In case of the <> or composite fields like +<> the `$` is used to reference their member fields. + +[source,xml] +---- + + + + + + + +---- + [[intro-references-to-interface-fields]] ==== References to Interface Fields ==== Some properties support references to the member fields of an <>. From 7a3a0c08c6e5767d2baa1acb75f104ef407d9289 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Mon, 23 Dec 2024 11:10:00 +1000 Subject: [PATCH 18/20] Added "copyConstructFrom", "copyReadCondFrom", and "copyValidCondFrom" properties to definition. --- aliases/aliases.adoc | 4 +-- appendix/message.adoc | 5 +++- fields/bitfield.adoc | 18 ++++++++++- fields/bundle.adoc | 17 +++++++++++ messages/messages.adoc | 68 +++++++++++++++++++++++++++++++++++++++++- 5 files changed, 107 insertions(+), 5 deletions(-) diff --git a/aliases/aliases.adoc b/aliases/aliases.adoc index 7e4c7ea..69f605e 100644 --- a/aliases/aliases.adoc +++ b/aliases/aliases.adoc @@ -72,7 +72,7 @@ traffic reuse the same byte occupied by the `SomeEnum` field, like below. - @@ -93,7 +93,7 @@ like this: - ... diff --git a/appendix/message.adoc b/appendix/message.adoc index f3e9b45..74f7204 100644 --- a/appendix/message.adoc +++ b/appendix/message.adoc @@ -11,9 +11,12 @@ for detailed description. |**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. +|**copyCodeFrom**|<> string|5|no||Message from which overriding or other extra code needs to be copied. +|**copyConstructFrom**|<> string|7|no||Message from which to copy construction requirements. |**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. +|**copyReadCondFrom**|<> string|7|no||Message from which to copy read conditions. +|**copyValidCondFrom**|<> string|7|no||Message from which to copy validity conditions. |**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**. diff --git a/fields/bitfield.adoc b/fields/bitfield.adoc index d1eebe9..766b50c 100644 --- a/fields/bitfield.adoc +++ b/fields/bitfield.adoc @@ -214,6 +214,22 @@ property. ---- - +**Note** that **copyValidCondFrom** is an __action__ property, which causes the copy +of the original validity conditions. When such field is <> +in the future the original definition doesn't really have property named **copyValidCondFrom** to be +copied, only the real validity condition(s). The `SomeOtherBitfield` definition above is equivalent to: +[source,xml] +---- + + + + + + + + + + +---- Use <> for future references. diff --git a/fields/bundle.adoc b/fields/bundle.adoc index f1ae288..ce37dfc 100644 --- a/fields/bundle.adoc +++ b/fields/bundle.adoc @@ -242,5 +242,22 @@ property. ---- +**Note** that **copyValidCondFrom** is an __action__ property, which causes the copy +of the original validity conditions. When such field is <> +in the future the original definition doesn't really have property named **copyValidCondFrom** to be +copied, only the real validity condition(s). The `SomeOtherBundle` definition above is equivalent to: +[source,xml] +---- + + + + + + + + + + +---- Use <> for future references. diff --git a/messages/messages.adoc b/messages/messages.adoc index bab9ceb..1e13856 100644 --- a/messages/messages.adoc +++ b/messages/messages.adoc @@ -607,6 +607,27 @@ the referenced field. The code generator may also not impose many restrictions o Usage of the wrong **<interface>** class with the missing referenced field in the end application may result in compilation errors. +It is possible to copy construction requirements from one message definition to another to avoid unnecessary duplication +using **copyConstructFrom** property. +[source,xml] +---- + + + + + + ... + + + ... + + + + ... + + +---- + [[messages-read-conditions]] === Extra Read Conditions === The **read** operation of every <> means invoking @@ -723,6 +744,27 @@ It is equivalent to ---- +It is possible to copy read conditions from one message definition to another to avoid unnecessary duplication +using **copyReadCondFrom** property. +[source,xml] +---- + + + + + + ... + + + ... + + + + ... + + +---- + [[messages-valid-conditions]] === Extra Validity Conditions === The **valid** operation of every <> means invoking @@ -824,6 +866,25 @@ to the **constructAsReadCond** property described < ---- +It is possible to copy validity conditions from one message definition to another to avoid unnecessary duplication +using **copyValidCondFrom** property. +[source,xml] +---- + + + + + ... + + ... + + + + ... + + +---- + [[messages-fail-read-on-invalid]] === Failing Read on Invalid Contents === In the <> it was shown that the `` @@ -866,7 +927,7 @@ case any of the member fields has an invalid value. ---- -[[messages-reusing-other-fields]] +[[messages-reusing-other-messages]] === Reusing Other Messages === Sometimes two different messages are very similar but differ in one or two particular aspects. It is possible to reuse the other message definition using **reuse** property (similar to <>), @@ -912,5 +973,10 @@ boolean value can be used in addition to **reuse** one. ---- +**Note** that some message definition properties mentioned earlier (such as +**copyFieldsFrom**, **copyConstructFrom**, **copyReadCondFrom**, etc...) are __action__ ones. They +force copy of elements from one message to another and disappear when it comes to +<> of the message definition that uses them. + Use <> for future references. From 957cd3490272fc7fb12a141d7fd43f19de340a67 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Mon, 23 Dec 2024 11:35:56 +1000 Subject: [PATCH 19/20] Added support for "reuseAliases" property for and . --- aliases/aliases.adoc | 75 ++++++++++++++--------------------------- appendix/bundle.adoc | 2 +- appendix/interface.adoc | 1 + appendix/message.adoc | 1 + 4 files changed, 29 insertions(+), 50 deletions(-) diff --git a/aliases/aliases.adoc b/aliases/aliases.adoc index 69f605e..bf56536 100644 --- a/aliases/aliases.adoc +++ b/aliases/aliases.adoc @@ -109,6 +109,7 @@ There can be any number of different **<alias>** nodes. The elements that are allowed to have **<alias>**-es are <>, <>, and <>. +[[aliases-description]] === Description === The **<alias>** node may also have **description** <> which is expected to find its way into @@ -130,76 +131,52 @@ the generated code as a comment for the relevant access functions. ---- -=== More on Aliases in <message>-es === -When a new <> is defined, it can -copy all the fields from other already defined <> or <> -(using **copyFieldsFrom** <>). -By default all the <> definitions are also copied. -It is possible to modify this default behavior by using **copyFieldsAliases** +[[aliases-reuse]] +=== Reusing Definition === +By default when the original definition is <> its aliases are also copied. +It is possible to modify this default behavior by using **reuseAliases** <> with <> value. [source,xml] ---- - - ... - + + + ... + + + - - ... - - + + ... + + ---- -=== More on Aliases in <interface>-es === -Similar to <>-es -<> can also use **copyFieldsFrom** -<> to copy its field from some other -<> or <> definition and have all -the aliases copied by default. The control of such default copying behavior -is also done by using **copyFieldsAliases** +[[aliases-copy]] +=== Copying Fields === +When a new <> or <> is defined, it can +copy all the fields from other already defined <>, <>, or <> +(using **copyFieldsFrom** <>). +By default all the <> definitions are also copied. +It is possible to modify this default behavior by using **copyFieldsAliases** <> with <> value. [source,xml] ---- - + ... - + - + ... - + ---- -=== More on Aliases in <bundle>-es === -When a new <> field is defined it can -reuse definition of already defined other <> -(using **reuse** <>). -By default all the <> definitions are also copied. -It is possible to modify this default behavior by using **reuseAliases** -<> with <> value. -[source,xml] ----- - - - - - ... - - - - - - ... - - - ----- - Use <> for future references. diff --git a/appendix/bundle.adoc b/appendix/bundle.adoc index c53c674..4346fec 100644 --- a/appendix/bundle.adoc +++ b/appendix/bundle.adoc @@ -10,7 +10,7 @@ for detailed description. |Property Name|Allowed Type / Value|DSL Version|Required|Default Value ^.^|Description |**copyValidCondFrom**|<> string|7|no||<> field definition from which extra validity condition needs to be copied. -|**reuseAliases**|<>|3|no|true|Control copy of the defined <> from reused other <> when **reuse** property is used. +|**reuseAliases**|<>|3|no|true|Control copy of the defined <> from reused other <> when **reuse** property is used. |**validCond**|string|7|no||Extra validity check operation condition. |=== diff --git a/appendix/interface.adoc b/appendix/interface.adoc index a6b483c..ddf13e7 100644 --- a/appendix/interface.adoc +++ b/appendix/interface.adoc @@ -13,6 +13,7 @@ for detailed description. |**description**|string|1|no||Human readable description of the interface. |**name**|<> string|1|yes||Name of the interface. |**reuse**|<> string|7|no||Interface definition of which to copy. +|**reuseAliases**|<>|7|no|true|Control copy of the defined <> from reused other <> when **reuse** property is used. |**reuseCode**|<>|7|no|false|In case of **reuse** apply **copyCodeFrom** with the same <> string. |=== diff --git a/appendix/message.adoc b/appendix/message.adoc index 74f7204..5292c0f 100644 --- a/appendix/message.adoc +++ b/appendix/message.adoc @@ -32,6 +32,7 @@ Must be greater than value of **sinceVersion**. |**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. |**reuse**|<> string|7|no||Message definition of which to copy. +|**reuseAliases**|<>|7|no|true|Control copy of the defined <> from reused other <> when **reuse** property is used. |**reuseCode**|<>|7|no|false|In case of **reuse** apply **copyCodeFrom** with the same <> string. |**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. From 0f344a021de0c3806012ac639aa8d82b6123a739 Mon Sep 17 00:00:00 2001 From: Alex Robenko Date: Sun, 12 Jan 2025 09:27:15 +1000 Subject: [PATCH 20/20] Updated date to be 2025-01. --- commsdsl_spec.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/commsdsl_spec.adoc b/commsdsl_spec.adoc index 48e40b9..3e2dc0f 100644 --- a/commsdsl_spec.adoc +++ b/commsdsl_spec.adoc @@ -1,6 +1,6 @@ = CommsDSL Specification v7.0 Alex Robenko -v7.0, 2024-12 +v7.0, 2025-01 :doctype: article :toc: left :source-highlighter: rouge