bootloader Firmware More...

Collaboration diagram for Bootloader:

Classes
struct	BootCanTiming
	Selection for the supported CAN Bitrates. More...

struct	CanSettings
	CAN Settings. More...

struct	Boot_CanMessage
	CAN message structure. More...

struct	BootloaderDatagram
	Datagram message definition. More...

Macros
#define	CAN_HW_BASE CAN1

#define	ACK 0U
	ACK defined as 0.

#define	NACK 1U
	NACK defined as 1.

#define	DGRAM_MAX_MSG_SIZE 8
	Max message size of datagram.

#define	BYTES_TO_WORD(bytes) (bytes / 4)
	Convert bytes to number of words for ARM32 system.

#define	ALLIGNMENT_SIZE 4

#define	NUM_FLASH_PAGES 128U
	256KB of memory / 2KB per page

#define	BOOTLOADER_PAGE_BYTES ((size_t)0x800)
	2KB per flash page as per datasheet

#define	BOOTLOADER_PING_BYTES ((size_t)0x1000)
	4KB max per ping

#define	BOOTLOADER_FLASH_WORD_SIZE 4U
	ARM32 Word size is 4 bytes.

#define	BOOTLOADER_ADDR_TO_PAGE(addr) (((uintptr_t)(addr) - (uintptr_t)APP_ACTIVE_START_ADDRESS) / BOOTLOADER_PAGE_BYTES)
	Convert memory address to page number. More...

#define	BOOTLOADER_PAGE_TO_ADDR(page) ((uintptr_t)(page) * (uintptr_t)BOOTLOADER_PAGE_BYTES + (uintptr_t)APP_ACTIVE_START_ADDRESS)
	Convert page number to memory address. More...

#define	FLASH_START_ADDRESS_LINKERSCRIPT ((uint32_t) & _flash_start)
	Flash start address as defined in the linkerscripts.

#define	FLASH_SIZE_LINKERSCRIPT ((size_t) & _flash_size)
	Flash size as defined in the linkerscripts.

#define	FLASH_PAGE_SIZE_LINKERSCRIPT ((size_t) & _flash_page_size)
	Flash page size as defined in the linkerscripts.

#define	APP_ACTIVE_START_ADDRESS ((uint32_t) & _app_active_start)
	Application Active start address as defined in the linkerscripts.

#define	APP_ACTIVE_SIZE ((size_t) & _app_active_size)
	Application Active size as defined in the linkerscripts.

#define	APP_STAGING_START_ADDRESS ((uint32_t) & _app_staging_start)
	Application Staging start address as defined in the linkerscripts.

#define	APP_STAGING_SIZE ((size_t) & _app_staging_size)
	Application Staging size as defined in the linkerscripts.

#define	BOOTLOADER_START_ADDRESS ((uint32_t) & _bootloader_start)
	Bootloader start address as defined in the linkerscripts.

#define	BOOTLOADER_SIZE ((size_t) & _bootloader_size)
	Bootloader size as defined in the linkerscripts.

#define	BOOTSTRAP_START_ADDRESS ((uint32_t) & _bootstrap_start)
	Bootstrap start address as defined in the linkerscripts.

#define	BOOTSTRAP_SIZE ((size_t) & _bootstrap_size)
	Bootstrap size as defined in the linkerscripts.

#define	FS_STORAGE_START_ADDRESS ((uint32_t) & _fs_storage_start)
	File System Storage start address as defined in the linkerscripts.

#define	FS_STORAGE_SIZE ((size_t) & _fs_storage_size)
	File System Storage size as defined in the linkerscripts.

#define	SRAM_START_ADDRESS ((uint32_t) & _sram_start)
	SRAM start address as defined in the linkerscripts.

#define	SRAM_SIZE ((size_t) & _sram_size)
	SRAM size as defined in the linkerscripts.

Typedefs
typedef struct CanSettings	Boot_CanSettings
	CAN Settings. More...

Enumerations
enum	BootloaderStates { BOOTLOADER_UNINITIALIZED = 0 , BOOTLOADER_IDLE , BOOTLOADER_START , BOOTLOADER_WAIT_SEQUENCING , BOOTLOADER_DATA_RECEIVE , BOOTLOADER_JUMP_APP , BOOTLOADER_FAULT , BOOTLOADER_PING }
	Bootloader State Machine. More...

enum	BootloaderPingStates { BOOTLOADER_PING_NODES = 0 , BOOTLOADER_PING_BRANCH , BOOTLOADER_PING_PROJECT }
	Bootloader Ping States. More...

