#include <string.h>
#include <unistd.h>
#include "freertos/bootloader_hal.h"
#include "openlcb/Defs.hxx"
#include "openlcb/CanDefs.hxx"
#include "openlcb/DatagramDefs.hxx"
#include "openlcb/MemoryConfig.hxx"
#include "openlcb/ApplicationChecksum.hxx"
#include "can_frame.h"

Classes
struct	openlcb::BootloaderState
	Internal state of the bootloader stack. More...

Namespaces
namespace	openlcb

Macros
#define	_OPENLCB_BOOTLOADER_HXX_
	include guard macro

#define	FLASH_SPACE (MemoryConfigDefs::SPACE_FIRMWARE)
	Which OpenLCB Memory Config Space number should the bootloader export.

#define	STREAM_ID 0x5A
	local stream ID.

#define	PIP_REPLY_VALUE
	Protocol support bitmask that the bootloader should export.

Enumerations
enum	openlcb::InitState { PICK_ALIAS = 0 , SEND_CID_7 , SEND_CID_6 , SEND_CID_5 , SEND_CID_4 , WAIT_RID , SEND_RID , SEND_AMD , SEND_NMRANET_INIT , INITIALIZED }
	State machine states for initializing the bootloader node. More...

Functions
void	reset_stream_state ()
	Clears out the stream state in state_.

void	setup_can_frame ()
	Prepares the outgoing frame buffer for a frame to be sent.

void	set_can_frame_global (Defs::MTI mti)
	Sets up the outgoing frame buffer for a global OpenLCB packet.

void	set_can_frame_addressed (Defs::MTI mti, NodeAlias alias=CanDefs::get_src(GET_CAN_FRAME_ID_EFF(state_.input_frame)))
	Sets the outgoing CAN frame to addressed, destination taken from the source field of the incoming message or the given alias.

void	set_can_frame_nodeid ()
	Adds the node id ad the data payload of the outgoing can frame.

bool	is_can_frame_nodeid ()
	Checks whether the incoming frame contains the current (bootloader) node's node_id as the data payload.

void	set_error_code (uint16_t error_code)
	Sets output frame dlc to 4; adds the given error code to bytes 2 and 3.

void	reject_datagram ()
	Kills the input frame and sends back a datagram rejected error message with permanent error.

uint32_t	load_uint32_be (const uint8_t *ptr)
	Loads an unaligned 32-bit value that is network-endian.

void	add_memory_config_error_response (uint16_t error_code)
	turns an already prepared memory config response datagram into an error response.

void	init_flash_write_buffer ()
	Clears out the flash write buffer with all 0xFF values.

bool	normalize_write_buffer_offset ()
	Translates from the logical address space of the OpenLCB memory config protocol memory space to the physical address space in the flash.

void	flush_flash_buffer ()
	Writes the flash write buffer into flash, and clears it out for continuing the bootloading process.

void	handle_memory_config_frame ()
	Decodes the memory config protocol's incoming data.

void	handle_stream_complete ()
	Handles incoming stream data complete message.

void	handle_addressed_message (Defs::MTI mti)
	Handles incoming addressed message (non-datagram).

void	handle_global_message (Defs::MTI mti)
	Handles incoming global message.

void	handle_stream_data ()

void	handle_input_frame ()
	Handles an incoming CAN frame.

void	handle_init ()
	Initialization state machine.

void	handle_send_datagram ()
	Fills outgoing frame from the pending datagram send buffer.

bool	bootloader_init ()
	Called once before starting the bootloader loop.

bool	bootloader_loop ()
	Called repeatedly in an infinite loop to run the bootloader.

void	bootloader_entry ()
	Main entry point for MCU-based bootloaders. Never returns.

Variables
BootloaderState	openlcb::state_
	Global state variables.

uint8_t	openlcb::g_write_buffer [WRITE_BUFFER_SIZE]
	Write buffer; the OpenLCB protocol engine collects the incoming bytes into this buffer and repeatedly flushes to flash.

volatile unsigned	g_bootloader_busy = 1
	1 if the bootloader is active, 0 if the bootloader is not active.

static const uint64_t	PIP_REPLY
	We manually convert to big-endian to store this value in .rodata.

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.

