[PATCH 0/3] lib/crc: improve docs and change crc32() to inline function

[PATCH 0/3] lib/crc: improve docs and change crc32() to inline function

[Eric Biggers]

Document crc32_le(), crc32_be(), and crc32c().  Also change crc32() from
a macro to an inline function.

Eric Biggers (3):
  lib/crc/crc32: document crc32_le(), crc32_be(), and crc32c()
  lib/crc/crc32: change crc32() from macro to inline function and remove
    cast
  lib/crc/crc64: add include/linux/crc64.h to kernel-api.rst

 Documentation/core-api/kernel-api.rst |  6 ++-
 include/linux/crc32.h                 | 74 ++++++++++++++++++++++++++-
 include/linux/crc32poly.h             | 16 ++----
 3 files changed, 81 insertions(+), 15 deletions(-)


base-commit: ee925097a5a76eaf9c4954cdd7288a070d57a8d4
-- 
2.50.0

[PATCH 1/3] lib/crc/crc32: document crc32_le(), crc32_be(), and crc32c()

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

Document these widely used functions.

Update kernel-api.rst to point to the correct place, instead of to
crc32-main.c which no longer contains kerneldoc comments.

Simplify the documentation in crc32poly.h to just point to the
corresponding functions, now that they are properly documented.  Change
the value of CRC32C_POLY_LE to lower case, for consistency.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 Documentation/core-api/kernel-api.rst |  4 +-
 include/linux/crc32.h                 | 66 +++++++++++++++++++++++++++
 include/linux/crc32poly.h             | 16 ++-----
 3 files changed, 73 insertions(+), 13 deletions(-)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 9c8370891a39b..0096463c7d7f7 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -146,18 +146,18 @@ CRC Functions
    :export:
 
 .. kernel-doc:: lib/crc/crc16.c
    :export:
 
-.. kernel-doc:: lib/crc/crc32-main.c
-
 .. kernel-doc:: lib/crc/crc-ccitt.c
    :export:
 
 .. kernel-doc:: lib/crc/crc-itu-t.c
    :export:
 
+.. kernel-doc:: include/linux/crc32.h
+
 Base 2 log and power Functions
 ------------------------------
 
 .. kernel-doc:: include/linux/log2.h
    :internal:
diff --git a/include/linux/crc32.h b/include/linux/crc32.h
index 22dbe7144eb44..f9c173206d4d1 100644
--- a/include/linux/crc32.h
+++ b/include/linux/crc32.h
@@ -3,12 +3,78 @@
 #define _LINUX_CRC32_H
 
 #include <linux/types.h>
 #include <linux/bitrev.h>
 
+/**
+ * crc32_le() - Compute least-significant-bit-first IEEE CRC-32
+ * @crc: Initial CRC value.  ~0 (recommended) or 0 for a new CRC computation, or
+ *	 the previous CRC value if computing incrementally.
+ * @p: Pointer to the data buffer
+ * @len: Length of data in bytes
+ *
+ * This implements the CRC variant that is often known as the IEEE CRC-32, or
+ * simply CRC-32, and is widely used in Ethernet and other applications:
+ *
+ * - Polynomial: x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 +
+ *		 x^7 + x^5 + x^4 + x^2 + x^1 + x^0
+ * - Bit order: Least-significant-bit-first
+ * - Polynomial in integer form: 0xedb88320
+ *
+ * This does *not* invert the CRC at the beginning or end.  The caller is
+ * expected to do that if it needs to.  Inverting at both ends is recommended.
+ *
+ * For new applications, prefer to use CRC-32C instead.  See crc32c().
+ *
+ * Context: Any context
+ * Return: The new CRC value
+ */
 u32 crc32_le(u32 crc, const void *p, size_t len);
+
+/**
+ * crc32_be() - Compute most-significant-bit-first IEEE CRC-32
+ * @crc: Initial CRC value.  ~0 (recommended) or 0 for a new CRC computation, or
+ *	 the previous CRC value if computing incrementally.
+ * @p: Pointer to the data buffer
+ * @len: Length of data in bytes
+ *
+ * crc32_be() is the same as crc32_le() except that crc32_be() computes the
+ * *most-significant-bit-first* variant of the CRC.  I.e., within each byte, the
+ * most significant bit is processed first (treated as highest order polynomial
+ * coefficient).  The same bit order is also used for the CRC value itself:
+ *
+ * - Polynomial: x^32 + x^26 + x^23 + x^22 + x^16 + x^12 + x^11 + x^10 + x^8 +
+ *		 x^7 + x^5 + x^4 + x^2 + x^1 + x^0
+ * - Bit order: Most-significant-bit-first
+ * - Polynomial in integer form: 0x04c11db7
+ *
+ * Context: Any context
+ * Return: The new CRC value
+ */
 u32 crc32_be(u32 crc, const void *p, size_t len);