enum	Boot_CanBitrate { BOOT_CAN_BITRATE_125KBPS , BOOT_CAN_BITRATE_250KBPS , BOOT_CAN_BITRATE_500KBPS , BOOT_CAN_BITRATE_1000KBPS , NUM_BOOT_CAN_BITRATES }

enum	Boot_CanMode { CAN_CONTINUOUS = 0 , CAN_ONE_SHOT_MODE , NUM_CAN_MODES , CAN_CONTINUOUS = 0 , CAN_ONE_SHOT_MODE , NUM_CAN_MODES }

enum	BootloaderCanID { BOOTLOADER_CAN_SEQUENCING_ID = 30 , BOOTLOADER_CAN_FLASH_ID , BOOTLOADER_CAN_JUMP_APPLICATION_ID , BOOTLOADER_CAN_ACK_ID , BOOTLOADER_CAN_START_ID , BOOTLOADER_CAN_JUMP_BOOTLOADER , BOOTLOADER_CAN_PING_METADATA_ID , BOOTLOADER_CAN_PING_DATA_ID }
	Bootloader reserved CAN arbitration IDs. More...

enum	BootloaderError { BOOTLOADER_ERROR_NONE = 0 , BOOTLOADER_OVERSIZE , BOOTLOADER_DATA_NOT_ALIGNED , BOOTLOADER_INVALID_ID , BOOTLOADER_INTERNAL_ERR , BOOTLOADER_INVALID_ARGS , BOOTLOADER_ERROR_UNINITIALIZED , BOOTLOADER_FLASH_ERR , BOOTLOADER_FLASH_WRITE_NOT_ALIGNED , BOOTLOADER_FLASH_WRITE_OUT_OF_BOUNDS , BOOTLOADER_FLASH_READ_FAILED , BOOTLOADER_BUFFER_OVERFLOW , BOOTLOADER_CAN_INIT_ERR , BOOLOADER_CAN_TRANSMISSION_ERROR , BOOTLOADER_CAN_RECEIVE_ERROR , BOOTLOADER_CAN_TRANSMIT_ERROR , BOOTLOADER_INVALID_ADDRESS , BOOTLOADER_CRC_MISMATCH_BEFORE_WRITE , BOOTLOADER_CRC_MISMATCH_AFTER_WRITE , BOOTLOADER_SEQUENCE_ERROR , BOOTLOADER_TIMEOUT , BOOTLOADER_FLASH_MEMORY_VERIFY_FAILED , BOOTLOADER_PING_TIMEOUT }
	Bootloader error definitions. More...

Functions
BootloaderError	bootloader_init (void)
	Initialize the bootloader. More...

BootloaderError	bootloader_run (Boot_CanMessage *msg)
	Run the bootloader. More...

BootloaderError	bootloader_jump_app (void)
	Jump application. More...

BootloaderError	boot_can_init (const Boot_CanSettings *settings)
	Initialize the CAN interface for the bootloader. More...

BootloaderError	boot_can_transmit (uint32_t id, bool extended, const uint8_t *data, size_t len)
	Transmit a CAN message in the bootloader. More...

BootloaderError	boot_can_receive (Boot_CanMessage *const msg)
	Receive a CAN message in the bootloader. More...

BootloaderDatagram	deserialize_datagram (Boot_CanMessage msg, uint16_t target_nodes)
	Deserialize an incoming CAN message. More...

void	send_ack_datagram (bool ack, BootloaderError error)
	Send Bootloader ACK/NACK message over CAN. More...

BootloaderError	boot_crc32_init (void)
	Initialize the CRC hardware component. More...

uint32_t	boot_crc32_calculate (const uint32_t *buffer, size_t buffer_len)
	Calculate a CRC32 on a provided data buffer. More...

void	boot_align_to_32bit_words (uint8_t buffer, size_t buffer_len)
	Align a provided data buffer to the 4-byte boundary. More...

BootloaderError	boot_flash_write (uintptr_t address, uint8_t *buffer, size_t buffer_len)
	Write to flash memory. More...

BootloaderError	boot_flash_erase (uint8_t start_page, uint8_t num_pages)
	Erase some number of flash pages. More...

BootloaderError	boot_flash_read (uintptr_t address, uint8_t *buffer, size_t buffer_len)
	Read from flash memory. More...

BootloaderError	boot_verify_flash_memory (void)
	Verify that the flash memory is not erased. More...