A standalone NMRAnet stack with the sole purpose of reflashing a microcontroller.

Author: Balazs Racz

Date: 8 Dec 2014

Definition in file Bootloader.hxx.

Macro Definition Documentation

◆ _OPENLCB_BOOTLOADER_HXX_

#define _OPENLCB_BOOTLOADER_HXX_

include guard macro

Definition at line 41 of file Bootloader.hxx.

◆ FLASH_SPACE

#define FLASH_SPACE (MemoryConfigDefs::SPACE_FIRMWARE)

Which OpenLCB Memory Config Space number should the bootloader export.

Definition at line 150 of file Bootloader.hxx.

◆ PIP_REPLY_VALUE

#define PIP_REPLY_VALUE

Value:

(Defs::DATAGRAM | Defs::STREAM | Defs::MEMORY_CONFIGURATION | \

Defs::FIRMWARE_UPGRADE_ACTIVE)

Protocol support bitmask that the bootloader should export.

Definition at line 168 of file Bootloader.hxx.

◆ STREAM_ID

#define STREAM_ID 0x5A

local stream ID.

Definition at line 152 of file Bootloader.hxx.

Function Documentation

◆ add_memory_config_error_response()

void add_memory_config_error_response ( uint16_t error_code )

turns an already prepared memory config response datagram into an error response.

Parameters

error_code 16-bit OpenLCB error code to report in the response datagram.

Definition at line 298 of file Bootloader.hxx.

◆ bootloader_entry()

void bootloader_entry ( )

Main entry point for MCU-based bootloaders. Never returns.

Definition at line 1115 of file Bootloader.hxx.

◆ bootloader_init()

bool bootloader_init ( )

Called once before starting the bootloader loop.

Returns: true if the application should be started, false if the bootloader.

Definition at line 1028 of file Bootloader.hxx.

◆ bootloader_loop()

bool bootloader_loop ( )

Called repeatedly in an infinite loop to run the bootloader.

Returns: true if the board has to be rebooted, false if the bootloader should keep running (i.e., to call again).

Definition at line 1049 of file Bootloader.hxx.

◆ flush_flash_buffer()

void flush_flash_buffer ( )

Writes the flash write buffer into flash, and clears it out for continuing the bootloading process.

This call usually takes quite a few milliseconds.

Definition at line 336 of file Bootloader.hxx.

◆ handle_addressed_message()

void handle_addressed_message ( Defs::MTI mti )

Handles incoming addressed message (non-datagram).

Definition at line 528 of file Bootloader.hxx.

◆ handle_global_message()

void handle_global_message ( Defs::MTI mti )

Handles incoming global message.

Todo:: (balazs.racz) what about global identify messages?

Definition at line 638 of file Bootloader.hxx.

◆ handle_init()

void handle_init ( )

Initialization state machine.

Called repeatedly from the main loop so long as initialization is not complete.

Definition at line 895 of file Bootloader.hxx.

◆ handle_input_frame()

void handle_input_frame ( )

Handles an incoming CAN frame.

Definition at line 756 of file Bootloader.hxx.

◆ handle_memory_config_frame()

void handle_memory_config_frame ( )

Decodes the memory config protocol's incoming data.

Definition at line 356 of file Bootloader.hxx.

◆ handle_send_datagram()

void handle_send_datagram ( )

Fills outgoing frame from the pending datagram send buffer.

Definition at line 987 of file Bootloader.hxx.

◆ handle_stream_complete()

void handle_stream_complete ( )

Handles incoming stream data complete message.

Definition at line 720 of file Bootloader.hxx.

◆ handle_stream_data()

void handle_stream_data ( )

Definition at line 678 of file Bootloader.hxx.

◆ init_flash_write_buffer()

void init_flash_write_buffer ( )

Clears out the flash write buffer with all 0xFF values.

Definition at line 306 of file Bootloader.hxx.

◆ is_can_frame_nodeid()

bool is_can_frame_nodeid ( )

Checks whether the incoming frame contains the current (bootloader) node's node_id as the data payload.

Returns: true if the current node's address is in the payload.

Definition at line 250 of file Bootloader.hxx.

◆ load_uint32_be()

uint32_t load_uint32_be ( const uint8_t * ptr )

Loads an unaligned 32-bit value that is network-endian.

