[avr-libc-dev] [bug #45067] inconsistency & errors in crc.h documentation

[anonymous]

URL:
<http://savannah.nongnu.org/bugs/?45067>

Summary: inconsistency & errors in crc.h documentation
Project: AVR C Runtime Library
Submitted by: None
Submitted on: Sun 10 May 2015 05:59:16 PM UTC
Category: Documentation
Severity: 3 - Normal
Priority: 5 - Normal
Item Group: Documentation
Status: None
Percent Complete: 0%
Assigned to: None
Originator Email: ***@gmail.com
Open/Closed: Open
Discussion Lock: Any
Release: 1.8.0
Fixed Release: None

_______________________________________________________

Details:

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





_______________________________________________________

Reply to this item at:

<http://savannah.nongnu.org/bugs/?45067>

_______________________________________________
Message sent via/by Savannah
http://savannah.nongnu.org/

[Joerg Wunsch]

Follow-up Comment #1, bug #45067 (project avr-libc):

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?

_______________________________________________________

Reply to this item at:

<http://savannah.nongnu.org/bugs/?45067>

_______________________________________________
Message sent via/by Savannah
http://savannah.nongnu.org/

[anonymous]

Follow-up Comment #2, bug #45067 (project avr-libc):

"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).


_______________________________________________________

Reply to this item at:

<http://savannah.nongnu.org/bugs/?45067>

_______________________________________________
Message sent via/by Savannah
http://savannah.nongnu.org/

[Jan Waclawek]

In my experience, the only thing which really helps in disambiguating CRC
calculation is a couple of simple but nontrivial input examples together
with the respective outputs.

I know it sounds/looks bad in the documentation, but it really helps.

Jan Waclawek

[Joerg Wunsch]

Post by Jan Waclawek
In my experience, the only thing which really helps in
disambiguating CRC calculation is a couple of simple but nontrivial
input examples together with the respective outputs.

I could probably live with that.