Merge pull request #12 from AlexLanzano/boards

[boards, tests, examples] Create example boards directory. Move board cfg there

Author: AlexLanzano

.gitignore

@@ -60,4 +60,4 @@ compile_commands.json
 
 docs/
 
-tests/sim/test_sim
+tests/core/test_core

README.md

@@ -9,8 +9,8 @@ platforms.
 
 | Platform | Board | Drivers |
 |----------|-------|---------|
-| STM32WB55 | Nucleo | RCC (PLL + MSI), GPIO, UART, LPUART, SPI, Flash, SysTick |
-| PIC32CZ | Curiosity Ultra | Clock (dual PLL), GPIO, UART, Supply (SUPC), SysTick |
+| STM32WB55 | Nucleo | RCC (PLL + MSI), GPIO, UART, LPUART, SPI, Flash, RNG, SysTick |
+| PIC32CZ | Curiosity Ultra | Clock (dual PLL), GPIO, UART, Flash, Supply (SUPC), SysTick |
 
 ## Architecture
 
@@ -48,6 +48,7 @@ whal_Gpio g_whalGpio = {
 | Flash  | `wolfHAL/flash/flash.h` | Init, Deinit, Lock, Unlock, Read, Write, Erase |
 | SPI    | `wolfHAL/spi/spi.h` | Init, Deinit, SendRecv, Send, Recv |
 | Timer  | `wolfHAL/timer/timer.h` | Init, Deinit, Start, Stop, Reset |
+| RNG    | `wolfHAL/rng/rng.h` | Init, Deinit, Generate |
 | Supply | `wolfHAL/supply/supply.h` | Init, Deinit, Enable, Disable |
 
 Utilities: `wolfHAL/regmap.h` (masked register access), `wolfHAL/bitops.h`
@@ -61,13 +62,15 @@ wolfHAL/                    Public headers (API surface)
   platform/st/              STM32WB55 device macros
   platform/microchip/       PIC32CZ device macros
 src/                        Driver implementations (generic + platform)
+boards/
+  stm32wb55xx_nucleo/       STM32WB55 Nucleo board support
+  pic32cz_curiosity_ultra/  PIC32CZ Curiosity Ultra board support
 examples/
-  stm32wb/                  STM32WB55 Nucleo board bring-up and UART echo
-  pic32cz/                  PIC32CZ Curiosity Ultra board bring-up
+  blinky/                   LED blink + UART echo (multi-board)
 tests/
   test.h                    Minimal test framework (no libc dependency)
-  sim/                      Host-compiled tests (bitops, dispatch validation)
-  hw/stm32wb/               On-target tests (clock, GPIO, flash, timer)
+  core/                     Host-compiled tests (bitops, dispatch validation)
+  clock/ gpio/ flash/ ...   On-target per-module tests
 ```
 
 ## Getting started
@@ -82,7 +85,7 @@ src/reg.c
 # Generic dispatch (include all, or just the modules you use)
 src/clock/clock.c  src/gpio/gpio.c  src/uart/uart.c
 src/flash/flash.c  src/spi/spi.c    src/timer/timer.c
-src/supply/supply.c
+src/supply/supply.c  src/rng/rng.c
 
 # Platform drivers (pick your target)
 src/clock/stm32wb_rcc.c  src/gpio/stm32wb_gpio.c  ...
@@ -91,43 +94,50 @@ src/timer/systick.c
 ```
 
 Create a board config file that instantiates devices with your pin assignments,
-clock settings, and peripheral configs. See `examples/stm32wb/stm32wb55xx_nucleo.c`
-or `examples/pic32cz/pic32cz_curiosity_ultra.c` for reference.
+clock settings, and peripheral configs. See `boards/stm32wb55xx_nucleo/board.c`
+or `boards/pic32cz_curiosity_ultra/board.c` for reference.
 
 To write a driver for a new platform, implement the functions in the relevant
 `*Driver` vtable and provide device macros in a platform header.
 
 ## Building the examples
 
-Both examples use `arm-none-eabi-gcc` and produce a `.bin` suitable for flashing:
+Examples use `arm-none-eabi-gcc` and produce a `.bin` suitable for flashing.
+Select a board with `BOARD=`:
 
 ```sh
-cd examples/stm32wb && make    # -> boot.bin (Cortex-M4)
-cd examples/pic32cz && make    # -> boot.bin (Cortex-M33)
+cd examples/blinky
+make BOARD=stm32wb55xx_nucleo       # -> build/stm32wb55xx_nucleo/blinky.bin
+make BOARD=pic32cz_curiosity_ultra  # -> build/pic32cz_curiosity_ultra/blinky.bin
 ```
 
 ## Tests
 
-**Simulation tests** run on the host and validate the abstraction layer without
-any hardware:
+**Core tests** run on the host and validate the abstraction layer without any
+hardware:
 
 ```sh
-cd tests/sim && make run
+cd tests/core && make run
 ```
 
-**Hardware tests** cross-compile and run on an STM32WB55 Nucleo. They boot the
-board, report results over UART, and signal pass/fail via LED:
+**Hardware tests** cross-compile for a target board. They boot the board, report
+results over UART, and signal pass/fail via LED:
 
 ```sh
-cd tests/stm32wb && make    # -> test_hw.bin
+cd tests
+make BOARD=stm32wb55xx_nucleo       # -> build/stm32wb55xx_nucleo/test_hw.bin
+make BOARD=pic32cz_curiosity_ultra  # -> build/pic32cz_curiosity_ultra/test_hw.bin
 ```
 
+Each board's `Makefile.inc` defines a default `TESTS` list (e.g. `clock gpio
+flash timer rng`). Override it on the command line to run a subset.
+
 ## CI
 
 GitHub Actions runs on every push and PR to `main`:
-- **sim-tests** -- builds and runs the host test suite
+- **core-tests** -- builds and runs the host test suite
 - **cross-compile** -- verifies all examples and hardware tests compile cleanly
-  with `arm-none-eabi-gcc`
+  with `arm-none-eabi-gcc` for every supported board
 
 ## Documentation
 

boards/README.md

@@ -0,0 +1,70 @@
+# wolfHAL Example Board Definitions
+
+The board definitions in this directory are **examples** for use with
+wolfHAL's tests and sample applications. They are configured for specific
+development boards and are not intended for production use. Users should
+create their own board support packages tailored to their hardware.
+
+Each subdirectory contains a board support package (BSP) for a specific
+development board. A BSP provides everything needed to build wolfHAL for a
+given target: startup code, peripheral initialization, linker script, and
+build configuration.
+
+## Supported Boards
+
+| Board | Platform | CPU | Directory |
+|-------|----------|-----|-----------|
+| Microchip PIC32CZ CA Curiosity Ultra | PIC32CZ | Cortex-M7 | `pic32cz_curiosity_ultra/` |
+| ST STM32WB55 Nucleo | STM32WB | Cortex-M4 | `stm32wb55xx_nucleo/` |
+
+## Board Directory Contents
+
+Each board directory contains:
+
+- **`Makefile.inc`** - Build configuration: toolchain, CPU flags, platform
+  drivers, and linker script. Included by application Makefiles via
+  `include $(BOARD_DIR)/Makefile.inc`.
+- **`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).
+- **`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 `Makefile.inc` files use a self-referencing pattern so that they can be
+included from any directory:
+
+```makefile
+_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.
+
+### What `BOARD_SOURCE` includes
+
+Board `Makefile.inc` 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
+- Platform / SoC drivers: e.g. `pic32cz_*.c`, `stm32wb_*.c`
+- Architecture support: `systick.c` and any related startup / vector code
+- Core wolfHAL modules and common sources: generic drivers such as
+  `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
+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
+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>`

