#include <stdint.h>
#include "can_frame.h"

Classes
struct	app_header
	Static definitions of the application. More...

Macros
#define	CHECKSUM_COUNT 4
	Number of 32-bit words in one checksum data.

Typedefs
typedef unsigned	bool
	Hack to allow compiling this code in C context too.

Enumerations
enum	BootloaderLed { LED_ACTIVE = 1 , LED_WRITING = 2 , LED_IDENT = 4 , LED_CSUM_ERROR = 8 , LED_REQUEST = 16 , LED_FRAME_LOST = 32 }
	Parametrizes the bootloader_led function with logical functions that can be assigned to physical LEDs. More...

Functions
void	bootloader_hw_set_to_safe (void)
	Initializes the hardware to a safe state of the outputs.

void	bootloader_hw_init (void)
	Called after hw_set_to_safe and after the bss and data segments are initialized.

bool	request_bootloader (void)

void	application_entry (void)
	Enters the application.

void	bootloader_reboot (void)
	Resets the microcontroller.

void	bootloader_led (enum BootloaderLed led, bool value)
	Sets status LEDs.

bool	read_can_frame (struct can_frame *frame)
	Checks if there is an incoming CAN frame from the hardware.

void	get_flash_boundaries (const void flash_min, const void flash_max, const struct app_header **app_header)
	Returns the boundaries of the user flash.

void	get_flash_page_info (const void address, const void page_start, uint32_t page_length_bytes)
	Rounds a flash address into a flash page.

void	erase_flash_page (const void *address)
	Erases the flash page at a specific address.

void	raw_erase_flash_page (const void *address)
	Erases the flash page at a specific address.

void	write_flash (const void address, const void data, uint32_t size_bytes)
	Writes data to the flash.

void	raw_write_flash (const void address, const void data, uint32_t size_bytes)
	Writes data to the flash.

uint16_t	flash_complete (void)
	Signals that the bootloading operation is complete.

void	checksum_data (const void data, uint32_t size, uint32_t checksum)
	Computes checksum over a block of data.

uint16_t	nmranet_alias (void)
	Suggests an NMRAnet CAN alias for use.

uint64_t	nmranet_nodeid (void)
	Callback from the bootloader to obtain the node-id to use.

Variables
static const uint32_t	REQUEST_BOOTLOADER = 0x76b89b1eU
	Write this value to __bootloader_magic_ptr and jump to the bootloader entry point in order to explicitly call the bootloader.

uint32_t	__bootloader_magic_ptr
	This is the place where REQUEST_BOOTLOADER has to be written before rebooting the MCU to force entering the bootloader.

Detailed Description

Copyright: Copyright (c) 2014, Balazs Racz All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Hardware support functions for bootloader operation.

Author: Balazs Racz

Date: 8 Dec 2014

Definition in file bootloader_hal.h.

Macro Definition Documentation

◆ CHECKSUM_COUNT

#define CHECKSUM_COUNT 4

Number of 32-bit words in one checksum data.

Definition at line 50 of file bootloader_hal.h.

Typedef Documentation

◆ bool

typedef unsigned bool

Hack to allow compiling this code in C context too.

Definition at line 46 of file bootloader_hal.h.

Enumeration Type Documentation

◆ BootloaderLed

enum BootloaderLed

Parametrizes the bootloader_led function with logical functions that can be assigned to physical LEDs.

Definition at line 75 of file bootloader_hal.h.

Function Documentation

◆ application_entry()

void application_entry ( void )

extern

Enters the application.

Never returns.

Enters the application.

This will default to reboot the ESP32.

Definition at line 169 of file Esp32BootloaderHal.hxx.

◆ bootloader_hw_init()

void bootloader_hw_init ( void )

extern

Called after hw_set_to_safe and after the bss and data segments are initialized.

Initializes the processor state, CAN hardware etc.

Called after hw_set_to_safe and after the bss and data segments are initialized.

Definition at line 144 of file Esp32BootloaderHal.hxx.

◆ bootloader_hw_set_to_safe()

void bootloader_hw_set_to_safe ( void )

