wolfBoot/docs/HAL.md

Hardware Abstraction Layer (HAL)

The Hardware Abstraction Layer (HAL) provides the interface between wolfBoot and target hardware. Each supported microcontroller requires its own HAL implementation.

Overview

The HAL serves two primary purposes:

1. Provide hardware-specific flash operations (read/write/erase) for both:
   • Bootloader operations
   • Application-initiated firmware updates
2. Ensure optimal MCU performance during boot for fast signature verification

Implementation Structure

HAL implementations are organized as follows:

1. Platform-specific C files:

   • Located in the hal directory
   • One file per supported platform
   • Contains all hardware-specific function implementations

2. Platform-specific linker scripts:

   • Located alongside HAL C files
   • Named platform_name.ld
   • Defines:
     • Flash memory layout
     • RAM boundaries
     • Required symbol exports

Supported platforms

Please see Targets

Core HAL API

Every HAL implementation must provide these six core functions:

System Initialization

void hal_init(void)

Called at bootloader startup to initialize the hardware.

Responsibilities:

• Configure system clock for optimal performance
• Initialize critical peripherals
• Set up flash controller
• Configure any required hardware accelerators

Flash Memory Operations

Unlock Flash

void hal_flash_unlock(void)

Prepares flash memory for write/erase operations.

Notes:

• Called before any flash write/erase operation
• May be empty if target doesn't require explicit unlocking
• Must handle any required flash controller configuration

Write to Flash

int hal_flash_write(uint32_t address, const uint8_t *data, int len)

Writes data to internal flash memory.

Parameters:

• address: Offset from flash start address
• data: Pointer to data buffer to write
• len: Number of bytes to write

Requirements:

• Must handle any size/alignment of writes
• Must implement read-modify-write if needed
• Must work with minimum programmable unit size

Returns:

• 0 on success
• Negative value on failure

Lock Flash

void hal_flash_lock(void)

Re-enables flash write protection after operations.

Notes:

• Called after flash write/erase operations complete
• Restores flash controller to protected state
• Must reverse any changes made by hal_flash_unlock()

Erase Flash

int hal_flash_erase(uint32_t address, int len)

Erases a section of internal flash memory.

Parameters:

• address: Start address to erase (aligned to WOLFBOOT_SECTOR_SIZE)
• len: Number of bytes to erase (multiple of WOLFBOOT_SECTOR_SIZE)

Requirements:

• Must handle flash sector geometry
• Must erase all sectors in specified range
• Must use target's IAP interface

Returns:

• 0 on success
• Negative value on failure

Boot Preparation

void hal_prepare_boot(void)

Prepares system for firmware execution.

Called:

• Just before chain-loading firmware
• After all bootloader operations complete

Responsibilities:

• Restore default clock settings
• Reset modified peripherals
• Ensure clean hardware state for firmware

Optional HAL Extensions

External Flash Support

Enable with: make EXT_FLASH=1

This extension allows:

• Using external memory for UPDATE/SWAP partitions
• Custom handling of flash read operations
• Support for special flash interfaces

Configuration:

• PART_UPDATE_EXT: Store UPDATE partition in external memory
• PART_SWAP_EXT: Store SWAP partition in external memory

Important Notes:

• Incompatible with NVM_FLASH_WRITEONCE
• Requires implementing additional HAL functions
• Can be used for special flash handling needs

External Flash API

When EXT_FLASH=1 is enabled, the following functions must be implemented:

Write to External Flash

int ext_flash_write(uintptr_t address, const uint8_t *data, int len)

Writes data to external flash memory.

Parameters:

• address: Offset from external memory base address
• data: Pointer to data buffer to write
• len: Number of bytes to write

Requirements:

• Must follow same restrictions as hal_flash_write()
• Must handle device-specific protocols (e.g., SPI)

Returns:

• 0 on success
• Negative value on failure

Read from External Flash

int ext_flash_read(uintptr_t address, uint8_t *data, int len)

Reads data from external flash memory.

Parameters:

• address: Offset from external memory base address
• data: Buffer to store read data
• len: Number of bytes to read

Requirements:

• Must handle any size/alignment of reads
• Must implement device-specific read protocol

Returns:

• 0 on success
• Negative value on failure

Erase External Flash

int ext_flash_erase(uintptr_t address, int len)

Erases a section of external flash memory.

Parameters:

• address: Start address to erase
• len: Number of bytes to erase

Requirements:

• Must follow same restrictions as hal_flash_erase()
• Must handle device-specific sector geometry
• Must implement proper erase commands

Returns:

• 0 on success
• Negative value on failure

External Flash Protection

void ext_flash_lock(void)

Re-enables write protection for external flash.

Called:

• After external flash operations complete
• Before returning control to application

void ext_flash_unlock(void)

Disables write protection for external flash.

Called:

• Before external flash write/erase operations
• May be empty if device doesn't require unlocking

Dual-Bank Support

Some MCUs support hardware-assisted bank swapping for fail-safe updates. Enable with DUALBANK_SWAP=1.

Required Functions

void hal_flash_dualbank_swap(void)

Performs hardware bank swap operation.

Notes:

• Called to switch between flash banks
• May trigger system reboot
• Implementation is platform-specific
• May not return on some architectures

void fork_bootloader(void)

Manages bootloader redundancy across banks.

Responsibilities:

• Creates backup copy of bootloader if needed
• Ensures both banks have identical bootloader code
• Returns immediately if banks already match

Usage:

• Called during bank management operations
• Critical for fail-safe dual-bank operation
• Must be carefully implemented per platform