Add dual-bank STM32 bootloader support, given GPIO toggle on BOOT0 to charge RC circuit. (#8778)

docs/platformdev_chibios_earlyinit.md

@@ -4,17 +4,28 @@ This page describes a part of QMK that is a somewhat advanced concept, and is on
 
 QMK uses ChibiOS as the underlying layer to support a multitude of Arm-based devices. Each ChibiOS-supported keyboard has a low-level board definition which is responsible for initializing hardware peripherals such as the clocks, and GPIOs.
 
-Older QMK revisions required duplication of these board definitions inside your keyboard's directory in order to override such early initialization points; this is now abstracted into the following APIs, and allows usage of the board definitions supplied with ChibiOS itself. Check `<qmk_firmware>/lib/chibios/os/hal/boards` for the list of official definitions. If your keyboard needs extra initialization at a very early stage, consider providing keyboard-level overrides of the following APIs:
+Older QMK revisions required duplication of these board definitions inside your keyboard's directory in order to override such early initialization points; this is now abstracted into the following APIs, and allows usage of the board definitions supplied with ChibiOS itself. Check `<qmk_firmware>/lib/chibios/os/hal/boards` for the list of official definitions. If your keyboard needs extra initialization at a very early stage, consider providing keyboard-level overrides of the following APIs instead of duplicating the board definitions:
 
 ## `early_hardware_init_pre()` :id=early-hardware-init-pre
 
 The function `early_hardware_init_pre` is the earliest possible code that can be executed by a keyboard firmware. This is intended as a replacement for the ChibiOS board definition's `__early_init` function, and is the equivalent of executing at the start of the function.
 
-This is executed before RAM gets cleared, and before clocks or GPIOs are configured; any delays or preparation using GPIOs is not likely to work at this point. After executing this function, RAM on the MCU may be zero'ed. Assigning values to variables during execution of this function may be overwritten.
+This is executed before RAM gets cleared, and before clocks or GPIOs are configured; for example, ChibiOS delays are not likely to work at this point. After executing this function, RAM on the MCU may be zero'ed. Assigning values to variables during execution of this function may be overwritten.
 
-As such, if you wish to override this API consider limiting use to writing to low-level registers. The default implementation of this function can be configured to jump to bootloader if a `RESET` key was pressed, by ensuring `#define EARLY_INIT_PERFORM_BOOTLOADER_JUMP TRUE` is in the keyboard's `config.h` file.
+As such, if you wish to override this API consider limiting use to writing to low-level registers. The default implementation of this function can be configured to jump to bootloader if a `RESET` key was pressed:
 
-To implement your own version of this function, in your keyboard's source files:
+| `config.h` override                           | Description                                                                                                                                                                                                                                                                            | Default  |
+|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|
+| `#define EARLY_INIT_PERFORM_BOOTLOADER_JUMP`  | Whether or not bootloader is to be executed during the early initialisation code of QMK.                                                                                                                                                                                               | `FALSE`  |
+| `#define STM32_BOOTLOADER_ADDRESS`            | Relevant for single-bank STM32 MCUs, signifies the memory address to jump to bootloader. Consult [AN2606](https://www.st.com/content/st_com/en/search.html#q=an2606-t=resources-page=1) for the _System Memory_ address for your MCU. This value should be of the format `0x11111111`. | `<none>` |
+| `#define STM32_BOOTLOADER_DUAL_BANK`          | Relevant for dual-bank STM32 MCUs, signifies that a GPIO is to be toggled in order to enter bootloader mode.                                                                                                                                                                           | `FALSE`  |
+| `#define STM32_BOOTLOADER_DUAL_BANK_GPIO`     | Relevant for dual-bank STM32 MCUs, the pin to toggle when attempting to enter bootloader mode, e.g. `B8`                                                                                                                                                                               | `<none>` |
+| `#define STM32_BOOTLOADER_DUAL_BANK_POLARITY` | Relevant for dual-bank STM32 MCUs, the value to set the pin to in order to trigger charging of the RC circuit. e.g. `0` or `1`.                                                                                                                                                        | `0`      |
+| `#define STM32_BOOTLOADER_DUAL_BANK_DELAY`    | Relevant for dual-bank STM32 MCUs, an arbitrary measurement of time to delay before resetting the MCU. Increasing number increases the delay.                                                                                                                                          | `100000` |
+
+Kinetis MCUs have no configurable options.
+
+Alternatively, to implement your own version of this function, in your keyboard's source files:
 
 ```c
 void early_hardware_init_pre(void) {

tmk_core/common/chibios/bootloader.c

@@ -3,28 +3,82 @@
 #include "ch.h"
 #include "hal.h"
 
-#ifdef STM32_BOOTLOADER_ADDRESS
-/* STM32 */
-
 /* This code should be checked whether it runs correctly on platforms */
-#    define SYMVAL(sym) (uint32_t)(((uint8_t *)&(sym)) - ((uint8_t *)0))
+#define SYMVAL(sym) (uint32_t)(((uint8_t *)&(sym)) - ((uint8_t *)0))
-extern uint32_t __ram0_end__;
+#define BOOTLOADER_MAGIC 0xDEADBEEF
-#    define BOOTLOADER_MAGIC 0xDEADBEEF
+#define MAGIC_ADDR (unsigned long *)(SYMVAL(__ram0_end__) - 4)
-#    define MAGIC_ADDR (unsigned long *)(SYMVAL(__ram0_end__) - 4)
+
+#ifndef STM32_BOOTLOADER_DUAL_BANK
+#    define STM32_BOOTLOADER_DUAL_BANK FALSE
+#endif
+
+#if STM32_BOOTLOADER_DUAL_BANK
+
+// Need pin definitions
+#    include "config_common.h"
+
+#    ifndef STM32_BOOTLOADER_DUAL_BANK_GPIO
+#        error "No STM32_BOOTLOADER_DUAL_BANK_GPIO defined, don't know which pin to toggle"
+#    endif
+
+#    ifndef STM32_BOOTLOADER_DUAL_BANK_POLARITY
+#        define STM32_BOOTLOADER_DUAL_BANK_POLARITY 0
+#    endif
+
+#    ifndef STM32_BOOTLOADER_DUAL_BANK_DELAY
+#        define STM32_BOOTLOADER_DUAL_BANK_DELAY 100000
+#    endif
+
+extern uint32_t __ram0_end__;
+
+#    define bootdelay(loopcount)                  \
+        do {                                      \
+            for (int i = 0; i < loopcount; ++i) { \
+                __asm__ volatile("nop\n\t"        \
+                                 "nop\n\t"        \
+                                 "nop\n\t");      \
+            }                                     \
+        } while (0)
+
+void bootloader_jump(void) {
+    *MAGIC_ADDR = BOOTLOADER_MAGIC;  // set magic flag => reset handler will jump into boot loader
+    NVIC_SystemReset();
+}
+
+void enter_bootloader_mode_if_requested(void) {
+    unsigned long *check = MAGIC_ADDR;
+    if (*check == BOOTLOADER_MAGIC) {
+        *check = 0;
+
+        // For STM32 MCUs with dual-bank flash, and we're incapable of jumping to the bootloader. The first valid flash
+        // bank is executed unconditionally after a reset, so it doesn't enter DFU unless BOOT0 is high. Instead, we do
+        // it with hardware...in this case, we pull a GPIO high/low depending on the configuration, connects 3.3V to
+        // BOOT0's RC charging circuit, lets it charge the capacitor, and issue a system reset. See the QMK discord
+        // #hardware channel pins for an example circuit.
+        palSetPadMode(PAL_PORT(STM32_BOOTLOADER_DUAL_BANK_GPIO), PAL_PAD(STM32_BOOTLOADER_DUAL_BANK_GPIO), PAL_MODE_OUTPUT_PUSHPULL);
+#    if STM32_BOOTLOADER_DUAL_BANK_POLARITY
+        palSetPad(PAL_PORT(STM32_BOOTLOADER_DUAL_BANK_GPIO), PAL_PAD(STM32_BOOTLOADER_DUAL_BANK_GPIO));
+#    else
+        palClearPad(PAL_PORT(STM32_BOOTLOADER_DUAL_BANK_GPIO), PAL_PAD(STM32_BOOTLOADER_DUAL_BANK_GPIO));
+#    endif
+
+        // Wait for a while for the capacitor to charge
+        bootdelay(STM32_BOOTLOADER_DUAL_BANK_DELAY);
+
+        // Issue a system reset to get the ROM bootloader to execute, with BOOT0 high
+        NVIC_SystemReset();
+    }
+}
+
+#elif defined(STM32_BOOTLOADER_ADDRESS)  // STM32_BOOTLOADER_DUAL_BANK
+
+extern uint32_t __ram0_end__;
 
-/** \brief Jump to the bootloader
- *
- * FIXME: needs doc
- */
 void bootloader_jump(void) {
     *MAGIC_ADDR = BOOTLOADER_MAGIC;  // set magic flag => reset handler will jump into boot loader
     NVIC_SystemReset();
 }
 
-/** \brief Enter bootloader mode if requested
- *
- * FIXME: needs doc
- */
 void enter_bootloader_mode_if_requested(void) {
     unsigned long *check = MAGIC_ADDR;
     if (*check == BOOTLOADER_MAGIC) {
@@ -41,7 +95,7 @@ void enter_bootloader_mode_if_requested(void) {
     }
 }
 
-#elif defined(KL2x) || defined(K20x) /* STM32_BOOTLOADER_ADDRESS */
+#elif defined(KL2x) || defined(K20x)  // STM32_BOOTLOADER_DUAL_BANK // STM32_BOOTLOADER_ADDRESS
 /* Kinetis */
 
 #    if defined(KIIBOHD_BOOTLOADER)

tmk_core/protocol/chibios/main.c

@@ -35,6 +35,7 @@
 
 #ifndef EARLY_INIT_PERFORM_BOOTLOADER_JUMP
 // Change this to be TRUE once we've migrated keyboards to the new init system
+// Remember to change docs/platformdev_chibios_earlyinit.md as well.
 #    define EARLY_INIT_PERFORM_BOOTLOADER_JUMP FALSE
 #endif