extern

Initializes the hardware to a safe state of the outputs.

This function may not assume anything about previous hardware state. Also the memory layout is not yet initialized. (Do not use any static objects, and the DATA segment.)

This function should also disable interrupts.

◆ bootloader_led()

void bootloader_led	(	enum BootloaderLed	led,
		bool	value
	)

extern

Sets status LEDs.

Parameters

led	the logical function describing which LED to set.
value	is 1 to turn LED on, 0 to turn it off.

◆ bootloader_reboot()

void bootloader_reboot ( void )

extern

Resets the microcontroller.

Never returns.

Resets the microcontroller.

Currently a NO-OP.

Definition at line 184 of file Esp32BootloaderHal.hxx.

◆ checksum_data()

void checksum_data	(	const void *	data,
		uint32_t	size,
		uint32_t *	checksum
	)

extern

Computes checksum over a block of data.

Parameters

data	is the data to be checksummed.
size	is the number of bytes to checksum.
checksum	is a 16-byte array which will be filled with the checksum data. Unused entries have to be zeroed.

Computes checksum over a block of data.

Parameters

data	Start of block to calculate checksum for.
size	Number of bytes to calcuate checksum for.
checksum	Calculated checksum for the data block.

NOTE: The ESP32 does not use this method and will always set the checksum value to zero.

Definition at line 437 of file Esp32BootloaderHal.hxx.

◆ erase_flash_page()

void erase_flash_page ( const void * address )

extern

Erases the flash page at a specific address.

Blocks the caller until the flash erase is successful. (Microcontrollers often cannot execute code while the flash is being written or erased, so a polling mechanism would not help here too much.)

Parameters

address is the start address of a valid page, as returned by get_flash_page_info.

Erases the flash page at a specific address.

Parameters

address Flash address to erase.

NOTE: This is a NO-OP on the ESP32 as this is handled internally by the esp_ota_write() API.

Definition at line 276 of file Esp32BootloaderHal.hxx.

◆ flash_complete()

uint16_t flash_complete ( void )

extern

Signals that the bootloading operation is complete.

Returns: 0 upon success or an OpenLCB error code (e.g. 0x1000 for permanent error).

Signals that the bootloading operation is complete.

Returns: ERROR_CODE_OK (0x0000) if the firmware has been received and updated to be used for the next startup, otherwise ERROR_FIRMWARE_CSUM (0x2088) indicating there was a failure that may be recoverable by retrying.

Definition at line 406 of file Esp32BootloaderHal.hxx.

◆ get_flash_boundaries()

void get_flash_boundaries	(	const void **	flash_min,
		const void **	flash_max,
		const struct app_header **	app_header
	)

extern

Returns the boundaries of the user flash.

Parameters

flash_min	is set to the pointer of the first valid byte to be flashed.
flash_max	is set to the pointer of the last valid byte to be flashed.
app_header	is set to the pointer in the application flash where the application header is located.

Returns the boundaries of the user flash.

Parameters

flash_min	Minimum flash address to write to.
flash_max	Maximum flash address to write to.
app_header	Pointer to the app_header struct for the currently running firmware.

NOTE: This will default to set

Parameters

flash_min	to zero,
flash_max	to the partition size and
app_header	to a statically declared struct with only the size populated.

Definition at line 242 of file Esp32BootloaderHal.hxx.

◆ get_flash_page_info()

void get_flash_page_info	(	const void *	address,
		const void **	page_start,
		uint32_t *	page_length_bytes
	)

extern

Rounds a flash address into a flash page.

Parameters

address	is the address for which the page information is queried.
page_start	will be set to the first byte of that page.
page_length_bytes	is set to the number of bytes in that flash page.

In other words, *page_start <= address < (*page_start + *page_length_bytes).

Rounds a flash address into a flash page.

Parameters

address	Flash address to retrieve information on.
page_state	Starting address for the page.
page_length_bytes	Length of the page.

Definition at line 258 of file Esp32BootloaderHal.hxx.

◆ nmranet_alias()

uint16_t nmranet_alias ( void )

extern

