mirror of https://github.com/wolfSSL/wolfBoot.git
98 lines
4.4 KiB
Markdown
98 lines
4.4 KiB
Markdown
# Hooks
|
|
|
|
wolfBoot provides a hooks framework that allows users to inject custom logic at
|
|
well-defined points in the boot process without modifying wolfBoot source code.
|
|
Each hook is independently enabled via its own build-time macro and compiled in
|
|
from a single user-provided source file.
|
|
|
|
Typical use cases include board-specific hardware setup not covered in the
|
|
default HAL, debug logging, watchdog management, setting a safe state on boot
|
|
failure, etc.
|
|
|
|
## Available Hooks
|
|
|
|
| Hook | Macro | Signature | When Called |
|
|
|------|-------|-----------|------------|
|
|
| Preinit | `WOLFBOOT_HOOK_LOADER_PREINIT` | `void wolfBoot_hook_preinit(void)` | Before `hal_init()` in the loader |
|
|
| Postinit | `WOLFBOOT_HOOK_LOADER_POSTINIT` | `void wolfBoot_hook_postinit(void)` | After all loader initialization, just before `wolfBoot_start()` |
|
|
| Preboot | `WOLFBOOT_HOOK_PREBOOT` | `void wolfBoot_hook_preboot(struct wolfBoot_image *boot_img)` | After verification, immediately **before** `hal_prepare_boot()` |
|
|
| Boot | `WOLFBOOT_HOOK_BOOT` | `void wolfBoot_hook_boot(struct wolfBoot_image *boot_img)` | After `hal_prepare_boot()` but before `do_boot()` |
|
|
| Panic | `WOLFBOOT_HOOK_PANIC` | `void wolfBoot_hook_panic(void)` | Inside `wolfBoot_panic()`, before halt |
|
|
|
|
## Boot Flow
|
|
|
|
The following diagram shows where each hook fires in the wolfBoot boot sequence:
|
|
|
|
```
|
|
loader main()
|
|
|
|
|
+-- [HOOK: wolfBoot_hook_preinit()] <-- WOLFBOOT_HOOK_LOADER_PREINIT
|
|
|
|
|
+-- hal_init()
|
|
+-- other initialization...
|
|
|
|
|
+-- [HOOK: wolfBoot_hook_postinit()] <-- WOLFBOOT_HOOK_LOADER_POSTINIT
|
|
|
|
|
+-- wolfBoot_start()
|
|
|
|
|
+-- (image verification, update logic)
|
|
|
|
|
+-- [HOOK: wolfBoot_hook_preboot()] <-- WOLFBOOT_HOOK_PREBOOT
|
|
|
|
|
+-- hal_prepare_boot()
|
|
|
|
|
+-- [HOOK: wolfBoot_hook_boot()] <-- WOLFBOOT_HOOK_BOOT
|
|
|
|
|
+-- do_boot()
|
|
|
|
wolfBoot_panic() (called on any fatal error)
|
|
|
|
|
+-- [HOOK: wolfBoot_hook_panic()] <-- WOLFBOOT_HOOK_PANIC
|
|
|
|
|
+-- halt / infinite loop
|
|
```
|
|
|
|
## Build Configuration
|
|
|
|
First, enable hooks in your `.config`:
|
|
|
|
```makefile
|
|
# Path to a single .c file containing your hook implementations
|
|
WOLFBOOT_HOOKS_FILE=path/to/my_hooks.c
|
|
|
|
# Enable individual hooks (each is independent)
|
|
WOLFBOOT_HOOK_LOADER_PREINIT=1
|
|
WOLFBOOT_HOOK_LOADER_POSTINIT=1
|
|
WOLFBOOT_HOOK_PREBOOT=1
|
|
WOLFBOOT_HOOK_BOOT=1
|
|
WOLFBOOT_HOOK_PANIC=1
|
|
```
|
|
|
|
Or pass them on the `make` command line:
|
|
|
|
```bash
|
|
make WOLFBOOT_HOOKS_FILE=my_hooks.c WOLFBOOT_HOOK_LOADER_PREINIT=1
|
|
```
|
|
|
|
## Notes
|
|
|
|
- `WOLFBOOT_HOOKS_FILE` tells the build system to compile and link your hooks
|
|
source file. The resulting object file is added to the wolfBoot binary.
|
|
- Hook prototypes are declared in `include/hooks.h`.
|
|
- Each hook is independently enabled. You only need to implement the hooks you
|
|
wish to enable in your build. Additionally, all hooks are optional. If no
|
|
`WOLFBOOT_HOOK_*` macros are defined, the boot flow is unchanged.
|
|
- The preinit hook runs before any hardware initialization. Be careful to only
|
|
use functionality that does not depend on `hal_init()` having been called.
|
|
- The boot hook receives a pointer to the verified `wolfBoot_image` struct,
|
|
allowing inspection of firmware version, type, and other metadata before boot.
|
|
- The preboot hook gets the same struct but fires on the other side of `hal_prepare_boot()`, where a port tears the environment down for handoff: flushing or disabling caches, disabling the MMU (`hal/cm4.c`), leaving 4-byte flash addressing (`hal/zynq.c`). Anything touching DMA, a live MMU mapping or external flash belongs in the preboot hook; use the boot hook only for the last thing before `do_boot()`.
|
|
- On `MMU` / `WOLFBOOT_FDT` builds, `wolfBoot_get_dts_address()` returns the device tree wolfBoot is about to pass to the OS, or `NULL`. It is published just before the preboot hook, so it is only meaningful from there on. Parse it with the `fdt_*` API in `include/fdt.h`; `fdt_get_alias()` and `fdt_get_reg()` turn a board label into a peripheral base address.
|
|
- The panic hook fires inside `wolfBoot_panic()` just before the system halts.
|
|
Use it to set the system to a safe state, log errors, toggle GPIOs, notify
|
|
external systems, etc.
|
|
- **Note (WOLFBOOT_ARMORED):** When armored glitch protection is enabled, the
|
|
panic hook is called on a best-effort basis before the glitch-hardened halt
|
|
loop. The hook itself is not glitch-protected — a fault during the hook call
|
|
could skip it entirely. The halt loop remains hardened regardless.
|