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(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(my_data); 49 50.. cpp:function:: uint32_t Crc32(span<const std::byte> data, uint32_t previous_result) 51 52 Incrementally append calculation of a CRC32, need to pass in the previous 53 result. 54 55 .. code-block:: cpp 56 57 uint32_t crc = Crc32(my_data); 58 crc = Crc32(more_data, crc); 59 60.. _CRC32 Implementations: 61 62Implementations 63--------------- 64Pigweed provides 3 different CRC32 implementations with different size and 65runtime tradeoffs. The below table summarizes the variants. For more detailed 66size information see the :ref:`pw_checksum-size-report` below. Instructions 67counts were calculated by hand by analyzing the 68`assembly <https://godbolt.org/z/nY1bbb5Pb>`_. Clock Cycle counts were measured 69using :ref:`module-pw_perf_test` on a STM32F429I-DISC1 development board. 70 71 72.. list-table:: 73 :header-rows: 1 74 75 * - Variant 76 - Relative size (see Size Report below) 77 - Speed 78 - Lookup table size (entries) 79 - Instructions/byte (M33/-Os) 80 - Clock Cycles (123 char string) 81 - Clock Cycles (9 bytes) 82 * - 8 bits per iteration (default) 83 - large 84 - fastest 85 - 256 86 - 8 87 - 1538 88 - 170 89 * - 4 bits per iteration 90 - small 91 - fast 92 - 16 93 - 13 94 - 2153 95 - 215 96 * - 1 bit per iteration 97 - smallest 98 - slow 99 - 0 100 - 43 101 - 7690 102 - 622 103 104The default implementation provided by the APIs above can be selected through 105:ref:`Module Configuration Options`. Additionally ``pw_checksum`` provides 106variants of the C++ API to explicitly use each of the implementations. These 107classes provide the same API as ``Crc32``: 108 109* ``Crc32EightBit`` 110* ``Crc32FourBit`` 111* ``Crc32OneBit`` 112 113.. _pw_checksum-size-report: 114 115Size report 116=========== 117The CRC module currently optimizes for speed instead of binary size, by using 118pre-computed 256-entry tables to reduce the CPU cycles per byte CRC 119calculation. 120 121.. include:: size_report 122 123Compatibility 124============= 125* C 126* C++17 127 128Dependencies 129============ 130- :ref:`module-pw_span` 131 132.. _Module Configuration Options: 133 134Module Configuration Options 135============================ 136The following configurations can be adjusted via compile-time configuration of 137this module, see the 138:ref:`module documentation <module-structure-compile-time-configuration>` for 139more details. 140 141.. c:macro:: PW_CHECKSUM_CRC32_DEFAULT_IMPL 142 143 Selects which of the :ref:`CRC32 Implementations` the default CRC32 APIs 144 use. Set to one of the following values: 145 146 * ``PW_CHECKSUM_CRC32_8BITS`` 147 * ``PW_CHECKSUM_CRC32_4BITS`` 148 * ``PW_CHECKSUM_CRC32_1BITS`` 149 150Zephyr 151====== 152To enable ``pw_checksum`` for Zephyr add ``CONFIG_PIGWEED_CHECKSUM=y`` to the 153project's configuration. 154