From 31a75e77a63b0d475f80ddbc72f9a04ef7085607 Mon Sep 17 00:00:00 2001 From: Etienne Carriere Date: Tue, 14 Oct 2025 15:15:48 +0200 Subject: [PATCH] include: zephyr: sys: correct sys_test_bit() and friends description Correct the documentation of sys_test_bit() and its derivative helper functions (listed below) since these return a bit mask value instead of an essentially boolean value as previosuly described. In tree implementation do conform with that: the result of these functions are always implicitly tested against being 0 or a non-zero value. Helper functions which documentation is modified are sys_test_bit(), sys_test_and_set_bit(), sys_test_and_clear_bit(), sys_bitfield_test_bit(), sys_bitfield_test_and_set_bit() and sys_bitfield_test_and_clear_bit(). Signed-off-by: Etienne Carriere --- include/zephyr/sys/sys_io.h | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/include/zephyr/sys/sys_io.h b/include/zephyr/sys/sys_io.h index fc3c1205d6185..ae2692764c263 100644 --- a/include/zephyr/sys/sys_io.h +++ b/include/zephyr/sys/sys_io.h @@ -285,7 +285,8 @@ typedef uintptr_t mem_addr_t; * @param addr the memory address from where to look for the bit * @param bit the designated bit to test (from 0 to 31) * - * @return 1 if it is set, 0 otherwise + * @return the bitwise AND result of @p addr content and (1 << @p bit). + * Result is 0 only if the bit is cleared otherwise result is a non-0 value. */ /** @@ -298,7 +299,8 @@ typedef uintptr_t mem_addr_t; * @param addr the memory address from where to look for the bit * @param bit the designated bit to test and set (from 0 to 31) * - * @return 1 if it was set, 0 otherwise + * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit + * is set. Result is 0 only if the bit was cleared otherwise result is a non-0 value. */ /** @@ -311,7 +313,8 @@ typedef uintptr_t mem_addr_t; * @param addr the memory address from where to look for the bit * @param bit the designated bit to test and clear (from 0 to 31) * - * @return 0 if it was clear, 1 otherwise + * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit + * is cleared. Result is 0 only if the bit was cleared otherwise result is a non-0 value. */ /** @@ -344,7 +347,8 @@ typedef uintptr_t mem_addr_t; * @param addr the memory address from where to look for the bit * @param bit the designated bit to test (arbitrary * - * @return 1 if it is set, 0 otherwise + * @return the bitwise AND result of @p addr content and (1 << @p bit). Result is 0 + * only if the bit is cleared otherwise result is a non-0 value. */ /** @@ -357,7 +361,8 @@ typedef uintptr_t mem_addr_t; * @param addr the memory address from where to look for the bit * @param bit the designated bit to test and set (arbitrary) * - * @return 1 if it was set, 0 otherwise + * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit + * is set. Result is 0 only if the bit was cleared otherwise result is a non-0 value. */ /** @@ -370,7 +375,8 @@ typedef uintptr_t mem_addr_t; * @param addr the memory address from where to look for the bit * @param bit the designated bit to test and clear (arbitrary) * - * @return 0 if it was clear, 1 otherwise + * @return the bitwise AND result of @p addr content and (1 << @p bit) before target bit + * is cleared. Result is 0 only if the bit was cleared otherwise result is a non-0 value. */