Bootloader

Bootloader Overview

A bootloader is a small piece of software that runs before the operating system starts. Its primary role is to initialize hardware and load the operating system or firmware into memory. Bootloaders are a critical component in embedded systems, microcontrollers, and general computing environments.

Supported bootloader interfaces

The following interfaces are supported:

User selection Interface
CAN Interface
USB Interface
UART Interface
Cloud Interface

Application Interface

The below table captures the functions that are to be called from the application layer.

API Functions
Function	Description
rs_bl_init	To open the bootloader.
rs_bl_set_config	To configure the bootloader.
rs_bl_msg_queue_init	To initialize the message queue for bootloader.
rs_bl_push_data_to_queue	To push the data to the queue.
rs_bl_pop_data_from_queue	To pop the data from the queue
rs_bl_check_for_update	To check for the update availability.
rs_bl_set_state	To set the bootloader instance to the specified state.
rs_bl_state_machine	To execute the application validation and binary download process

Error Code

Every API’s for the bootloader returns some success or failure values. Please refer below section,

RAPIDSEA ERROR CODES

Implementation Guide

This section explains how to implement the bootloader using the RAPIDSEA stack, the steps to be followed are

Configure the bootloader information.
Initialize the bootloader with the instance and config structure.
Then initialize the message queue
Push the data to the queue and pop the data from the queue.

Note:

The configurations are done by loading the provided bootloader config structure(rs_bl_config_t) from the application layer.

Bootloader Header Details

Documentation from the relevant header as follows:

Bootloader Specific APIs.

Defines macros and functions specific to Bootloader functionality

Author: Embien RAPIDSEA Team
Copyright: Embien Technologies India Pvt. Ltd.

Defines

RS_BL_FIRMWARE_HASH_SIZE: Firmware validation parameters size Firmware hash size

RS_BL_FIRMWARE_SIGNATURE_SIZE: Firmware signature size

RS_BL_FIRMWARE_DOWNLOAD_LINK_SIZE: Firmware download link size

RS_BL_MQTT_HOST_NAME_SIZE: Firmware download link size

RS_BL_MQTT_ACCESS_TOKEN_LEN: Maximum size of mqtt connect token

RS_BL_FW_UPDATE_TRIGGER: Flag to set firmware update triggered Trigger for firmware update

RS_BL_READ_BINARY_HEADER: Bl file download State machine values Stage 0: Read binary header

RS_BL_VALIDATE_HEADER: Stage 1: Validate header.

RS_BL_DOWNLOAD_BINARY: Stage 2: Download binary

RS_BL_PROGRAM_BINARY: Stage 3: Program binary.

RS_BL_PROGRAM_BINARY_DONE: Stage 4: Binary programming completed.

RS_BL_VALIDATE_BINARY: Stage 5: Validate binary

RS_BL_CLOSE_CONNECTORS: Stage 6: Close connectors

RS_BL_JUMP_APPLICATION: Stage 7: Jump to application.

RS_BL_MAX_DOWNLOAD_JUNK: Maximum size of downloaded junk data.

RS_BL_FIRMWARE_TAG_SIZE: Tag size.

RS_BL_STATUS_FILE_DOWNLOAD_INITIATED: File download status File download initiated

RS_BL_STATUS_FILE_DOWNLOAD_PROCESS_STARTED: File download process started.

RS_BL_STATUS_FILE_DOWNLOAD_SUCCESS: File download successful.

RS_BL_STATUS_FILE_VAlIDATED_SUCCESSFULLY: File validated successfully.

RS_BL_STATUS_FILE_VAlIDATION_FAILED: File validation failed.

RS_BL_APP_VECTOR_TABLE: Address of the application vector table in memory.

Typedefs

typedef struct tag_rs_bl_firmware_info rs_bl_firmware_info_t: Struct representing firmware information.

typedef struct tag_rs_bl_application_header rs_bl_application_header_t: Struct representing the bootloader application header.

typedef struct tag_rs_bl_fw_download_info rs_bl_download_info_t: Struct representing firmware download information in the bootloader.

typedef struct tag_rs_bl_config rs_bl_config_t: Struct representing bootloader configuration information.

typedef struct tag_rs_bl_instance rs_bl_instance_t: Struct representing bootloader instance information.

Enums

enum rs_bl_authentication_type_t

Enum representing different bootloader authentication types.

Values:

enumerator BL_CRC_VALIDATION: CRC validation.

enumerator BL_HASH_VALIDATION: Hash validation

enumerator BL_RSA_SIGN_VALIDATION: RSA signature validation.

enumerator BL_RSA_AES_CBC_VALIDATION: RSA + AES CBC validation.

enumerator BL_RSA_AES_ECB_VALIDATION: RSA + AES ECB validation.

Functions

rs_ret_val_t rs_bl_init(rs_bl_instance_t *ptr_instance, rs_bl_config_t *ptr_config)

Initializes the bootloader with the provided instance and configuration.

This function performs the necessary initialization steps to set up the bootloader instance.

Parameters:

ptr_bl_instance – [out] - Pointer to the bootloader instance structure.
ptr_config – [in] - Pointer to the bootloader configuration structure.

Returns:

0 on success or error code on failure

rs_ret_val_t rs_bl_set_config(rs_bl_config_t *ptr_config, uint32_t u32_application_fw_header_addr, uint32_t u32_application_fw_addr, uint32_t u32_fw_header_size, uint32_t u32_downloaded_image_addr, uint8_t u8_mqtt_state, uint8_t *ptr_token)

