stm32: Add header guard and fix fmt/doc of registers header file

We enforce that all family specific registers file can only be
included from registers.h.

We add a brief history and rationale behind splitting registers.h into
multiple family specific header files.

We fix formatting of preprocessor conditionals and documentation.

BRANCH=none
BUG=none
TEST=make buildall -j
TEST=Grab registers-extract.bash
     from http://go/bit/hesling/6385147721023488/4 .
     chmod +x ./registers-extract.bash
     ./registers-extract.bash board-regs-new
     git checkout cros/master
     ./registers-extract.bash board-regs-original
     diff board-regs-original board-regs-new
     [ $? -eq 0 ] && echo "# Good2Go" || echo "# Bad"

Signed-off-by: Craig Hesling <hesling@chromium.org>
Change-Id: I5d5983eb1e0cf7fb46339cba2987d551ff6b16cc
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/1693879
Reviewed-by: Daisuke Nojiri <dnojiri@chromium.org>

7 files changed, 347 insertions, 260 deletions

diff --git a/chip/stm32/registers-stm32f0.h b/chip/stm32/registers-stm32f0.h
index d495f76f4d..f5cc11947d 100644
--- a/chip/stm32/registers-stm32f0.h
+++ b/chip/stm32/registers-stm32f0.h
@@ -1,10 +1,20 @@
 /* Copyright 2019 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ * @brief Register map for the STM32F0 family of chips
  *
- * Register map for STM32 processor
+ * This header file should not be included directly.
+ * Please include registers.h instead.
  */
 
+#ifndef __CROS_EC_REGISTERS_H
+#error "This header file should not be included directly."
+#endif
+
 /* --- IRQ numbers --- */
 #define STM32_IRQ_WWDG             0
 #define STM32_IRQ_PVD              1
@@ -730,7 +740,7 @@ typedef volatile struct stm32_dma_regs stm32_dma_regs_t;
 
 #define STM32_DMA_CCR_CHANNEL(channel)		 (0)
 
-#if defined(CHIP_VARIANT_STM32F09X)
+#ifdef CHIP_VARIANT_STM32F09X
 #define STM32_DMA2_REGS ((stm32_dma_regs_t *)STM32_DMA2_BASE)
 #define STM32_DMA_REGS(channel) \
 	((channel) < STM32_DMAC_PER_CTLR ? STM32_DMA1_REGS : STM32_DMA2_REGS)
diff --git a/chip/stm32/registers-stm32f3.h b/chip/stm32/registers-stm32f3.h
index 79cb8286d0..548b9b5fe8 100644
--- a/chip/stm32/registers-stm32f3.h
+++ b/chip/stm32/registers-stm32f3.h
@@ -1,10 +1,20 @@
 /* Copyright 2019 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ * @brief Register map for the STM32F3 family of chips
  *
- * Register map for STM32 processor
+ * This header file should not be included directly.
+ * Please include registers.h instead.
  */
 
+#ifndef __CROS_EC_REGISTERS_H
+#error "This header file should not be included directly."
+#endif
+
 /* --- IRQ numbers --- */
 #define STM32_IRQ_WWDG             0
 #define STM32_IRQ_PVD              1
@@ -585,7 +595,7 @@ typedef volatile struct stm32_spi_regs stm32_spi_regs_t;
 #define EXTI_RTC_ALR_EVENT BIT(17)
 
 /* --- ADC --- */
-#if defined(CHIP_VARIANT_STM32F373)
+#ifdef CHIP_VARIANT_STM32F373
 #define STM32_ADC_SR               REG32(STM32_ADC1_BASE + 0x00)
 #define STM32_ADC_CR1              REG32(STM32_ADC1_BASE + 0x04)
 #define STM32_ADC_CR2              REG32(STM32_ADC1_BASE + 0x08)
