THE I915 REGISTER MACRO DEFINITION STYLE GUIDE(9)

💖 The i915 register macro definition style guide 💖

okay bestie, vibe check: this is the Kernel API Manual page The i915 reg... style guide(9), and it's literally the style guide for i915 register macros. 🫶

follow the style described here for new macros, and while changing existing macros. and pls do not mass change existing definitions just to update the style — that is not the move, no cap. 💅

---

✨ File Layout ✨

• Keep helper macros near the top. for example, _PIPE and friends. 🎀
• Prefix macros that generally should not be used outside of this file with an underscore _. for example, _PIPE and friends, single instances of registers that are defined solely for the use by function-like macros. 🧷
• Avoid using the underscore prefixed macros outside of this file. there are exceptions, but keep them to a minimum. 🙈

There are two basic types of register definitions: single registers and register groups. register groups are registers which have two or more instances, for example one per pipe, port, transcoder, etc. register groups should be defined using function-like macros. 💡

• For single registers, define the register offset first, followed by register contents. 🧱
• For register groups, define the register instance offsets first, prefixed with underscore, followed by a function-like macro choosing the right instance based on the parameter, followed by register contents. 🎛️

Define the register contents (i.e. bit and bit field macros) from most significant to least significant bit. indent the register content macros using two extra spaces between #define and the macro name. 📐

Define bit fields using REG_GENMASK(h, l). define bit field contents using REG_FIELD_PREP(mask, value). this will define the values already shifted in place, so they can be directly OR'd together. for convenience, function-like macros may be used to define bit fields, but do note that the macros may be needed to read as well as write the register contents. 🧠✨

Define bits using REG_BIT(N). do not add _BIT suffix to the name. 🚫

Group the register and its contents together without blank lines, separate from other registers and their contents with one blank line. 🧼

Indent macro values from macro names using TABs. align values vertically. use braces in macro values as needed to avoid unintended precedence after macro substitution. use spaces in macro values according to kernel coding style. use lower case in hexadecimal values. 🔠

🏷️ Naming 🏷️

• Try to name registers according to the specs. if the register name changes in the specs from platform to another, stick to the original name. 💖
• Try to reuse existing register macro definitions. only add new macros for new register offsets, or when the register contents have changed enough to warrant a full redefinition. ♻️
• When a register macro changes for a new platform, prefix the new macro using the platform acronym or generation. for example, SKL_ or GEN8_. the prefix signifies the start platform/generation using the register. 🏁
• When a bit (field) macro changes or gets added for a new platform, while retaining the existing register macro, add a platform acronym or generation suffix to the name. for example, _SKL or _GEN8. 🎯

🌸 Examples 🌸

(Note that the values in the example are indented using spaces instead of TABs to avoid misalignment in generated documentation. Use TABs in the definitions.): 😌

#define _FOO_A                      0xf000
#define _FOO_B                      0xf001
#define FOO(pipe)                   _MMIO_PIPE(pipe, _FOO_A, _FOO_B)
#define   FOO_ENABLE                REG_BIT(31)
#define   FOO_MODE_MASK             REG_GENMASK(19, 16)
#define   FOO_MODE_BAR              REG_FIELD_PREP(FOO_MODE_MASK, 0)
#define   FOO_MODE_BAZ              REG_FIELD_PREP(FOO_MODE_MASK, 1)
#define   FOO_MODE_QUX_SNB          REG_FIELD_PREP(FOO_MODE_MASK, 2)

#define BAR                         _MMIO(0xb000)
#define GEN8_BAR                    _MMIO(0xb888)

👀 SEE ALSO 👀

• Kernel file ./drivers/gpu/drm/i915/i915_reg.h 📄

---

and that's the whole page, bestie 🫶 — source/version: ./drivers/gpu/drm/i915; date: October 2026; manual page: The i915 reg... style guide(9). slay, go define those registers responsibly 💅✨