Suggests an NMRAnet CAN alias for use.

If the running application has saved the last used alias, this function returns it.

Returns: the suggested alias.

Suggests an NMRAnet CAN alias for use.

Returns: zero to have the bootloader assign one based on the node-id.

Definition at line 449 of file Esp32BootloaderHal.hxx.

◆ nmranet_nodeid()

uint64_t nmranet_nodeid ( void )

extern

Callback from the bootloader to obtain the node-id to use.

Returns: the NMRAnet NodeID for this hardware node.; node-id provided to esp32_bootloader_run.

Definition at line 459 of file Esp32BootloaderHal.hxx.

◆ raw_erase_flash_page()

void raw_erase_flash_page ( const void * address )

extern

Erases the flash page at a specific address.

Blocks the caller until the flash erase is successful. (Microcontrollers often cannot execute code while the flash is being written or erased, so a polling mechanism would not help here too much.) Does NOT ensure that the reset vector is intact.

Parameters

address is the start address of a valid page, as returned by get_flash_page_info.

◆ raw_write_flash()

void raw_write_flash	(	const void *	address,
		const void *	data,
		uint32_t	size_bytes
	)

extern

Writes data to the flash.

Does NOT ensure that the reset vector is intact.

Parameters

address	is the location to write data to. Aligned to 4 bytes.
data	is the buffer to write data from.
size_bytes	is the total number of bytes to write. Has to be a multiple of 4.

◆ read_can_frame()

bool read_can_frame ( struct can_frame * frame )

extern

Checks if there is an incoming CAN frame from the hardware.

Parameters

frame will be loaded with the incoming frame.

Returns: true if a frame has arrived, false if no frame was loaded into frame.

Checks if there is an incoming CAN frame from the hardware.

Parameters

frame buffer for receiving a CAN frame into.

Returns: true when successful, false otherwise.

Definition at line 193 of file Esp32BootloaderHal.hxx.

◆ request_bootloader()

bool request_bootloader ( void )

extern

Returns: true if the hardware state requests entry to the bootloader. This will typically read a GPIO pin for a bootloader switch. This function will run after hw_init.

◆ write_flash()

void write_flash	(	const void *	address,
		const void *	data,
		uint32_t	size_bytes
	)

extern

Writes data to the flash.

Parameters

address	is the location to write data to. Aligned to 4 bytes.
data	is the buffer to write data from.
size_bytes	is the total number of bytes to write. Has to be a multiple of 4.

Writes data to the flash.

Parameters

address	Flash address to write to.
data	Buffer to write to flash.
size_bytes	Number of bytes to write to flash.

This method leverages the ESP32 OTA APIs to write the flash data. Upon writing to flash address zero (first address), the

Parameters

data	will be validated to ensure the firmware being received is applicable to the ESP32 and that it appears correct (has correct image magic byte). If the firmware is not applicable or otherwise corrupted for the first flash address the ESP32 will reboot to abort the bootloader download.

Definition at line 295 of file Esp32BootloaderHal.hxx.

Variable Documentation

◆ REQUEST_BOOTLOADER

const uint32_t REQUEST_BOOTLOADER = 0x76b89b1eU

static

Write this value to __bootloader_magic_ptr and jump to the bootloader entry point in order to explicitly call the bootloader.

Definition at line 93 of file bootloader_hal.h.

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ CHECKSUM_COUNT

Typedef Documentation

◆ bool

Enumeration Type Documentation

◆ BootloaderLed

Function Documentation

◆ application_entry()

◆ bootloader_hw_init()

◆ bootloader_hw_set_to_safe()

◆ bootloader_led()

◆ bootloader_reboot()

◆ checksum_data()

◆ erase_flash_page()

◆ flash_complete()

◆ get_flash_boundaries()

◆ get_flash_page_info()

◆ nmranet_alias()

◆ nmranet_nodeid()

◆ raw_erase_flash_page()

◆ raw_write_flash()

◆ read_can_frame()

◆ request_bootloader()

◆ write_flash()

Variable Documentation

◆ REQUEST_BOOTLOADER