…rds/pic32cz_curiosity_ultra/Makefile.inc …rds/pic32cz_curiosity_ultra/Makefile.inctests/boards/pic32cz_curiosity_ultra/Makefile.inc renamed to boards/pic32cz_curiosity_ultra/Makefile.inc tests/boards/pic32cz_curiosity_ultra/Makefile.inc renamed to boards/pic32cz_curiosity_ultra/Makefile.inc

@@ -1,5 +1,7 @@
+_BOARD_DIR := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
+
 PLATFORM = pic32cz
-TESTS = clock gpio flash timer
+TESTS ?= clock gpio flash timer
 
 GCC = $(GCC_PATH)arm-none-eabi-gcc
 LD = $(GCC_PATH)arm-none-eabi-ld
@@ -10,14 +12,19 @@ CFLAGS += -Wall -Werror $(INCLUDE) -g3 \
           -DPLATFORM_PIC32CZ -MMD -MP
 LDFLAGS = --omagic -static
 
-BOARD_SOURCE = $(BOARD_DIR)/ivt.c
-BOARD_SOURCE += $(BOARD_DIR)/board.c
+LINKER_SCRIPT ?= $(_BOARD_DIR)/linker.ld
+
+INCLUDE += -I$(_BOARD_DIR)
+
+BOARD_SOURCE = $(_BOARD_DIR)/ivt.c
+BOARD_SOURCE += $(_BOARD_DIR)/board.c
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/gpio.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/clock.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/uart.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/timer.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/supply.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/flash.c)
+BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/rng.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/pic32cz_*.c)
 BOARD_SOURCE += $(wildcard $(WHAL_DIR)/src/*/systick.c)