[PATCH 07/21] bits: Add BITS() macro

Yury Norov (NVIDIA)
2025-10-25T16:29:19Z

The BITS(low, high) macro is preferable over a similar GENMASK(high, low)
because (low, high) parameters order is more natural. The (high, low)
order is confusing and has a record of misuse.

To enforce unintuitive parameters order, GENMASK() is enforced with
compile time checks. In addition, fixed-width versions of GENMASK() had
been developed. They make sense in describing hardware registers.

In generic code, using standard ordering (low to high) is more preferable,
and fixed-width features are not that useful.

In non-driver code, BITS() must be taken over GENMASK(). In drivers code,
BITS() is preferable over GENMASK().

The following pattern of using GENMASK() is highly unfavorable:

/* Status register (SR) */
#define I2C_SR_OP GENMASK(1, 0) /* Operation */
#define I2C_SR_STATUS GENMASK(3, 2) /* controller status */
#define I2C_SR_CAUSE GENMASK(6, 4) /* Abort cause */
#define I2C_SR_TYPE GENMASK(8, 7) /* Receive type */
#define I2C_SR_LENGTH GENMASK(19, 9) /* Transfer length */

Suggested-by: Linus Torvalds <torvalds@linux-foundation.org>
Link: https://lore.kernel.org/all/CAHk-=whoOUsqPKb7OQwhQf9H_3=5sXGPJrDbfQfwLB3Bi13tcQ@mail.gmail.com/
Signed-off-by: Yury Norov (NVIDIA) <yury.norov@gmail.com>
---
include/linux/bits.h | 3 +++
1 file changed, 3 insertions(+)

diff --git a/include/linux/bits.h b/include/linux/bits.h
index a40cc861b3a7..c7c587e90e2d 100644
--- a/include/linux/bits.h
+++ b/include/linux/bits.h
@@ -57,6 +57,9 @@
#define GENMASK_U64(h, l) GENMASK_TYPE(u64, h, l)
#define GENMASK_U128(h, l) GENMASK_TYPE(u128, h, l)

+#define BITS(l, h) GENMASK(h, l)
+#define BITS_ULL(l, h) GENMASK_ULL(h, l)
+
/*
* Fixed-type variants of BIT(), with additional checks like GENMASK_TYPE(). The
* following examples generate compiler warnings due to -Wshift-count-overflow:
--
2.43.0