1.. _module-pw_checksum: 2 3----------- 4pw_checksum 5----------- 6.. pigweed-module:: 7 :name: pw_checksum 8 9The ``pw_checksum`` module provides functions for calculating checksums. 10 11pw_checksum/crc16_ccitt.h 12========================= 13 14.. cpp:namespace:: pw::checksum 15 16.. cpp:var:: constexpr uint16_t kCcittCrc16DefaultInitialValue = 0xFFFF 17 18 The default initial value for the CRC16. 19 20.. cpp:function:: uint16_t CcittCrc16(span<const std::byte> data, uint16_t initial_value = kCcittCrc16DefaultInitialValue) 21 22 Calculates the CRC16 of the provided data using polynomial 0x1021, with a 23 default initial value of :cpp:expr:`0xFFFF`. 24 25 To incrementally calculate a CRC16, use the previous value as the initial 26 value. 27 28 .. code-block:: cpp 29 30 uint16_t crc = CcittCrc16(my_data); 31 32 crc = CcittCrc16(more_data, crc); 33 34pw_checksum/crc32.h 35=================== 36 37.. cpp:var:: constexpr uint32_t kCrc32InitialValue = 0xFFFFFFFF 38 39 The initial value for the CRC32. 40 41.. cpp:function:: uint32_t Crc32::Calculate(span<const std::byte> data) 42 43 Calculates the initial / one-time CRC32 of the provided data using polynomial 44 0x4C11DB7, with an initial value of :cpp:expr:`0xFFFFFFFF`. 45 46 .. code-block:: cpp 47 48 uint32_t crc = Crc32::Calculate(my_data); 49 50.. _CRC32 Implementations: 51 52Implementations 53--------------- 54Pigweed provides 3 different CRC32 implementations with different size and 55runtime tradeoffs. The below table summarizes the variants. For more detailed 56size information see the :ref:`pw_checksum-size-report` below. Instructions 57counts were calculated by hand by analyzing the 58`assembly <https://godbolt.org/z/nY1bbb5Pb>`_. Clock Cycle counts were measured 59using :ref:`module-pw_perf_test` on a STM32F429I-DISC1 development board. 60 61 62.. list-table:: 63 :header-rows: 1 64 65 * - Variant 66 - Relative size (see Size Report below) 67 - Speed 68 - Lookup table size (entries) 69 - Instructions/byte (M33/-Os) 70 - Clock Cycles (123 char string) 71 - Clock Cycles (9 bytes) 72 * - 8 bits per iteration (default) 73 - large 74 - fastest 75 - 256 76 - 8 77 - 1538 78 - 170 79 * - 4 bits per iteration 80 - small 81 - fast 82 - 16 83 - 13 84 - 2153 85 - 215 86 * - 1 bit per iteration 87 - smallest 88 - slow 89 - 0 90 - 43 91 - 7690 92 - 622 93 94The default implementation provided by the APIs above can be selected through 95:ref:`Module Configuration Options`. Additionally ``pw_checksum`` provides 96variants of the C++ API to explicitly use each of the implementations. These 97classes provide the same API as ``Crc32``: 98 99* ``Crc32EightBit`` 100* ``Crc32FourBit`` 101* ``Crc32OneBit`` 102 103.. _pw_checksum-size-report: 104 105Size report 106=========== 107The CRC module currently optimizes for speed instead of binary size, by using 108pre-computed 256-entry tables to reduce the CPU cycles per byte CRC 109calculation. 110 111.. TODO: b/388905812 - Re-enable the size report. 112.. .. include:: size_report 113.. include:: ../size_report_notice 114 115Compatibility 116============= 117* C 118* C++17 119 120Dependencies 121============ 122- :ref:`module-pw_span` 123 124.. _Module Configuration Options: 125 126Module Configuration Options 127============================ 128The following configurations can be adjusted via compile-time configuration of 129this module, see the 130:ref:`module documentation <module-structure-compile-time-configuration>` for 131more details. 132 133.. c:macro:: PW_CHECKSUM_CRC32_DEFAULT_IMPL 134 135 Selects which of the :ref:`CRC32 Implementations` the default CRC32 APIs 136 use. Set to one of the following values: 137 138 * ``PW_CHECKSUM_CRC32_8BITS`` 139 * ``PW_CHECKSUM_CRC32_4BITS`` 140 * ``PW_CHECKSUM_CRC32_1BITS`` 141 142Zephyr 143====== 144To enable ``pw_checksum`` for Zephyr add ``CONFIG_PIGWEED_CHECKSUM=y`` to the 145project's configuration. 146