@@ -746,7 +756,7 @@ enum dma_channel {
 	STM32_DMAC_I2C1_RX = STM32_DMAC_CH7,
 	STM32_DMAC_PMSE_ROW = STM32_DMAC_CH6,
 	STM32_DMAC_PMSE_COL = STM32_DMAC_CH7,
-#if defined(CHIP_VARIANT_STM32F373)
+#ifdef CHIP_VARIANT_STM32F373
 	STM32_DMAC_SPI2_RX = STM32_DMAC_CH4,
 	STM32_DMAC_SPI2_TX = STM32_DMAC_CH5,
 	STM32_DMAC_SPI3_RX = STM32_DMAC_CH9,
diff --git a/chip/stm32/registers-stm32f4.h b/chip/stm32/registers-stm32f4.h
index 9be1920846..bd33b6798f 100644
--- a/chip/stm32/registers-stm32f4.h
+++ b/chip/stm32/registers-stm32f4.h
@@ -1,10 +1,20 @@
 /* Copyright 2019 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ * @brief Register map for the STM32F4 family of chips
  *
- * Register map for STM32 processor
+ * This header file should not be included directly.
+ * Please include registers.h instead.
  */
 
+#ifndef __CROS_EC_REGISTERS_H
+#error "This header file should not be included directly."
+#endif
+
 /* --- IRQ numbers --- */
 #define STM32_IRQ_WWDG             0
 #define STM32_IRQ_PVD              1
@@ -231,7 +241,7 @@
 /* Register definitions */
 
 /* --- USART --- */
-#if defined(CHIP_VARIANT_STM32F76X)
+#ifdef CHIP_VARIANT_STM32F76X
 #define STM32_USART_CR1(base)      STM32_USART_REG(base, 0x00)
 #define STM32_USART_CR1_UE		BIT(0)
 #define STM32_USART_CR1_UESM            BIT(1)
@@ -271,8 +281,7 @@
 #define STM32_USART_SR_RXNE		BIT(5)
 #define STM32_USART_SR_TC		BIT(6)
 #define STM32_USART_SR_TXE		BIT(7)
-#else
-/* !CHIP_FAMILY_STM32F0 && !CHIP_FAMILY_STM32F3 && !CHIP_FAMILY_STM32L4 */
+#else /* !CHIP_VARIANT_STM32F76X */
 #define STM32_USART_SR(base)       STM32_USART_REG(base, 0x00)
 #define STM32_USART_SR_ORE		BIT(3)
 #define STM32_USART_SR_RXNE		BIT(5)
@@ -301,8 +310,7 @@
 /* register aliases */
 #define STM32_USART_TDR(base)      STM32_USART_DR(base)
 #define STM32_USART_RDR(base)      STM32_USART_DR(base)
-#endif
-/* !CHIP_FAMILY_STM32F0 && !CHIP_FAMILY_STM32F3 && !CHIP_FAMILY_STM32L4 */
+#endif /* !CHIP_VARIANT_STM32F76X*/
 
 /* --- GPIO --- */
 
@@ -590,11 +598,11 @@
 #define STM32_RCC_CSR_LSION		BIT(0)
 #define STM32_RCC_CSR_LSIRDY		BIT(1)
 
-#if defined(CHIP_FAMILY_STM32F4)
+#ifdef CHIP_FAMILY_STM32F4
 #define STM32_RCC_PB2_TIM9		BIT(16)
 #define STM32_RCC_PB2_TIM10		BIT(17)
 #define STM32_RCC_PB2_TIM11		BIT(18)
-#else /* !defined(CHIP_FAMILY_STM32F4) */
+#else /* !CHIP_FAMILY_STM32F4 */
 #define STM32_RCC_HB_DMA1		BIT(24)
 #define STM32_RCC_PB2_TIM9		BIT(2)
 #define STM32_RCC_PB2_TIM10		BIT(3)
diff --git a/chip/stm32/registers-stm32h7.h b/chip/stm32/registers-stm32h7.h
index 939dedaac5..970c0483dc 100644
--- a/chip/stm32/registers-stm32h7.h
+++ b/chip/stm32/registers-stm32h7.h
@@ -1,10 +1,20 @@
 /* Copyright 2019 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ * @brief Register map for the STM32H7 family of chips
  *
- * Register map for STM32 processor
+ * This header file should not be included directly.
+ * Please include registers.h instead.
  */
 
+#ifndef __CROS_EC_REGISTERS_H
+#error "This header file should not be included directly."
+#endif
+
 /* --- IRQ numbers --- */
 #define STM32_IRQ_WWDG             0
 #define STM32_IRQ_PVD              1
@@ -217,59 +227,59 @@
 /* Register definitions */
 
 /* --- USART --- */
-#define STM32_USART_CR1(base)      STM32_USART_REG(base, 0x00)
-#define STM32_USART_CR1_UE		BIT(0)
-#define STM32_USART_CR1_UESM            BIT(1)
-#define STM32_USART_CR1_RE		BIT(2)
-#define STM32_USART_CR1_TE		BIT(3)
-#define STM32_USART_CR1_RXNEIE		BIT(5)
-#define STM32_USART_CR1_TCIE		BIT(6)
-#define STM32_USART_CR1_TXEIE		BIT(7)
-#define STM32_USART_CR1_PS		BIT(9)
-#define STM32_USART_CR1_PCE		BIT(10)
-#define STM32_USART_CR1_M		BIT(12)
-#define STM32_USART_CR1_OVER8		BIT(15)
-#define STM32_USART_CR2(base)      STM32_USART_REG(base, 0x04)
-#define STM32_USART_CR2_SWAP		BIT(15)
-#define STM32_USART_CR3(base)      STM32_USART_REG(base, 0x08)
-#define STM32_USART_CR3_EIE		BIT(0)
-#define STM32_USART_CR3_DMAR		BIT(6)
-#define STM32_USART_CR3_DMAT		BIT(7)
-#define STM32_USART_CR3_ONEBIT		BIT(11)
-#define STM32_USART_CR3_OVRDIS		BIT(12)
-#define STM32_USART_CR3_WUS_START_BIT	(2 << 20)
-#define STM32_USART_CR3_WUFIE		BIT(22)
-#define STM32_USART_BRR(base)      STM32_USART_REG(base, 0x0C)
-#define STM32_USART_GTPR(base)     STM32_USART_REG(base, 0x10)
-#define STM32_USART_RTOR(base)     STM32_USART_REG(base, 0x14)
-#define STM32_USART_RQR(base)      STM32_USART_REG(base, 0x18)
-#define STM32_USART_ISR(base)      STM32_USART_REG(base, 0x1C)
-#define STM32_USART_ICR(base)      STM32_USART_REG(base, 0x20)
-#define STM32_USART_ICR_ORECF		BIT(3)
-#define STM32_USART_ICR_TCCF		BIT(6)
-#define STM32_USART_RDR(base)      STM32_USART_REG(base, 0x24)
-#define STM32_USART_TDR(base)      STM32_USART_REG(base, 0x28)
-#define STM32_USART_PRESC(base)    STM32_USART_REG(base, 0x2C)
+#define STM32_USART_CR1(base)         STM32_USART_REG(base, 0x00)
+#define  STM32_USART_CR1_UE            BIT(0)
+#define  STM32_USART_CR1_UESM          BIT(1)
+#define  STM32_USART_CR1_RE            BIT(2)
+#define  STM32_USART_CR1_TE            BIT(3)
+#define  STM32_USART_CR1_RXNEIE        BIT(5)
+#define  STM32_USART_CR1_TCIE          BIT(6)
+#define  STM32_USART_CR1_TXEIE         BIT(7)
+#define  STM32_USART_CR1_PS            BIT(9)
+#define  STM32_USART_CR1_PCE           BIT(10)
+#define  STM32_USART_CR1_M             BIT(12)
+#define  STM32_USART_CR1_OVER8         BIT(15)
+#define STM32_USART_CR2(base)         STM32_USART_REG(base, 0x04)
+#define  STM32_USART_CR2_SWAP          BIT(15)
+#define STM32_USART_CR3(base)         STM32_USART_REG(base, 0x08)
+#define  STM32_USART_CR3_EIE           BIT(0)
+#define  STM32_USART_CR3_DMAR          BIT(6)
+#define  STM32_USART_CR3_DMAT          BIT(7)
+#define  STM32_USART_CR3_ONEBIT        BIT(11)
+#define  STM32_USART_CR3_OVRDIS        BIT(12)
+#define  STM32_USART_CR3_WUS_START_BIT (2 << 20)
+#define  STM32_USART_CR3_WUFIE         BIT(22)
+#define STM32_USART_BRR(base)         STM32_USART_REG(base, 0x0C)
+#define STM32_USART_GTPR(base)        STM32_USART_REG(base, 0x10)
+#define STM32_USART_RTOR(base)        STM32_USART_REG(base, 0x14)
+#define STM32_USART_RQR(base)         STM32_USART_REG(base, 0x18)
+#define STM32_USART_ISR(base)         STM32_USART_REG(base, 0x1C)
+#define STM32_USART_ICR(base)         STM32_USART_REG(base, 0x20)
+#define  STM32_USART_ICR_ORECF         BIT(3)
+#define  STM32_USART_ICR_TCCF          BIT(6)
+#define STM32_USART_RDR(base)         STM32_USART_REG(base, 0x24)
+#define STM32_USART_TDR(base)         STM32_USART_REG(base, 0x28)
+#define STM32_USART_PRESC(base)       STM32_USART_REG(base, 0x2C)
 /* register alias */
-#define STM32_USART_SR(base)       STM32_USART_ISR(base)
-#define STM32_USART_SR_ORE		BIT(3)
-#define STM32_USART_SR_RXNE		BIT(5)
-#define STM32_USART_SR_TC		BIT(6)
-#define STM32_USART_SR_TXE		BIT(7)
+#define STM32_USART_SR(base)          STM32_USART_ISR(base)
+#define  STM32_USART_SR_ORE            BIT(3)
+#define  STM32_USART_SR_RXNE           BIT(5)
+#define  STM32_USART_SR_TC             BIT(6)
+#define  STM32_USART_SR_TXE            BIT(7)
 
 /* --- GPIO --- */
 
 
-#define STM32_GPIO_MODER(b)     REG32((b) + 0x00)
-#define STM32_GPIO_OTYPER(b)    REG16((b) + 0x04)
-#define STM32_GPIO_OSPEEDR(b)   REG32((b) + 0x08)
-#define STM32_GPIO_PUPDR(b)     REG32((b) + 0x0C)
-#define STM32_GPIO_IDR(b)       REG16((b) + 0x10)
-#define STM32_GPIO_ODR(b)       REG16((b) + 0x14)
-#define STM32_GPIO_BSRR(b)      REG32((b) + 0x18)
-#define STM32_GPIO_LCKR(b)      REG32((b) + 0x1C)
-#define STM32_GPIO_AFRL(b)      REG32((b) + 0x20)
-#define STM32_GPIO_AFRH(b)      REG32((b) + 0x24)
+#define STM32_GPIO_MODER(b)           REG32((b) + 0x00)
+#define STM32_GPIO_OTYPER(b)          REG16((b) + 0x04)
+#define STM32_GPIO_OSPEEDR(b)         REG32((b) + 0x08)
+#define STM32_GPIO_PUPDR(b)           REG32((b) + 0x0C)
+#define STM32_GPIO_IDR(b)             REG16((b) + 0x10)
+#define STM32_GPIO_ODR(b)             REG16((b) + 0x14)
+#define STM32_GPIO_BSRR(b)            REG32((b) + 0x18)
+#define STM32_GPIO_LCKR(b)            REG32((b) + 0x1C)
+#define STM32_GPIO_AFRL(b)            REG32((b) + 0x20)
+#define STM32_GPIO_AFRH(b)            REG32((b) + 0x24)
 
 #define GPIO_ALT_SYS                 0x0
 #define GPIO_ALT_TIM2                0x1
@@ -286,74 +296,74 @@
 #define GPIO_ALT_EVENTOUT            0xF
 
 /* --- I2C --- */
-#define STM32_I2C_CR1(n)            REG16(stm32_i2c_reg(n, 0x00))
-#define STM32_I2C_CR1_PE	BIT(0)
-#define STM32_I2C_CR1_START	BIT(8)
-#define STM32_I2C_CR1_STOP	BIT(9)
-#define STM32_I2C_CR1_ACK	BIT(10)
-#define STM32_I2C_CR1_POS	BIT(11)
-#define STM32_I2C_CR1_SWRST	BIT(15)
-#define STM32_I2C_CR2(n)            REG16(stm32_i2c_reg(n, 0x04))
-#define STM32_I2C_CR2_ITERREN	BIT(8)
-#define STM32_I2C_CR2_ITEVTEN	BIT(9)
-#define STM32_I2C_CR2_ITBUFEN	BIT(10)
-#define STM32_I2C_CR2_DMAEN	BIT(11)
-#define STM32_I2C_CR2_LAST	BIT(12)
-#define STM32_I2C_OAR1(n)           REG16(stm32_i2c_reg(n, 0x08))
-#define STM32_I2C_OAR1_B14	BIT(14)
-#define STM32_I2C_OAR2(n)           REG16(stm32_i2c_reg(n, 0x0C))
-#define STM32_I2C_OAR2_ENDUAL	BIT(0)
-#define STM32_I2C_DR(n)             REG16(stm32_i2c_reg(n, 0x10))
-#define STM32_I2C_SR1(n)            REG16(stm32_i2c_reg(n, 0x14))
-#define STM32_I2C_SR1_SB	BIT(0)
-#define STM32_I2C_SR1_ADDR	BIT(1)
-#define STM32_I2C_SR1_BTF	BIT(2)
-#define STM32_I2C_SR1_STOPF	BIT(4)
-#define STM32_I2C_SR1_RXNE	BIT(6)
-#define STM32_I2C_SR1_TXE	BIT(7)
-#define STM32_I2C_SR1_BERR	BIT(8)
-#define STM32_I2C_SR1_ARLO	BIT(9)
-#define STM32_I2C_SR1_AF	BIT(10)
-
-#define STM32_I2C_SR2(n)            REG16(stm32_i2c_reg(n, 0x18))
-#define STM32_I2C_SR2_BUSY	BIT(1)
-#define STM32_I2C_SR2_TRA	BIT(2)
-#define STM32_I2C_SR2_DUALF	BIT(7)
-
-#define STM32_I2C_CCR(n)            REG16(stm32_i2c_reg(n, 0x1C))
-#define STM32_I2C_CCR_DUTY	BIT(14)
-#define STM32_I2C_CCR_FM	BIT(15)
-#define STM32_I2C_TRISE(n)          REG16(stm32_i2c_reg(n, 0x20))
+#define STM32_I2C_CR1(n)              REG16(stm32_i2c_reg(n, 0x00))
+#define  STM32_I2C_CR1_PE              BIT(0)
+#define  STM32_I2C_CR1_START           BIT(8)
+#define  STM32_I2C_CR1_STOP            BIT(9)
+#define  STM32_I2C_CR1_ACK             BIT(10)
+#define  STM32_I2C_CR1_POS             BIT(11)
+#define  STM32_I2C_CR1_SWRST           BIT(15)
+#define STM32_I2C_CR2(n)              REG16(stm32_i2c_reg(n, 0x04))
+#define  STM32_I2C_CR2_ITERREN         BIT(8)
+#define  STM32_I2C_CR2_ITEVTEN         BIT(9)
+#define  STM32_I2C_CR2_ITBUFEN         BIT(10)
+#define  STM32_I2C_CR2_DMAEN           BIT(11)
+#define  STM32_I2C_CR2_LAST            BIT(12)
+#define STM32_I2C_OAR1(n)             REG16(stm32_i2c_reg(n, 0x08))
+#define  STM32_I2C_OAR1_B14            BIT(14)
+#define STM32_I2C_OAR2(n)             REG16(stm32_i2c_reg(n, 0x0C))
+#define  STM32_I2C_OAR2_ENDUAL         BIT(0)
+#define STM32_I2C_DR(n)               REG16(stm32_i2c_reg(n, 0x10))
+#define STM32_I2C_SR1(n)              REG16(stm32_i2c_reg(n, 0x14))
+#define  STM32_I2C_SR1_SB              BIT(0)
+#define  STM32_I2C_SR1_ADDR            BIT(1)
+#define  STM32_I2C_SR1_BTF             BIT(2)
+#define  STM32_I2C_SR1_STOPF           BIT(4)
+#define  STM32_I2C_SR1_RXNE            BIT(6)
+#define  STM32_I2C_SR1_TXE             BIT(7)
+#define  STM32_I2C_SR1_BERR            BIT(8)
+#define  STM32_I2C_SR1_ARLO            BIT(9)
+#define  STM32_I2C_SR1_AF              BIT(10)
+
+#define STM32_I2C_SR2(n)              REG16(stm32_i2c_reg(n, 0x18))
+#define  STM32_I2C_SR2_BUSY            BIT(1)
+#define  STM32_I2C_SR2_TRA             BIT(2)
+#define  STM32_I2C_SR2_DUALF           BIT(7)
+
+#define STM32_I2C_CCR(n)              REG16(stm32_i2c_reg(n, 0x1C))
+#define  STM32_I2C_CCR_DUTY            BIT(14)
+#define  STM32_I2C_CCR_FM              BIT(15)
+#define STM32_I2C_TRISE(n)            REG16(stm32_i2c_reg(n, 0x20))
 
 
 /* --- Power / Reset / Clocks --- */
 #define STM32_PWR_CSR               REG32(STM32_PWR_BASE + 0x04)
 #define STM32_PWR_CR2               REG32(STM32_PWR_BASE + 0x08)
 #define STM32_PWR_CR3               REG32(STM32_PWR_BASE + 0x0C)
-#define STM32_PWR_CR3_BYPASS        BIT(0)
-#define STM32_PWR_CR3_LDOEN         BIT(1)
-#define STM32_PWR_CR3_SCUEN         BIT(2)
-#define STM32_PWR_CR3_VBE           BIT(8)
-#define STM32_PWR_CR3_VBRS          BIT(9)
-#define STM32_PWR_CR3_USB33DEN      BIT(24)
-#define STM32_PWR_CR3_USBREGEN      BIT(25)
-#define STM32_PWR_CR3_USB33RDY      BIT(26)
+#define  STM32_PWR_CR3_BYPASS        BIT(0)
+#define  STM32_PWR_CR3_LDOEN         BIT(1)
+#define  STM32_PWR_CR3_SCUEN         BIT(2)
+#define  STM32_PWR_CR3_VBE           BIT(8)
+#define  STM32_PWR_CR3_VBRS          BIT(9)
+#define  STM32_PWR_CR3_USB33DEN      BIT(24)
+#define  STM32_PWR_CR3_USBREGEN      BIT(25)
+#define  STM32_PWR_CR3_USB33RDY      BIT(26)
 #define STM32_PWR_CPUCR             REG32(STM32_PWR_BASE + 0x10)
-#define STM32_PWR_CPUCR_PDDS_D1     BIT(0)
-#define STM32_PWR_CPUCR_PDDS_D2     BIT(1)
-#define STM32_PWR_CPUCR_PDDS_D3     BIT(2)
-#define STM32_PWR_CPUCR_STOPF       BIT(5)
-#define STM32_PWR_CPUCR_SBF         BIT(6)
-#define STM32_PWR_CPUCR_SBF_D1      BIT(7)
-#define STM32_PWR_CPUCR_SBF_D2      BIT(8)
-#define STM32_PWR_CPUCR_CSSF        BIT(9)
-#define STM32_PWR_CPUCR_RUN_D3      BIT(11)
+#define  STM32_PWR_CPUCR_PDDS_D1     BIT(0)
+#define  STM32_PWR_CPUCR_PDDS_D2     BIT(1)
+#define  STM32_PWR_CPUCR_PDDS_D3     BIT(2)
+#define  STM32_PWR_CPUCR_STOPF       BIT(5)
+#define  STM32_PWR_CPUCR_SBF         BIT(6)
+#define  STM32_PWR_CPUCR_SBF_D1      BIT(7)
+#define  STM32_PWR_CPUCR_SBF_D2      BIT(8)
+#define  STM32_PWR_CPUCR_CSSF        BIT(9)
+#define  STM32_PWR_CPUCR_RUN_D3      BIT(11)
 #define STM32_PWR_D3CR              REG32(STM32_PWR_BASE + 0x18)
-#define STM32_PWR_D3CR_VOS1         (3 << 14)
-#define STM32_PWR_D3CR_VOS2         (2 << 14)
-#define STM32_PWR_D3CR_VOS3         (1 << 14)
-#define STM32_PWR_D3CR_VOSMASK      (3 << 14)
-#define STM32_PWR_D3CR_VOSRDY       (1 << 13)
+#define  STM32_PWR_D3CR_VOS1         (3 << 14)
+#define  STM32_PWR_D3CR_VOS2         (2 << 14)
+#define  STM32_PWR_D3CR_VOS3         (1 << 14)
+#define  STM32_PWR_D3CR_VOSMASK      (3 << 14)
+#define  STM32_PWR_D3CR_VOSRDY       (1 << 13)
 #define STM32_PWR_WKUPCR            REG32(STM32_PWR_BASE + 0x20)
 #define STM32_PWR_WKUPFR            REG32(STM32_PWR_BASE + 0x24)
 #define STM32_PWR_WKUPEPR           REG32(STM32_PWR_BASE + 0x28)
@@ -532,14 +542,14 @@
 #define STM32_RCC_PB2_TIM17             BIT(18)
 
 /* Peripheral bits for AHB1/2/3/4ENR regs */
-#define STM32_RCC_HB1_DMA1		BIT(0)
-#define STM32_RCC_HB1_DMA2		BIT(1)
-#define STM32_RCC_HB3_MDMA		BIT(0)
-#define STM32_RCC_HB4_BDMA		BIT(21)
+#define STM32_RCC_HB1_DMA1              BIT(0)
+#define STM32_RCC_HB1_DMA2              BIT(1)
+#define STM32_RCC_HB3_MDMA              BIT(0)
+#define STM32_RCC_HB4_BDMA              BIT(21)
 
 
 /* Peripheral bits for RCC_APB/AHB and DBGMCU regs */
-#define STM32_RCC_PB2_USART1		BIT(4)
+#define STM32_RCC_PB2_USART1           BIT(4)
 
 /* Reset causes definitions */
 #define STM32_RCC_RESET_CAUSE STM32_RCC_RSR
@@ -561,18 +571,18 @@
 #define STM32_RTC_TR                REG32(STM32_RTC_BASE + 0x00)
 #define STM32_RTC_DR                REG32(STM32_RTC_BASE + 0x04)
 #define STM32_RTC_CR                REG32(STM32_RTC_BASE + 0x08)
-#define STM32_RTC_CR_BYPSHAD        BIT(5)
-#define STM32_RTC_CR_ALRAE          BIT(8)
-#define STM32_RTC_CR_ALRAIE         BIT(12)
+#define  STM32_RTC_CR_BYPSHAD        BIT(5)
+#define  STM32_RTC_CR_ALRAE          BIT(8)
+#define  STM32_RTC_CR_ALRAIE         BIT(12)
 #define STM32_RTC_ISR               REG32(STM32_RTC_BASE + 0x0C)
-#define STM32_RTC_ISR_ALRAWF        BIT(0)
-#define STM32_RTC_ISR_RSF           BIT(5)
-#define STM32_RTC_ISR_INITF         BIT(6)
-#define STM32_RTC_ISR_INIT          BIT(7)
-#define STM32_RTC_ISR_ALRAF         BIT(8)
+#define  STM32_RTC_ISR_ALRAWF        BIT(0)
+#define  STM32_RTC_ISR_RSF           BIT(5)
+#define  STM32_RTC_ISR_INITF         BIT(6)
+#define  STM32_RTC_ISR_INIT          BIT(7)
+#define  STM32_RTC_ISR_ALRAF         BIT(8)
 #define STM32_RTC_PRER              REG32(STM32_RTC_BASE + 0x10)
-#define STM32_RTC_PRER_A_MASK       (0x7f << 16)
-#define STM32_RTC_PRER_S_MASK       (0x7fff << 0)
+#define  STM32_RTC_PRER_A_MASK       (0x7f << 16)
+#define  STM32_RTC_PRER_S_MASK       (0x7fff << 0)
 #define STM32_RTC_WUTR              REG32(STM32_RTC_BASE + 0x14)
 #define STM32_RTC_CALIBR            REG32(STM32_RTC_BASE + 0x18)
 #define STM32_RTC_ALRMAR            REG32(STM32_RTC_BASE + 0x1C)
@@ -617,29 +627,30 @@ typedef volatile struct stm32_spi_regs stm32_spi_regs_t;
 #define STM32_SPI3_REGS ((stm32_spi_regs_t *)STM32_SPI3_BASE)
 #define STM32_SPI4_REGS ((stm32_spi_regs_t *)STM32_SPI4_BASE)
 
-#define STM32_SPI_CR1_SPE		BIT(0)
-#define STM32_SPI_CR1_CSTART		BIT(9)
-#define STM32_SPI_CR1_SSI		BIT(12)
-#define STM32_SPI_CR1_DIV(div)		((div) << 28)
-#define STM32_SPI_CFG1_DATASIZE(n)	(((n) - 1) << 0)
-#define STM32_SPI_CFG1_FTHLV(n)		(((n) - 1) << 5)
-#define STM32_SPI_CFG1_UDRCFG_CONST	(0 << 9)
-#define STM32_SPI_CFG1_UDRCFG_LAST_RX	(1 << 9)
-#define STM32_SPI_CFG1_UDRCFG_LAST_TX	(2 << 9)
-#define STM32_SPI_CFG1_UDRDET_BEGIN_FRM	(0 << 11)
-#define STM32_SPI_CFG1_UDRDET_END_FRM	(1 << 11)
-#define STM32_SPI_CFG1_UDRDET_BEGIN_SS	(2 << 11)
-#define STM32_SPI_CFG1_RXDMAEN		BIT(14)
-#define STM32_SPI_CFG1_TXDMAEN		BIT(15)
-#define STM32_SPI_CFG1_CRCSIZE(n)	(((n) - 1) << 16)
-#define STM32_SPI_CFG2_MSTR		BIT(22)
-#define STM32_SPI_CFG2_SSM		BIT(26)
-#define STM32_SPI_CFG2_AFCNTR		BIT(31)
-
-#define STM32_SPI_SR_RXNE		BIT(0)
-#define STM32_SPI_SR_UDR		BIT(5)
-#define STM32_SPI_SR_FRLVL		(3 << 13)
-#define STM32_SPI_SR_TXC		BIT(12)
+#define STM32_SPI_CR1_SPE                      BIT(0)
+#define STM32_SPI_CR1_CSTART                   BIT(9)
+#define STM32_SPI_CR1_SSI                      BIT(12)
+#define STM32_SPI_CR1_DIV(div)                 ((div) << 28)
+#define STM32_SPI_CFG1_DATASIZE(n)             (((n) - 1) << 0)
+#define STM32_SPI_CFG1_FTHLV(n)                (((n) - 1) << 5)
+#define STM32_SPI_CFG1_UDRCFG_CONST            (0 << 9)
+#define STM32_SPI_CFG1_UDRCFG_LAST_RX          (1 << 9)
+#define STM32_SPI_CFG1_UDRCFG_LAST_TX          (2 << 9)
+#define STM32_SPI_CFG1_UDRDET_BEGIN_FRM        (0 << 11)
+#define STM32_SPI_CFG1_UDRDET_END_FRM          (1 << 11)
+#define STM32_SPI_CFG1_UDRDET_BEGIN_SS         (2 << 11)
+#define STM32_SPI_CFG1_RXDMAEN                 BIT(14)
+#define STM32_SPI_CFG1_TXDMAEN                 BIT(15)
+#define STM32_SPI_CFG1_CRCSIZE(n)              (((n) - 1) << 16)
+#define  STM32_SPI_CFG2_MSTR                   BIT(22)
+#define  STM32_SPI_CFG2_SSM                    BIT(26)
+#define  STM32_SPI_CFG2_AFCNTR                 BIT(31)
+
+#define STM32_SPI_SR_RXNE                      BIT(0)
+#define STM32_SPI_SR_UDR                       BIT(5)
+#define STM32_SPI_SR_FRLVL                     (3 << 13)
+#define STM32_SPI_SR_TXC                       BIT(12)
+
 /* --- Debug --- */
 #define STM32_DBGMCU_APB3FZ         REG32(STM32_DBGMCU_BASE + 0x34)
 #define STM32_DBGMCU_APB1LFZ        REG32(STM32_DBGMCU_BASE + 0x3C)
@@ -662,41 +673,41 @@ typedef volatile struct stm32_spi_regs stm32_spi_regs_t;
 #define STM32_FLASH_ACR_WRHIGHFREQ_385MHZ (3 << 4)
 
 #define STM32_FLASH_KEYR(bank)            STM32_FLASH_REG(bank, 0x04)
-#define  FLASH_KEYR_KEY1                  0x45670123
-#define  FLASH_KEYR_KEY2                  0xCDEF89AB
+#define  FLASH_KEYR_KEY1                   0x45670123
+#define  FLASH_KEYR_KEY2                   0xCDEF89AB
 #define STM32_FLASH_OPTKEYR(bank)         STM32_FLASH_REG(bank, 0x08)
-#define  FLASH_OPTKEYR_KEY1               0x08192A3B
-#define  FLASH_OPTKEYR_KEY2               0x4C5D6E7F
+#define  FLASH_OPTKEYR_KEY1                0x08192A3B
+#define  FLASH_OPTKEYR_KEY2                0x4C5D6E7F
 #define STM32_FLASH_CR(bank)              STM32_FLASH_REG(bank, 0x0C)
-#define  FLASH_CR_LOCK                    BIT(0)
-#define  FLASH_CR_PG                      BIT(1)
-#define  FLASH_CR_SER                     BIT(2)
-#define  FLASH_CR_BER                     BIT(3)
-#define  FLASH_CR_PSIZE_BYTE              (0 << 4)
-#define  FLASH_CR_PSIZE_HWORD             (1 << 4)
-#define  FLASH_CR_PSIZE_WORD              (2 << 4)
-#define  FLASH_CR_PSIZE_DWORD             (3 << 4)
-#define  FLASH_CR_PSIZE_MASK              (3 << 4)
-#define  FLASH_CR_FW                      BIT(6)
-#define  FLASH_CR_STRT                    BIT(7)
-#define  FLASH_CR_SNB(sec)                (((sec) & 0x7) << 8)
+#define  FLASH_CR_LOCK                     BIT(0)
+#define  FLASH_CR_PG                       BIT(1)
+#define  FLASH_CR_SER                      BIT(2)
+#define  FLASH_CR_BER                      BIT(3)
+#define  FLASH_CR_PSIZE_BYTE               (0 << 4)
+#define  FLASH_CR_PSIZE_HWORD              (1 << 4)
+#define  FLASH_CR_PSIZE_WORD               (2 << 4)
+#define  FLASH_CR_PSIZE_DWORD              (3 << 4)
+#define  FLASH_CR_PSIZE_MASK               (3 << 4)
+#define  FLASH_CR_FW                       BIT(6)
+#define  FLASH_CR_STRT                     BIT(7)
+#define  FLASH_CR_SNB(sec)                 (((sec) & 0x7) << 8)
 #define  FLASH_CR_SNB_MASK                FLASH_CR_SNB(0x7)
 #define STM32_FLASH_SR(bank)              STM32_FLASH_REG(bank, 0x10)
-#define  FLASH_SR_BUSY                    BIT(0)
-#define  FLASH_SR_WBNE                    BIT(1)
-#define  FLASH_SR_QW                      BIT(2)
-#define  FLASH_SR_CRC_BUSY                BIT(3)
-#define  FLASH_SR_EOP                     BIT(16)
-#define  FLASH_SR_WRPERR                  BIT(17)
-#define  FLASH_SR_PGSERR                  BIT(18)
-#define  FLASH_SR_STRBERR                 BIT(19)
-#define  FLASH_SR_INCERR                  BIT(21)
-#define  FLASH_SR_OPERR                   BIT(22)
-#define  FLASH_SR_RDPERR                  BIT(23)
-#define  FLASH_SR_RDSERR                  BIT(24)
-#define  FLASH_SR_SNECCERR                BIT(25)
-#define  FLASH_SR_DBECCERR                BIT(26)
-#define  FLASH_SR_CRCEND                  BIT(27)
+#define  FLASH_SR_BUSY                     BIT(0)
+#define  FLASH_SR_WBNE                     BIT(1)
+#define  FLASH_SR_QW                       BIT(2)
+#define  FLASH_SR_CRC_BUSY                 BIT(3)
+#define  FLASH_SR_EOP                      BIT(16)
+#define  FLASH_SR_WRPERR                   BIT(17)
+#define  FLASH_SR_PGSERR                   BIT(18)
+#define  FLASH_SR_STRBERR                  BIT(19)
+#define  FLASH_SR_INCERR                   BIT(21)
+#define  FLASH_SR_OPERR                    BIT(22)
+#define  FLASH_SR_RDPERR                   BIT(23)
+#define  FLASH_SR_RDSERR                   BIT(24)
+#define  FLASH_SR_SNECCERR                 BIT(25)
+#define  FLASH_SR_DBECCERR                 BIT(26)
+#define  FLASH_SR_CRCEND                   BIT(27)
 #define STM32_FLASH_CCR(bank)             STM32_FLASH_REG(bank, 0x14)
 #define  FLASH_CCR_ERR_MASK              (FLASH_SR_WRPERR | FLASH_SR_PGSERR \
 					| FLASH_SR_STRBERR | FLASH_SR_INCERR \
@@ -897,9 +908,9 @@ typedef volatile struct stm32_dma_regs stm32_dma_regs_t;
 #define STM32_DMA_CCR_HTIE              BIT(3)
 #define STM32_DMA_CCR_TCIE              BIT(4)
 #define STM32_DMA_CCR_PFCTRL            BIT(5)
-#define STM32_DMA_CCR_DIR_P2M		(0 << 6)
-#define STM32_DMA_CCR_DIR_M2P		(1 << 6)
-#define STM32_DMA_CCR_DIR_M2M		(2 << 6)
+#define STM32_DMA_CCR_DIR_P2M           (0 << 6)
+#define STM32_DMA_CCR_DIR_M2P           (1 << 6)
+#define STM32_DMA_CCR_DIR_M2M           (2 << 6)
 #define STM32_DMA_CCR_CIRC              BIT(8)
 #define STM32_DMA_CCR_PINC              BIT(9)
 #define STM32_DMA_CCR_MINC              BIT(10)
@@ -916,15 +927,13 @@ typedef volatile struct stm32_dma_regs stm32_dma_regs_t;
 #define STM32_DMA_CCR_PL_VERY_HIGH      (3 << 16)
 #define STM32_DMA_CCR_DBM               BIT(18)
 #define STM32_DMA_CCR_CT                BIT(19)
-#define STM32_DMA_CCR_PBURST(b_len)		 ((((b_len) - 4) / 4) << 21)
-#define STM32_DMA_CCR_MBURST(b_len)		 ((((b_len) - 4) / 4) << 21)
-#define STM32_DMA_CCR_CHANNEL_MASK		 (0 << 25)
-#define STM32_DMA_CCR_CHANNEL(channel)		 (0)
-#define STM32_DMA_CCR_RSVD_MASK		(0xF0100000)
-
-
-#define STM32_DMA_SFCR_DMDIS		BIT(2)
-#define STM32_DMA_SFCR_FTH(level)	(((level) - 1) << 0)
+#define STM32_DMA_CCR_PBURST(b_len)     ((((b_len) - 4) / 4) << 21)
+#define STM32_DMA_CCR_MBURST(b_len)     ((((b_len) - 4) / 4) << 21)
+#define STM32_DMA_CCR_CHANNEL_MASK      (0 << 25)
+#define STM32_DMA_CCR_CHANNEL(channel)  (0)
+#define STM32_DMA_CCR_RSVD_MASK         (0xF0100000)
+#define STM32_DMA_SFCR_DMDIS            BIT(2)
+#define STM32_DMA_SFCR_FTH(level)       (((level) - 1) << 0)
 
 
 #define STM32_DMA_CH_LOCAL(channel)     ((channel) % STM32_DMAS_COUNT)
@@ -1079,22 +1088,20 @@ enum dmamux1_request {
 #define STM32_CRC_DR32              REG32(STM32_CRC_BASE + 0x0)
 #define STM32_CRC_DR16              REG16(STM32_CRC_BASE + 0x0)
 #define STM32_CRC_DR8               REG8(STM32_CRC_BASE + 0x0)
-
 #define STM32_CRC_IDR               REG32(STM32_CRC_BASE + 0x4)
 #define STM32_CRC_CR                REG32(STM32_CRC_BASE + 0x8)
+#define  STM32_CRC_CR_RESET          BIT(0)
+#define  STM32_CRC_CR_POLYSIZE_32    (0 << 3)
+#define  STM32_CRC_CR_POLYSIZE_16    (1 << 3)
+#define  STM32_CRC_CR_POLYSIZE_8     (2 << 3)
+#define  STM32_CRC_CR_POLYSIZE_7     (3 << 3)
+#define  STM32_CRC_CR_REV_IN_BYTE    (1 << 5)
+#define  STM32_CRC_CR_REV_IN_HWORD   (2 << 5)
+#define  STM32_CRC_CR_REV_IN_WORD    (3 << 5)
+#define  STM32_CRC_CR_REV_OUT        BIT(7)
 #define STM32_CRC_INIT              REG32(STM32_CRC_BASE + 0x10)
 #define STM32_CRC_POL               REG32(STM32_CRC_BASE + 0x14)
 
-#define STM32_CRC_CR_RESET          BIT(0)
-#define STM32_CRC_CR_POLYSIZE_32    (0 << 3)
-#define STM32_CRC_CR_POLYSIZE_16    (1 << 3)
-#define STM32_CRC_CR_POLYSIZE_8     (2 << 3)
-#define STM32_CRC_CR_POLYSIZE_7     (3 << 3)
-#define STM32_CRC_CR_REV_IN_BYTE    (1 << 5)
-#define STM32_CRC_CR_REV_IN_HWORD   (2 << 5)
-#define STM32_CRC_CR_REV_IN_WORD    (3 << 5)
-#define STM32_CRC_CR_REV_OUT        BIT(7)
-
 /* --- PMSE --- */
 #define STM32_PMSE_ARCR             REG32(STM32_PMSE_BASE + 0x0)
 #define STM32_PMSE_ACCR             REG32(STM32_PMSE_BASE + 0x4)
@@ -1120,36 +1127,34 @@ enum dmamux1_request {
 #define STM32_USB_EP(n)            REG16(STM32_USB_FS_BASE + (n) * 4)
 
 #define STM32_USB_CNTR             REG16(STM32_USB_FS_BASE + 0x40)
-
-#define STM32_USB_CNTR_FRES	    BIT(0)
-#define STM32_USB_CNTR_PDWN	    BIT(1)
-#define STM32_USB_CNTR_LP_MODE	    BIT(2)
-#define STM32_USB_CNTR_FSUSP	    BIT(3)
-#define STM32_USB_CNTR_RESUME	    BIT(4)
-#define STM32_USB_CNTR_L1RESUME	    BIT(5)
-#define STM32_USB_CNTR_L1REQM	    BIT(7)
-#define STM32_USB_CNTR_ESOFM	    BIT(8)
-#define STM32_USB_CNTR_SOFM	    BIT(9)
-#define STM32_USB_CNTR_RESETM	    BIT(10)
-#define STM32_USB_CNTR_SUSPM	    BIT(11)
-#define STM32_USB_CNTR_WKUPM	    BIT(12)
-#define STM32_USB_CNTR_ERRM	    BIT(13)
-#define STM32_USB_CNTR_PMAOVRM	    BIT(14)
-#define STM32_USB_CNTR_CTRM	    BIT(15)
+#define  STM32_USB_CNTR_FRES        BIT(0)
+#define  STM32_USB_CNTR_PDWN        BIT(1)
+#define  STM32_USB_CNTR_LP_MODE     BIT(2)
+#define  STM32_USB_CNTR_FSUSP       BIT(3)
+#define  STM32_USB_CNTR_RESUME      BIT(4)
+#define  STM32_USB_CNTR_L1RESUME    BIT(5)
+#define  STM32_USB_CNTR_L1REQM      BIT(7)
+#define  STM32_USB_CNTR_ESOFM       BIT(8)
+#define  STM32_USB_CNTR_SOFM        BIT(9)
+#define  STM32_USB_CNTR_RESETM      BIT(10)
+#define  STM32_USB_CNTR_SUSPM       BIT(11)
+#define  STM32_USB_CNTR_WKUPM       BIT(12)
+#define  STM32_USB_CNTR_ERRM        BIT(13)
+#define  STM32_USB_CNTR_PMAOVRM     BIT(14)
+#define  STM32_USB_CNTR_CTRM        BIT(15)
 
 #define STM32_USB_ISTR             REG16(STM32_USB_FS_BASE + 0x44)
-
-#define STM32_USB_ISTR_EP_ID_MASK   (0x000f)
-#define STM32_USB_ISTR_DIR	    BIT(4)
-#define STM32_USB_ISTR_L1REQ	    BIT(7)
-#define STM32_USB_ISTR_ESOF	    BIT(8)
-#define STM32_USB_ISTR_SOF	    BIT(9)
-#define STM32_USB_ISTR_RESET	    BIT(10)
-#define STM32_USB_ISTR_SUSP	    BIT(11)
-#define STM32_USB_ISTR_WKUP	    BIT(12)
-#define STM32_USB_ISTR_ERR	    BIT(13)
-#define STM32_USB_ISTR_PMAOVR	    BIT(14)
-#define STM32_USB_ISTR_CTR	    BIT(15)
+#define  STM32_USB_ISTR_EP_ID_MASK  (0x000f)
+#define  STM32_USB_ISTR_DIR         BIT(4)
+#define  STM32_USB_ISTR_L1REQ       BIT(7)
+#define  STM32_USB_ISTR_ESOF        BIT(8)
+#define  STM32_USB_ISTR_SOF         BIT(9)
+#define  STM32_USB_ISTR_RESET       BIT(10)
+#define  STM32_USB_ISTR_SUSP        BIT(11)
+#define  STM32_USB_ISTR_WKUP        BIT(12)
+#define  STM32_USB_ISTR_ERR         BIT(13)
+#define  STM32_USB_ISTR_PMAOVR      BIT(14)
+#define  STM32_USB_ISTR_CTR         BIT(15)
 
 #define STM32_USB_FNR              REG16(STM32_USB_FS_BASE + 0x48)
 
@@ -1160,15 +1165,14 @@ enum dmamux1_request {
 #define STM32_USB_BTABLE           REG16(STM32_USB_FS_BASE + 0x50)
 #define STM32_USB_LPMCSR           REG16(STM32_USB_FS_BASE + 0x54)
 #define STM32_USB_BCDR             REG16(STM32_USB_FS_BASE + 0x58)
-
-#define STM32_USB_BCDR_BCDEN	    BIT(0)
-#define STM32_USB_BCDR_DCDEN	    BIT(1)
-#define STM32_USB_BCDR_PDEN	    BIT(2)
-#define STM32_USB_BCDR_SDEN	    BIT(3)
-#define STM32_USB_BCDR_DCDET	    BIT(4)
-#define STM32_USB_BCDR_PDET	    BIT(5)
-#define STM32_USB_BCDR_SDET	    BIT(6)
-#define STM32_USB_BCDR_PS2DET	    BIT(7)
+#define  STM32_USB_BCDR_BCDEN       BIT(0)
+#define  STM32_USB_BCDR_DCDEN       BIT(1)
+#define  STM32_USB_BCDR_PDEN        BIT(2)
+#define  STM32_USB_BCDR_SDEN        BIT(3)
+#define  STM32_USB_BCDR_DCDET       BIT(4)
+#define  STM32_USB_BCDR_PDET        BIT(5)
+#define  STM32_USB_BCDR_SDET        BIT(6)
+#define  STM32_USB_BCDR_PS2DET      BIT(7)
 
 #define EP_MASK     0x0F0F
 #define EP_TX_DTOG  0x0040
@@ -1195,11 +1199,11 @@ enum dmamux1_request {
 
 /* --- TRNG --- */
 #define STM32_RNG_CR                REG32(STM32_RNG_BASE + 0x0)
-#define STM32_RNG_CR_RNGEN          BIT(2)
-#define STM32_RNG_CR_IE             BIT(3)
-#define STM32_RNG_CR_CED            BIT(5)
+#define  STM32_RNG_CR_RNGEN          BIT(2)
+#define  STM32_RNG_CR_IE             BIT(3)
+#define  STM32_RNG_CR_CED            BIT(5)
 #define STM32_RNG_SR                REG32(STM32_RNG_BASE + 0x4)
-#define STM32_RNG_SR_DRDY           BIT(0)
+#define  STM32_RNG_SR_DRDY           BIT(0)
 #define STM32_RNG_DR                REG32(STM32_RNG_BASE + 0x8)
 
 /* --- AXI interconnect --- */
@@ -1207,8 +1211,8 @@ enum dmamux1_request {
 /* STM32H7: AXI_TARGx_FN_MOD exists for masters x = 1, 2 and 7 */
 #define STM32_AXI_TARG_FN_MOD(x)    REG32(STM32_GPV_BASE + 0x1108 + \
 					  0x1000 * (x))
-#define  WRITE_ISS_OVERRIDE         BIT(1)
-#define  READ_ISS_OVERRIDE          BIT(0)
+#define  WRITE_ISS_OVERRIDE          BIT(1)
+#define  READ_ISS_OVERRIDE           BIT(0)
 
 /* --- MISC --- */
 #define STM32_UNIQUE_ID_ADDRESS     REG32_ADDR(STM32_UNIQUE_ID_BASE)
diff --git a/chip/stm32/registers-stm32l.h b/chip/stm32/registers-stm32l.h
index d4b59780b5..4dd7d24709 100644
--- a/chip/stm32/registers-stm32l.h
+++ b/chip/stm32/registers-stm32l.h
@@ -1,10 +1,20 @@
 /* Copyright 2019 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ * @brief Register map for the STM32L family of chips
  *
- * Register map for STM32 processor
+ * This header file should not be included directly.
+ * Please include registers.h instead.
  */
 
+#ifndef __CROS_EC_REGISTERS_H
+#error "This header file should not be included directly."
+#endif
+
 /* --- IRQ numbers --- */
 #define STM32_IRQ_WWDG             0
 #define STM32_IRQ_PVD              1
diff --git a/chip/stm32/registers-stm32l4.h b/chip/stm32/registers-stm32l4.h
index e1ae7c9376..6b1211af27 100644
--- a/chip/stm32/registers-stm32l4.h
+++ b/chip/stm32/registers-stm32l4.h
@@ -1,10 +1,20 @@
 /* Copyright 2019 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ * @brief Register map for the STM32L4 family of chips
  *
- * Register map for STM32 processor
+ * This header file should not be included directly.
+ * Please include registers.h instead.
  */
 
+#ifndef __CROS_EC_REGISTERS_H
+#error "This header file should not be included directly."
+#endif
+
 /* --- IRQ numbers --- */
 #define STM32_IRQ_WWDG             0
 #define STM32_IRQ_PVD              1
diff --git a/chip/stm32/registers.h b/chip/stm32/registers.h
index 77f59a87be..c996edd2ad 100644
--- a/chip/stm32/registers.h
+++ b/chip/stm32/registers.h
@@ -1,8 +1,43 @@
 /* Copyright 2013 The Chromium OS Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
+ */
+
+/**
+ * @file
+ * @brief Register map for the STM32 family of chips
+ *
+ * This header file should only contain register definitions and
+ * functionality that are common to all STM32 chips.
+ * Any chip/family specific macros must be placed in their family
+ * specific registers file, which is conditionally included at the
+ * end of this file.
+ * Include this file directly for all STM32 register definitions.
+ *
+ * ### History and Reasoning ###
+ * In a time before chip family register file separation,
+ * long long ago, there lived a single file called `registers.h`,
+ * which housed register definitions for all STM32 chip family and variants.
+ * This poor file was 3000 lines of register macros and C definitions,
+ * swiss-cheesed by nested preprocessor conditional logic.
+ * Adding a single new chip variant required splitting multiple,
+ * already nested, conditional sections throughout the file.
+ * Readability was on the difficult side and refactoring was dangerous.
+ *
+ * The number of STM32 variants had outgrown the single registers file model.
+ * The minor gains of sharing a set of registers between a subset of chip
+ * variants no longer outweighed the complexity of the following operations:
+ * - Adding a new chip variant or variant feature
+ * - Determining if a register was properly setup for a variant or if it
+ *   was simply not unset
+ *
+ * To strike a balance between shared registers and chip specific registers,
+ * the registers.h file remains a place for common definitions, but family
+ * specific definitions were moved to their own files.
+ * These family specific files contain a much reduced level of preprocessor
+ * logic for variant specific registers.
  *
- * Register map for STM32 processor
+ * See https://crrev.com/c/1674679 to witness the separation steps.
  */
 
 #ifndef __CROS_EC_REGISTERS_H