crc32.h

  1/* SPDX-License-Identifier: GPL-2.0-only */
  2#ifndef _LINUX_CRC32_H
  3#define _LINUX_CRC32_H
  4
  5#include <linux/types.h>
  6#include <linux/bitrev.h>
  7
  8/**
  9 * crc32_le() - Compute least-significant-bit-first IEEE CRC-32
 10 * @crc: Initial CRC value.  ~0 (recommended) or 0 for a new CRC computation, or
 11 *	 the previous CRC value if computing incrementally.
 12 * @p: Pointer to the data buffer
 13 * @len: Length of data in bytes
 14 *
 15 * This implements the CRC variant that is often known as the IEEE CRC-32, or
 16 * simply CRC-32, and is widely used in Ethernet and other applications:
 17 *
 18 * - Polynomial: x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 +
 19 *		 x^7 + x^5 + x^4 + x^2 + x^1 + x^0
 20 * - Bit order: Least-significant-bit-first
 21 * - Polynomial in integer form: 0xedb88320
 22 *
 23 * This does *not* invert the CRC at the beginning or end.  The caller is
 24 * expected to do that if it needs to.  Inverting at both ends is recommended.
 25 *
 26 * For new applications, prefer to use CRC-32C instead.  See crc32c().
 27 *
 28 * Context: Any context
 29 * Return: The new CRC value
 30 */
 31u32 crc32_le(u32 crc, const void *p, size_t len);
 32
 33/* This is just an alias for crc32_le(). */
 34static inline u32 crc32(u32 crc, const void *p, size_t len)
 35{
 36	return crc32_le(crc, p, len);
 37}
 38
 39/**
 40 * crc32_be() - Compute most-significant-bit-first IEEE CRC-32
 41 * @crc: Initial CRC value.  ~0 (recommended) or 0 for a new CRC computation, or
 42 *	 the previous CRC value if computing incrementally.
 43 * @p: Pointer to the data buffer
 44 * @len: Length of data in bytes
 45 *
 46 * crc32_be() is the same as crc32_le() except that crc32_be() computes the
 47 * *most-significant-bit-first* variant of the CRC.  I.e., within each byte, the
 48 * most significant bit is processed first (treated as highest order polynomial
 49 * coefficient).  The same bit order is also used for the CRC value itself:
 50 *
 51 * - Polynomial: x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 +
 52 *		 x^7 + x^5 + x^4 + x^2 + x^1 + x^0
 53 * - Bit order: Most-significant-bit-first
 54 * - Polynomial in integer form: 0x04c11db7
 55 *
 56 * Context: Any context
 57 * Return: The new CRC value
 58 */
 59u32 crc32_be(u32 crc, const void *p, size_t len);
 60
 61/**
 62 * crc32c() - Compute CRC-32C
 63 * @crc: Initial CRC value.  ~0 (recommended) or 0 for a new CRC computation, or
 64 *	 the previous CRC value if computing incrementally.
 65 * @p: Pointer to the data buffer
 66 * @len: Length of data in bytes
 67 *
 68 * This implements CRC-32C, i.e. the Castagnoli CRC.  This is the recommended
 69 * CRC variant to use in new applications that want a 32-bit CRC.
 70 *
 71 * - Polynomial: x^32 + x^28 + x^27 + x^26 + x^25 + x^23 + x^22 + x^20 + x^19 +
 72 *		 x^18 + x^14 + x^13 + x^11 + x^10 + x^9 + x^8 + x^6 + x^0
 73 * - Bit order: Least-significant-bit-first
 74 * - Polynomial in integer form: 0x82f63b78
 75 *
 76 * This does *not* invert the CRC at the beginning or end.  The caller is
 77 * expected to do that if it needs to.  Inverting at both ends is recommended.
 78 *
 79 * Context: Any context
 80 * Return: The new CRC value
 81 */
 82u32 crc32c(u32 crc, const void *p, size_t len);
 83
 84/*
 85 * crc32_optimizations() returns flags that indicate which CRC32 library
 86 * functions are using architecture-specific optimizations.  Unlike
 87 * IS_ENABLED(CONFIG_CRC32_ARCH) it takes into account the different CRC32
 88 * variants and also whether any needed CPU features are available at runtime.
 89 */
 90#define CRC32_LE_OPTIMIZATION	BIT(0) /* crc32_le() is optimized */
 91#define CRC32_BE_OPTIMIZATION	BIT(1) /* crc32_be() is optimized */
 92#define CRC32C_OPTIMIZATION	BIT(2) /* crc32c() is optimized */
 93#if IS_ENABLED(CONFIG_CRC32_ARCH)
 94u32 crc32_optimizations(void);
 95#else
 96static inline u32 crc32_optimizations(void) { return 0; }
 97#endif
 98
 99/*
100 * Helpers for hash table generation of ethernet nics:
101 *
102 * Ethernet sends the least significant bit of a byte first, thus crc32_le
103 * is used. The output of crc32_le is bit reversed [most significant bit
104 * is in bit nr 0], thus it must be reversed before use. Except for
105 * nics that bit swap the result internally...
106 */
107#define ether_crc(length, data)    bitrev32(crc32_le(~0, data, length))
108#define ether_crc_le(length, data) crc32_le(~0, data, length)
109
110#endif /* _LINUX_CRC32_H */