[all] Refactor project

Author: AlexLanzano

.claude/skills/port-stm32-platform/SKILL.md

@@ -51,6 +51,8 @@ For each device type, decide **reuse existing driver (with alias)** OR **write a
 
 The clock driver is almost always new per family. GPIO, I2C, and IWDG/WWDG are almost always reusable. UART, flash, RNG, DMA require careful diffing.
 
+**Clock is the architectural exception.** Unlike every other driver type, the clock subsystem has no `whal_ClockDriver` vtable and no generic `whal_Clock_Init`/`Enable`/`Disable` API. Chip clock drivers expose imperative `Enable*`/`Disable*`/`Set*` helpers (e.g. `whal_<Platform>_Rcc_EnableOsc`, `EnablePll`, `SetSysClock`, `EnablePeriphClk`) and boards call them directly. See `docs/writing_a_driver.md` "Clock" section. The platform header does NOT define a `WHAL_<PLATFORM>_RCC_DRIVER` macro, and the chip's `g_whalClock` global has only `.regmap = { ... }` — no `.driver`, no `.cfg`. Reference: `wolfHAL/clock/stm32wb_rcc.h` and `boards/stm32wb55xx_nucleo/board.c`.
+
 ## Phase 2 — Platform header
 
 Create `wolfHAL/platform/st/<chip>.h` (e.g., `stm32g431cb.h`). Reference: `stm32wba55cg.h` (GPDMA chip) or `stm32wb55xx.h` (DMA+DMAMUX chip).
@@ -88,9 +90,9 @@ Skeleton:
 1. Read `docs/writing_a_driver.md` for the driver pattern.
 2. Copy the closest existing driver as a starting point.
 3. Update register offsets, bit positions, and sequences per the TRM. **Cross-check register-map diagrams against the textual bit descriptions** — they sometimes disagree, and the textual description is authoritative.
-4. Match the existing naming: `whal_<Platform><Type>_<Func>` for functions, `whal_<Platform><Type>_Driver` for the vtable, `whal_<Platform><Type>_Cfg` for the config struct.
+4. Match the existing naming: `whal_<Platform><Type>_<Func>` for functions, `whal_<Platform><Type>_Driver` for the vtable, `whal_<Platform><Type>_Cfg` for the config struct. **Exception: the clock driver has no vtable and no `_Driver` symbol** — its public API is the imperative `Enable*`/`Disable*`/`Set*` helpers. See `docs/writing_a_driver.md` "Clock".
 5. Place files at `wolfHAL/<type>/<platform>_<type>.h` and `src/<type>/<platform>_<type>.c`.
-6. Do not add cross-driver calls from inside a driver — clock enables, power sequencing, flash wait states, pin muxing are the board's responsibility.
+6. Do not add cross-driver calls from inside a driver — clock enables, power sequencing, flash wait states, pin muxing are the board's responsibility. Boards toggle peripheral clocks via the chip clock driver's `whal_<Platform>_Rcc_EnablePeriphClk(&g_whalClock, &gateDescriptor)` (or chip-equivalent name).
 
 ### For each device type marked "reuse existing driver" — create an alias header + stub .c
 
@@ -186,13 +188,13 @@ Create `boards/<board_name>/` with:
 Exports `extern whal_<Type>` instances and declares `Board_Init`/`Board_Deinit`/`Board_WaitMs`. Follow `docs/adding_a_board.md`.
 
 ### `board.c`
-Define each `whal_<Type>` global with its platform macro + board-specific config (pins, baud rates, timeout, DMA channel assignments). Implement `Board_Init` in dependency order: PWR → Clock → peripheral clock enables → GPIO → UART → Timer → the rest. Keep the watchdog out of `Board_Init` (the app starts it when ready to refresh) per `docs/adding_a_board.md`. Guard DMA-specific setup under `#ifdef BOARD_DMA`, matching `boards/stm32wba55cg_nucleo/board.c`.
+Define each `whal_<Type>` global with its platform macro + board-specific config (pins, baud rates, timeout, DMA channel assignments). The `whal_Clock` global is just `.regmap = { ... }` (no `.driver`, no `.cfg`) since the clock subsystem has no vtable. Implement `Board_Init` in dependency order: PWR → bring up clock tree imperatively (oscillator on, PLL configure+enable, sysclk switch) → enable peripheral clocks → GPIO → UART → Timer → the rest. Keep the watchdog out of `Board_Init` (the app starts it when ready to refresh) per `docs/adding_a_board.md`. Guard DMA-specific setup under `#ifdef BOARD_DMA`, matching `boards/stm32wba55cg_nucleo/board.c`.
 
 ### GPIO pin conflict check
 After writing the `pinCfg` array in `board.c`, scan every entry pair and verify no two entries share the same physical port+pin. This is a common mistake when a pin serves double duty (e.g., PA5 used as both an LED and SPI1_SCK). If a conflict is found, consult the chip's alternate-function table in the datasheet and remap the conflicting peripheral to an alternate pin on a different port.
 