Parameters

ptr	is an unaligned pointer to ram.

Returns: the big-endian interpreted value at the pointed value converted to host endian.

Definition at line 287 of file Bootloader.hxx.

◆ normalize_write_buffer_offset()

bool normalize_write_buffer_offset ( )

Translates from the logical address space of the OpenLCB memory config protocol memory space to the physical address space in the flash.

Returns: true if the translation is successful, false if the address is out of bounds.

Definition at line 318 of file Bootloader.hxx.

◆ reject_datagram()

void reject_datagram ( )

Kills the input frame and sends back a datagram rejected error message with permanent error.

Definition at line 275 of file Bootloader.hxx.

◆ reset_stream_state()

void reset_stream_state ( )

Clears out the stream state in state_.

Definition at line 665 of file Bootloader.hxx.

◆ set_can_frame_addressed()

void set_can_frame_addressed	(	Defs::MTI	mti,
		NodeAlias	alias = `CanDefs::get_src( GET_CAN_FRAME_ID_EFF(state_.input_frame))`
	)

Sets the outgoing CAN frame to addressed, destination taken from the source field of the incoming message or the given alias.

Parameters

mti	the MTI of the outgoing value.
alias	the destination node alias; defaults to taking the alias of the incoming frame.

Definition at line 218 of file Bootloader.hxx.

◆ set_can_frame_global()

void set_can_frame_global ( Defs::MTI mti )

Sets up the outgoing frame buffer for a global OpenLCB packet.

Parameters

mti	message transmit indicator to set for the outgoing message.

Definition at line 203 of file Bootloader.hxx.

◆ set_can_frame_nodeid()

void set_can_frame_nodeid ( )

Adds the node id ad the data payload of the outgoing can frame.

Definition at line 233 of file Bootloader.hxx.

◆ set_error_code()

void set_error_code ( uint16_t error_code )

Sets output frame dlc to 4; adds the given error code to bytes 2 and 3.

Parameters

error_code send this in bytes 2 and 3 of the reply message

Definition at line 266 of file Bootloader.hxx.

◆ setup_can_frame()

void setup_can_frame ( )

Prepares the outgoing frame buffer for a frame to be sent.

Definition at line 190 of file Bootloader.hxx.

Variable Documentation

◆ g_bootloader_busy

volatile unsigned g_bootloader_busy = 1

1 if the bootloader is active, 0 if the bootloader is not active.

Used by unit tests instead of sleeping to avoid race conditions.

Definition at line 161 of file Bootloader.hxx.

◆ PIP_REPLY

const uint64_t PIP_REPLY

static

Initial value:

=         
    ((PIP_REPLY_VALUE >> 40) & 0xff) |    
    ((PIP_REPLY_VALUE >> 24) & 0xff00) |  
    ((PIP_REPLY_VALUE >> 8) & 0xff0000) | 
    ((PIP_REPLY_VALUE & 0xff0000) << 8) | 
    ((PIP_REPLY_VALUE & 0xff00) << 24) |  
    ((PIP_REPLY_VALUE & 0xff) << 40)

We manually convert to big-endian to store this value in .rodata.

Definition at line 178 of file Bootloader.hxx.

Classes

Namespaces

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ _OPENLCB_BOOTLOADER_HXX_

◆ FLASH_SPACE

◆ PIP_REPLY_VALUE

◆ STREAM_ID

Function Documentation

◆ add_memory_config_error_response()

◆ bootloader_entry()

◆ bootloader_init()

◆ bootloader_loop()

◆ flush_flash_buffer()

◆ handle_addressed_message()

◆ handle_global_message()

◆ handle_init()

◆ handle_input_frame()

◆ handle_memory_config_frame()

◆ handle_send_datagram()

◆ handle_stream_complete()

◆ handle_stream_data()

◆ init_flash_write_buffer()

◆ is_can_frame_nodeid()

◆ load_uint32_be()

◆ normalize_write_buffer_offset()

◆ reject_datagram()

◆ reset_stream_state()

◆ set_can_frame_addressed()

◆ set_can_frame_global()

◆ set_can_frame_nodeid()

◆ set_error_code()

◆ setup_can_frame()

Variable Documentation

◆ g_bootloader_busy

◆ PIP_REPLY