[coreboot-gerrit] Change in coreboot[master]: device/mmio.h: Add bit field helpers

[Hung-Te Lin (Code Review)]

Hung-Te Lin has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/35463 )

Change subject: device/mmio.h: Add bit field helpers
......................................................................

device/mmio.h: Add bit field helpers

When accessing register with multiple bit fields, the common approach is
to use clrsetbits_le32, for example:

clrsetbits(&reg, (1 << 0) | (0x3 << 1) | (0x7 << 10),
                   (1 << 0) | (0x1 << 1) | (0x5 << 10));

This hard to maintain because we have to calculate the mask values
manually, make sure the duplicated shift (offset) was set correctly.
And it may be even worse if the value to set will be based on some
runtime values (that many developers will do a if-block with two very
similar argument list), and leaving lots of magic numbers.

We want to encourage developers always giving field names, and have a
better way of setting fields. The proposed utility macros are:

DEFINE_BITFIELD(name, start, end)
 SET_BITFIELDS(addr, name, value, [name2, value2, ...])

Where a developer can easily convert from data sheet like

BITS  NAME
 26:24 SEC_VIO

Into a declaration

DEFINE_BITFIELD(SEC_VIO, 26, 24)

Then, a simple call can set the field as:

SET_BITFIELDS(&reg, SEC_VIO, 2);

That is much easier to understand than

clrsetbits(&reg, 0x7 << 24, 0x2 << 24);

Change-Id: I8a1b17142f7a7dc6c441b0b1ee67d60d73ec8cc8
Signed-off-by: Hung-Te Lin 
---
M src/include/device/mmio.h
1 file changed, 78 insertions(+), 0 deletions(-)

git pull ssh://review.coreboot.org:29418/coreboot refs/changes/63/35463/1

diff --git a/src/include/device/mmio.h b/src/include/device/mmio.h
index e40b40f..b3b51c2 100644
--- a/src/include/device/mmio.h
+++ b/src/include/device/mmio.h
@@ -53,4 +53,82 @@
 }
 #endif	/* !__ROMCC__ */

+/*
+ * Utilities to help processing bit fields.
+ *
+ * To define a bit field (usually inside a register, do:
+ *
+ * DEFINE_BITFIELD(name, start end)
+ *
+ *  - name: String for name of the field to access.
+ *  - start: starting (high) bit from data sheet.
+ *  - end: ending (low) bit from data sheet.
+ *
+ * Then, set the values using:
+ *
+ * SET_BITFIELDS(&reg, name, value, [name, value, ...])
+ *
+ * Example:
+ *
+ * DEFINE_BITFIELD(DISP_TYPE, 2, 1);
+ * DEFINE_BITFIELD(DISP_EN, 0, 0);
+ *
+ *  SET_BITFIELDS(&disp_regs.ctrl, DISP_TYPE, 2);
+ *  SET_BITFIELDS(&disp_regs.ctrl, DISP_EN, 0);
+ *
+ *  SET_BITFIELDS(&disp_regs.ctrl, DISP_TYPE, 1, DISP_EN, 1);
+ *
+ * This will be translated to:
+ *
+ *  clrsetbits_le32(&disp_regs.ctrl, 0x6, 0x4);
+ *  clrsetbits_le32(&disp_regs.ctrl, 0x1, 0x0);
+ *
+ *  clrsetbits_le32(&disp_regs.ctrl, 0x7, 0x3);
+ */
+
+#define DEFINE_BITFIELD(name, start, end) \
+	_Static_assert(start >= end, "invalid bit field range"); \
+	enum { \
+		name##_FIELD_SHIFT = (end), \
+		name##_FIELD_SIZE = (start) - (end) + 1 }
+
+#define _BF_MASK(name, value) \
+	(((1 << name##_FIELD_SIZE) - 1) << name##_FIELD_SHIFT)
+
+#define _BF_VALUE(name, value) \
+	((value) << name##_FIELD_SHIFT)
+
+#define _BF_APPLY1(op, name, value, ...) (op(name, value))
+#define _BF_APPLY2(op, name, value, ...) ((op(name, value)) | \
+		_BF_APPLY1(op, __VA_ARGS__))
+#define _BF_APPLY3(op, name, value, ...) ((op(name, value)) | \
+		_BF_APPLY2(op, __VA_ARGS__))
+#define _BF_APPLY4(op, name, value, ...) ((op(name, value)) | \
+		_BF_APPLY3(op, __VA_ARGS__))
+#define _BF_APPLY5(op, name, value, ...) ((op(name, value)) | \
+		_BF_APPLY4(op, __VA_ARGS__))
+#define _BF_APPLY6(op, name, value, ...) ((op(name, value)) | \
+		_BF_APPLY5(op, __VA_ARGS__))
+#define _BF_APPLY7(op, name, value, ...) ((op(name, value)) | \
+		_BF_APPLY6(op, __VA_ARGS__))
+#define _BF_APPLY8(op, name, value, ...) ((op(name, value)) | \
+		_BF_APPLY7(op, __VA_ARGS__))
+#define _BF_APPLYINVALID(...) \
+		_Static_assert(0, "Invalid arguments to SET_BITFIELDS");
+
+#define _SET_BITFIELDS_IMPL(addr, \
+	n1, v1, n2, v2, n3, v3, n4, v4, n5, v5, n6, v6, n7, v7, n8, v8, \
+	NARGS, ...) \
+	\
+	clrsetbits_le32(addr, \
+		_BF_APPLY##NARGS(_BF_MASK, n1, v1, n2, v2, n3, v3, n4, v4, \
+				 n5, v5, n6, v6, n7, v7, n8, v8), \
+		_BF_APPLY##NARGS(_BF_VALUE, n1, v1, n2, v2, n3, v3, n4, v4, \
+				 n5, v5, n6, v6, n7, v7, n8, v8))
+
+#define SET_BITFIELDS(addr, ...) \
+	_SET_BITFIELDS_IMPL(addr, __VA_ARGS__, \
+		       8, INVALID, 7, INVALID, 6, INVALID, 5, INVALID, \
+		       4, INVALID, 3, INVALID, 2, INVALID, 1, INVALID)
+
 #endif	/* __DEVICE_MMIO_H__ */