-### `Makefile.inc`
-Model on `boards/stm32wba55cg_nucleo/Makefile.inc`:
+### `board.mk`
+Model on `boards/stm32wba55cg_nucleo/board.mk`:
 - `PLATFORM = <platform>` — matches the prefix used in `src/*/<platform>_*.c`
 - `TESTS ?= clock gpio flash timer rng crypto uart spi i2c irq` — trim to what the board supports
 - `CFLAGS` — `-mcpu=cortex-m4`/`cortex-m33` to match the core, `-DPLATFORM_<UPPER>` for platform ifdefs

boards/README.md

@@ -29,20 +29,20 @@ build configuration.
 
 Each board directory contains:
 
-- **`Makefile.inc`** - Build configuration: toolchain, CPU flags, platform
+- **`board.mk`** - Build configuration: toolchain, CPU flags, platform
   drivers, and linker script. Included by application Makefiles via
-  `include $(BOARD_DIR)/Makefile.inc`.
+  `include $(BOARD_DIR)/board.mk`.
 - **`board.h`** - Board-level declarations: global peripheral instances,
   pin definitions, and `Board_Init()`/`Board_Deinit()` prototypes.
 - **`board.c`** - Peripheral instantiation and `Board_Init()` implementation
-  (supply, clock, GPIO, UART, flash, timer).
+  (power, clock, GPIO, UART, flash, timer).
 - **`linker.ld`** - Linker script defining memory regions (flash, RAM).
 - Any additional board-specific source files (e.g. interrupt vector table,
   architecture-specific startup code).
 
-## Makefile.inc Convention
+## board.mk Convention
 
