mirror of https://github.com/wolfSSL/wolfBoot.git
106 lines
2.8 KiB
Markdown
106 lines
2.8 KiB
Markdown
# Application Interface for wolfBoot
|
|
|
|
wolfBoot provides an API through libwolfboot that allows applications to:
|
|
- Query firmware versions in both BOOT and UPDATE partitions
|
|
- Initiate firmware updates
|
|
- Confirm successful firmware boots
|
|
- Access partition states
|
|
|
|
## Compiling and Linking with libwolfboot
|
|
|
|
Applications using wolfBoot functionality must:
|
|
|
|
1. Include the wolfBoot header:
|
|
```c
|
|
#include <wolfboot/wolfboot.h>`
|
|
```
|
|
|
|
2. Link against libwolfboot library
|
|
|
|
The header provides:
|
|
- API function declarations
|
|
- Predefined partition flag values
|
|
- Image tag definitions
|
|
- Partition state constants
|
|
|
|
For details about flash partitions, flags and states see [Flash partitions](flash_partitions.md).
|
|
|
|
## Core API Functions
|
|
|
|
libwolfboot provides both high-level and low-level interfaces to manage firmware updates:
|
|
|
|
### High-Level Functions
|
|
|
|
```c
|
|
uint32_t wolfBoot_get_image_version(uint8_t part)
|
|
void wolfBoot_update_trigger(void)
|
|
void wolfBoot_success(void)
|
|
```
|
|
|
|
### Version Management Functions
|
|
|
|
#### Get Image Version
|
|
```c
|
|
uint32_t wolfBoot_get_image_version(uint8_t part)
|
|
```
|
|
Retrieves the version number of the firmware in the specified partition.
|
|
|
|
Parameters:
|
|
- `part`: Partition ID (PART_BOOT or PART_UPDATE)
|
|
|
|
Returns:
|
|
- Version number of the firmware in the specified partition
|
|
- 0 if no valid firmware exists in the partition
|
|
|
|
#### Convenience Macros
|
|
```c
|
|
wolfBoot_current_firmware_version() // Get version of firmware in BOOT partition
|
|
wolfBoot_update_firmware_version() // Get version of firmware in UPDATE partition
|
|
```
|
|
|
|
### Update Management Functions
|
|
|
|
#### Trigger Update
|
|
```c
|
|
void wolfBoot_update_trigger(void)
|
|
```
|
|
Initiates the firmware update process for the next boot.
|
|
|
|
Operation:
|
|
1. Sets UPDATE partition state to `STATE_UPDATING`
|
|
2. On next boot, wolfBoot will:
|
|
- Verify the update image signature
|
|
- Swap BOOT and UPDATE partition contents using SWAP space
|
|
- Set new firmware state to `STATE_TESTING`
|
|
- Boot into new firmware
|
|
|
|
Note: The update image must be stored in the UPDATE partition before calling this function.
|
|
|
|
### Boot Confirmation Functions
|
|
|
|
#### Confirm Successful Boot
|
|
```c
|
|
void wolfBoot_success(void)
|
|
```
|
|
Confirms successful boot of the current firmware.
|
|
|
|
Operation:
|
|
1. Marks current firmware in BOOT partition as `STATE_SUCCESS`
|
|
2. Prevents automatic rollback on next boot
|
|
|
|
Important:
|
|
- Should be called only after verifying critical system functionality
|
|
- Recommended to verify:
|
|
- Core system features work correctly
|
|
- Update capability is functional
|
|
- Any required peripherals are accessible
|
|
|
|
Rollback Behavior:
|
|
- If firmware remains in `STATE_TESTING` state after reboot
|
|
- wolfBoot will automatically rollback to previous version
|
|
- Accomplished by re-swapping BOOT and UPDATE partitions
|
|
|
|
Related Documentation:
|
|
- [Firmware Update Process](firmware_update.md)
|
|
- [Firmware Image Format](firmware_image.md)
|