[bug #45067] inconsistency & errors in crc.h documentation

[avrs-admin]

Sun 10 May 2015 07:59:16 PM CEST

From http://www.nongnu.org/avr-libc/user-manual/group__util__crc.html:

"Optimized CRC-XMODEM calculation. x^16 + x^12 + x^5 + 1 (0x1021)"

The hex representation of the poly is correct, but doesn't match the long form, which should be: x^16 + x^15 + x^5 + 1

Other parts of the docs give the reversed poly in hex instead of the actual poly: "Optimized Dallas (now Maxim) iButton 8-bit CRC calculation. Polynomial: x^8 + x^5 + x^4 + 1 (0x8C)"

It would be better to describe them the way pycrc does, with the actual poly used and whether or not the crc reflects (reverses) the bits. https://www.tty1.net/pycrc/crc-models_en.html

This issue was migrated from https://savannah.nongnu.org/bugs/?45067

[avrs-admin]

Joerg Wunsch <joerg_wunsch> Sun 10 May 2015 08:22:54 PM CEST

Unfortunately, the bit order of the CRC polynomial appears to be one of the things where there is never consensus about. :( Just because you cite pycrc as one source, you'll as well be able to find numerous other sources quoting the opposite.

In your case of the Xmodem CRC, the official protocol documentation[1] declares the polynomial the same way our documentation does:

7.1  CRC Calculation

7.1.1  Formal_Definition
To calculate the 16 bit   CRC the message bits are considered to be the
coefficients of a polynomial. This message polynomial is first multiplied
by X^16 and then divided by the generator polynomial (X^16 + X^12 + X^5 +
1) using modulo two arithmetic.

[1]http://techheap.packetizer.com/communication/modems/xmodem-ymodem_reference.html

In essence, the difference between Xmodem and CCITT is only the bit order of the polynomial, since in both cases, the official doucumentation declares the polynomial being x^16 + x^12 + x^5 + 1, but in Xmodem, that translates into a hex value of 0x1021, while in CCITT, it translates into 0x8048.

Yes, I wish all these people would have agreed to a common definition. :)  The only useful option I see is that we could explain these ambiguities in deeper detail in the introduction to make people aware of it.

Opinions?

[avrs-admin]

Mon 25 May 2015 09:48:56 PM CEST

"Unfortunately, the bit order of the CRC polynomial appears to be one of the things where there is never consensus about. :( " I agree, so just pick one and be consistent about it.  My point is that crc.h mixes both bit orders without even a comment explaining it.

And if you're going to pick one, I think the way pycrc does it is best because it is explicit as to when the polynomial division is bit-reversed.  In cases where a CRC shows a polynomial in bit-reversed order, that's an implicit indication that it operates on the bits in reverse order (shift right instead of shift left).