[peripheral, tests, docs] Rename peripheral drivers to <chip>_<type> convention. Move spi_loopback test into spi/. Add platform test support to main.c for all device type

AlexLanzano · AlexLanzano · commit 360245fb606d · 2026-04-09T22:42:01.000-04:00
diff --git a/boards/peripheral/Makefile.inc b/boards/peripheral/Makefile.inc
@@ -5,18 +5,18 @@ BOARD_SOURCE += $(_PERIPHERAL_DIR)/peripheral.c
 ifneq ($(filter sdhc_spi_sdcard32gb,$(PERIPHERALS)),)
 CFLAGS += -DPERIPHERAL_SDHC_SPI_SDCARD32GB
 BOARD_SOURCE += $(_PERIPHERAL_DIR)/block/sdhc_spi_sdcard32gb.c
-BOARD_SOURCE += $(WHAL_DIR)/src/block/sdhc_spi.c
+BOARD_SOURCE += $(WHAL_DIR)/src/block/sdhc_spi_block.c
 endif
 
 ifneq ($(filter spi_nor_w25q64,$(PERIPHERALS)),)
 CFLAGS += -DPERIPHERAL_SPI_NOR_W25Q64
 BOARD_SOURCE += $(_PERIPHERAL_DIR)/flash/spi_nor_w25q64.c
-BOARD_SOURCE += $(WHAL_DIR)/src/flash/spi_nor.c
+BOARD_SOURCE += $(WHAL_DIR)/src/flash/spi_nor_flash.c
 endif
 
 ifneq ($(filter bmi270,$(PERIPHERALS)),)
 CFLAGS += -DPERIPHERAL_BMI270
 BOARD_SOURCE += $(_PERIPHERAL_DIR)/sensor/imu/bmi270.c
-BOARD_SOURCE += $(WHAL_DIR)/src/sensor/imu/bmi270.c
+BOARD_SOURCE += $(WHAL_DIR)/src/sensor/imu/bmi270_sensor.c
 BOARD_SOURCE += $(WHAL_DIR)/src/sensor/imu/bmi270_config_data.c
 endif
diff --git a/boards/peripheral/block/sdhc_spi_sdcard32gb.c b/boards/peripheral/block/sdhc_spi_sdcard32gb.c
@@ -1,5 +1,5 @@
 #include "sdhc_spi_sdcard32gb.h"