void	protect_bootloader_memory (uint32_t bootloader_start_address, uint32_t bootloader_size)
	Protect the bootloader memory provided the bootloaders start address and size. More...

Variables
uint32_t	_flash_start

uint32_t	_flash_size

uint32_t	_flash_page_size

uint32_t	_bootstrap_start

uint32_t	_bootstrap_size

uint32_t	_bootloader_start

uint32_t	_bootloader_size

uint32_t	_app_active_start

uint32_t	_app_active_size

uint32_t	_app_staging_start

uint32_t	_app_staging_size

uint32_t	_fs_storage_start

uint32_t	_fs_storage_size

uint32_t	_sram_start

uint32_t	_sram_size

Detailed Description

bootloader Firmware

Macro Definition Documentation

◆ ALLIGNMENT_SIZE

#define ALLIGNMENT_SIZE 4

The data buffer allignment size

◆ BOOTLOADER_ADDR_TO_PAGE

#define BOOTLOADER_ADDR_TO_PAGE ( addr ) (((uintptr_t)(addr) - (uintptr_t)APP_ACTIVE_START_ADDRESS) / BOOTLOADER_PAGE_BYTES)

Convert memory address to page number.

Parameters

addr	Address to be converted to page number

Returns: Page number

◆ BOOTLOADER_PAGE_TO_ADDR

#define BOOTLOADER_PAGE_TO_ADDR ( page ) ((uintptr_t)(page) * (uintptr_t)BOOTLOADER_PAGE_BYTES + (uintptr_t)APP_ACTIVE_START_ADDRESS)

Convert page number to memory address.

Parameters

page	Page number

Returns: 32-bit address

Typedef Documentation

◆ Boot_CanSettings

typedef struct CanSettings Boot_CanSettings

CAN Settings.

TX Pin will transmit data. RX pin will receive data. The bitrate is the number of bits sent per second. The device ID is the CAN ID of the STM32 node. Loopback will internally connect the transmit and receive CAN lines for testing. Silent mode is used for only listening to the bus.

Enumeration Type Documentation

◆ Boot_CanBitrate

enum Boot_CanBitrate

Enumerator
BOOT_CAN_BITRATE_125KBPS	125 KBits per second
BOOT_CAN_BITRATE_250KBPS	250 KBits per second
BOOT_CAN_BITRATE_500KBPS	500 KBits per second
BOOT_CAN_BITRATE_1000KBPS	1000 KBits per second
NUM_BOOT_CAN_BITRATES	Number of supported bit rates

◆ BootloaderCanID

enum BootloaderCanID

Bootloader reserved CAN arbitration IDs.

Enumerator
BOOTLOADER_CAN_SEQUENCING_ID	Data sequencing command (Highest priority)
BOOTLOADER_CAN_FLASH_ID	Incoming flash data command
BOOTLOADER_CAN_JUMP_APPLICATION_ID	Jump to application command
BOOTLOADER_CAN_ACK_ID	Bootloader ACK/NACK message
BOOTLOADER_CAN_START_ID	Start DFU command
BOOTLOADER_CAN_JUMP_BOOTLOADER	Jump to bootloader command
BOOTLOADER_CAN_PING_METADATA_ID	Incoming ping metadata
BOOTLOADER_CAN_PING_DATA_ID	Incoming ping data

◆ BootloaderError

enum BootloaderError

Bootloader error definitions.

