Move tmk_core/common/<plat> (#13918)

23 files changed, 3721 insertions, 0 deletions

diff --git a/platforms/chibios/_timer.h b/platforms/chibios/_timer.h
new file mode 100644
index 0000000000..77402b612a
--- /dev/null
+++ b/platforms/chibios/_timer.h
@@ -0,0 +1,19 @@
+/* Copyright 2021 Simon Arlott
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+// The platform is 32-bit, so prefer 32-bit timers to avoid overflow
+#define FAST_TIMER_T_SIZE 32
diff --git a/platforms/chibios/_wait.c b/platforms/chibios/_wait.c
new file mode 100644
index 0000000000..1fbea2dd5e
--- /dev/null
+++ b/platforms/chibios/_wait.c
@@ -0,0 +1,89 @@
+/* Copyright 2021 QMK
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#ifndef __OPTIMIZE__
+#    pragma message "Compiler optimizations disabled; wait_cpuclock() won't work as designed"
+#endif
+
+#define CLOCK_DELAY_NOP8 "nop\n\t nop\n\t nop\n\t nop\n\t   nop\n\t nop\n\t nop\n\t nop\n\t"
+
+__attribute__((always_inline)) static inline void wait_cpuclock(unsigned int n) { /* n: 1..135 */
+    /* The argument n must be a constant expression.
+     * That way, compiler optimization will remove unnecessary code. */
+    if (n < 1) {
+        return;
+    }
+    if (n > 8) {
+        unsigned int n8 = n / 8;
+        n               = n - n8 * 8;
+        switch (n8) {
+            case 16:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 15:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 14:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 13:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 12:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 11:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 10:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 9:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 8:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 7:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 6:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 5:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 4:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 3:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 2:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 1:
+                asm volatile(CLOCK_DELAY_NOP8::: "memory");
+            case 0:
+                break;
+        }
+    }
+    switch (n) {
+        case 8:
+            asm volatile("nop" ::: "memory");
+        case 7:
+            asm volatile("nop" ::: "memory");
+        case 6:
+            asm volatile("nop" ::: "memory");
+        case 5:
+            asm volatile("nop" ::: "memory");
+        case 4:
+            asm volatile("nop" ::: "memory");
+        case 3:
+            asm volatile("nop" ::: "memory");
+        case 2:
+            asm volatile("nop" ::: "memory");
+        case 1:
+            asm volatile("nop" ::: "memory");
+        case 0:
+            break;
+    }
+}
diff --git a/platforms/chibios/_wait.h b/platforms/chibios/_wait.h
new file mode 100644
index 0000000000..2f36c64a2e
--- /dev/null
+++ b/platforms/chibios/_wait.h
@@ -0,0 +1,60 @@
+/* Copyright 2021 QMK
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+#include <ch.h>
+#include <hal.h>
+
+/* chThdSleepX of zero maps to infinite - so we map to a tiny delay to still yield */
+#define wait_ms(ms)                     \
+    do {                                \
+        if (ms != 0) {                  \
+            chThdSleepMilliseconds(ms); \
+        } else {                        \
+            chThdSleepMicroseconds(1);  \
+        }                               \
+    } while (0)
+
+#ifdef WAIT_US_TIMER
+void wait_us(uint16_t duration);
+#else
+#    define wait_us(us)                     \
+        do {                                \
+            if (us != 0) {                  \
+                chThdSleepMicroseconds(us); \
+            } else {                        \
+                chThdSleepMicroseconds(1);  \
+            }                               \
+        } while (0)
+#endif
+
+#include "_wait.c"
+
+/* For GPIOs on ARM-based MCUs, the input pins are sampled by the clock of the bus
+ * to which the GPIO is connected.
+ * The connected buses differ depending on the various series of MCUs.
+ * And since the instruction execution clock of the CPU and the bus clock of GPIO are different,
+ * there is a delay of several clocks to read the change of the input signal.
+ *
+ * Define this delay with the GPIO_INPUT_PIN_DELAY macro.
+ * If the GPIO_INPUT_PIN_DELAY macro is not defined, the following default values will be used.
+ * (A fairly large value of 0.25 microseconds is set.)
+ */
+#ifndef GPIO_INPUT_PIN_DELAY
+#    define GPIO_INPUT_PIN_DELAY (CPU_CLOCK / 1000000L / 4)
+#endif
+
+#define waitInputPinDelay() wait_cpuclock(GPIO_INPUT_PIN_DELAY)
diff --git a/platforms/chibios/atomic_util.h b/platforms/chibios/atomic_util.h
new file mode 100644
index 0000000000..8975045153
--- /dev/null
+++ b/platforms/chibios/atomic_util.h
@@ -0,0 +1,37 @@
+/* Copyright 2021 QMK
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+#include <ch.h>
+
+static __inline__ uint8_t __interrupt_disable__(void) {
+    chSysLock();
+
+    return 1;
+}
+
+static __inline__ void __interrupt_enable__(const uint8_t *__s) {
+    chSysUnlock();
+
+    __asm__ volatile("" ::: "memory");
+    (void)__s;
+}
+
+#define ATOMIC_BLOCK(type) for (type, __ToDo = __interrupt_disable__(); __ToDo; __ToDo = 0)
+#define ATOMIC_FORCEON uint8_t sreg_save __attribute__((__cleanup__(__interrupt_enable__))) = 0
+
+#define ATOMIC_BLOCK_RESTORESTATE _Static_assert(0, "ATOMIC_BLOCK_RESTORESTATE not implemented")
+#define ATOMIC_BLOCK_FORCEON ATOMIC_BLOCK(ATOMIC_FORCEON)
diff --git a/platforms/chibios/bootloader.c b/platforms/chibios/bootloader.c
new file mode 100644
index 0000000000..5cadadeeeb
--- /dev/null
+++ b/platforms/chibios/bootloader.c
@@ -0,0 +1,145 @@
+#include "bootloader.h"
+
+#include <ch.h>
+#include <hal.h>
+#include "wait.h"
+
+/* This code should be checked whether it runs correctly on platforms */
+#define SYMVAL(sym) (uint32_t)(((uint8_t *)&(sym)) - ((uint8_t *)0))
+#define BOOTLOADER_MAGIC 0xDEADBEEF
+#define MAGIC_ADDR (unsigned long *)(SYMVAL(__ram0_end__) - 4)
+
+#ifndef STM32_BOOTLOADER_DUAL_BANK
+#    define STM32_BOOTLOADER_DUAL_BANK FALSE
+#endif
+
+#ifdef BOOTLOADER_TINYUF2
+
+#    define DBL_TAP_MAGIC 0xf01669ef  // From tinyuf2's board_api.h
+
+// defined by linker script
+extern uint32_t _board_dfu_dbl_tap[];
+#    define DBL_TAP_REG _board_dfu_dbl_tap[0]
+
+void bootloader_jump(void) {
+    DBL_TAP_REG = DBL_TAP_MAGIC;
+    NVIC_SystemReset();
+}
+
+void enter_bootloader_mode_if_requested(void) { /* not needed, no two-stage reset */
+}
+
+#elif 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__;
+
+__attribute__((weak)) void bootloader_jump(void) {
+    // 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
+    wait_ms(100);
+
+    // Issue a system reset to get the ROM bootloader to execute, with BOOT0 high
+    NVIC_SystemReset();
+}
+
+void enter_bootloader_mode_if_requested(void) {}  // not needed at all, but if anybody attempts to invoke it....
+
+#elif defined(STM32_BOOTLOADER_ADDRESS)  // STM32_BOOTLOADER_DUAL_BANK
+
+extern uint32_t __ram0_end__;
+
+__attribute__((weak)) 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;
+        __set_CONTROL(0);
+        __set_MSP(*(__IO uint32_t *)STM32_BOOTLOADER_ADDRESS);
+        __enable_irq();
+
+        typedef void (*BootJump_t)(void);
+        BootJump_t boot_jump = *(BootJump_t *)(STM32_BOOTLOADER_ADDRESS + 4);
+        boot_jump();
+        while (1)
+            ;
+    }
+}
+
+#elif defined(GD32VF103)
+
+#    define DBGMCU_KEY_UNLOCK 0x4B5A6978
+#    define DBGMCU_CMD_RESET 0x1
+
+__IO uint32_t *DBGMCU_KEY = (uint32_t *)DBGMCU_BASE + 0x0CU;
+__IO uint32_t *DBGMCU_CMD = (uint32_t *)DBGMCU_BASE + 0x08U;
+
+__attribute__((weak)) void bootloader_jump(void) {
+    /* The MTIMER unit of the GD32VF103 doesn't have the MSFRST
+     * register to generate a software reset request.
+     * BUT instead two undocumented registers in the debug peripheral
+     * that allow issueing a software reset. WHO would need the MSFRST
+     * register anyway? Source:
+     * https://github.com/esmil/gd32vf103inator/blob/master/include/gd32vf103/dbg.h */
+    *DBGMCU_KEY = DBGMCU_KEY_UNLOCK;
+    *DBGMCU_CMD = DBGMCU_CMD_RESET;
+}
+
+void enter_bootloader_mode_if_requested(void) { /* Jumping to bootloader is not possible from user code. */
+}
+
+#elif defined(KL2x) || defined(K20x) || defined(MK66F18) || defined(MIMXRT1062)  // STM32_BOOTLOADER_DUAL_BANK // STM32_BOOTLOADER_ADDRESS
+/* Kinetis */
+
+#    if defined(BOOTLOADER_KIIBOHD)
+/* Kiibohd Bootloader (MCHCK and Infinity KB) */
+#        define SCB_AIRCR_VECTKEY_WRITEMAGIC 0x05FA0000
+const uint8_t              sys_reset_to_loader_magic[] = "\xff\x00\x7fRESET TO LOADER\x7f\x00\xff";
+__attribute__((weak)) void bootloader_jump(void) {
+    void *volatile vbat = (void *)VBAT;
+    __builtin_memcpy(vbat, (const void *)sys_reset_to_loader_magic, sizeof(sys_reset_to_loader_magic));
+    // request reset
+    SCB->AIRCR = SCB_AIRCR_VECTKEY_WRITEMAGIC | SCB_AIRCR_SYSRESETREQ_Msk;
+}
+
+#    else /* defined(BOOTLOADER_KIIBOHD) */
+/* Default for Kinetis - expecting an ARM Teensy */
+#        include "wait.h"
+__attribute__((weak)) void bootloader_jump(void) {
+    wait_ms(100);
+    __BKPT(0);
+}
+#    endif /* defined(BOOTLOADER_KIIBOHD) */
+
+#else /* neither STM32 nor KINETIS */
+__attribute__((weak)) void bootloader_jump(void) {}
+#endif
diff --git a/platforms/chibios/chibios_config.h b/platforms/chibios/chibios_config.h
new file mode 100644
index 0000000000..ad2f808a95
--- /dev/null
+++ b/platforms/chibios/chibios_config.h
@@ -0,0 +1,78 @@
+/* Copyright 2019
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+#pragma once
+
+#ifndef USB_VBUS_PIN
+#    define SPLIT_USB_DETECT  // Force this on when dedicated pin is not used
+#endif
+
+// STM32 compatibility
+#if defined(MCU_STM32)
+#    define CPU_CLOCK STM32_SYSCLK
+
+#    if defined(STM32F1XX)
+#        define USE_GPIOV1
+#        define PAL_MODE_ALTERNATE_OPENDRAIN PAL_MODE_STM32_ALTERNATE_OPENDRAIN
+#        define PAL_MODE_ALTERNATE_PUSHPULL PAL_MODE_STM32_ALTERNATE_PUSHPULL
+#    else
+#        define PAL_OUTPUT_TYPE_OPENDRAIN PAL_STM32_OTYPE_OPENDRAIN
+#        define PAL_OUTPUT_TYPE_PUSHPULL PAL_STM32_OTYPE_PUSHPULL
+#        define PAL_OUTPUT_SPEED_HIGHEST PAL_STM32_OSPEED_HIGHEST
+#        define PAL_PUPDR_FLOATING PAL_STM32_PUPDR_FLOATING
+#    endif
+
+#    if defined(STM32F1XX) || defined(STM32F2XX) || defined(STM32F4XX) || defined(STM32L1XX)
+#        define USE_I2CV1
+#    endif
+#endif
+
+// GD32 compatibility
+#if defined(MCU_GD32V)
+#    define CPU_CLOCK GD32_SYSCLK
+
+#    if defined(GD32VF103)
+#        define USE_GPIOV1
+#        define USE_I2CV1
+#        define PAL_MODE_ALTERNATE_OPENDRAIN PAL_MODE_GD32_ALTERNATE_OPENDRAIN
+#        define PAL_MODE_ALTERNATE_PUSHPULL PAL_MODE_GD32_ALTERNATE_PUSHPULL
+#    endif
+#endif
+
+#if defined(GD32VF103)
+/* This chip has the same API as STM32F103, but uses different names for literally the same thing.
+ * As of 4.7.2021 QMK is tailored to use STM32 defines/names, for compatibility sake
+ * we just redefine the GD32 names. */
+#    include "gd32v_compatibility.h"
+#endif
+
+// teensy compatibility
+#if defined(MCU_KINETIS)
+#    define CPU_CLOCK KINETIS_SYSCLK_FREQUENCY
+
+#    if defined(K20x) || defined(KL2x)
+#        define USE_I2CV1
+#        define USE_I2CV1_CONTRIB  // for some reason a bunch of ChibiOS-Contrib boards only have clock_speed
+#        define USE_GPIOV1
+#    endif
+#endif
+
+#if defined(HT32)
+#    define CPU_CLOCK HT32_CK_SYS_FREQUENCY
+#    define PAL_MODE_ALTERNATE PAL_HT32_MODE_AF
+#    define PAL_OUTPUT_TYPE_OPENDRAIN (PAL_HT32_MODE_OD | PAL_HT32_MODE_DIR)
+#    define PAL_OUTPUT_TYPE_PUSHPULL PAL_HT32_MODE_DIR
+#    define PAL_OUTPUT_SPEED_HIGHEST 0
+#endif
diff --git a/platforms/chibios/eeprom_stm32.c b/platforms/chibios/eeprom_stm32.c
new file mode 100644
index 0000000000..acc6a48516
--- /dev/null
+++ b/platforms/chibios/eeprom_stm32.c
@@ -0,0 +1,687 @@
+/*
+ * This software is experimental and a work in progress.
+ * Under no circumstances should these files be used in relation to any critical system(s).
+ * Use of these files is at your own risk.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+ * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+ * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ *
+ * This files are free to use from http://engsta.com/stm32-flash-memory-eeprom-emulator/ by
+ * Artur F.
+ *
+ * Modifications for QMK and STM32F303 by Yiancar
+ * Modifications to add flash wear leveling by Ilya Zhuravlev
+ * Modifications to increase flash density by Don Kjer
+ */
+
+#include <stdio.h>
+#include <stdbool.h>
+#include "util.h"
+#include "debug.h"
+#include "eeprom_stm32.h"
+#include "flash_stm32.h"
+
+/*
+ * We emulate eeprom by writing a snapshot compacted view of eeprom contents,
+ * followed by a write log of any change since that snapshot:
+ *
+ * === SIMULATED EEPROM CONTENTS ===
+ *
+ * ┌─ Compacted ┬ Write Log ─┐
+ * │............│[BYTE][BYTE]│
+ * │FFFF....FFFF│[WRD0][WRD1]│
+ * │FFFFFFFFFFFF│[WORD][NEXT]│
+ * │....FFFFFFFF│[BYTE][WRD0]│
+ * ├────────────┼────────────┤
+ * └──PAGE_BASE │            │
+ *    PAGE_LAST─┴─WRITE_BASE │
+ *                WRITE_LAST ┘
+ *
+ * Compacted contents are the 1's complement of the actual EEPROM contents.
+ * e.g. An 'FFFF' represents a '0000' value.
+ *
+ * The size of the 'compacted' area is equal to the size of the 'emulated' eeprom.
+ * The size of the compacted-area and write log are configurable, and the combined
+ * size of Compacted + WriteLog is a multiple FEE_PAGE_SIZE, which is MCU dependent.
+ * Simulated Eeprom contents are located at the end of available flash space.
+ *
+ * The following configuration defines can be set:
+ *
+ * FEE_PAGE_COUNT   # Total number of pages to use for eeprom simulation (Compact + Write log)
+ * FEE_DENSITY_BYTES   # Size of simulated eeprom. (Defaults to half the space allocated by FEE_PAGE_COUNT)
+ * NOTE: The current implementation does not include page swapping,
+ * and FEE_DENSITY_BYTES will consume that amount of RAM as a cached view of actual EEPROM contents.
+ *
+ * The maximum size of FEE_DENSITY_BYTES is currently 16384. The write log size equals
+ * FEE_PAGE_COUNT * FEE_PAGE_SIZE - FEE_DENSITY_BYTES.
+ * The larger the write log, the less frequently the compacted area needs to be rewritten.
+ *
+ *
+ * *** General Algorithm ***
+ *
+ * During initialization:
+ * The contents of the Compacted-flash area are loaded and the 1's complement value
+ * is cached into memory (e.g. 0xFFFF in Flash represents 0x0000 in cache).
+ * Write log entries are processed until a 0xFFFF is reached.
+ * Each log entry updates a byte or word in the cache.
+ *
+ * During reads:
+ * EEPROM contents are given back directly from the cache in memory.
+ *
+ * During writes:
+ * The contents of the cache is updated first.
+ * If the Compacted-flash area corresponding to the write address is unprogrammed, the 1's complement of the value is written directly into Compacted-flash
+ * Otherwise:
+ * If the write log is full, erase both the Compacted-flash area and the Write log, then write cached contents to the Compacted-flash area.
+ * Otherwise a Write log entry is constructed and appended to the next free position in the Write log.
+ *
+ *
+ * *** Write Log Structure ***
+ *
+ * Write log entries allow for optimized byte writes to addresses below 128. Writing 0 or 1 words are also optimized when word-aligned.
+ *
+ * === WRITE LOG ENTRY FORMATS ===
+ *
+ * ╔═══ Byte-Entry ══╗
+ * ║0XXXXXXX║YYYYYYYY║
+ * ║ └──┬──┘║└──┬───┘║
+ * ║ Address║ Value  ║
+ * ╚════════╩════════╝
+ * 0 <= Address < 0x80 (128)
+ *
+ * ╔ Word-Encoded 0 ╗
+ * ║100XXXXXXXXXXXXX║
+ * ║  │└─────┬─────┘║
+ * ║  │Address >> 1 ║
+ * ║  └── Value: 0  ║
+ * ╚════════════════╝
+ * 0 <= Address <= 0x3FFE (16382)
+ *
+ * ╔ Word-Encoded 1 ╗
+ * ║101XXXXXXXXXXXXX║
+ * ║  │└─────┬─────┘║
+ * ║  │Address >> 1 ║
+ * ║  └── Value: 1  ║
+ * ╚════════════════╝
+ * 0 <= Address <= 0x3FFE (16382)
+ *
+ * ╔═══ Reserved ═══╗
+ * ║110XXXXXXXXXXXXX║
+ * ╚════════════════╝
+ *
+ * ╔═══════════ Word-Next ═══════════╗
+ * ║111XXXXXXXXXXXXX║YYYYYYYYYYYYYYYY║
+ * ║   └─────┬─────┘║└───────┬──────┘║
+ * ║(Address-128)>>1║     ~Value     ║
+ * ╚════════════════╩════════════════╝
+ * (  0 <= Address <  0x0080 (128): Reserved)
+ * 0x80 <= Address <= 0x3FFE (16382)
+ *
+ * Write Log entry ranges:
+ * 0x0000 ... 0x7FFF - Byte-Entry;     address is (Entry & 0x7F00) >> 4; value is (Entry & 0xFF)
+ * 0x8000 ... 0x9FFF - Word-Encoded 0; address is (Entry & 0x1FFF) << 1; value is 0
+ * 0xA000 ... 0xBFFF - Word-Encoded 1; address is (Entry & 0x1FFF) << 1; value is 1
+ * 0xC000 ... 0xDFFF - Reserved
+ * 0xE000 ... 0xFFBF - Word-Next;      address is (Entry & 0x1FFF) << 1 + 0x80; value is ~(Next_Entry)
+ * 0xFFC0 ... 0xFFFE - Reserved
+ * 0xFFFF            - Unprogrammed
+ *
+ */
+
+#include "eeprom_stm32_defs.h"
+#if !defined(FEE_PAGE_SIZE) || !defined(FEE_PAGE_COUNT) || !defined(FEE_MCU_FLASH_SIZE) || !defined(FEE_PAGE_BASE_ADDRESS)
+#    error "not implemented."
+#endif
+
+/* These bits are used for optimizing encoding of bytes, 0 and 1 */
+#define FEE_WORD_ENCODING 0x8000
+#define FEE_VALUE_NEXT 0x6000
+#define FEE_VALUE_RESERVED 0x4000
+#define FEE_VALUE_ENCODED 0x2000
+#define FEE_BYTE_RANGE 0x80
+
+/* Addressable range 16KByte: 0 <-> (0x1FFF << 1) */
+#define FEE_ADDRESS_MAX_SIZE 0x4000
+
+/* Flash word value after erase */
+#define FEE_EMPTY_WORD ((uint16_t)0xFFFF)
+
+/* Size of combined compacted eeprom and write log pages */
+#define FEE_DENSITY_MAX_SIZE (FEE_PAGE_COUNT * FEE_PAGE_SIZE)
+
+#ifndef FEE_MCU_FLASH_SIZE_IGNORE_CHECK /* *TODO: Get rid of this check */
+#    if FEE_DENSITY_MAX_SIZE > (FEE_MCU_FLASH_SIZE * 1024)
+#        pragma message STR(FEE_DENSITY_MAX_SIZE) " > " STR(FEE_MCU_FLASH_SIZE * 1024)
+#        error emulated eeprom: FEE_DENSITY_MAX_SIZE is greater than available flash size
+#    endif
+#endif
+
+/* Size of emulated eeprom */
+#ifdef FEE_DENSITY_BYTES
+#    if (FEE_DENSITY_BYTES > FEE_DENSITY_MAX_SIZE)
+#        pragma message STR(FEE_DENSITY_BYTES) " > " STR(FEE_DENSITY_MAX_SIZE)
+#        error emulated eeprom: FEE_DENSITY_BYTES exceeds FEE_DENSITY_MAX_SIZE
+#    endif
+#    if (FEE_DENSITY_BYTES == FEE_DENSITY_MAX_SIZE)
+#        pragma message STR(FEE_DENSITY_BYTES) " == " STR(FEE_DENSITY_MAX_SIZE)
+#        warning emulated eeprom: FEE_DENSITY_BYTES leaves no room for a write log.  This will greatly increase the flash wear rate!
+#    endif
+#    if FEE_DENSITY_BYTES > FEE_ADDRESS_MAX_SIZE
+#        pragma message STR(FEE_DENSITY_BYTES) " > " STR(FEE_ADDRESS_MAX_SIZE)
+#        error emulated eeprom: FEE_DENSITY_BYTES is greater than FEE_ADDRESS_MAX_SIZE allows
+#    endif
+#    if ((FEE_DENSITY_BYTES) % 2) == 1
+#        error emulated eeprom: FEE_DENSITY_BYTES must be even
+#    endif
+#else
+/* Default to half of allocated space used for emulated eeprom, half for write log */
+#    define FEE_DENSITY_BYTES (FEE_PAGE_COUNT * FEE_PAGE_SIZE / 2)
+#endif
+
+/* Size of write log */
+#ifdef FEE_WRITE_LOG_BYTES
+#    if ((FEE_DENSITY_BYTES + FEE_WRITE_LOG_BYTES) > FEE_DENSITY_MAX_SIZE)
+#        pragma message STR(FEE_DENSITY_BYTES) " + " STR(FEE_WRITE_LOG_BYTES) " > " STR(FEE_DENSITY_MAX_SIZE)
+#        error emulated eeprom: FEE_WRITE_LOG_BYTES exceeds remaining FEE_DENSITY_MAX_SIZE
+#    endif
+#    if ((FEE_WRITE_LOG_BYTES) % 2) == 1
+#        error emulated eeprom: FEE_WRITE_LOG_BYTES must be even
+#    endif
+#else
+/* Default to use all remaining space */
+#    define FEE_WRITE_LOG_BYTES (FEE_PAGE_COUNT * FEE_PAGE_SIZE - FEE_DENSITY_BYTES)
+#endif
+
+/* Start of the emulated eeprom compacted flash area */
+#define FEE_COMPACTED_BASE_ADDRESS FEE_PAGE_BASE_ADDRESS
+/* End of the emulated eeprom compacted flash area */
+#define FEE_COMPACTED_LAST_ADDRESS (FEE_COMPACTED_BASE_ADDRESS + FEE_DENSITY_BYTES)
+/* Start of the emulated eeprom write log */
+#define FEE_WRITE_LOG_BASE_ADDRESS FEE_COMPACTED_LAST_ADDRESS
+/* End of the emulated eeprom write log */
+#define FEE_WRITE_LOG_LAST_ADDRESS (FEE_WRITE_LOG_BASE_ADDRESS + FEE_WRITE_LOG_BYTES)
+
+#if defined(DYNAMIC_KEYMAP_EEPROM_MAX_ADDR) && (DYNAMIC_KEYMAP_EEPROM_MAX_ADDR >= FEE_DENSITY_BYTES)
+#    error emulated eeprom: DYNAMIC_KEYMAP_EEPROM_MAX_ADDR is greater than the FEE_DENSITY_BYTES available
+#endif
+
+/* In-memory contents of emulated eeprom for faster access */
+/* *TODO: Implement page swapping */
+static uint16_t WordBuf[FEE_DENSITY_BYTES / 2];
+static uint8_t *DataBuf = (uint8_t *)WordBuf;
+
+/* Pointer to the first available slot within the write log */
+static uint16_t *empty_slot;
+
+// #define DEBUG_EEPROM_OUTPUT
+
+/*
+ * Debug print utils
+ */
+
+#if defined(DEBUG_EEPROM_OUTPUT)
+
+#    define debug_eeprom debug_enable
+#    define eeprom_println(s) println(s)
+#    define eeprom_printf(fmt, ...) xprintf(fmt, ##__VA_ARGS__);
+
+#else /* NO_DEBUG */
+
+#    define debug_eeprom false
+#    define eeprom_println(s)
+#    define eeprom_printf(fmt, ...)
+
+#endif /* NO_DEBUG */
+
+void print_eeprom(void) {
+#ifndef NO_DEBUG
+    int empty_rows = 0;
+    for (uint16_t i = 0; i < FEE_DENSITY_BYTES; i++) {
+        if (i % 16 == 0) {
+            if (i >= FEE_DENSITY_BYTES - 16) {
+                /* Make sure we display the last row */
+                empty_rows = 0;
+            }
+            /* Check if this row is uninitialized */
+            ++empty_rows;
+            for (uint16_t j = 0; j < 16; j++) {
+                if (DataBuf[i + j]) {
+                    empty_rows = 0;
+                    break;
+                }
+            }
+            if (empty_rows > 1) {
+                /* Repeat empty row */
+                if (empty_rows == 2) {
+                    /* Only display the first repeat empty row */
+                    println("*");
+                }
+                i += 15;
+                continue;
+            }
+            xprintf("%04x", i);
+        }
+        if (i % 8 == 0) print(" ");
+
+        xprintf(" %02x", DataBuf[i]);
+        if ((i + 1) % 16 == 0) {
+            println("");
+        }
+    }
+#endif
+}
+
+uint16_t EEPROM_Init(void) {
+    /* Load emulated eeprom contents from compacted flash into memory */
+    uint16_t *src  = (uint16_t *)FEE_COMPACTED_BASE_ADDRESS;
+    uint16_t *dest = (uint16_t *)DataBuf;
+    for (; src < (uint16_t *)FEE_COMPACTED_LAST_ADDRESS; ++src, ++dest) {
+        *dest = ~*src;
+    }
+
+    if (debug_eeprom) {
+        println("EEPROM_Init Compacted Pages:");
+        print_eeprom();
+        println("EEPROM_Init Write Log:");
+    }
+
+    /* Replay write log */
+    uint16_t *log_addr;
+    for (log_addr = (uint16_t *)FEE_WRITE_LOG_BASE_ADDRESS; log_addr < (uint16_t *)FEE_WRITE_LOG_LAST_ADDRESS; ++log_addr) {
+        uint16_t address = *log_addr;
+        if (address == FEE_EMPTY_WORD) {
+            break;
+        }
+        /* Check for lowest 128-bytes optimization */
+        if (!(address & FEE_WORD_ENCODING)) {
+            uint8_t bvalue = (uint8_t)address;
+            address >>= 8;
+            DataBuf[address] = bvalue;
+            eeprom_printf("DataBuf[0x%02x] = 0x%02x;\n", address, bvalue);
+        } else {
+            uint16_t wvalue;
+            /* Check if value is in next word */
+            if ((address & FEE_VALUE_NEXT) == FEE_VALUE_NEXT) {
+                /* Read value from next word */
+                if (++log_addr >= (uint16_t *)FEE_WRITE_LOG_LAST_ADDRESS) {
+                    break;
+                }
+                wvalue = ~*log_addr;
+                if (!wvalue) {
+                    eeprom_printf("Incomplete write at log_addr: 0x%04x;\n", (uint32_t)log_addr);
+                    /* Possibly incomplete write.  Ignore and continue */
+                    continue;
+                }
+                address &= 0x1FFF;
+                address <<= 1;
+                /* Writes to addresses less than 128 are byte log entries */
+                address += FEE_BYTE_RANGE;
+            } else {
+                /* Reserved for future use */
+                if (address & FEE_VALUE_RESERVED) {
+                    eeprom_printf("Reserved encoded value at log_addr: 0x%04x;\n", (uint32_t)log_addr);
+                    continue;
+                }
+                /* Optimization for 0 or 1 values. */
+                wvalue = (address & FEE_VALUE_ENCODED) >> 13;
+                address &= 0x1FFF;
+                address <<= 1;
+            }
+            if (address < FEE_DENSITY_BYTES) {
+                eeprom_printf("DataBuf[0x%04x] = 0x%04x;\n", address, wvalue);
+                *(uint16_t *)(&DataBuf[address]) = wvalue;
+            } else {
+                eeprom_printf("DataBuf[0x%04x] cannot be set to 0x%04x [BAD ADDRESS]\n", address, wvalue);
+            }
+        }
+    }
+
+    empty_slot = log_addr;
+
+    if (debug_eeprom) {
+        println("EEPROM_Init Final DataBuf:");
+        print_eeprom();
+    }
+
+    return FEE_DENSITY_BYTES;
+}
+
+/* Clear flash contents (doesn't touch in-memory DataBuf) */