rs_ret_val_t rs_bl_set_state(rs_bl_instance_t *ptr_bl_instance, uint8_t u8_state)

Sets the state of the bootloader instance.

This function sets the bootloader instance to the specified state.

Parameters:

ptr_bl_instance – [out] - Pointer to the bootloader instance structure.
u8_state – [in] - The state to set the bootloader instance to.

Returns:

0 on success or error code on failure

rs_ret_val_t rs_bl_state_machine(rs_bl_instance_t *ptr_bl_instance)

Execute the application validation and binary download process.

This function is to execute the application validation and binary download process

Parameters:: ptr_bl_instance – [in] - Pointer to the bootloader instance structure.
Returns:: 0 on success or error code on failure

rs_ret_val_t rs_bl_push_data_to_queue(uint8_t *ptr_data, uint32_t u32_len)

Copy data to the msg queue.

This function pushes and stores data into msg queue.

Parameters:

ptr_data – [in] - Pointer to the input data.
u32_len – [in] - length of the input data.

Returns:

0 on success or error code on failure

rs_ret_val_t rs_bl_msg_queue_init()

Initializes the msg queue.

This function initializes the msg queue.

Returns:: 0 on success or error code on failure

rs_ret_val_t rs_bl_pop_data_from_queue(uint8_t *ptr_data, uint32_t *u32_len)

Initializes the msg queue.

This function initializes the msg queue.

Parameters:

ptr_data – [out] - Pointer to the output data.
u32_len – [out] - length of the output data.

Returns:

0 on success or error code on failure

rs_ret_val_t rs_bl_err_handler(uint8_t *ptr_data)

Error handling method.

This function gets lock in the while condition.

Parameters:: ptr_data – [in] - pointer to the data
Returns:: 0 on success or error code on failure

rs_ret_val_t rs_bl_check_for_update(rs_bl_instance_t *ptr_bl_instance)

Check for the update availability.

This function is to check if any firmware update available.

Parameters:: ptr_bl_instance – [in] - Pointer to the bootloader instance structure.
Returns:: 0 on success or error code on failure

struct tag_rs_bl_firmware_info

#include <rs_bootloader.h>

Struct representing firmware information.

Public Members

uint32_t u32_firmware_size: Firmware size (bytes)

uint8_t u8_major_number: Major number.

uint8_t u8_minor_number: Minor number.

uint8_t u8_version: Version number.

uint8_t u8_reserved: Reserved byte.

struct tag_rs_bl_application_header

#include <rs_bootloader.h>

Struct representing the bootloader application header.

Public Members

uint32_t u32_magic_number: Magic Number ‘0x11223344’to identify the firmware header.

rs_bl_firmware_info_t firmware_info: Firmware information.

uint32_t bl_authentication_type: Security Type; None - no security, 1 - RSA authentication ,2 - RSA + AES authentication.

uint32_t u32_crc: CRC value for firmware validation.

struct tag_rs_bl_fw_download_info

#include <rs_bootloader.h>

Struct representing firmware download information in the bootloader.

Public Members

uint8_t u8_is_fw_update_triggered: Flag to indicate if firmware update has been triggered.

uint8_t u8_fw_download_mode: Firmware download mode.

uint16_t u16_reserved: Reserved space.

rs_bl_firmware_info_t firmware_info: Firmware information.

uint8_t fw_download_link[RS_BL_FIRMWARE_DOWNLOAD_LINK_SIZE]: Firmware link to download.

uint8_t mqtt_host_name[RS_BL_MQTT_HOST_NAME_SIZE]: MQTT host name.

uint8_t reserved[308]: Reserved space.

struct tag_rs_bl_config

#include <rs_bootloader.h>

Struct representing bootloader configuration information.

Public Members

uint32_t u32_application_fw_header_addr: Address of the application firmware header.

uint32_t u32_fw_header_size: Size of the firmware header.

uint32_t u32_application_fw_addr: Address of the application firmware.

uint32_t u32_downloaded_image_addr: Address where the downloaded image is stored.

uint8_t u8_is_mqtt_enable: Enable/Disable MQTT.

uint8_t *mqtt_access_token: MQTT connect access token.

struct tag_rs_bl_instance

#include <rs_bootloader.h>

Struct representing bootloader instance information.

Public Members

rs_bl_config_t *ptr_config: Pointer to the bootloader configuration.

uint8_t u8_bl_state: Current state of the bootloader.

rs_bl_application_header_t app_header: Application header structure.

uint8_t u8_fw_update_interface_type: Firmware update interface type.

uint32_t u32_application_programming_addr: Address where the application is being programmed.

uint32_t u32_application_programming_size: Size of the application being programmed.

uint32_t u32_remaining_application_size: Remaining size of the application to be programmed.

uint32_t u32_firmware_size: Total size of the firmware.

uint8_t u8_bl_fmw_download_status: Bootloader firmware download status.

uint8_t *ptr_bianry_data: Pointer to the binary data for the firmware.

rs_handle_t flash_handle: Handle for the flash memory.

uint8_t u8_download_file_data[RS_BL_MAX_DOWNLOAD_JUNK]: Buffer for downloaded file data.

rs_bl_download_info_t bl_download_info: Firmware download information.