3.4.14 Checksum Option

The -mchecksum=specs option will calculate a hash value (for example checksum or CRC) over the address range specified and stores the result in the hex file at the indicated destination address. The general form of this option is as follows.

-mchecksum=start-end@destination[,specifications]

The start, end and destination attributes are, by default, hexadecimal constants. The addresses defining the input range (start - end) are typically made multiples of the algorithm width. If this is not the case, bytes (with value 0) will pad any missing input word locations. The destination is where the hash result will be stored. This address cannot be within the range of addresses over which the hash is calculated.

The following specifications are appended as a comma-separated list to this option.

Table 3-4. Checksum Arguments
Argument	Description
`width=n`	Optionally specifies a decimal width of the result. The width can be specified as 1 to 8 bytes for most algorithms, but it represents the bit width for SHA algorithms. If a positive width is requested, the result will be stored in big-endian byte order. A negative width will cause the result to be stored in little-endian byte order. If the width is left unspecified, the result will be 2 bytes wide and stored in little-endian byte order. This width argument is not required with any Fletcher algorithm, as they have fixed widths, but it may be used to alter the default endianism of the result.
`offset=nnnn`	Specifies an initial hexadecimal value or offset to be used in the hash calculation. It is not used with SHA algorithms.
`algorithm=n`	The decimal argument selects one of the hash algorithms implemented in Hexmate. The selectable algorithms are described in the following table. If unspecified, the default algorithm used is 8-bit checksum addition (algorithm 1).
`polynomial=nn`	Selects the polynomial value when using CRC algorithms
`code=nn.Base`	Selects a hexadecimal code that will trail each byte in the result. This can allow each byte of the hash result to be embedded within an instruction, for example `code=34` will embed each byte of the result in a `retlw` instruction on Mid-range devices, or `code=0000` will append two 0x00 bytes to each byte of the hash. This code sequence can be optionally followed by `.Base`, where `Base` is the number of bytes of the hash to be output before the trailing code sequence is appended. A specification of `code=1122.2`, for example, will output the bytes 0x11 and 0x22 after each two bytes of the hash result.
`revword=n`	Specifies a decimal word width. If this is non-zero, then bytes within each word are read in reverse order when calculating a hash value. Words are aligned to the addresses in the HEX file. At present, the width must be 0 or 2. A zero width disables the reverse-byte feature, as if the `revword` suboption was not present. This suboption should be used when using Hexmate to match a CRC produced by a PIC hardware CRC module that use the Scanner module to stream data to it.
`skip=n.Bytes`	Specifies a decimal word width. If this is non-zero, then the MSB within each word is skipped for the purposes of calculating a hash value. Words are aligned to the addresses in the HEX file. At present, the width must be 0 (which disables the skip feature, as if the `skip` suboption was not present) or greater than 1. This value can be optionally followed by `.Bytes`, where `Bytes` is a number representing the number of bytes to skip in each word, for example `skip=4.2` will skip the two most significant bytes in each 4-byte word.
`xor=n`	Specifies a hexadecimal value (a leading `0x` or `0X` prefix is optional) that will be XORed with CRC results before it is stored. XORs cannot be performed when using other algorithms.

Note that the reverse and skip features act on words that are aligned to the HEX file addresses, not to the position of the data in the sequence being processed. In other words, the alignment of the words are not affected by the start and end addresses specified with the option.

If an accompanying --fill option (3.4.5 Fill Option) has not been specified, unused locations within the specified address range will be automatically filled with 0xFFF for baseline devices, 0x3FFF for mid-range devices, or 0xFFFF for PIC18 devices. This is to remove any unknown values from the calculations and ensure the accuracy of the result.

For example:

-mchecksum=800-fff@20,width=1,algorithm=2

will calculate a 1-byte checksum from address 0x800 to 0xfff and store this at address 0x20. A 16-bit addition algorithm will be used. The table below shows the available algorithms and 7.2.4 Hash Value Calculations describes these in detail.

Table 3-5. Checksum Algorithm Selection
Selector	Algorithm description
`-5`	Reflected cyclic redundancy check (CRC)
`-4`	Subtraction of 32 bit values from initial value
`-3`	Subtraction of 24 bit values from initial value
`-2`	Subtraction of 16 bit values from initial value
`-1`	Subtraction of 8 bit values from initial value
`1`	Addition of 8 bit values from initial value
`2`	Addition of 16 bit values from initial value
`3`	Addition of 24 bit values from initial value
`4`	Addition of 32 bit values from initial value
`5`	Cyclic redundancy check (CRC)
`7`	Fletcher’s checksum (8 bit calculation, 2-byte result width)
`8`	Fletcher’s checksum (16 bit calculation, 4-byte result width)
`10`	SHA-2 (currently only SHA256 is supported)
`11`	SHA-1 (160 bit)

The hash calculations are performed by the Hexmate utility. Further information regarding how hashes are calculated can be found in 7.2.3.12 Ck Hexmate Option.