pw_checksum#

Checksum calculation API

Stable C C++

The pw_checksum module provides functions for calculating checksums.

pw_checksum/crc16_ccitt.h#

constexpr uint16_t kCcittCrc16DefaultInitialValue = 0xFFFF#

The default initial value for the CRC16.

uint16_t CcittCrc16(span<const std::byte> data, uint16_t initial_value = kCcittCrc16DefaultInitialValue)#

Calculates the CRC16 of the provided data using polynomial 0x1021, with a default initial value of 0xFFFF.

To incrementally calculate a CRC16, use the previous value as the initial value.

uint16_t crc = CcittCrc16(my_data);

crc  = CcittCrc16(more_data, crc);

pw_checksum/crc32.h#

constexpr uint32_t kCrc32InitialValue = 0xFFFFFFFF#

The initial value for the CRC32.

uint32_t Crc32(span<const std::byte> data)#

Calculates the initial / one-time CRC32 of the provided data using polynomial 0x4C11DB7, with an initial value of 0xFFFFFFFF.

uint32_t crc = Crc32(my_data);
uint32_t Crc32(span<const std::byte> data, uint32_t previous_result)#

Incrementally append calculation of a CRC32, need to pass in the previous result.

uint32_t crc = Crc32(my_data);
crc = Crc32(more_data, crc);

Implementations#

Pigweed provides 3 different CRC32 implementations with different size and runtime tradeoffs. The below table summarizes the variants. For more detailed size information see the Size report below. Instructions counts were calculated by hand by analyzing the assembly. Clock Cycle counts were measured using pw_perf_test on a STM32F429I-DISC1 development board.

Variant

Relative size (see Size Report below)

Speed

Lookup table size (entries)

Instructions/byte (M33/-Os)

Clock Cycles (123 char string)

Clock Cycles (9 bytes)

8 bits per iteration (default)

large

fastest

256

8

1538

170

4 bits per iteration

small

fast

16

13

2153

215

1 bit per iteration

smallest

slow

0

43

7690

622

The default implementation provided by the APIs above can be selected through Module Configuration Options. Additionally pw_checksum provides variants of the C++ API to explicitly use each of the implementations. These classes provide the same API as Crc32:

  • Crc32EightBit

  • Crc32FourBit

  • Crc32OneBit

Size report#

The CRC module currently optimizes for speed instead of binary size, by using pre-computed 256-entry tables to reduce the CPU cycles per byte CRC calculation.

Label

Segment

Delta

CRC16 with 256-entry table

FLASH

-8

[section .code]

-4

quorem

+4

pw::checksum::RunChecksum()

DEL

-4

pw::checksum::NoOpChecksum::value()

NEW

+520

pw::checksum::(anonymous namespace)::kCrc16CcittTable

NEW

+44

pw_checksum_Crc16Ccitt

+552

CRC32: 8 bits per iteration, 256-entry table

FLASH

-8

[section .code]

+4

pw::checksum::RunChecksum()

DEL

-4

pw::checksum::NoOpChecksum::value()

NEW

+1,032

_pw_checksum_InternalCrc32EightBit::kCrc32Table

NEW

+40

_pw_checksum_InternalCrc32EightBit

+1,064

CRC32: 4 bits per iteration, 16-entry table

FLASH

-8

[section .code]

-4

quorem

+4

pw::checksum::RunChecksum()

DEL

-4

pw::checksum::NoOpChecksum::value()

NEW

+72

_pw_checksum_InternalCrc32FourBit::kCrc32Table

NEW

+52

_pw_checksum_InternalCrc32FourBit

+112

CRC32: 1 bit per iteration, no table

FLASH

-4

quorem

+4

pw::checksum::RunChecksum()

DEL

-4

pw::checksum::NoOpChecksum::value()

NEW

+44

_pw_checksum_InternalCrc32OneBit

+40

Fletcher16 (illustrative only)

FLASH

+32

pw::checksum::RunChecksum()

DEL

-4

pw::checksum::NoOpChecksum::value()

NEW

+62

pw::checksum::Fletcher16::Update()

NEW

+6

pw::checksum::Fletcher16::value()

+96

Compatibility#

  • C

  • C++17

Dependencies#

Module Configuration Options#

The following configurations can be adjusted via compile-time configuration of this module, see the module documentation for more details.

PW_CHECKSUM_CRC32_DEFAULT_IMPL#

Selects which of the Implementations the default CRC32 APIs use. Set to one of the following values:

  • PW_CHECKSUM_CRC32_8BITS

  • PW_CHECKSUM_CRC32_4BITS

  • PW_CHECKSUM_CRC32_1BITS

Zephyr#

To enable pw_checksum for Zephyr add CONFIG_PIGWEED_CHECKSUM=y to the project’s configuration.