[docs, README] Update READMEs. Add some docs.

.gitignore

@@ -58,6 +58,4 @@ dkms.conf
 *.cache
 compile_commands.json
 
-docs/
-
 tests/core/test_core

README.md

@@ -1,148 +1,29 @@
 # wolfHAL
 
-wolfHAL is a lightweight hardware abstraction layer for embedded targets written
-in C. It provides a uniform driver model based on vtable dispatch, register
-helpers for safe read-modify-write access, and reference drivers for multiple
-platforms.
-
-## Supported platforms
-
-| Platform | Board | Drivers |
-|----------|-------|---------|
-| 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
-
-Every peripheral is represented as a device struct containing a register map, a
-driver vtable, and a platform-specific config:
-
-```c
-typedef struct {
-    const whal_Regmap regmap;       /* base address + size */
-    const whal_GpioDriver *driver;  /* function pointers  */
-    void *cfg;                      /* platform config     */
-} whal_Gpio;
-```
-
-Public API functions validate the device, driver, and vtable entry before
-dispatching. When `WHAL_CFG_DIRECT_CALLBACKS` is defined, dispatch compiles down to
-direct calls with zero overhead.
-
-Board configs instantiate devices using platform macros:
-
-```c
-whal_Gpio g_whalGpio = {
-    WHAL_STM32WB55_GPIO_DEVICE,
-    .cfg = &gpioConfig,
-};
-```
-
-## Modules
-
-| Module | Header | Operations |
-|--------|--------|------------|
-| Clock  | `wolfHAL/clock/clock.h` | Init, Deinit, Enable, Disable, GetRate |
-| GPIO   | `wolfHAL/gpio/gpio.h` | Init, Deinit, Get, Set |
-| UART   | `wolfHAL/uart/uart.h` | Init, Deinit, Send, Recv |
-| 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`
-(bit manipulation), `wolfHAL/error.h` (error codes).
+wolfHAL is a lightweight, OS-agnostic, compiler-agnostic hardware abstraction
+layer for embedded targets written in C. It provides a uniform driver model
+based on vtable dispatch.
 
 ## Repository layout
 
 ```
 wolfHAL/                    Public headers (API surface)
-  platform/arm/             Cortex-M SysTick definitions
-  platform/st/              STM32WB55 device macros
-  platform/microchip/       PIC32CZ device macros
+  platform/                 Platform-specific device macros and definitions
 src/                        Driver implementations (generic + platform)