+
+/**
+ * crc32c() - Compute CRC-32C
+ * @crc: Initial CRC value.  ~0 (recommended) or 0 for a new CRC computation, or
+ *	 the previous CRC value if computing incrementally.
+ * @p: Pointer to the data buffer
+ * @len: Length of data in bytes
+ *
+ * This implements CRC-32C, i.e. the Castagnoli CRC.  This is the recommended
+ * CRC variant to use in new applications that want a 32-bit CRC.
+ *
+ * - Polynomial: x^32 + x^28 + x^27 + x^26 + x^25 + x^23 + x^22 + x^20 + x^19 +
+ *		 x^18 + x^14 + x^13 + x^11 + x^10 + x^9 + x^8 + x^6 + x^0
+ * - Bit order: Least-significant-bit-first
+ * - Polynomial in integer form: 0x82f63b78
+ *
+ * This does *not* invert the CRC at the beginning or end.  The caller is
+ * expected to do that if it needs to.  Inverting at both ends is recommended.
+ *
+ * Context: Any context
+ * Return: The new CRC value
+ */
 u32 crc32c(u32 crc, const void *p, size_t len);
 
 /*
  * crc32_optimizations() returns flags that indicate which CRC32 library
  * functions are using architecture-specific optimizations.  Unlike
diff --git a/include/linux/crc32poly.h b/include/linux/crc32poly.h
index 62c4b7790a285..ccab711295fab 100644
--- a/include/linux/crc32poly.h
+++ b/include/linux/crc32poly.h
@@ -1,20 +1,14 @@
 /* SPDX-License-Identifier: GPL-2.0 */
 #ifndef _LINUX_CRC32_POLY_H
 #define _LINUX_CRC32_POLY_H
 
-/*
- * There are multiple 16-bit CRC polynomials in common use, but this is
- * *the* standard CRC-32 polynomial, first popularized by Ethernet.
- * x^32+x^26+x^23+x^22+x^16+x^12+x^11+x^10+x^8+x^7+x^5+x^4+x^2+x^1+x^0
- */
+/* The polynomial used by crc32_le(), in integer form.  See crc32_le(). */
 #define CRC32_POLY_LE 0xedb88320
+
+/* The polynomial used by crc32_be(), in integer form.  See crc32_be(). */
 #define CRC32_POLY_BE 0x04c11db7
 
-/*
- * This is the CRC32c polynomial, as outlined by Castagnoli.
- * x^32+x^28+x^27+x^26+x^25+x^23+x^22+x^20+x^19+x^18+x^14+x^13+x^11+x^10+x^9+
- * x^8+x^6+x^0
- */
-#define CRC32C_POLY_LE 0x82F63B78
+/* The polynomial used by crc32c(), in integer form.  See crc32c(). */
+#define CRC32C_POLY_LE 0x82f63b78
 
 #endif /* _LINUX_CRC32_POLY_H */
-- 
2.50.0

[PATCH 2/3] lib/crc/crc32: change crc32() from macro to inline function and remove cast

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

There's no need for crc32() to be a macro.  Make it an inline function
instead.  Also, remove the cast of the data pointer to
'unsigned char const *', which is no longer necessary now that the type
used in the function prototype is 'const void *'.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 include/linux/crc32.h | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/include/linux/crc32.h b/include/linux/crc32.h
index f9c173206d4d1..da78b215ff2e9 100644
--- a/include/linux/crc32.h
+++ b/include/linux/crc32.h
@@ -28,10 +28,16 @@
  * Context: Any context
  * Return: The new CRC value
  */
 u32 crc32_le(u32 crc, const void *p, size_t len);
 
