> For the complete documentation index, see [llms.txt](https://alex-robenko.gitbook.io/commsdsl-specification/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alex-robenko.gitbook.io/commsdsl-specification/frames/checksum.md).

# checksum Layer

The **\<checksum>** layer represents checksum bytes, usually (but not always) present at the end of the [frame](/commsdsl-specification/frames.md).

```
<?xml version="1.0" encoding="UTF-8"?>
<schema endian="big" ...>
    <frame name="ProtocolFrame">
        <sync name="Sync">
            ...
        </sync>
        <size name="Size">
            ...
        </size>
        <id name="Id">
            ...  
        </id>
        <payload name="Data" />
        <checksum name="Checksum" ...>
            <int name="ChecksumField" type="uint16" />
        </checksum>
    </frame>
</schema>
```

The **\<checksum>** layer has all the [common](/commsdsl-specification/frames/common.md) properties as well as extra properties and elements described below.

## Checksum Algorithm

The checksum calculation algorithm must be specified using **alg** [property](/commsdsl-specification/properties.md). Supported values are:

* **sum** - Sum of all the bytes.
* **crc-ccitt** (aliases: **crc\_ccitt**) - [CRC-16-CCITT](https://en.wikipedia.org/wiki/Cyclic_redundancy_check)

  where polynomial is `0x1021`, initial value is `0xffff`, final XOR value is `0`, and no reflection of bytes.
* **crc-16** (aliases: **crc\_16**) - [CRC-16-IBM](https://en.wikipedia.org/wiki/Cyclic_redundancy_check),

  where polynomial is `0x8005`, initial value is `0`, final XOR value is `0`, reflection is performed on every

  byte as well as final value.
* **crc-32** (aliases: **crc\_32**) - [CRC-32](https://en.wikipedia.org/wiki/Cyclic_redundancy_check),

  where polynomial is `0x04C11DB7`, initial value is `0xffffffff`, final XOR value is `0xffffffff`, reflection is

  performed on every byte as well as final value.
* **custom** - Custom algorithm, code for which needs to be provided to the

  code generator, so it can copy it to the generated code.

  ```
  <?xml version="1.0" encoding="UTF-8"?>
  <schema endian="big" ...>
    <frame name="ProtocolFrame">
        ...
        <payload name="Data" />
        <checksum name="Checksum" alg="crc-16" ...>
            <int name="ChecksumField" type="uint16" />
        </checksum>
    </frame>
  </schema>
  ```

When **custom** algorithm is selected, its name must be provided using **algName** property.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema endian="big" ...>
    <frame name="ProtocolFrame">
        ...
        <payload name="Data" />
        <checksum name="Checksum" alg="custom" algName="MyCustomChecksumCalc" ...>
            <int name="ChecksumField" type="uint16" />
        </checksum>
    </frame>
</schema>
```

The provided name of the custom algorithm can be used by the code generator to locate the required external implementation file and use appropriate class / function name when the calculation functionality needs to be invoked.

## Calculation Area

The **checksum** layer definition must also specify the layers, data of which is used to calculate the checksum. It is done using **from** property that is expected to specify name of the layer where checksum calculation starts.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema endian="big" ...>
    <frame name="ProtocolFrame">
        <sync name="Sync">
            ...
        </sync>
        <size name="Size">
            ...
        </size>
        <id name="Id">
            ...  
        </id>
        <payload name="Data" />
        <checksum name="Checksum" alg="crc-16" from="Size">
            <int name="ChecksumField" type="uint16" />
        </checksum>
    </frame>
</schema>
```

The example above defines `SYNC | SIZE | ID | PAYLOAD | CHECKSUM` frame where the checksum is calculated on `SIZE` + `ID` + `PAYLOAD` bytes.

Some protocols may put checksum value as prefix to the area on which the checksum needs to be calculated. In this case use **until** property (instead of **from**) to specify layers for checksum calculation.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema endian="big" ...>
    <frame name="ProtocolFrame">
        <sync name="Sync">
            ...
        </sync>
        <size name="Size">
            ...
        </size>
        <id name="Id">
            ...  
        </id>
        <checksum name="Checksum" alg="crc-16" until="Data">
            <int name="ChecksumField" type="uint16" />
        </checksum>
        <payload name="Data" />
    </frame>
</schema>
```

## Checksum Verification Order

The default behavior of the **\<checksum>** layer is to perform calculation after all relevant layers and their fields have been successfully read and processed. However, it is possible to force the checksum verification right away (without reading fields of other layers and/or message payload). It is usually possible to do when value of the [\<size>](/commsdsl-specification/frames/size.md) field is already processed, so the right location of checksum value is known, and it is not included in checksum calculation. To force immediate checksum verification use **verifyBeforeRead** [property](/commsdsl-specification/properties.md) with [boolean](/commsdsl-specification/boolean.md) value.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema endian="big" ...>
    <frame name="ProtocolFrame">
        <sync name="Sync">
            ...
        </sync>
        <size name="Size">
            ...
        </size>
        <id name="Id">
            ...  
        </id>
        <checksum name="Checksum" alg="crc-16" until="Data" verifyBeforeRead="true">
            <int name="ChecksumField" type="uint16" />
        </checksum>
        <payload name="Data" />
    </frame>
</schema>
```

Use [properties table](/commsdsl-specification/appendix/checksum.md) for future references.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alex-robenko.gitbook.io/commsdsl-specification/frames/checksum.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.