Enumerator
BOOTLOADER_ERROR_NONE	No error is detected
BOOTLOADER_OVERSIZE	More data is received than expected
BOOTLOADER_DATA_NOT_ALIGNED	Data is not 4-byte aligned as per ARM32 spec
BOOTLOADER_INVALID_ID	Invalid authenication ID
BOOTLOADER_INTERNAL_ERR	Unidentified internal controller error
BOOTLOADER_INVALID_ARGS	Invalid arguments are passed into the bootloader
BOOTLOADER_ERROR_UNINITIALIZED	Bootloader is uninitialized
BOOTLOADER_FLASH_ERR	Flash write or erase failure
BOOTLOADER_FLASH_WRITE_NOT_ALIGNED	Bootloader flash write is not aligned
BOOTLOADER_FLASH_WRITE_OUT_OF_BOUNDS	Bootloader flash write adddress is out of bounds
BOOTLOADER_FLASH_READ_FAILED	Bootloader flash read failed
BOOTLOADER_BUFFER_OVERFLOW	Bootloader flash buffer has overflowed (More than 2048 bytes)
BOOTLOADER_CAN_INIT_ERR	Bootloader CAN initialization failed
BOOLOADER_CAN_TRANSMISSION_ERROR	CAN Bus transmission failed
BOOTLOADER_CAN_RECEIVE_ERROR	CAN Bus receive failed
BOOTLOADER_CAN_TRANSMIT_ERROR	CAN Bus receive failed
BOOTLOADER_INVALID_ADDRESS	Attempted to write/read to an incorrect address
BOOTLOADER_CRC_MISMATCH_BEFORE_WRITE	Bootloader has detected a CRC32 mismatch before writing to flash
BOOTLOADER_CRC_MISMATCH_AFTER_WRITE	Bootloader has detected a CRC32 mismatch after writing to flash
BOOTLOADER_SEQUENCE_ERROR	Bootloader has received an incorrect sequence number
BOOTLOADER_TIMEOUT	Bootloader has timed out
BOOTLOADER_FLASH_MEMORY_VERIFY_FAILED	Bootloader flash memory verification failed. Everything is still erased
BOOTLOADER_PING_TIMEOUT	Bootloader ping timed out

◆ BootloaderPingStates

enum BootloaderPingStates

Bootloader Ping States.

Enumerator
BOOTLOADER_PING_NODES	Bootloader should start pinging MCU's.
BOOTLOADER_PING_BRANCH	Bootloader ping should do branch stuff.
BOOTLOADER_PING_PROJECT	Bootloader ping should do group stuff.

◆ BootloaderStates

enum BootloaderStates

Bootloader State Machine.

Enumerator
BOOTLOADER_UNINITIALIZED	Bootloader starts as unitialized
BOOTLOADER_IDLE	Bootloader is initialized and waiting for messages
BOOTLOADER_START	Bootloader is processing a start message
BOOTLOADER_WAIT_SEQUENCING	Bootloader is waiting for the data sequencing packet
BOOTLOADER_DATA_RECEIVE	Bootloader is receiving streamed data and flashing it in 2048 byte chunks
BOOTLOADER_JUMP_APP	Bootloader is prompted to jump to application defined by APP_ACTIVE_START_ADDRESS
BOOTLOADER_FAULT	Bootloader is in fault state
BOOTLOADER_PING	Bootloader is ready to start receiving data

Function Documentation

◆ boot_align_to_32bit_words()

void boot_align_to_32bit_words	(	uint8_t *	buffer,
		size_t *	buffer_len
	)

Align a provided data buffer to the 4-byte boundary.

This prevents hard faults when writing to flash memory, ensuring all our flash is 4-byte aligned

Parameters

buffer	Pointer to the data buffer to be aligned
buffer_len	Length of the data buffer

◆ boot_can_init()

BootloaderError boot_can_init ( const Boot_CanSettings * settings )

Initialize the CAN interface for the bootloader.

Returns: BOOTLOADER_ERROR_NONE if the interface is initialized successfully BOOTLOADER_CAN_INIT_ERR if initialization fails

◆ boot_can_receive()

BootloaderError boot_can_receive ( Boot_CanMessage *const msg )

Receive a CAN message in the bootloader.

Parameters

msg	Pointer to the message that will be updated with incoming data

Returns: BOOTLOADER_ERROR_NONE if the message is received successfully BOOTLOADER_CAN_RECEIVE_ERROR if receiving the message fails

◆ boot_can_transmit()

BootloaderError boot_can_transmit	(	uint32_t	id,
		bool	extended,
		const uint8_t *	data,
		size_t	len
	)

Transmit a CAN message in the bootloader.

Parameters

id	CAN Message arbitration Id
extended	Boolean flag to select 11-bit vs 29-bit CAN transmission
data	Pointer to the data buffer to transmit
len	Length of the data buffer

Returns: BOOTLOADER_ERROR_NONE if the message is transmitted successfully BOOLOADER_CAN_TRANSMISSION_ERROR if transmitting the message fails

◆ boot_crc32_calculate()

uint32_t boot_crc32_calculate	(	const uint32_t *	buffer,
		size_t	buffer_len
	)

Calculate a CRC32 on a provided data buffer.

Parameters

buffer	Pointer to the data buffer to be checksummed
buffer_len	Length of the data buffer

Returns: Calculated 32-bit CRC value

◆ boot_crc32_init()

BootloaderError boot_crc32_init ( void )

Initialize the CRC hardware component.