+/* This is just an alias for crc32_le(). */
+static inline u32 crc32(u32 crc, const void *p, size_t len)
+{
+	return crc32_le(crc, p, len);
+}
+
 /**
  * crc32_be() - Compute most-significant-bit-first IEEE CRC-32
  * @crc: Initial CRC value.  ~0 (recommended) or 0 for a new CRC computation, or
  *	 the previous CRC value if computing incrementally.
  * @p: Pointer to the data buffer
@@ -88,12 +94,10 @@ u32 crc32c(u32 crc, const void *p, size_t len);
 u32 crc32_optimizations(void);
 #else
 static inline u32 crc32_optimizations(void) { return 0; }
 #endif
 
-#define crc32(seed, data, length)  crc32_le(seed, (unsigned char const *)(data), length)
-
 /*
  * Helpers for hash table generation of ethernet nics:
  *
  * Ethernet sends the least significant bit of a byte first, thus crc32_le
  * is used. The output of crc32_le is bit reversed [most significant bit
-- 
2.50.0

[PATCH 3/3] lib/crc/crc64: add include/linux/crc64.h to kernel-api.rst

[Eric Biggers]

From: Eric Biggers <ebiggers@google.com>

The other CRC functions with kerneldoc are here, so add crc64.h too.

Signed-off-by: Eric Biggers <ebiggers@google.com>
---
 Documentation/core-api/kernel-api.rst | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/core-api/kernel-api.rst b/Documentation/core-api/kernel-api.rst
index 0096463c7d7f7..111f6a595e48d 100644
--- a/Documentation/core-api/kernel-api.rst
+++ b/Documentation/core-api/kernel-api.rst
@@ -154,10 +154,12 @@ CRC Functions
 .. kernel-doc:: lib/crc/crc-itu-t.c
    :export:
 
 .. kernel-doc:: include/linux/crc32.h
 
+.. kernel-doc:: include/linux/crc64.h
+
 Base 2 log and power Functions
 ------------------------------
 
 .. kernel-doc:: include/linux/log2.h
    :internal:
-- 
2.50.0

Re: [PATCH 2/3] lib/crc/crc32: change crc32() from macro to inline function and remove cast

[kernel test robot]

Hi Eric,

kernel test robot noticed the following build errors:

[auto build test ERROR on ee925097a5a76eaf9c4954cdd7288a070d57a8d4]

url:    https://github.com/intel-lab-lkp/linux/commits/Eric-Biggers/lib-crc-crc32-document-crc32_le-crc32_be-and-crc32c/20250620-023634
base:   ee925097a5a76eaf9c4954cdd7288a070d57a8d4
patch link:    https://lore.kernel.org/r/20250619183414.100082-3-ebiggers%40kernel.org
patch subject: [PATCH 2/3] lib/crc/crc32: change crc32() from macro to inline function and remove cast
config: x86_64-buildonly-randconfig-004-20250620 (https://download.01.org/0day-ci/archive/20250620/202506201401.OhkkTlo0-lkp@intel.com/config)
compiler: gcc-12 (Debian 12.2.0-14) 12.2.0
reproduce (this is a W=1 build): (https://download.01.org/0day-ci/archive/20250620/202506201401.OhkkTlo0-lkp@intel.com/reproduce)

If you fix the issue in a separate patch/commit (i.e. not just a new version of
the same patch/commit), kindly add following tags
| Reported-by: kernel test robot <lkp@intel.com>
| Closes: https://lore.kernel.org/oe-kbuild-all/202506201401.OhkkTlo0-lkp@intel.com/

All errors (new ones prefixed by >>):

   drivers/nvmem/layouts/u-boot-env.c: In function 'u_boot_env_parse':
>> drivers/nvmem/layouts/u-boot-env.c:151:16: error: called object 'crc32' is not a function or function pointer
     151 |         calc = crc32(~0, buf + crc32_data_offset, crc32_data_len) ^ ~0L;
         |                ^~~~~
   drivers/nvmem/layouts/u-boot-env.c:99:18: note: declared here
      99 |         uint32_t crc32;
         |                  ^~~~~


vim +/crc32 +151 drivers/nvmem/layouts/u-boot-env.c

5f15811286aff4 Rafał Miłecki 2024-09-02   88  
5f15811286aff4 Rafał Miłecki 2024-09-02   89  int u_boot_env_parse(struct device *dev, struct nvmem_device *nvmem,
5f15811286aff4 Rafał Miłecki 2024-09-02   90  		     enum u_boot_env_format format)
5f15811286aff4 Rafał Miłecki 2024-09-02   91  {
5f15811286aff4 Rafał Miłecki 2024-09-02   92  	size_t crc32_data_offset;
5f15811286aff4 Rafał Miłecki 2024-09-02   93  	size_t crc32_data_len;
5f15811286aff4 Rafał Miłecki 2024-09-02   94  	size_t crc32_offset;
5f15811286aff4 Rafał Miłecki 2024-09-02   95  	__le32 *crc32_addr;
5f15811286aff4 Rafał Miłecki 2024-09-02   96  	size_t data_offset;
5f15811286aff4 Rafał Miłecki 2024-09-02   97  	size_t data_len;
5f15811286aff4 Rafał Miłecki 2024-09-02   98  	size_t dev_size;
5f15811286aff4 Rafał Miłecki 2024-09-02   99  	uint32_t crc32;
5f15811286aff4 Rafał Miłecki 2024-09-02  100  	uint32_t calc;
5f15811286aff4 Rafał Miłecki 2024-09-02  101  	uint8_t *buf;
5f15811286aff4 Rafał Miłecki 2024-09-02  102  	int bytes;
5f15811286aff4 Rafał Miłecki 2024-09-02  103  	int err;
5f15811286aff4 Rafał Miłecki 2024-09-02  104  
5f15811286aff4 Rafał Miłecki 2024-09-02  105  	dev_size = nvmem_dev_size(nvmem);
5f15811286aff4 Rafał Miłecki 2024-09-02  106  
5f15811286aff4 Rafał Miłecki 2024-09-02  107  	buf = kzalloc(dev_size, GFP_KERNEL);
5f15811286aff4 Rafał Miłecki 2024-09-02  108  	if (!buf) {
5f15811286aff4 Rafał Miłecki 2024-09-02  109  		err = -ENOMEM;
5f15811286aff4 Rafał Miłecki 2024-09-02  110  		goto err_out;
5f15811286aff4 Rafał Miłecki 2024-09-02  111  	}
5f15811286aff4 Rafał Miłecki 2024-09-02  112  
5f15811286aff4 Rafał Miłecki 2024-09-02  113  	bytes = nvmem_device_read(nvmem, 0, dev_size, buf);
5f15811286aff4 Rafał Miłecki 2024-09-02  114  	if (bytes < 0) {
5f15811286aff4 Rafał Miłecki 2024-09-02  115  		err = bytes;
5f15811286aff4 Rafał Miłecki 2024-09-02  116  		goto err_kfree;
5f15811286aff4 Rafał Miłecki 2024-09-02  117  	} else if (bytes != dev_size) {
5f15811286aff4 Rafał Miłecki 2024-09-02  118  		err = -EIO;
5f15811286aff4 Rafał Miłecki 2024-09-02  119  		goto err_kfree;
5f15811286aff4 Rafał Miłecki 2024-09-02  120  	}
5f15811286aff4 Rafał Miłecki 2024-09-02  121  
5f15811286aff4 Rafał Miłecki 2024-09-02  122  	switch (format) {
5f15811286aff4 Rafał Miłecki 2024-09-02  123  	case U_BOOT_FORMAT_SINGLE:
5f15811286aff4 Rafał Miłecki 2024-09-02  124  		crc32_offset = offsetof(struct u_boot_env_image_single, crc32);
5f15811286aff4 Rafał Miłecki 2024-09-02  125  		crc32_data_offset = offsetof(struct u_boot_env_image_single, data);
5f15811286aff4 Rafał Miłecki 2024-09-02  126  		data_offset = offsetof(struct u_boot_env_image_single, data);
5f15811286aff4 Rafał Miłecki 2024-09-02  127  		break;
5f15811286aff4 Rafał Miłecki 2024-09-02  128  	case U_BOOT_FORMAT_REDUNDANT:
5f15811286aff4 Rafał Miłecki 2024-09-02  129  		crc32_offset = offsetof(struct u_boot_env_image_redundant, crc32);
5f15811286aff4 Rafał Miłecki 2024-09-02  130  		crc32_data_offset = offsetof(struct u_boot_env_image_redundant, data);
5f15811286aff4 Rafał Miłecki 2024-09-02  131  		data_offset = offsetof(struct u_boot_env_image_redundant, data);
5f15811286aff4 Rafał Miłecki 2024-09-02  132  		break;
5f15811286aff4 Rafał Miłecki 2024-09-02  133  	case U_BOOT_FORMAT_BROADCOM:
5f15811286aff4 Rafał Miłecki 2024-09-02  134  		crc32_offset = offsetof(struct u_boot_env_image_broadcom, crc32);
5f15811286aff4 Rafał Miłecki 2024-09-02  135  		crc32_data_offset = offsetof(struct u_boot_env_image_broadcom, data);
5f15811286aff4 Rafał Miłecki 2024-09-02  136  		data_offset = offsetof(struct u_boot_env_image_broadcom, data);
5f15811286aff4 Rafał Miłecki 2024-09-02  137  		break;
5f15811286aff4 Rafał Miłecki 2024-09-02  138  	}
5f15811286aff4 Rafał Miłecki 2024-09-02  139  
5f15811286aff4 Rafał Miłecki 2024-09-02  140  	if (dev_size < data_offset) {
5f15811286aff4 Rafał Miłecki 2024-09-02  141  		dev_err(dev, "Device too small for u-boot-env\n");
5f15811286aff4 Rafał Miłecki 2024-09-02  142  		err = -EIO;
5f15811286aff4 Rafał Miłecki 2024-09-02  143  		goto err_kfree;
5f15811286aff4 Rafał Miłecki 2024-09-02  144  	}
5f15811286aff4 Rafał Miłecki 2024-09-02  145  
5f15811286aff4 Rafał Miłecki 2024-09-02  146  	crc32_addr = (__le32 *)(buf + crc32_offset);
5f15811286aff4 Rafał Miłecki 2024-09-02  147  	crc32 = le32_to_cpu(*crc32_addr);
5f15811286aff4 Rafał Miłecki 2024-09-02  148  	crc32_data_len = dev_size - crc32_data_offset;
5f15811286aff4 Rafał Miłecki 2024-09-02  149  	data_len = dev_size - data_offset;
5f15811286aff4 Rafał Miłecki 2024-09-02  150  
5f15811286aff4 Rafał Miłecki 2024-09-02 @151  	calc = crc32(~0, buf + crc32_data_offset, crc32_data_len) ^ ~0L;
5f15811286aff4 Rafał Miłecki 2024-09-02  152  	if (calc != crc32) {
5f15811286aff4 Rafał Miłecki 2024-09-02  153  		dev_err(dev, "Invalid calculated CRC32: 0x%08x (expected: 0x%08x)\n", calc, crc32);
5f15811286aff4 Rafał Miłecki 2024-09-02  154  		err = -EINVAL;
5f15811286aff4 Rafał Miłecki 2024-09-02  155  		goto err_kfree;
5f15811286aff4 Rafał Miłecki 2024-09-02  156  	}
5f15811286aff4 Rafał Miłecki 2024-09-02  157  
5f15811286aff4 Rafał Miłecki 2024-09-02  158  	buf[dev_size - 1] = '\0';
5f15811286aff4 Rafał Miłecki 2024-09-02  159  	err = u_boot_env_parse_cells(dev, nvmem, buf, data_offset, data_len);
5f15811286aff4 Rafał Miłecki 2024-09-02  160  
5f15811286aff4 Rafał Miłecki 2024-09-02  161  err_kfree:
5f15811286aff4 Rafał Miłecki 2024-09-02  162  	kfree(buf);
5f15811286aff4 Rafał Miłecki 2024-09-02  163  err_out:
5f15811286aff4 Rafał Miłecki 2024-09-02  164  	return err;
5f15811286aff4 Rafał Miłecki 2024-09-02  165  }
5f15811286aff4 Rafał Miłecki 2024-09-02  166  EXPORT_SYMBOL_GPL(u_boot_env_parse);
5f15811286aff4 Rafał Miłecki 2024-09-02  167  

-- 
0-DAY CI Kernel Test Service
https://github.com/intel/lkp-tests/wiki

Re: [PATCH 0/3] lib/crc: improve docs and change crc32() to inline function

[Ard Biesheuvel]

On Thu, 19 Jun 2025 at 20:35, Eric Biggers <ebiggers@kernel.org> wrote:
>
> Document crc32_le(), crc32_be(), and crc32c().  Also change crc32() from
> a macro to an inline function.
>
> Eric Biggers (3):
>   lib/crc/crc32: document crc32_le(), crc32_be(), and crc32c()
>   lib/crc/crc32: change crc32() from macro to inline function and remove
>     cast
>   lib/crc/crc64: add include/linux/crc64.h to kernel-api.rst
>

For the series,

Acked-by: Ard Biesheuvel <ardb@kernel.org>