-boards/
-  stm32wb55xx_nucleo/       STM32WB55 Nucleo board support
-  pic32cz_curiosity_ultra/  PIC32CZ Curiosity Ultra board support
-examples/
-  blinky/                   LED blink + UART echo (multi-board)
-tests/
-  test.h                    Minimal test framework (no libc dependency)
-  core/                     Host-compiled tests (bitops, dispatch validation)
-  clock/ gpio/ flash/ ...   On-target per-module tests
-```
-
-## Getting started
-
-Add the repository root to your include path (`-I/path/to/wolfHAL`) and compile
-the sources you need:
-
-```
-# 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/rng/rng.c
-
-# Platform drivers (pick your target)
-src/clock/stm32wb_rcc.c  src/gpio/stm32wb_gpio.c  ...
-src/clock/pic32cz_clock.c  src/gpio/pic32cz_gpio.c  ...
-src/timer/systick.c
+boards/                     Example board configurations used for testing and examples
+examples/                   Example applications
+tests/                      Test framework and test suites
 ```
 
-Create a board config file that instantiates devices with your pin assignments,
-clock settings, and peripheral configs. See `boards/stm32wb55xx_nucleo/board.c`
-or `boards/pic32cz_curiosity_ultra/board.c` for reference.
+## Further reading
 
-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
-
-Examples use `arm-none-eabi-gcc` and produce a `.bin` suitable for flashing.
-Select a board with `BOARD=`:
-
-```sh
-cd examples/blinky
-make BOARD=stm32wb55xx_nucleo       # -> build/stm32wb55xx_nucleo/blinky.bin
-make BOARD=pic32cz_curiosity_ultra  # -> build/pic32cz_curiosity_ultra/blinky.bin
-```
-
-## Tests
-
-**Core tests** run on the host and validate the abstraction layer without any
-hardware:
-
-```sh
-cd tests/core && make run
-```
-
-**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
-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`:
-- **core-tests** -- builds and runs the host test suite
-- **cross-compile** -- verifies all examples and hardware tests compile cleanly
-  with `arm-none-eabi-gcc` for every supported board
-
-## Documentation
-
-Headers are annotated for Doxygen. Generate HTML docs with:
-
-```sh
-doxygen Doxyfile
-```
+- [Boards](boards/README.md) — Example board configurations
+- [Examples](examples/README.md) — Example applications
+- [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 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
 
 ## License
 

docs/adding_a_board.md

@@ -0,0 +1,133 @@
+# Adding a New Board
+
+This guide covers adding a new board configuration to wolfHAL.
+
+## Overview
+
+A board ties a platform to concrete hardware by defining peripheral instances,
+pin assignments, clock settings, and startup code. Each board lives in its own
+directory under `boards/` named `<platform>_<board_name>/`.
+
+## Required Files
+
+### board.h
+
+Exports global peripheral instances and board-specific constants:
+
+```c
+#pragma once
+
+#include <wolfHAL/wolfHAL.h>
+
+extern whal_Clock g_whalClock;
+extern whal_Gpio  g_whalGpio;
+extern whal_Uart  g_whalUart;
+extern whal_Timer g_whalTimer;
+extern whal_Flash g_whalFlash;
+
+#define BOARD_LED_PIN 0
+
+whal_Error Board_Init(void);
+whal_Error Board_Deinit(void);
+void Board_WaitMs(size_t ms);
+```
+
+### board.c
+
+Defines global device instances with their configurations and implements
+`Board_Init()` and `Board_Deinit()`.
+
+`Board_Init()` is responsible for initializing all peripherals in dependency
+order. For example, the clock controller must be initialized before peripherals
+that depend on it, and a power supply controller (if present) may need to come
+before the clock. It should return `WHAL_SUCCESS` on success or an error code
+on failure.
+
+`Board_Deinit()` tears down peripherals in reverse order.
+
+```c
+#include "board.h"
+#include <wolfHAL/platform/vendor/device.h>
+
+static whal_MyplatformGpio_PinCfg pinCfg[] = { /* ... */ };
+
+static whal_MyplatformGpio_Cfg gpioConfig = {
+    .clkCtrl = &g_whalClock,
+    .pinCfg  = pinCfg,
+    .pinCount = sizeof(pinCfg) / sizeof(pinCfg[0]),
+};
+
+whal_Gpio g_whalGpio = {
+    WHAL_MYPLATFORM_GPIO_DEVICE,
+    .cfg = &gpioConfig,
+};
+
+whal_Error Board_Init(void)
+{
+    whal_Error err;
+
+    err = whal_Clock_Init(&g_whalClock);
+    if (err != WHAL_SUCCESS) return err;
+
+    err = whal_Gpio_Init(&g_whalGpio);
+    if (err != WHAL_SUCCESS) return err;
+
+    err = whal_Uart_Init(&g_whalUart);
+    if (err != WHAL_SUCCESS) return err;
+
+    err = whal_Timer_Init(&g_whalTimer);
+    if (err != WHAL_SUCCESS) return err;
+
+    err = whal_Timer_Start(&g_whalTimer);
+    if (err != WHAL_SUCCESS) return err;
+
+    return WHAL_SUCCESS;
+}
+
+whal_Error Board_Deinit(void)
+{
+    whal_Timer_Stop(&g_whalTimer);
+    whal_Timer_Deinit(&g_whalTimer);
+    whal_Uart_Deinit(&g_whalUart);
+    whal_Gpio_Deinit(&g_whalGpio);
+    whal_Clock_Deinit(&g_whalClock);
+    return WHAL_SUCCESS;
+}
+```
+
+### Makefile.inc
+
+Defines the toolchain, compiler flags, and source file list:
+
+```makefile
+_BOARD_DIR := $(patsubst %/,%,$(dir $(lastword $(MAKEFILE_LIST))))
+
+PLATFORM = myplatform
+TESTS = gpio clock uart flash timer
+
+GCC     = arm-none-eabi-gcc
+LD      = arm-none-eabi-gcc
+OBJCOPY = arm-none-eabi-objcopy
+
+CFLAGS  = -mcpu=cortex-m4 -mthumb -Os -Wall -MMD $(INCLUDE) -I$(_BOARD_DIR)
+LDFLAGS = -mcpu=cortex-m4 -mthumb -nostdlib -lgcc
+
+LINKER_SCRIPT = $(_BOARD_DIR)/linker.ld
+
+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
+```
+
+### linker.ld
+
+Linker script defining the memory layout for your board's MCU. Must define
+FLASH and RAM regions, place `.isr_vector` at the start of FLASH, and set up
+`.text`, `.data`, and `.bss` sections.
+
+### ivt.c (ARM targets)
+
+Interrupt vector table and `Reset_Handler`. The reset handler copies `.data`
+from FLASH to RAM, zeroes `.bss`, and calls `main()`. This file is specific to
+ARM Cortex-M targets. Other architectures will need their own startup code.