[spi_nor, boards, tests, docs] Add SPI-NOR flash driver. Add W25Q64 peripheral.

.github/workflows/ci.yml

@@ -45,6 +45,7 @@ jobs:
       matrix:
         source:
           - src/block/sdhc_spi.c
+          - src/flash/spi_nor.c
     steps:
       - uses: actions/checkout@v4
 

README.md

@@ -23,6 +23,7 @@ tests/                      Test framework and test suites
 - [Tests](tests/README.md) — Test framework and test suites
 - [Writing a Driver](docs/writing_a_driver.md) — How to implement a driver for a new platform
 - [Adding a Board](docs/adding_a_board.md) — How to add a new board configuration
+- [Adding a Peripheral](docs/adding_a_peripheral.md) — How to add an external peripheral device
 - [Adding an Example](docs/adding_an_example.md) — How to add a new example application
 - [Adding a Test](docs/adding_a_test.md) — How to add hardware tests
 

boards/peripheral/Makefile.inc

@@ -7,3 +7,9 @@ CFLAGS += -DPERIPHERAL_SDHC_SPI_SDCARD32GB
 BOARD_SOURCE += $(_PERIPHERAL_DIR)/block/sdhc_spi_sdcard32gb.c
 BOARD_SOURCE += $(WHAL_DIR)/src/block/sdhc_spi.c
 endif
+
+ifdef PERIPHERAL_SPI_NOR_W25Q64
+CFLAGS += -DPERIPHERAL_SPI_NOR_W25Q64
+BOARD_SOURCE += $(_PERIPHERAL_DIR)/flash/spi_nor_w25q64.c
+BOARD_SOURCE += $(WHAL_DIR)/src/flash/spi_nor.c
+endif

boards/peripheral/flash/spi_nor_w25q64.c

@@ -0,0 +1,35 @@
+#include "spi_nor_w25q64.h"
+#include <wolfHAL/flash/spi_nor.h>
+#include "board.h"
+
+/*
+ * Winbond W25Q64 — 64 Mbit (8 MB) SPI-NOR Flash
+ *
+ * - Page size:   256 bytes
+ * - Sector size: 4 KB (smallest erasable unit)
+ * - Capacity:    8,388,608 bytes (8 MB)
+ * - SPI modes 0 and 3, up to 104 MHz (standard read up to 50 MHz)
+ */
+
+#define W25Q64_PAGE_SZ  256
+#define W25Q64_CAPACITY (8 * 1024 * 1024) /* 8 MB */
+
+static whal_Spi_ComCfg g_w25q64ComCfg = {
+    .freq = 25000000, /* 25 MHz */
+    .mode = WHAL_SPI_MODE_0,
+    .wordSz = 8,
+    .dataLines = 1,
+};
+
+whal_Flash g_whalSpiNorW25q64 = {
+    .driver = &whal_SpiNor_Driver,
+    .cfg = &(whal_SpiNor_Cfg) {
+        .spiDev = &g_whalSpi,
+        .spiComCfg = &g_w25q64ComCfg,
+        .gpioDev = &g_whalGpio,
+        .csPin = SPI_CS_PIN,
+        .timeout = &g_whalTimeout,
+        .pageSz = W25Q64_PAGE_SZ,
+        .capacity = W25Q64_CAPACITY,
+    },
+};

boards/peripheral/flash/spi_nor_w25q64.h

@@ -0,0 +1,10 @@
+#ifndef BOARD_SPI_NOR_W25Q64_H
+#define BOARD_SPI_NOR_W25Q64_H
+
+#include <wolfHAL/wolfHAL.h>
+#include <wolfHAL/flash/flash.h>
+#include <wolfHAL/flash/spi_nor.h>
+
+extern whal_Flash g_whalSpiNorW25q64;
+
+#endif /* BOARD_SPI_NOR_W25Q64_H */

boards/peripheral/peripheral.c

@@ -4,6 +4,10 @@
 #include "block/sdhc_spi_sdcard32gb.h"
 #endif
 
