XTCE13 — Missing a number of changes and enumerations in ErrorDetectCorrectType children

The reworked XTCE 1.2 from the proposed BitBucket schema has additional checksums (also hashes) and a new XOR element. In addition, there is a missing @parameterRef that should appear to specify the parameter that holds the value. Some systems do not store that so it can be optional.

Propose to come back on deferred XTCE 1.2 resolution and enhance

An update was proposed for XTCE 1.2, but time ran out and nobody applied the change.

Here we intend to revisit the fix for XTCE 1.3. Much of this is borrowed and updated from the previous proposal in XTCE12-475. Some additional updates have been made based on my implementer's experience.

Existing Definition of ErrorDetectCorrectType:

<complexType name="ErrorDetectCorrectType">
<annotation>
<documentation>Describe error detection/correction algorithm.</documentation>
</annotation>
<choice>
<element name="Checksum" type="xtce:ChecksumType"/>
<element name="CRC" type="xtce:CRCType"/>
<element name="Parity" type="xtce:ParityType"/>
</choice>
</complexType>

Proposed New Definition of ErrorDetectCorrectType:

Changes:
1 - Added/Changed Annotation
2 - Added XOR type
3 - Made choice unbounded to multiple algorithms can be specified

<complexType name="ErrorDetectCorrectType">
<annotation>
<documentation>Describe CRC, Checksum, Parity, or XOR for error detection and correction algorithm calculation. See CRCType, ChecksumType, ParityType, and XORType.</documentation>
</annotation>
<choice maxOccurs="unbounded">
<element name="Checksum" type="xtce:ChecksumType">
<annotation>
<documentation xml:lang="en">Describe checksum or hash function applied to all or part of this container definition.</documentation>
</annotation>
</element>
<element name="CRC" type="xtce:CRCType">
<annotation>
<documentation xml:lang="en">Describe a Cyclic Redundancy Check (CRC) algorithm applied to all or part of this container definition.</documentation>
</annotation>
</element>
<element name="XOR" type="xtce:XORType">
<annotation>
<documentation xml:lang="en">Describe an "exclusive or" (XOR) checksum applied to all or part of this container definition.</documentation>
</annotation>
</element>
<element name="Parity" type="xtce:ParityType">
<annotation>
<documentation xml:lang="en">Describe a parity applied to all or part of this container definition.</documentation>
</annotation>
</element>
</choice>
</complexType>

The new type alluded to above needs to be added. Add XORType immediately after ValueEnumerationType:

<complexType name="XORType">
<annotation>
<documentation xml:lang="en">Describe an exclusive or (XOR) checksum definition. See ErrorDetectCorrectType.</documentation>
</annotation>
<attribute name="bitsFromReference" type="xtce:NonNegativeLongType" default="0">
<annotation>
<documentation xml:lang="en">An offset of non-zero may be specified to skip some bits against the reference position in the reference attribute.</documentation>
</annotation>
</attribute>
<attribute name="reference" type="xtce:ReferencePointType" default="start">
<annotation>
<documentation xml:lang="en">The bits involved in the calculation may start at the beginning or the end of the container.</documentation>
</annotation>
</attribute>
<attribute name="parameterRef" type="xtce:NameReferenceType">
<annotation>
<documentation xml:lang="en">Reference to the parameter that contains the value of this computed XOR based on this container. This attribute is optional because not all implementations verify (telemetry) or create (telecommand) error control fields using the XTCE definition.</documentation>
</annotation>
</attribute>
</complexType>

Next update the annotation on the ChecksumType. Existing Definition of ChecksumType:

<complexType name="ChecksumType">
<annotation>
<documentation>Describe checksum information.</documentation>
</annotation>
<sequence>
<element name="InputAlgorithm" type="xtce:InputAlgorithmType" minOccurs="0">
<annotation>
<documentation>Assumed to return the computed checksum.</documentation>
</annotation>
</element>
</sequence>
<attribute name="bitsFromReference" type="xtce:NonNegativeLongType"/>
<attribute name="reference" type="xtce:ReferencePointType" default="start"/>
<attribute name="name" use="required">
<annotation>
<documentation>Qualified list of name checksum algorithms. If custom is chosen, InputAlgorithm must be set.</documentation>
</annotation>
<simpleType>
<restriction base="string">
<enumeration value="unix_sum"/>
<enumeration value="sum8"/>
<enumeration value="sum16"/>
<enumeration value="sum24"/>
<enumeration value="sum32"/>
<enumeration value="fletcher4"/>
<enumeration value="fletcher8"/>
<enumeration value="fletcher16"/>
<enumeration value="fletcher32"/>
<enumeration value="adler32"/>
<enumeration value="luhn"/>
<enumeration value="verhoeff"/>
<enumeration value="damm"/>
<enumeration value="custom">
<annotation>
<documentation>Document a custom checksum algorithm</documentation>
</annotation>
</enumeration>
</restriction>
</simpleType>
</attribute>
<attribute name="hashSizeInBits" type="xtce:PositiveLongType"/>
</complexType>

Proposed New Definition of ChecksumType:

1 - Added/Changed annotation
2 - Added parameterRef attribute

<complexType name="ChecksumType">
<annotation>
<documentation xml:lang="en">Describe checksum or hash function definiton. See ErrorDetectCorrectType.</documentation>
</annotation>
<sequence>
<element name="InputAlgorithm" type="xtce:InputAlgorithmType" minOccurs="0">
<annotation>
<documentation xml:lang="en">Provided to account for an algorithm not otherwise listed by enumeration. Assumed to return the computed checksum.</documentation>
</annotation>
</element>
</sequence>
<attribute name="bitsFromReference" type="xtce:NonNegativeLongType" default="0">
<annotation>
<documentation xml:lang="en">An offset of non-zero may be specified to skip some bits against the reference position in the reference attribute.</documentation>
</annotation>
</attribute>
<attribute name="reference" type="xtce:ReferencePointType" default="start">
<annotation>
<documentation xml:lang="en">The bits involved in the calculation may start at the beginning or the end of the container.</documentation>
</annotation>
</attribute>
<attribute name="name" use="required">
<annotation>
<documentation xml:lang="en">Qualified list of named common checksum algorithms. If custom is chosen, InputAlgorithm must be set.</documentation>
</annotation>
<simpleType>
<restriction base="string">
<enumeration value="unix_sum"/>
<enumeration value="sum8"/>
<enumeration value="sum16"/>
<enumeration value="sum24"/>
<enumeration value="sum32"/>
<enumeration value="fletcher4"/>
<enumeration value="fletcher8"/>
<enumeration value="fletcher16"/>
<enumeration value="fletcher32"/>
<enumeration value="adler32"/>
<enumeration value="luhn"/>
<enumeration value="verhoeff"/>
<enumeration value="damm"/>
<enumeration value="custom">
<annotation>
<documentation xml:lang="en">Document a custom checksum algorithm in the InputAlgorithm element.</documentation>
</annotation>
</enumeration>
</restriction>
</simpleType>
</attribute>
<attribute name="hashSizeInBits" type="xtce:PositiveLongType">
<annotation>
<documentation xml:lang="en">The hashing algorithm may use a larger internal bucket size than the emitted value size in bits captured by the parameterRef attribute.</documentation>
</annotation>
</attribute>
<attribute name="parameterRef" type="xtce:NameReferenceType">
<annotation>
<documentation xml:lang="en">Reference to the parameter that contains the value of this computed checksum or hash based on this container. This attribute is optional because not all implementations verify (telemetry) or create (telecommand) error control fields using the XTCE definition.</documentation>
</annotation>
</attribute>
</complexType>

Next update the annotation on the ParityType. Existing Definition of ParityType:

<complexType name="ParityType">
<annotation>
<documentation xml:lang="en">Bit position starts with 'zero'.</documentation>
</annotation>
<attribute name="type" type="xtce:ParityFormType" use="required"/>
<attribute name="bitsFromReference" type="xtce:NonNegativeLongType" use="required"/>
<attribute name="reference" type="xtce:ReferencePointType" default="start"/>
</complexType>