Returns: BOOTLOADER_ERROR_NONE if initialized successfully

◆ boot_flash_erase()

BootloaderError boot_flash_erase	(	uint8_t	start_page,
		uint8_t	num_pages
	)

Erase some number of flash pages.

Parameters

start_page	Initial page number to erase
num_pages	Number of pages to erase

Returns: BOOTLOADER_ERROR_NONE if data is erased successfully BOOTLOADER_FLASH_ERR if page is out of bounds OR erasing failed

◆ boot_flash_read()

BootloaderError boot_flash_read	(	uintptr_t	address,
		uint8_t *	buffer,
		size_t	buffer_len
	)

Read from flash memory.

Parameters

address	Base memory address to read from
buffer	Pointer to the data buffer
buffer_len	Length of the data buffer

Returns: BOOTLOADER_ERROR_NONE if data is read successfully BOOTLOADER_FLASH_READ_FAILED if data read failed

◆ boot_flash_write()

BootloaderError boot_flash_write	(	uintptr_t	address,
		uint8_t *	buffer,
		size_t	buffer_len
	)

Write to flash memory.

Parameters

address	Base memory address to write to
buffer	Pointer to the data buffer
buffer_len	Length of the data buffer

Returns: BOOTLOADER_ERROR_NONE if data is written successfully BOOTLOADER_FLASH_WRITE_OUT_OF_BOUNDS if address is out of bounds BOOTLOADER_FLASH_WRITE_NOT_ALIGNED if data is not aligned

◆ boot_verify_flash_memory()

BootloaderError boot_verify_flash_memory ( void )

Verify that the flash memory is not erased.

This checks the entire application flash memory to ensure it is not entirely erased

Returns: BOOTLOADER_ERROR_NONE if the memomry is valid BOOTLOADER_FLASH_ERR if the memory is corrupt

◆ bootloader_init()

BootloaderError bootloader_init ( void )

Initialize the bootloader.

Returns: BOOTLOADER_ERROR_NONE if the bootloader is initialized successfully

◆ bootloader_jump_app()

BootloaderError bootloader_jump_app ( void )

Jump application.

Exits bootloader and jumps to main application

Returns: BOOTLOADER_INTERNAL_ERR. This function should never return

◆ bootloader_run()

BootloaderError bootloader_run ( Boot_CanMessage * msg )

Run the bootloader.

Parameters

msg	Pointer to incoming CAN data to feed the bootloader

Returns: BootloaderError collected through the state machine

◆ deserialize_datagram()

BootloaderDatagram deserialize_datagram	(	Boot_CanMessage *	msg,
		uint16_t *	target_nodes
	)

Deserialize an incoming CAN message.

This will deserialize a CAN message and produce a datagram

Parameters

msg	Pointer to the incoming CAN message
target_nodes	Pointer that will be updated with the target MCU Id

Returns: Updated datagram with new data

◆ protect_bootloader_memory()

void protect_bootloader_memory	(	uint32_t	bootloader_start_address,
		uint32_t	bootloader_size
	)

Protect the bootloader memory provided the bootloaders start address and size.

Parameters

bootloader_start_address	The start address defined in the linkerscript
bootloader_size	The bootloader size defined in the linkerscript

◆ send_ack_datagram()

void send_ack_datagram	(	bool	ack,
		BootloaderError	error
	)

Send Bootloader ACK/NACK message over CAN.

Parameters

ack	Boolean ACK status. 0: ACK, 1: NACK
error	Bootloader error status for further information

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ ALLIGNMENT_SIZE

◆ BOOTLOADER_ADDR_TO_PAGE

◆ BOOTLOADER_PAGE_TO_ADDR

Typedef Documentation

◆ Boot_CanSettings

Enumeration Type Documentation

◆ Boot_CanBitrate

◆ BootloaderCanID

◆ BootloaderError

◆ BootloaderPingStates

◆ BootloaderStates

Function Documentation

◆ boot_align_to_32bit_words()

◆ boot_can_init()

◆ boot_can_receive()

◆ boot_can_transmit()

◆ boot_crc32_calculate()

◆ boot_crc32_init()

◆ boot_flash_erase()

◆ boot_flash_read()

◆ boot_flash_write()

◆ boot_verify_flash_memory()

◆ bootloader_init()

◆ bootloader_jump_app()

◆ bootloader_run()

◆ deserialize_datagram()

◆ protect_bootloader_memory()

◆ send_ack_datagram()