+#ifdef PERIPHERAL_SPI_NOR_W25Q64
+#include "flash/spi_nor_w25q64.h"
+#endif
+
 whal_PeripheralBlock_Cfg g_peripheralBlock[] = {
 #ifdef PERIPHERAL_SDHC_SPI_SDCARD32GB
     {
@@ -17,3 +21,52 @@ whal_PeripheralBlock_Cfg g_peripheralBlock[] = {
 #endif
     {0}, /* sentinel */
 };
+
+whal_PeripheralFlash_Cfg g_peripheralFlash[] = {
+#ifdef PERIPHERAL_SPI_NOR_W25Q64
+    {
+        .name = "spi_nor_w25q64",
+        .dev = &g_whalSpiNorW25q64,
+        .sectorSz = 4096,
+    },
+#endif
+    {0}, /* sentinel */
+};
+
+whal_Error Peripheral_Init(void)
+{
+    whal_Error err;
+
+    for (size_t i = 0; g_peripheralBlock[i].dev; i++) {
+        err = whal_Block_Init(g_peripheralBlock[i].dev);
+        if (err)
+            return err;
+    }
+
+    for (size_t i = 0; g_peripheralFlash[i].dev; i++) {
+        err = whal_Flash_Init(g_peripheralFlash[i].dev);
+        if (err)
+            return err;
+    }
+
+    return WHAL_SUCCESS;
+}
+
+whal_Error Peripheral_Deinit(void)
+{
+    whal_Error err;
+
+    for (size_t i = 0; g_peripheralFlash[i].dev; i++) {
+        err = whal_Flash_Deinit(g_peripheralFlash[i].dev);
+        if (err)
+            return err;
+    }
+
+    for (size_t i = 0; g_peripheralBlock[i].dev; i++) {
+        err = whal_Block_Deinit(g_peripheralBlock[i].dev);
+        if (err)
+            return err;
+    }
+
+    return WHAL_SUCCESS;
+}

boards/peripheral/peripheral.h

@@ -3,6 +3,7 @@
 
 #include <wolfHAL/wolfHAL.h>
 #include <wolfHAL/block/block.h>
+#include <wolfHAL/flash/flash.h>
 #include <stddef.h>
 #include <stdint.h>
 
@@ -16,6 +17,17 @@ typedef struct {
     uint8_t erasedByte;  /* Expected byte value after erase (0x00 or 0xFF) */
 } whal_PeripheralBlock_Cfg;
 
+/* Peripheral flash device test configuration */
+typedef struct {
+    const char *name;
+    whal_Flash *dev;
+    size_t sectorSz;     /* Sector (erase) size in bytes */
+} whal_PeripheralFlash_Cfg;
+
 extern whal_PeripheralBlock_Cfg g_peripheralBlock[];
+extern whal_PeripheralFlash_Cfg g_peripheralFlash[];
+
+whal_Error Peripheral_Init(void);
+whal_Error Peripheral_Deinit(void);
 
 #endif /* BOARD_PERIPHERAL_H */

boards/pic32cz_curiosity_ultra/Makefile.inc

@@ -14,7 +14,7 @@ LDFLAGS = --omagic -static
 
 LINKER_SCRIPT ?= $(_BOARD_DIR)/linker.ld
 
-INCLUDE += -I$(_BOARD_DIR)
+INCLUDE += -I$(_BOARD_DIR) -I$(WHAL_DIR)/boards/peripheral
 
 BOARD_SOURCE = $(_BOARD_DIR)/ivt.c
 BOARD_SOURCE += $(_BOARD_DIR)/board.c
@@ -29,3 +29,6 @@ BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/rng.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/block.c)
 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

boards/pic32cz_curiosity_ultra/board.c

@@ -4,6 +4,7 @@
 #include <stddef.h>
 #include "board.h"
 #include <wolfHAL/platform/microchip/pic32cz.h>
+#include "peripheral.h"
 
 /* Supply */
 static whal_Supply g_whalSupply = {
@@ -199,13 +200,23 @@ whal_Error Board_Init(void)
         return err;
     }
 
+    err = Peripheral_Init();
+    if (err) {
+        return err;
+    }
+
     return WHAL_SUCCESS;
 }
 
 whal_Error Board_Deinit(void)
 {
     whal_Error err;
 
+    err = Peripheral_Deinit();
+    if (err) {
+        return err;
+    }
+
     err = whal_Timer_Stop(&g_whalTimer);
     if (err) {
         return err;

boards/stm32wb55xx_nucleo/board.c

@@ -280,13 +280,6 @@ whal_Error Board_Init(void)
         return err;
     }
 
-    /* Initialize peripheral block devices */
-    for (size_t i = 0; g_peripheralBlock[i].dev; i++) {
-        err = whal_Block_Init(g_peripheralBlock[i].dev);
-        if (err)
-            return err;
-    }
-
     err = whal_Rng_Init(&g_whalRng);
     if (err) {
         return err;
@@ -307,13 +300,23 @@ whal_Error Board_Init(void)
         return err;
     }
 
+    err = Peripheral_Init();
+    if (err) {
+        return err;
+    }
+
     return WHAL_SUCCESS;
 }
 
 whal_Error Board_Deinit(void)
 {
     whal_Error err;
 
+    err = Peripheral_Deinit();
+    if (err) {
+        return err;
+    }
+
     err = whal_Timer_Stop(&g_whalTimer);
     if (err) {
         return err;
@@ -334,13 +337,6 @@ whal_Error Board_Deinit(void)
         return err;
     }
 
-    /* Deinitialize peripheral block devices */
-    for (size_t i = 0; g_peripheralBlock[i].dev; i++) {
-        err = whal_Block_Deinit(g_peripheralBlock[i].dev);
-        if (err)
-            return err;
-    }
-
     err = whal_Flash_Deinit(&g_whalFlash);
     if (err) {
         return err;

boards/stm32wb55xx_nucleo/linker.ld

@@ -54,9 +54,8 @@ _Min_Stack_Size = 0x500;   /* required amount of stack */
 /* Specify the memory areas */
 MEMORY
 {
-FLASH (rx)                 : ORIGIN = 0x08000000, LENGTH = 512K
-BOOTLOADER_MAGIC (rx)      : ORIGIN = 0x20000004, LENGTH = 0x4
-RAM1 (xrw)                 : ORIGIN = 0x20000008, LENGTH = 0x1ffc
+FLASH (rx) : ORIGIN = 0x08000000, LENGTH = 512K
+RAM1 (rwx) : ORIGIN = 0x20000000, LENGTH = 0x00030000
 }
 
 /* Define output sections */

docs/adding_a_board.md

@@ -49,6 +49,7 @@ on failure.
 ```c
 #include "board.h"
 #include <wolfHAL/platform/vendor/device.h>
+#include "peripheral.h"
 
 static whal_MyplatformGpio_PinCfg pinCfg[] = { /* ... */ };
 
@@ -99,13 +100,21 @@ whal_Error Board_Init(void)
     if (err)
         return err;
 
+    err = Peripheral_Init();
+    if (err)
+        return err;
+
     return WHAL_SUCCESS;
 }
 
 whal_Error Board_Deinit(void)
 {
     whal_Error err;
 
+    err = Peripheral_Deinit();
+    if (err)
+        return err;
+
     whal_Timer_Stop(&g_whalTimer);
     whal_Timer_Deinit(&g_whalTimer);
     whal_Uart_Deinit(&g_whalUart);
@@ -141,12 +150,41 @@ LDFLAGS = -mcpu=cortex-m4 -mthumb -nostdlib -lgcc
 
 LINKER_SCRIPT = $(_BOARD_DIR)/linker.ld
 
+INCLUDE += -I$(_BOARD_DIR) -I$(WHAL_DIR)/boards/peripheral
+
 BOARD_SOURCE  = $(_BOARD_DIR)/board.c
 BOARD_SOURCE += $(_BOARD_DIR)/ivt.c
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/myplatform_*.c)
 BOARD_SOURCE += $(WHAL_DIR)/src/timer/systick.c
+
+# Peripheral devices
+include $(WHAL_DIR)/boards/peripheral/Makefile.inc
 ```
 
+## Peripheral Devices
+
+Boards support optional external peripheral devices (e.g., SPI-NOR flash, SD
+cards) through the peripheral system in `boards/peripheral/`. To enable this:
+
+1. Include `peripheral.h` in `board.c` and add the peripheral include path
+   (`-I$(WHAL_DIR)/boards/peripheral`) in `Makefile.inc`.
+
+2. Include `boards/peripheral/Makefile.inc` at the end of the board's
+   `Makefile.inc`. This conditionally compiles peripheral drivers based on
+   build-time flags (e.g., `PERIPHERAL_SPI_NOR_W25Q64=1`).
+
+3. Call `Peripheral_Init()` at the end of `Board_Init()` and
+   `Peripheral_Deinit()` at the top of `Board_Deinit()`. These functions
+   iterate the peripheral registry arrays and initialize/deinitialize all
+   enabled peripheral devices.
+
+`Peripheral_Init()` and `Peripheral_Deinit()` are safe to call even when no
+peripherals are enabled — the registry arrays will be empty and the functions
+return immediately.
+
+See [Adding a Peripheral](adding_a_peripheral.md) for details on how to add
+new peripheral devices to the registry.
+
 ### linker.ld
 
 Linker script defining the memory layout for your board's MCU. Must define