Proposed New Definition of ParityType:

1 - Added/Changed annotation
2 - Made bitsFromReference optional like the other forms
3 - Added parameterRef attribute

<complexType name="ParityType">
<annotation>
<documentation xml:lang="en">Describe the parity value. See ErrorDetectCorrectType.</documentation>
</annotation>
<attribute name="type" type="xtce:ParityFormType" use="required">
<annotation>
<documentation xml:lang="en">The parity form.</documentation>
</annotation>
</attribute>
<attribute name="bitsFromReference" type="xtce:NonNegativeLongType" default="0">
<annotation>
<documentation xml:lang="en">An offset of non-zero may be specified to skip some bits against the reference position in the reference attribute.</documentation>
</annotation>
</attribute>
<attribute name="reference" type="xtce:ReferencePointType" default="start">
<annotation>
<documentation xml:lang="en">The bits involved in the calculation may start at the beginning or the end of the container.</documentation>
</annotation>
</attribute>
<attribute name="parameterRef" type="xtce:NameReferenceType">
<annotation>
<documentation xml:lang="en">Reference to the parameter that contains the value of the parity based on this container. This attribute is optional because not all implementations verify (telemetry) or create (telecommand) error control fields using the XTCE definition.</documentation>
</annotation>
</attribute>
</complexType>

Next update the annotation on the CRCType. Existing Definition of CRCType:

<complexType name="CRCType">
<annotation>
<documentation xml:lang="en">Cyclic Redundancy Check (CRC) definition. The polynomial coefficients for the CRC
are defined as a truncated hex value. The coefficient for the nth bit of an n-bit CRC will always be 1 and is not
represented in the truncated hex value. For example, the truncated hex value of CRC-32 (width=32 bits) used in the
Ethernet specification is 0x04C11DB7, where each non-zero bit of the truncated hex represents a coefficient of 1 in
the polynomial and the bit position represents the exponent. There may also be an initial remainder "InitRemainder"
and a final XOR "FinalXOR" to fully specify the CRC. reflectData and reflectRemainder may also be specified to
reverse the bit order in the incoming data and/or the result.
</documentation>
</annotation>
<sequence>
<element name="Polynomial" type="hexBinary"/>
<element name="InitRemainder" type="hexBinary" minOccurs="0"/>
<element name="FinalXOR" type="hexBinary" minOccurs="0"/>
</sequence>
<attribute name="width" type="xtce:PositiveLongType"/>
<attribute name="reflectData" type="boolean" default="false"/>
<attribute name="reflectRemainder" type="boolean" default="false"/>
<attribute name="bitsFromReference" type="xtce:NonNegativeLongType"/>
<attribute name="reference" type="xtce:ReferencePointType" default="start"/>
</complexType>

Proposed New Definition of CRCType:

1 - Added/Changed annotation
2 - Added parameterRef attribute
3 - Added direction attribute

