Re: [PATCH 01/20] bitfield: introduce HWORD_UPDATE bitfield macros
From: Robin Murphy <robin.murphy@arm.com>
Date: 2025-06-13 13:55:03
Also in:
dri-devel, linux-clk, linux-media, linux-mmc, linux-pci, linux-phy, linux-pm, linux-rockchip, linux-sound, lkml, llvm
On 2025-06-12 7:56 pm, Nicolas Frattaroli wrote:
Hardware of various vendors, but very notably Rockchip, often uses 32-bit registers where the upper 16-bit half of the register is a write-enable mask for the lower half. This type of hardware setup allows for more granular concurrent register write access. Over the years, many drivers have hand-rolled their own version of this macro, usually without any checks, often called something like HIWORD_UPDATE or FIELD_PREP_HIWORD, commonly with slightly different semantics between them. Clearly there is a demand for such a macro, and thus the demand should be satisfied in a common header file. Add two macros: HWORD_UPDATE, and HWORD_UPDATE_CONST. The latter is a version that can be used in initializers, like FIELD_PREP_CONST. The macro names are chosen to not clash with any potential other macros that drivers may already have implemented themselves, while retaining a familiar name.
Nit: while from one angle it indeed looks similar, from another it's even more opaque and less meaningful than what we have already. Personally I cannot help but see "hword" as "halfword", so logically if we want 32+32-bit or 8+8-bit variants in future those would be WORD_UPDATE() and BYTE_UPDATE(), right? ;) It's also confounded by "update" not actually having any obvious meaning at this level without all the implicit usage context. FWIW my suggestion would be FIELD_PREP_WM_U16, such that the reader instantly sees "FIELD_PREP with some additional semantics", even if they then need to glance at the kerneldoc for clarification that WM stands for writemask (or maybe WE for write-enable if people prefer). Plus it then leaves room to easily support different sizes (and potentially even bonkers upside-down Ux_WM variants?!) without any bother if we need to. Thanks, Robin.
quoted hunk ↗ jump to hunk
Signed-off-by: Nicolas Frattaroli <nicolas.frattaroli@collabora.com> --- include/linux/bitfield.h | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+)diff --git a/include/linux/bitfield.h b/include/linux/bitfield.h index 6d9a53db54b66c0833973c880444bd289d9667b1..b90d88db7405f95b78cdd6f3426263086bab5aa6 100644 --- a/include/linux/bitfield.h +++ b/include/linux/bitfield.h@@ -8,6 +8,7 @@ #define _LINUX_BITFIELD_H #include <linux/build_bug.h> +#include <linux/limits.h> #include <linux/typecheck.h> #include <asm/byteorder.h>@@ -142,6 +143,52 @@ (((typeof(_mask))(_val) << __bf_shf(_mask)) & (_mask)) \ ) +/** + * HWORD_UPDATE() - prepare a bitfield element with a mask in the upper half + * @_mask: shifted mask defining the field's length and position + * @_val: value to put in the field + * + * HWORD_UPDATE() masks and shifts up the value, as well as bitwise ORs the + * result with the mask shifted up by 16. + * + * This is useful for a common design of hardware registers where the upper + * 16-bit half of a 32-bit register is used as a write-enable mask. In such a + * register, a bit in the lower half is only updated if the corresponding bit + * in the upper half is high. + */ +#define HWORD_UPDATE(_mask, _val) \ + ({ \ + __BF_FIELD_CHECK(_mask, ((u16) 0U), _val, \ + "HWORD_UPDATE: "); \ + (((typeof(_mask))(_val) << __bf_shf(_mask)) & (_mask)) | \ + ((_mask) << 16); \ + }) + +/** + * HWORD_UPDATE_CONST() - prepare a constant bitfield element with a mask in + * the upper half + * @_mask: shifted mask defining the field's length and position + * @_val: value to put in the field + * + * HWORD_UPDATE_CONST() masks and shifts up the value, as well as bitwise ORs + * the result with the mask shifted up by 16. + * + * This is useful for a common design of hardware registers where the upper + * 16-bit half of a 32-bit register is used as a write-enable mask. In such a + * register, a bit in the lower half is only updated if the corresponding bit + * in the upper half is high. + * + * Unlike HWORD_UPDATE(), this is a constant expression and can therefore + * be used in initializers. Error checking is less comfortable for this + * version. + */ +#define HWORD_UPDATE_CONST(_mask, _val) \ + ( \ + FIELD_PREP_CONST(_mask, _val) | \ + (BUILD_BUG_ON_ZERO(const_true((u64) (_mask) > U16_MAX)) + \ + ((_mask) << 16)) \ + ) + /** * FIELD_GET() - extract a bitfield element * @_mask: shifted mask defining the field's length and position