-Board `Makefile.inc` files use a self-referencing pattern so that they can be
+Board `board.mk` files use a self-referencing pattern so that they can be
 included from any directory:
 
 ```makefile
@@ -52,11 +52,11 @@ _BOARD_DIR := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
 `_BOARD_DIR` points to the board's own directory, while the application
 Makefile sets `BOARD_DIR` which may point elsewhere (e.g. a private board
 overlay). This enables private repositories to extend a board by including
-the base `Makefile.inc` and adding additional sources.
+the base `board.mk` and adding additional sources.
 
 ### What `BOARD_SOURCE` includes
 
-Board `Makefile.inc` populates `BOARD_SOURCE` with all of the sources
+Board `board.mk` populates `BOARD_SOURCE` with all of the sources
 required to build the wolfHAL tests and sample applications for that board:
 
 - Board files: `board.c` and any additional board-specific source files
@@ -66,13 +66,13 @@ required to build the wolfHAL tests and sample applications for that board:
   `gpio.c`, `clock.c`, `uart.c`, and other files under `src/*.c`
 
 In your own projects you may either reuse these defaults by including the
-board `Makefile.inc` as-is, or define your own `BOARD_SOURCE` in your
+board `board.mk` as-is, or define your own `BOARD_SOURCE` in your
 application Makefile to select a different set of modules.
 
 ## Adding a New Board
 
 1. Create a new directory: `boards/<vendor>_<board>/`
-2. Add `Makefile.inc` following the `_BOARD_DIR` pattern above
+2. Add `board.mk` following the `_BOARD_DIR` pattern above
 3. Implement `board.h`, `board.c`, and `linker.ld`
 4. Set `PLATFORM`, `TESTS`, toolchain variables, `CFLAGS`, and `BOARD_SOURCE`
 5. Build with `make BOARD=<your_board>`

boards/peripheral/Makefile.inc boards/peripheral/board.mkboards/peripheral/Makefile.inc renamed to boards/peripheral/board.mk

@@ -6,50 +6,18 @@
 #include <wolfHAL/platform/microchip/pic32cz.h>
 #include "peripheral.h"
 
-/* Supply */
-static whal_Supply g_whalSupply = {
-    .regmap = { WHAL_PIC32CZ_SUPPLY_REGMAP },
-    /* .driver: direct API mapping */
+/* Power */
+static whal_Power g_whalPower = {
+    .regmap = { WHAL_PIC32CZ_SUPC_REGMAP },
 };
 
 /* Clock */
 whal_Clock g_whalClock = {
-    .regmap = { WHAL_PIC32CZ_CLOCK_PLL_REGMAP },
-    /* .driver: direct API mapping */
-
-    .cfg = &(whal_Pic32czClock_Cfg) {
-        /* 300MHz clock */
-        .oscCtrlCfg = &(whal_Pic32czClockPll_OscCtrlCfg) {
-            .pllInst = WHAL_PIC32CZ_PLL0,
-            .refSel = WHAL_PIC32CZ_REFSEL_DFLL48M,
-            .bwSel = WHAL_PIC32CZ_BWSEL_10MHz_TO_20MHz,
-
-            .fbDiv = 225,
-            .refDiv = 12,
-
-            .outCfgCount = 1,
-            .outCfg = &(whal_Pic32czClockPll_OutCfg) {
-                .postDivMask = WHAL_PIC32CZ_POSTDIV0_Msk,
-                .postDivPos = WHAL_PIC32CZ_POSTDIV0_Pos,
-                .outEnMask = WHAL_PIC32CZ_OUTEN0_Msk,
-                .outEnPos = WHAL_PIC32CZ_OUTEN0_Pos,
-                .postDiv = 3,
-            },
-        },
-        .mclkCfg = &(whal_Pic32czClock_MclkCfg) {
-            .div = 2,
-        },
-        .gclkCfgCount = 1,
-        .gclkCfg = &(whal_Pic32czClock_GclkCfg) {
-            .gen = 0,
-            .genSrc = WHAL_PIC32CZ_GENSRC_PLL0_CLOCKOUT0,
-            .genDiv = 1,
-        },
-    },
+    .regmap = { WHAL_PIC32CZ_CLOCK_REGMAP },
 };
 
 /* Peripheral clocks */
-static const whal_Pic32czClock_Clk g_peripheralClocks[] = {
+static const whal_Pic32cz_Clock_PeriphClk g_periphClks[] = {
     { /* SERCOM 4 (UART) */
         .gclkPeriphChannel = 25,
         .gclkPeriphSrc = 0, /* GEN 0 */
@@ -58,16 +26,16 @@ static const whal_Pic32czClock_Clk g_peripheralClocks[] = {
         .mclkEnablePos = 3,
     },
 };
-#define CLOCK_COUNT (sizeof(g_peripheralClocks) / sizeof(g_peripheralClocks[0]))
+#define PERIPH_CLK_COUNT (sizeof(g_periphClks) / sizeof(g_periphClks[0]))
 
 /* GPIO */
 whal_Gpio g_whalGpio = {
     .regmap = { WHAL_PIC32CZ_GPIO_REGMAP },
     /* .driver: direct API mapping */
 
-    .cfg = &(whal_Pic32czGpio_Cfg) {
+    .cfg = &(whal_Pic32cz_Gpio_Cfg) {
         .pinCfgCount = 3,
-        .pinCfg = (whal_Pic32czGpio_PinCfg[]) {
+        .pinCfg = (whal_Pic32cz_Gpio_PinCfg[]) {
             { /* LED */
                 .port = 1,
                 .pin = 21,
@@ -95,7 +63,7 @@ whal_Uart g_whalUart = {
     .regmap = { WHAL_PIC32CZ_SERCOM4_UART_REGMAP },
     /* .driver: direct API mapping */
 
-    .cfg = &(whal_Pic32czUart_Cfg) {
+    .cfg = &(whal_Pic32cz_Uart_Cfg) {
         .baud = WHAL_PIC32CZ_UART_BAUD(115200, 300000000),
         .txPad = WHAL_PIC32CZ_UART_TXPO_PAD0,
         .rxPad = WHAL_PIC32CZ_UART_RXPO_PAD1,
@@ -157,26 +125,46 @@ whal_Error Board_Init(void)
 {
     whal_Error err;
 
-    err = whal_Supply_Init(&g_whalSupply);
-    if (err) {
-        return err;
-    }
-
     /* Enable PLL power supply before clock init */
-    err = whal_Supply_Enable(&g_whalSupply,
-                             &(whal_Pic32czSupc_Supply){WHAL_PIC32CZ_SUPPLY_PLL});
-    if (err) {
+    err = whal_Pic32cz_Supc_EnableSupply(&g_whalPower,
+            &(whal_Pic32cz_Supc_Supply){WHAL_PIC32CZ_SUPC_PLL});
+    if (err) {
+        return err;
+    }
+
+    /* PLL0: DFLL48 / 12 * 225 / 3 = 300 MHz, then GCLK0 from PLL0 OUT0,
+     * then MCLK CPU divider /2 = 150 MHz CPU. */
+    err = whal_Pic32cz_Clock_EnablePll(&g_whalClock, &(whal_Pic32cz_Clock_PllCfg){
+        .pllInst = WHAL_PIC32CZ_PLL0,
+        .refSel = WHAL_PIC32CZ_REFSEL_DFLL48M,
+        .bwSel = WHAL_PIC32CZ_BWSEL_10MHz_TO_20MHz,
+        .fbDiv = 225,
+        .refDiv = 12,
+        .outCfgCount = 1,
+        .outCfg = &(whal_Pic32cz_Clock_PllOutCfg){
+            .postDivMask = WHAL_PIC32CZ_POSTDIV0_Msk,
+            .postDivPos  = WHAL_PIC32CZ_POSTDIV0_Pos,
+            .outEnMask   = WHAL_PIC32CZ_OUTEN0_Msk,
+            .outEnPos    = WHAL_PIC32CZ_OUTEN0_Pos,
+            .postDiv = 3,
+        },
+    });
+    if (err)
         return err;
-    }
-
-    err = whal_Clock_Init(&g_whalClock);
-    if (err) {
+    err = whal_Pic32cz_Clock_SetMclkDiv(&g_whalClock, 2);
+    if (err)
+        return err;
+    err = whal_Pic32cz_Clock_EnableGclkGen(&g_whalClock, &(whal_Pic32cz_Clock_GenCfg){
+        .gen = 0,
+        .genSrc = WHAL_PIC32CZ_GENSRC_PLL0_CLOCKOUT0,
+        .genDiv = 1,
+    });
+    if (err)
         return err;
-    }
 
     /* Enable peripheral clocks */
-    for (size_t i = 0; i < CLOCK_COUNT; i++) {
-        err = whal_Clock_Enable(&g_whalClock, &g_peripheralClocks[i]);
+    for (size_t i = 0; i < PERIPH_CLK_COUNT; i++) {
+        err = whal_Pic32cz_Clock_EnablePeriphClk(&g_whalClock, &g_periphClks[i]);
         if (err)
             return err;
     }
@@ -249,21 +237,13 @@ whal_Error Board_Deinit(void)
     }
 
     /* Disable peripheral clocks */
-    for (size_t i = 0; i < CLOCK_COUNT; i++) {
-        err = whal_Clock_Disable(&g_whalClock, &g_peripheralClocks[i]);
+    for (size_t i = 0; i < PERIPH_CLK_COUNT; i++) {
+        err = whal_Pic32cz_Clock_DisablePeriphClk(&g_whalClock, &g_periphClks[i]);
         if (err)
             return err;
     }
 
-    err = whal_Clock_Deinit(&g_whalClock);
-    if (err) {
-        return err;
-    }
-
-    err = whal_Supply_Deinit(&g_whalSupply);
-    if (err) {
-        return err;
-    }
+    /* SUPC outputs are left as-is; no Deinit operation. */
 
     return WHAL_SUCCESS;
 }

boards/pic32cz_curiosity_ultra/board.c

@@ -1,7 +1,7 @@
 _BOARD_DIR := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
 
 PLATFORM = pic32cz
-TESTS ?= clock gpio flash timer supply uart
+TESTS ?= clock gpio flash timer uart
 
 GCC = $(GCC_PATH)arm-none-eabi-gcc
 LD = $(GCC_PATH)arm-none-eabi-ld
@@ -10,10 +10,9 @@ OBJCOPY = $(GCC_PATH)arm-none-eabi-objcopy
 CFLAGS += -Wall -Werror $(INCLUDE) -g3 \
           -ffreestanding -nostdlib -mcpu=cortex-m7 \
           -DPLATFORM_PIC32CZ -MMD -MP \
-          -DWHAL_CFG_GPIO_API_MAPPING_PIC32CZ \
-          -DWHAL_CFG_CLOCK_API_MAPPING_PIC32CZ_PLL \
-          -DWHAL_CFG_UART_API_MAPPING_PIC32CZ \
-          -DWHAL_CFG_SUPPLY_API_MAPPING_PIC32CZ
+          -DWHAL_CFG_PIC32CZ_GPIO_DIRECT_API_MAPPING \
+          -DWHAL_CFG_PIC32CZ_CLOCK_DIRECT_API_MAPPING \
+          -DWHAL_CFG_PIC32CZ_UART_DIRECT_API_MAPPING
 LDFLAGS = --omagic -static
 
 LINKER_SCRIPT ?= $(_BOARD_DIR)/linker.ld
@@ -32,4 +31,4 @@ BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/pic32cz_*.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/systick.c)
 
 # Peripheral devices
-include $(WHAL_DIR)/boards/peripheral/Makefile.inc
+include $(WHAL_DIR)/boards/peripheral/board.mk