<complexType name="CRCType">
<annotation>
<documentation xml:lang="en">Cyclic Redundancy Check (CRC) definition. The polynomial coefficients for the CRC are defined as a truncated hex value. The coefficient for the nth bit of an n-bit CRC will always be 1 and is not represented in the truncated hex value. For example, the truncated hex value of CRC-32 (width=32 bits) used in the Ethernet specification is 0x04C11DB7, where each non-zero bit of the truncated hex represents a coefficient of 1 in the polynomial and the bit position represents the exponent. There may also be an initial remainder "InitRemainder" and a final XOR "FinalXOR" to fully specify the CRC. reflectData and reflectRemainder may also be specified to reverse the bit order in the incoming data and/or the result.</documentation>
</annotation>
<sequence>
<element name="Polynomial" type="hexBinary">
<annotation>
<documentation xml:lang="en">The polynomial that represents the calculation in hexadecimal form (described at CRCType annotation).</documentation>
</annotation>
</element>
<element name="InitRemainder" type="hexBinary" minOccurs="0" default="00">
<annotation>
<documentation xml:lang="en">A hexadecimal digit string specifying the initial value to set in the shift register before computing the CRC.</documentation>
</annotation>
</element>
<element name="FinalXOR" type="hexBinary" minOccurs="0" default="00">
<annotation>
<documentation xml:lang="en">A hexadecimal digit string specifying the value to be added to the final shift register value before output.</documentation>
</annotation>
</element>
</sequence>
<attribute name="width" type="xtce:PositiveLongType" use="required">
<annotation>
<documentation xml:lang="en">The width is the number of bits in the shift register, which is not necessarily the number of bits of the parameter holding the value.</documentation>
</annotation>
</attribute>
<attribute name="reflectData" type="boolean" default="false">
<annotation>
<documentation xml:lang="en">Endianness of the input data, true=little, false=big.</documentation>
</annotation>
</attribute>
<attribute name="reflectRemainder" type="boolean" default="false">
<annotation>
<documentation xml:lang="en">Endianness of the output data, true=little, false=big.</documentation>
</annotation>
</attribute>
<attribute name="direction" type="xtce:BitOrderType" default="mostSignificantBitFirst">
<annotation>
<documentation xml:lang="en">The direction to perform the CRC calculation.</documentation>
</annotation>
</attribute>
<attribute name="bitsFromReference" type="xtce:NonNegativeLongType" default="0">
<annotation>
<documentation xml:lang="en">An offset of non-zero may be specified to skip some bits against the reference position in the reference attribute.</documentation>
</annotation>
</attribute>
<attribute name="reference" type="xtce:ReferencePointType" default="start">
<annotation>
<documentation xml:lang="en">The bits involved in the calculation may start at the beginning or the end of the container.</documentation>
</annotation>
</attribute>
<attribute name="parameterRef" type="xtce:NameReferenceType">
<annotation>
<documentation xml:lang="en">Reference to the parameter that contains the value of the CRC based on this container. This attribute is optional because not all implementations verify (telemetry) or create (telecommand) error control fields using the XTCE definition.</documentation>
</annotation>
</attribute>
</complexType>

Lastly, propose to mark the ErrorDetectCorrect element from the DataEncodingType definition as deprecated. This has the effect of removing the ErrorDetectCorrect element from the encoding types in the Parameter Type and Argument Type elements.

Existing Definition of DataEncodingType:

<complexType name="DataEncodingType" abstract="true">
<annotation>
<documentation xml:lang="en">Describes how a particular piece of data is sent or received from some non-native, off-platform device. (e.g. a spacecraft)</documentation>
</annotation>
<sequence>
<element name="ErrorDetectCorrect" type="xtce:ErrorDetectCorrectType" minOccurs="0"/>
</sequence>
<attribute name="bitOrder" type="xtce:BitOrderType" default="mostSignificantBitFirst"/>
<attribute name="byteOrder" type="xtce:ByteOrderType" default="mostSignificantByteFirst"/>
</complexType>

New proposed definition of DataEncodingType:

<complexType name="DataEncodingType" abstract="true">
<annotation>
<documentation xml:lang="en">Describes how a particular piece of data is sent or received from some non-native, off-platform device. (e.g. a spacecraft)</documentation>
</annotation>
<sequence>
<element name="ErrorDetectCorrect" type="xtce:ErrorDetectCorrectType" minOccurs="0">
<annotation>
<documentation xml:lang="en">DEPRECATED: Use the ErrorDetectCorrect element in the container elements instead.</documentation>
</annotation>
</element>
</sequence>
<attribute name="bitOrder" type="xtce:BitOrderType" default="mostSignificantBitFirst">
<annotation>
<documentation xml:lang="en">Describes the bit ordering of the encoded value.</documentation>
</annotation>
</attribute>
<attribute name="byteOrder" type="xtce:ByteOrderType" default="mostSignificantByteFirst">
<annotation>
<documentation xml:lang="en">Describes the endianness of the encoded value.</documentation>
</annotation>
</attribute>
</complexType>