util_crc(3)

📦 version 2.2.1, in fedora 43, fedora 44, opensuse-leap 16.0

💖 NAME 💖

okay so bestie, welcome to util_crc(3) — yes that's the real page name, and it lives in the avr-libc manual ✨ This whole page is literally the CRC squad: a header file full of optimized inline functions for calculating cyclic redundancy checks (CRC) using common polynomials. That's it, that's the vibe. 💅

✨ SYNOPSIS ✨

Here's the lineup, no cap. All of them static __inline__, all of them absolutely ready to eat your bytes:

  • static __inline__ uint16_t _crc16_update (uint16_t __crc, uint8_t __data)
  • static __inline__ uint16_t _crc_xmodem_update (uint16_t __crc, uint8_t __data)
  • static __inline__ uint16_t _crc_ccitt_update (uint16_t __crc, uint8_t __data)
  • static __inline__ uint8_t _crc_ibutton_update (uint8_t __crc, uint8_t __data)
  • static __inline__ uint8_t _crc8_ccitt_update (uint8_t __crc, uint8_t __data)

🌸 DETAILED DESCRIPTION 🌸

First things first, the portal you gotta walk through 🚪✨

#include <util/crc16.h>

This header file provides optimized inline functions for calculating cyclic redundancy checks (CRC) using common polynomials. Iconic behavior honestly.

References — aka the required reading, the syllabus, the homework 📚:

  • See the Dallas Semiconductor app note 27 for 8051 assembler example and general CRC optimization suggestions. The table on the last page of the app note is the key to understanding these implementations. iykyk.
  • Jack Crenshaw's 'Implementing CRCs' article in the January 1992 isue of Embedded Systems Programming. This may be difficult to find, but it explains CRC's in very clear and concise terms. Well worth the effort to obtain a copy. (Bestie, go get it. Do it for the plot. 🫶)

A typical application would look like:

// Dallas iButton test vector.
uint8_t serno[] = { 0x02, 0x1c, 0xb8, 0x01, 0, 0, 0, 0xa2 };

int
checkcrc(void)
{
uint8_t crc = 0, i;

for (i = 0; i < sizeof serno / sizeof serno[0]; i++)
    crc = _crc_ibutton_update(crc, serno[i]);

return crc; // must be 0
}

🔥 FUNCTION DOCUMENTATION 🔥

🌈 static __inline__ uint16_t _crc16_update (uint16_t __crc, uint8_t __data)

[static]

Optimized CRC-16 calculation. She's efficient, she's inline, she's booked and busy.

  • Polynomial: x^16 + x^15 + x^2 + 1 (0xa001)
  • Initial value: 0xffff

This CRC is normally used in disk-drive controllers. Fancy 💅

The following is the equivalent functionality written in C:

uint16_t
crc16_update(uint16_t crc, uint8_t a)
{
int i;

crc ^= a;
for (i = 0; i < 8; ++i)
{
    if (crc & 1)
    crc = (crc >> 1) ^ 0xA001;
    else
    crc = (crc >> 1);
}

return crc;
}

🦋 static __inline__ uint8_t _crc8_ccitt_update (uint8_t __crc, uint8_t __data)

[static]

Optimized CRC-8-CCITT calculation. Little 8-bit icon 🎀

  • Polynomial: x^8 + x^2 + x + 1 (0xE0)

Depending on which flavor of CRC-8 you're serving, the starting value changes:

The C equivalent has been originally written by Dave Hylands. Assembly code is based on _crc_ibutton_update optimization. Shoutout Dave, king behavior 👑

The following is the equivalent functionality written in C:

uint8_t
_crc8_ccitt_update (uint8_t inCrc, uint8_t inData)
{
    uint8_t   i;
    uint8_t   data;

    data = inCrc ^ inData;

    for ( i = 0; i < 8; i++ )
    {
        if (( data & 0x80 ) != 0 )
        {
            data <<= 1;
            data ^= 0x07;
        }
        else
        {
            data <<= 1;
        }
    }
    return data;
}

💜 static __inline__ uint16_t _crc_ccitt_update (uint16_t __crc, uint8_t __data)

[static]

Optimized CRC-CCITT calculation. The internet's little helper, fr fr.

  • Polynomial: x^16 + x^12 + x^5 + 1 (0x8408)
  • Initial value: 0xffff

This is the CRC used by PPP and IrDA.

See RFC1171 (PPP protocol) and IrDA IrLAP 1.1

Note: Although the CCITT polynomial is the same as that used by the Xmodem protocol, they are quite different. The difference is in how the bits are shifted through the alorgithm. Xmodem shifts the MSB of the CRC and the input first, while CCITT shifts the LSB of the CRC and the input first. Not me pointing out that they're cousins, not twins. 💀

The following is the equivalent functionality written in C:

uint16_t
crc_ccitt_update (uint16_t crc, uint8_t data)
{
    data ^= lo8 (crc);
    data ^= data << 4;

    return ((((uint16_t)data << 8) | hi8 (crc)) ^ (uint8_t)(data >> 4)
            ^ ((uint16_t)data << 3));
}

🍓 static __inline__ uint8_t _crc_ibutton_update (uint8_t __crc, uint8_t __data)

[static]

Optimized Dallas (now Maxim) iButton 8-bit CRC calculation. The one with a whole test vector named after it, main character energy 🔥

  • Polynomial: x^8 + x^5 + x^4 + 1 (0x8C)
  • Initial value: 0x0

See http://www.maxim-ic.com/appnotes.cfm/appnote_number/27

The following is the equivalent functionality written in C:

uint8_t
_crc_ibutton_update(uint8_t crc, uint8_t data)
{
uint8_t i;

crc = crc ^ data;
for (i = 0; i < 8; i++)
{
    if (crc & 0x01)
        crc = (crc >> 1) ^ 0x8C;
    else
        crc >>= 1;
}

return crc;
}

⭐ static __inline__ uint16_t _crc_xmodem_update (uint16_t __crc, uint8_t __data)

[static]

Optimized CRC-XMODEM calculation. 16 bits of pure dedication ✨

  • Polynomial: x^16 + x^12 + x^5 + 1 (0x1021)
  • Initial value: 0x0

This is the CRC used by the Xmodem-CRC protocol.

The following is the equivalent functionality written in C:

uint16_t
crc_xmodem_update (uint16_t crc, uint8_t data)
{
    int i;

    crc = crc ^ ((uint16_t)data << 8);
    for (i=0; i<8; i++)
    {
        if (crc & 0x8000)
            crc = (crc << 1) ^ 0x1021;
        else
            crc <<= 1;
    }

    return crc;
}

👑 AUTHOR 👑

Generated automatically by Doxygen for avr-libc from the source code. (Not a human author, just Doxygen doing its little autogenerated thing. Still ate. 💖)

okay bestie that's the whole page 🫶 and one last cute sign-off: this is Version 2.1.0, dated Sat Jan 29 2022. Go checksum something, you got this 💅✨

📦 where this page comes from