include: util: Add generic function to count bits set in a value

Adds a generic function that will count the number of bits set in
a value.

It uses POPCOUNT (e.g. __builtin_popcount for GCC) if available,
or else it will use Brian Kernighan’s Algorithm to count bits.

POPCOUNT will likely always support unsigned ints, but the function
was implemented to use it with uint8_t for the sake of simplicity
and compatibility with Brian Kernighan’s Algorithm.

A generic solution was chosen rather than a macro/function per
type (e.g. uint8_t, uint16_t, etc.) as that is easier to maintain
and also supports array types (e.g. counting the number of bits
in 128 or 256 octet arrays).

Signed-off-by: Emil Gydesen <emil.gydesen@nordicsemi.no>

Author: Thalley

doc/releases/release-notes-4.2.rst

@@ -184,6 +184,7 @@ New APIs and options
 
   * :c:func:`util_eq`
   * :c:func:`util_memeq`
+  * :c:func:`zephyr_count_bits`
 
 * LoRaWAN
    * :c:func:`lorawan_request_link_check`

include/zephyr/sys/util.h

@@ -46,16 +46,16 @@ extern "C" {
  */
 
 /** @brief Cast @p x, a pointer, to an unsigned integer. */
-#define POINTER_TO_UINT(x) ((uintptr_t) (x))
+#define POINTER_TO_UINT(x) ((uintptr_t)(x))
 /** @brief Cast @p x, an unsigned integer, to a <tt>void*</tt>. */
-#define UINT_TO_POINTER(x) ((void *) (uintptr_t) (x))
+#define UINT_TO_POINTER(x) ((void *)(uintptr_t)(x))
 /** @brief Cast @p x, a pointer, to a signed integer. */
-#define POINTER_TO_INT(x)  ((intptr_t) (x))
+#define POINTER_TO_INT(x)  ((intptr_t)(x))
 /** @brief Cast @p x, a signed integer, to a <tt>void*</tt>. */
-#define INT_TO_POINTER(x)  ((void *) (intptr_t) (x))
+#define INT_TO_POINTER(x)  ((void *)(intptr_t)(x))
 
 #if !(defined(__CHAR_BIT__) && defined(__SIZEOF_LONG__) && defined(__SIZEOF_LONG_LONG__))
-#	error Missing required predefined macros for BITS_PER_LONG calculation
+#error Missing required predefined macros for BITS_PER_LONG calculation
 #endif
 
 /** Number of bits in a byte. */
@@ -68,27 +68,25 @@ extern "C" {
 #define NIBBLES_PER_BYTE (BITS_PER_BYTE / BITS_PER_NIBBLE)
 
 /** Number of bits in a long int. */
-#define BITS_PER_LONG	(__CHAR_BIT__ * __SIZEOF_LONG__)
+#define BITS_PER_LONG (__CHAR_BIT__ * __SIZEOF_LONG__)
 
 /** Number of bits in a long long int. */
-#define BITS_PER_LONG_LONG	(__CHAR_BIT__ * __SIZEOF_LONG_LONG__)
+#define BITS_PER_LONG_LONG (__CHAR_BIT__ * __SIZEOF_LONG_LONG__)
 
 /**
  * @brief Create a contiguous bitmask starting at bit position @p l
  *        and ending at position @p h.
  */
-#define GENMASK(h, l) \
-	(((~0UL) - (1UL << (l)) + 1) & (~0UL >> (BITS_PER_LONG - 1 - (h))))
+#define GENMASK(h, l) (((~0UL) - (1UL << (l)) + 1) & (~0UL >> (BITS_PER_LONG - 1 - (h))))
 
 /**
  * @brief Create a contiguous 64-bit bitmask starting at bit position @p l
  *        and ending at position @p h.
  */
-#define GENMASK64(h, l) \
-	(((~0ULL) - (1ULL << (l)) + 1) & (~0ULL >> (BITS_PER_LONG_LONG - 1 - (h))))
+#define GENMASK64(h, l) (((~0ULL) - (1ULL << (l)) + 1) & (~0ULL >> (BITS_PER_LONG_LONG - 1 - (h))))
 
 /** @brief 0 if @p cond is true-ish; causes a compile error otherwise. */
-#define ZERO_OR_COMPILE_ERROR(cond) ((int) sizeof(char[1 - 2 * !(cond)]) - 1)
+#define ZERO_OR_COMPILE_ERROR(cond) ((int)sizeof(char[1 - 2 * !(cond)]) - 1)
 
 #if defined(__cplusplus)
 
@@ -104,10 +102,9 @@ extern "C" {
  *
  * This macro is available only from C, not C++.
  */
-#define IS_ARRAY(array) \
-	ZERO_OR_COMPILE_ERROR( \
-		!__builtin_types_compatible_p(__typeof__(array), \
-					      __typeof__(&(array)[0])))
+#define IS_ARRAY(array)                                                                            \
+	ZERO_OR_COMPILE_ERROR(                                                                     \
+		!__builtin_types_compatible_p(__typeof__(array), __typeof__(&(array)[0])))
 
 /**
  * @brief Number of elements in the given @p array
@@ -118,8 +115,7 @@ extern "C" {
  *
  * In C, passing a pointer as @p array causes a compile error.
  */
-#define ARRAY_SIZE(array) \
-	((size_t) (IS_ARRAY(array) + (sizeof(array) / sizeof((array)[0]))))
+#define ARRAY_SIZE(array) ((size_t)(IS_ARRAY(array) + (sizeof(array) / sizeof((array)[0]))))
 
 #endif /* __cplusplus */
 
@@ -140,10 +136,11 @@ extern "C" {
  * It is specially useful for cases where flexible arrays are
  * used in unions or are not the last element in the struct.
  */
-#define FLEXIBLE_ARRAY_DECLARE(type, name) \
-	struct { \
-		struct { } __unused_##name; \
-		type name[]; \
+#define FLEXIBLE_ARRAY_DECLARE(type, name)                                                         \
+	struct {                                                                                   \
+		struct {                                                                           \
+		} __unused_##name;                                                                 \
+		type name[];                                                                       \
 	}
 
 /**
@@ -161,7 +158,7 @@ extern "C" {
  * @return 1 if @p ptr is part of @p array, 0 otherwise
  */
 #define IS_ARRAY_ELEMENT(array, ptr)                                                               \
-	((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) &&                          \
+	((ptr) && POINTER_TO_UINT(array) <= POINTER_TO_UINT(ptr) &&                                \
 	 POINTER_TO_UINT(ptr) < POINTER_TO_UINT(&(array)[ARRAY_SIZE(array)]) &&                    \
 	 (POINTER_TO_UINT(ptr) - POINTER_TO_UINT(array)) % sizeof((array)[0]) == 0)
 
@@ -253,9 +250,8 @@ extern "C" {
  * @brief Validate CONTAINER_OF parameters, only applies to C mode.
  */
 #ifndef __cplusplus
-#define CONTAINER_OF_VALIDATE(ptr, type, field)               \
-	BUILD_ASSERT(SAME_TYPE(*(ptr), ((type *)0)->field) || \
-		     SAME_TYPE(*(ptr), void),                 \
+#define CONTAINER_OF_VALIDATE(ptr, type, field)                                                    \
+	BUILD_ASSERT(SAME_TYPE(*(ptr), ((type *)0)->field) || SAME_TYPE(*(ptr), void),             \
 		     "pointer type mismatch in CONTAINER_OF");
 #else
 #define CONTAINER_OF_VALIDATE(ptr, type, field)
@@ -282,10 +278,10 @@ extern "C" {
  * @param field the name of the field within the struct @p ptr points to
  * @return a pointer to the structure that contains @p ptr
  */
-#define CONTAINER_OF(ptr, type, field)                               \
-	({                                                           \
-		CONTAINER_OF_VALIDATE(ptr, type, field)              \
-		((type *)(((char *)(ptr)) - offsetof(type, field))); \
+#define CONTAINER_OF(ptr, type, field)                                                             \
+	({                                                                                         \
+		CONTAINER_OF_VALIDATE(ptr, type, field)                                            \
+		((type *)(((char *)(ptr)) - offsetof(type, field)));                               \
 	})
 
 /**
@@ -309,8 +305,7 @@ extern "C" {
  *
  * @return Concatenated token.
  */
-#define CONCAT(...) \
-	UTIL_CAT(_CONCAT_, NUM_VA_ARGS_LESS_1(__VA_ARGS__))(__VA_ARGS__)
+#define CONCAT(...) UTIL_CAT(_CONCAT_, NUM_VA_ARGS_LESS_1(__VA_ARGS__))(__VA_ARGS__)
 
 /**
  * @brief Check if @p ptr is aligned to @p align alignment
@@ -320,14 +315,14 @@ extern "C" {
 /**
  * @brief Value of @p x rounded up to the next multiple of @p align.
  */
-#define ROUND_UP(x, align)                                   \
-	((((unsigned long)(x) + ((unsigned long)(align) - 1)) / \
-	  (unsigned long)(align)) * (unsigned long)(align))
+#define ROUND_UP(x, align)                                                                         \
+	((((unsigned long)(x) + ((unsigned long)(align) - 1)) / (unsigned long)(align)) *          \
+	 (unsigned long)(align))
 
 /**
  * @brief Value of @p x rounded down to the previous multiple of @p align.
  */
-#define ROUND_DOWN(x, align)                                 \
+#define ROUND_DOWN(x, align)                                                                       \
 	(((unsigned long)(x) / (unsigned long)(align)) * (unsigned long)(align))
 
 /** @brief Value of @p x rounded up to the next word boundary. */
@@ -689,7 +684,7 @@ char *utf8_lcpy(char *dst, const char *src, size_t n);
 
 #define __z_log2d(x) (32 - __builtin_clz(x) - 1)
 #define __z_log2q(x) (64 - __builtin_clzll(x) - 1)
-#define __z_log2(x) (sizeof(__typeof__(x)) > 4 ? __z_log2q(x) : __z_log2d(x))
+#define __z_log2(x)  (sizeof(__typeof__(x)) > 4 ? __z_log2q(x) : __z_log2d(x))
 
 /**
  * @brief Compute log2(x)
@@ -713,7 +708,7 @@ char *utf8_lcpy(char *dst, const char *src, size_t n);
  *
  * @return ceil(log2(x)) when 1 <= x <= max(type(x)), 0 when x < 1
  */
-#define LOG2CEIL(x) ((x) <= 1 ?  0 : __z_log2((x)-1) + 1)
+#define LOG2CEIL(x) ((x) <= 1 ? 0 : __z_log2((x) - 1) + 1)
 
 /**
  * @brief Compute next highest power of two
@@ -727,7 +722,7 @@ char *utf8_lcpy(char *dst, const char *src, size_t n);
  *
  * @return 2^ceil(log2(x)) or 0 if 2^ceil(log2(x)) would saturate 64-bits
  */
-#define NHPOT(x) ((x) < 1 ? 1 : ((x) > (1ULL<<63) ? 0 : 1ULL << LOG2CEIL(x)))
+#define NHPOT(x) ((x) < 1 ? 1 : ((x) > (1ULL << 63) ? 0 : 1ULL << LOG2CEIL(x)))
 
 /**
  * @brief Determine if a buffer exceeds highest address
@@ -741,9 +736,8 @@ char *utf8_lcpy(char *dst, const char *src, size_t n);
  *
  * @return true if pointer overflow detected, false otherwise
  */
-#define Z_DETECT_POINTER_OVERFLOW(addr, buflen)  \
-	(((buflen) != 0) &&                        \
-	((UINTPTR_MAX - (uintptr_t)(addr)) <= ((uintptr_t)((buflen) - 1))))
+#define Z_DETECT_POINTER_OVERFLOW(addr, buflen)                                                    \
+	(((buflen) != 0) && ((UINTPTR_MAX - (uintptr_t)(addr)) <= ((uintptr_t)((buflen) - 1))))
 
 /**
  * @brief XOR n bytes
@@ -818,6 +812,39 @@ static inline bool util_eq(const void *m1, size_t len1, const void *m2, size_t l
 	return len1 == len2 && (m1 == m2 || util_memeq(m1, m2, len1));
 }
 
+/**
+ * @brief Returns the number of bits set in a value
+ *
+ * @param value The value to count number of bits set of
+ * @param len The number of octets in @p value
+ */
+static inline size_t zephyr_count_bits(const void *value, size_t len)
+{
+	size_t cnt = 0U;
+	size_t i = 0;
+
+#ifdef POPCOUNT
+	for (; i < len / sizeof(unsigned int); i++) {
+		unsigned int val = ((unsigned int *)value)[i];
+
+		cnt += POPCOUNT(val);
+	}
+	i *= sizeof(unsigned int); /* convert to a uint8_t index for the remainder (if any) */
+#endif
+
+	for (; i < len; i++) {
+		uint8_t value_u8 = ((uint8_t *)value)[i];
+
+		/* Implements Brian Kernighan’s Algorithm to count bits */
+		while (value_u8) {
+			value_u8 &= (value_u8 - 1);
+			cnt++;
+		}
+	}
+
+	return cnt;
+}
+
 #ifdef __cplusplus
 }
 #endif

tests/unit/util/main.c

@@ -1,14 +1,19 @@
 /*
  * Copyright (c) 2019 Oticon A/S
+ * Copyright (c) 2025 Nordic Semiconductor ASA
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#include <zephyr/ztest.h>
-#include <zephyr/sys/util.h>
+#include <stdint.h>
 #include <stdio.h>
 #include <string.h>
 
+#include <zephyr/ztest.h>
+#include <zephyr/sys/util.h>
+#include <zephyr/ztest_assert.h>
+#include <zephyr/ztest_test.h>
+
 ZTEST(util, test_u8_to_dec) {
 	char text[4];
 	uint8_t len;
@@ -768,6 +773,25 @@ ZTEST(util, test_mem_xor_128)
 	zassert_mem_equal(expected_result, dst, 16);
 }
 
+ZTEST(util, test_zephyr_count_bits)
+{
+	uint8_t zero = 0U;
+	uint8_t u8 = 29U;
+	uint16_t u16 = 29999U;
+	uint32_t u32 = 2999999999U;
+	uint64_t u64 = 123456789012345ULL;
+	uint8_t u8_arr[] = {u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8,
+			    u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8, u8};
+
+	zassert_equal(zephyr_count_bits(&zero, sizeof(zero)), 0);
+	zassert_equal(zephyr_count_bits(&u8, sizeof(u8)), 4);
+	zassert_equal(zephyr_count_bits(&u16, sizeof(u16)), 10);
+	zassert_equal(zephyr_count_bits(&u32, sizeof(u32)), 20);
+	zassert_equal(zephyr_count_bits(&u64, sizeof(u64)), 23);
+
+	zassert_equal(zephyr_count_bits(u8_arr, sizeof(u8_arr)), 128);
+}
+
 ZTEST(util, test_CONCAT)
 {
 #define _CAT_PART1 1