wolfHAL Design Review

.gitignore

@@ -0,0 +1,63 @@
+# Prerequisites
+*.d
+
+# Object files
+*.o
+*.ko
+*.obj
+*.elf
+
+# Linker output
+*.ilk
+*.map
+*.exp
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Libraries
+*.lib
+*.a
+*.la
+*.lo
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+*.i*86
+*.x86_64
+*.hex
+*.bin
+
+# Debug files
+*.dSYM/
+*.su
+*.idb
+*.pdb
+
+# Kernel Module Compile Results
+*.mod*
+*.cmd
+.tmp_versions/
+modules.order
+Module.symvers
+Mkfile.old
+dkms.conf
+
+# debug information files
+*.dwo
+
+*.cache
+compile_commands.json
+
+tests/core/test_core
+
+*.pdf

README.md

@@ -0,0 +1,32 @@
+# wolfHAL
+
+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/                 Platform-specific device macros and definitions
+src/                        Driver implementations (generic + platform)
+boards/                     Example board configurations used for testing and examples
+examples/                   Example applications
+tests/                      Test framework and test suites
+```
+
+## Further reading
+
+- [Getting Started](docs/getting_started.md) — Integrating wolfHAL into your project
+- [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 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
+
+## License
+
+GPLv3 -- see [LICENSE](LICENSE) for details.

boards/README.md

@@ -0,0 +1,78 @@
+# 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 NUCLEO-C031C6 | STM32C0 | Cortex-M0+ | `stm32c031_nucleo/` |
+| ST NUCLEO-F091RC | STM32F0 | Cortex-M0 | `stm32f091rc_nucleo/` |
+| ST NUCLEO-F302R8 | STM32F3 | Cortex-M4 | `stm32f302r8_nucleo/` |
+| WeAct BlackPill STM32F411 | STM32F4 | Cortex-M4 | `stm32f411_blackpill/` |
+| ST NUCLEO-H563ZI | STM32H5 | Cortex-M33 | `stm32h563zi_nucleo/` |
+| ST NUCLEO-WB55RG | STM32WB | Cortex-M4 | `stm32wb55xx_nucleo/` |
+| ST NUCLEO-L152RE | STM32L1 | Cortex-M3 | `stm32l152re_nucleo/` |
+| ST NUCLEO-N657X0-Q | STM32N6 | Cortex-M55 | `stm32n657a0_nucleo/` |
+| ST NUCLEO-WBA55CG | STM32WBA | Cortex-M33 | `stm32wba55cg_nucleo/` |
+
+## Board Directory Contents
+
+Each board directory contains:
+
+- **`board.mk`** - Build configuration: toolchain, CPU flags, platform
+  drivers, and linker script. Included by application Makefiles via
+  `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
+  (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).
+
+## board.mk Convention
+
+Board `board.mk` 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 `board.mk` and adding additional sources.
+
+### What `BOARD_SOURCE` includes
+
+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
+- 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 `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 `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>`