-#include <wolfHAL/block/sdhc_spi.h>
+#include <wolfHAL/block/sdhc_spi_block.h>
 #include "board.h"
 
 static whal_Spi_ComCfg g_sdcardComCfg = {
diff --git a/boards/peripheral/block/sdhc_spi_sdcard32gb.h b/boards/peripheral/block/sdhc_spi_sdcard32gb.h
@@ -3,7 +3,7 @@
 
 #include <wolfHAL/wolfHAL.h>
 #include <wolfHAL/block/block.h>
-#include <wolfHAL/block/sdhc_spi.h>
+#include <wolfHAL/block/sdhc_spi_block.h>
 
 extern whal_Block g_whalSdhcSpiSdcard32gb;
 
diff --git a/boards/peripheral/flash/spi_nor_w25q64.c b/boards/peripheral/flash/spi_nor_w25q64.c
@@ -1,5 +1,5 @@
 #include "spi_nor_w25q64.h"
-#include <wolfHAL/flash/spi_nor.h>
+#include <wolfHAL/flash/spi_nor_flash.h>
 #include "board.h"
 
 /*
diff --git a/boards/peripheral/flash/spi_nor_w25q64.h b/boards/peripheral/flash/spi_nor_w25q64.h
@@ -3,7 +3,7 @@
 
 #include <wolfHAL/wolfHAL.h>
 #include <wolfHAL/flash/flash.h>
-#include <wolfHAL/flash/spi_nor.h>
+#include <wolfHAL/flash/spi_nor_flash.h>
 
 extern whal_Flash g_whalSpiNorW25q64;
 
diff --git a/boards/peripheral/sensor/imu/bmi270.c b/boards/peripheral/sensor/imu/bmi270.c
@@ -1,5 +1,5 @@
 #include "bmi270.h"
-#include <wolfHAL/sensor/imu/bmi270.h>
+#include <wolfHAL/sensor/imu/bmi270_sensor.h>
 #include <wolfHAL/sensor/imu/bmi270_config_data.h>
 #include "board.h"
 
diff --git a/boards/peripheral/sensor/imu/bmi270.h b/boards/peripheral/sensor/imu/bmi270.h
@@ -3,7 +3,7 @@
 
 #include <wolfHAL/wolfHAL.h>
 #include <wolfHAL/sensor/sensor.h>
-#include <wolfHAL/sensor/imu/bmi270.h>
+#include <wolfHAL/sensor/imu/bmi270_sensor.h>
 
 extern whal_Sensor g_whalBmi270;
 
diff --git a/boards/stm32h563zi_nucleo/board.c b/boards/stm32h563zi_nucleo/board.c
@@ -4,7 +4,7 @@
 #include <stddef.h>
 #include "board.h"
 #include <wolfHAL/platform/st/stm32h563xx.h>
-#include <wolfHAL/eth_phy/lan8742a.h>
+#include <wolfHAL/eth_phy/lan8742a_eth_phy.h>
 #include "peripheral.h"
 
 /* SysTick timing */
diff --git a/docs/adding_a_peripheral.md b/docs/adding_a_peripheral.md
@@ -50,7 +50,7 @@ Declare the global device instance:
 
 #include <wolfHAL/wolfHAL.h>
 #include <wolfHAL/flash/flash.h>
-#include <wolfHAL/flash/spi_nor.h>
+#include <wolfHAL/flash/spi_nor_flash.h>
 
 extern whal_Flash g_whalSpiNorW25q64;
 
@@ -65,7 +65,7 @@ globals (`g_whalSpi`, `g_whalGpio`, `SPI_CS_PIN`, `g_whalTimeout`) from
 
 ```c
 #include "spi_nor_w25q64.h"
-#include <wolfHAL/flash/spi_nor.h>
+#include <wolfHAL/flash/spi_nor_flash.h>
 #include "board.h"
 
 #define W25Q64_PAGE_SZ  256
@@ -168,8 +168,16 @@ framework.
 
 ## Naming Convention
 
-- Flag: `PERIPHERAL_<NAME>` (e.g., `PERIPHERAL_BMI270`)
-- PERIPHERALS variable: lowercase name (e.g., `bmi270`, `spi_nor_w25q64`)
+Instance files are named `<driver>_<instance>`:
+
+- `sdhc_spi_sdcard32gb` — sdhc_spi driver, 32GB SD card
+- `spi_nor_w25q64` — spi_nor driver, W25Q64 chip
+- `bmi270` — bmi270 driver (single instance, no qualifier needed)
+
+Summary:
+
 - Directory: `boards/peripheral/<type>/` (e.g., `flash/`, `block/`, `sensor/imu/`)
-- Files: `<name>.h` and `<name>.c`
-- Global instance: `g_whal<Name>` (e.g., `g_whalBmi270`, `g_whalSpiNorW25q64`)
+- Files: `<driver>.h` and `<driver>.c` for single-instance peripherals; otherwise `<driver>_<instance>.h` and `<driver>_<instance>.c`
+- Flag: `PERIPHERAL_<NAME>` (e.g., `PERIPHERAL_SPI_NOR_W25Q64`)
+- PERIPHERALS variable: lowercase name (e.g., `spi_nor_w25q64`, `bmi270`)
+- Global instance: `g_whal<Name>` (e.g., `g_whalSpiNorW25q64`, `g_whalBmi270`)
diff --git a/docs/getting_started.md b/docs/getting_started.md
@@ -277,7 +277,7 @@ This eliminates the vtable indirection and lets the compiler inline or optimize
 the calls more aggressively.
 
 Register-level drivers do not call other drivers internally, so this works
-without any caveats. Bus-device drivers (e.g., SPI flash) still call their
+without any caveats. Peripheral drivers (e.g., SPI flash) still call their
 bus driver through the vtable.
 
 ## Next Steps
diff --git a/docs/writing_a_driver.md b/docs/writing_a_driver.md
@@ -1,27 +1,52 @@
 # Writing a Driver
 
-This guide covers how to implement a wolfHAL driver for a specific platform.
+This guide covers how to implement wolfHAL drivers.
+
+## Driver Categories
+
+wolfHAL has two categories of drivers:
+
+**Platform drivers** operate directly on SoC hardware registers at fixed memory
+addresses. They are tied to a specific microcontroller family and use the
+`whal_Reg_*` helpers to read and write peripheral registers. Examples:
+`stm32wb_uart`, `stm32wb_gpio`, `stm32wb_dma`, `pic32cz_clock`.
+
+**Peripheral drivers** communicate with external chips over a bus (SPI, I2C,
+MDIO). They call platform drivers (e.g., `whal_Spi_SendRecv`) to reach the
+hardware and are portable across any SoC that provides the required bus.
+Examples: `spi_nor_flash` (SPI flash), `sdhc_spi_block` (SD card over SPI),
+`bmi270_sensor` (IMU over I2C), `lan8742a_eth_phy` (Ethernet PHY over MDIO).
+
+Both categories implement the same vtable interface — the application calls
+`whal_Flash_Read()` whether the flash is on-chip (platform driver) or
+external SPI NOR (peripheral driver). The distinction matters for driver
+authors, not for application code.
 
 ## Common Pattern
 
 Every device type in wolfHAL follows the same structure:
 
-1. A **driver vtable** — a struct of function pointers that the platform driver
-   must populate.
+1. A **driver vtable** — a struct of function pointers that the driver must
+   populate.
 2. A **device struct** — contains a register map, a pointer to the driver
-   vtable, and a pointer to platform-specific configuration.
+   vtable, and a pointer to driver-specific configuration.
 3. A **generic dispatch layer** — validates inputs and calls through the vtable.
 
 To write a driver for a device type, you implement the functions defined in that
 type's vtable and expose them as a const driver instance.
 
 ### File Layout
 
-For a device type `foo` on platform `myplatform`:
+For a platform driver implementing device type `foo` on platform `myplatform`:
 
 - `wolfHAL/foo/myplatform_foo.h` — configuration types and driver extern
 - `src/foo/myplatform_foo.c` — driver implementation and vtable definition
 
+For a peripheral driver implementing device type `foo` for chip `mychip`:
+
+- `wolfHAL/foo/mychip_foo.h` — configuration types and driver extern
+- `src/foo/mychip_foo.c` — driver implementation and vtable definition
+
 ### Driver Vtable
 
 Every vtable includes `Init` and `Deinit`. The remaining functions are specific
@@ -51,18 +76,17 @@ static whal_Error whal_MyplatformFoo_Init(whal_Foo *fooDev)
 
 ### No Cross-Driver Calls
 
-Register-level drivers must not call other wolfHAL drivers. A UART driver
-must not call the clock driver to enable its own clock, and a clock driver
-must not call the flash driver to set wait states. The board is responsible
-for all cross-peripheral dependencies — enabling clocks, configuring power
-supplies, and setting flash latency — before calling a driver's Init.
+Platform drivers should only touch their own registers. The board handles all
+cross-peripheral setup — clock enables, power supply sequencing, flash wait
+states — before calling Init.
 
-This ensures drivers are pure register-level abstractions with no hidden
-dependencies, making them usable with or without the vtable dispatch layer.
+There are two exceptions:
 
-Bus-device drivers (e.g., SPI flash) are the exception — they inherently
-need to call their underlying bus driver (SPI, I2C) to communicate with the
-device.
+- **Peripheral drivers** call their underlying bus driver (SPI, I2C, MDIO) to
+  communicate with the external chip.
+- **DMA-backed platform drivers** (e.g., `stm32wb_uart_dma`) call the DMA
+  driver to set up and start transfers. The DMA device is passed through the
+  driver's configuration struct.
 
 ### Register Access
 
@@ -701,7 +725,7 @@ Erase a flash region. Flash erase operates at sector/page granularity
 - Validate that the region is unlocked before erasing
 
 The `addr` does not need to be page-aligned — the driver should erase all pages
-that overlap with the requested range. Bus-device flash drivers (e.g., SPI-NOR)
+that overlap with the requested range. Peripheral flash drivers (e.g., SPI-NOR)
 may enforce stricter alignment requirements where the underlying hardware
 requires aligned erase addresses.
 
@@ -716,9 +740,8 @@ SD cards and eMMC. Unlike flash, block devices are addressed by block number
 rather than byte address, and all operations work in units of fixed-size blocks
 (e.g. 512 bytes).
 
-Block drivers are bus-device drivers — they call their underlying bus driver
-(SPI, SDIO) to communicate with the storage device. This is the expected
-exception to the no-cross-driver-calls rule.
+Block drivers are peripheral drivers — they call their underlying bus driver
+(SPI, SDIO) to communicate with the storage device.
 
 ### Init
 
diff --git a/src/block/sdhc_spi_block.c b/src/block/sdhc_spi_block.c
@@ -1,5 +1,5 @@
 #include <stdint.h>
-#include <wolfHAL/block/sdhc_spi.h>
+#include <wolfHAL/block/sdhc_spi_block.h>
 #include <wolfHAL/block/block.h>
 #include <wolfHAL/spi/spi.h>
 #include <wolfHAL/gpio/gpio.h>
diff --git a/src/eth_phy/lan8742a_eth_phy.c b/src/eth_phy/lan8742a_eth_phy.c
@@ -1,4 +1,4 @@
-#include <wolfHAL/eth_phy/lan8742a.h>
+#include <wolfHAL/eth_phy/lan8742a_eth_phy.h>
 #include <wolfHAL/eth/eth.h>
 #include <wolfHAL/error.h>
 
diff --git a/src/flash/spi_nor_flash.c b/src/flash/spi_nor_flash.c
@@ -1,5 +1,5 @@
 #include <stdint.h>
-#include <wolfHAL/flash/spi_nor.h>
+#include <wolfHAL/flash/spi_nor_flash.h>
 #include <wolfHAL/flash/flash.h>
 #include <wolfHAL/spi/spi.h>
 #include <wolfHAL/gpio/gpio.h>
diff --git a/src/sensor/imu/bmi270_sensor.c b/src/sensor/imu/bmi270_sensor.c
@@ -1,5 +1,5 @@
 #include <stdint.h>
-#include <wolfHAL/sensor/imu/bmi270.h>
+#include <wolfHAL/sensor/imu/bmi270_sensor.h>
 #include <wolfHAL/sensor/sensor.h>
 #include <wolfHAL/i2c/i2c.h>
 #include <wolfHAL/error.h>
diff --git a/tests/Makefile b/tests/Makefile
@@ -10,7 +10,7 @@ include $(BOARD_DIR)/Makefile.inc
 
 uc = $(shell echo $(1) | tr a-z A-Z)
 CFLAGS += $(foreach t,$(TESTS),-DWHAL_TEST_ENABLE_$(call uc,$(t)))
-CFLAGS += $(foreach t,$(TESTS),$(if $(wildcard $(t)/test_$(PLATFORM)_$(t).c),-DWHAL_TEST_ENABLE_$(call uc,$(t))_PLATFORM))
+CFLAGS += $(foreach t,$(TESTS),$(if $(shell find . -name 'test_$(PLATFORM)_$(t).c'),-DWHAL_TEST_ENABLE_$(call uc,$(t))_PLATFORM))
 
 SOURCE = main.c
 SOURCE += $(BOARD_SOURCE)
diff --git a/tests/main.c b/tests/main.c
diff --git a/tests/sensor/imu/test_bmi270_sensor.c b/tests/sensor/imu/test_bmi270_sensor.c
diff --git a/tests/spi/test_spi_loopback.c b/tests/spi/test_spi_loopback.c
diff --git a/wolfHAL/block/sdhc_spi_block.h b/wolfHAL/block/sdhc_spi_block.h
diff --git a/wolfHAL/eth_phy/lan8742a_eth_phy.h b/wolfHAL/eth_phy/lan8742a_eth_phy.h
diff --git a/wolfHAL/flash/spi_nor_flash.h b/wolfHAL/flash/spi_nor_flash.h
diff --git a/wolfHAL/sensor/imu/bmi270_sensor.h b/wolfHAL/sensor/imu/bmi270_sensor.h
