CycloneBOOT IAP User API. More...

#include "update/update.h"
#include "core/crc32.h"
#include "core/flash.h"
#include "image/image.h"
#include "image/image_process.h"
#include "memory/memory.h"
#include "update/update_misc.h"
#include <stdlib.h>
#include "core/mailbox.h"
#include "boot_config.h"
#include "debug.h"

Macros
#define	TRACE_LEVEL CBOOT_TRACE_LEVEL

Functions
cboot_error_t	updateCalculateOutputImageIdx (UpdateContext context, uint32_t imgIdx)
	This function calculates the value of the output image index that will be store in external memory. It first retrieve the value of the image that contains the current application in internal memory, then it increment this value by one and save it in the given output index pointer. This function is used only when the UPDATE_SINGLE_BANK_MODE_SUPPORT is activated. In Single Bank mode the update image is processed to check its validity while a new ouput image is generated and stored in external memory. This output image will then be processed by the bootloader to complete the update procedure. The bootloader uses the index of the output image againts the index of the image containing the current application firmware to determine if an update is neeeded or not.

cboot_error_t	updateCalculateOutputBootImageIdx (UpdateContext context, uint32_t imgIdx)
	This function calculates the index of an output image holding a bootloader. The index is derived from the declared bootloader slot, or from the application when no bootloader slot is declared.

cboot_error_t	updateGetBootSlot (UpdateContext context, Slot *slot)
	This function returns the primary memory slot holding the resident bootloader.

cboot_error_t	updateGetUpdateSlot (UpdateContext context, Slot *slot)
	This function selects the slot that will hold the output image. The choice of the slot depends of the IAP mode: Dual or Single bank mode. In Dual bank mode:

char_t *	updateGetVersion (void)
	This function returns the current version of CycloneBOOT IAP.

void	updateGetDefaultSettings (UpdateSettings *settings)
	Initialize settings with default values.

cboot_error_t	updateRegisterRandCallback (IapRandCallback callback)
	Register RNG callback function.

cboot_error_t	updateInit (UpdateContext context, UpdateSettings settings)
	Initialize IAP Application context.

cboot_error_t	updateProcess (UpdateContext context, const void data, size_t length)
	Write receive firmware in the unused flash bank.

cboot_error_t	updateFinalize (UpdateContext *context)
	Finalize firmware update. It performs :

cboot_error_t	updateCreateBackup (UpdateContext *context)
	Save a copy of the running application in the spare update slot. The copy is written in the update image format, encrypted when IMAGE_OUTPUT_ENCRYPTED is enabled, so the bootloader can restore it on a fall back. Without it a fall back is only possible from the second update onwards.

cboot_error_t	updateReboot (UpdateContext *context)
	Reboot the device by triggering a system reset. This reboot can only be performed if firmware validation has been done succesfully. If not an error will be raised.

cboot_error_t	updateConfirm (void)
	Confirm firmware update. It performs :

__weak_func bool_t	updateAcceptUpdateImageCallback (ImageVersion currentAppVersion, ImageVersion updateAppVersion)
	This callback checks the version of firmware application inside the received update image. If the version of the firmware application in the update image is less than or equal to the version of the current firmware application then the update will be discarded. If not the update image is accepted. This function is used only the UPDATE_ANTI_ROLLBACK_SUPPORT feature is activated.

Variables
IapRandCallback	updateRandCallback

Detailed Description

CycloneBOOT IAP User API.

License

SPDX-License-Identifier: GPL-2.0-or-later

This file is part of CycloneBOOT Open.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

Author: Oryx Embedded SARL (www.oryx-embedded.com)

Version: 2.6.6

Function Documentation

◆ updateAcceptUpdateImageCallback()

__weak_func bool_t updateAcceptUpdateImageCallback	(	ImageVersion	currentAppVersion,
		ImageVersion	updateAppVersion
	)

This callback checks the version of firmware application inside the received update image. If the version of the firmware application in the update image is less than or equal to the version of the current firmware application then the update will be discarded. If not the update image is accepted. This function is used only the UPDATE_ANTI_ROLLBACK_SUPPORT feature is activated.

Parameters

[in]	currentAppVersion	Version of the current firmware application.
[in]	updateAppVersion	Version of the firmware application inside the update image.

Returns: TRUE if the update image is accepted, FALSE otherwise.

◆ updateCalculateOutputBootImageIdx()

cboot_error_t updateCalculateOutputBootImageIdx	(	UpdateContext *	context,
		uint32_t *	imgIdx
	)

This function calculates the index of an output image holding a bootloader. The index is derived from the declared bootloader slot, or from the application when no bootloader slot is declared.

Parameters

[in]	context	Pointer to the IAP context.
[out]	imgIdx	Calculated value of the output image index.

Returns: Error code.

◆ updateCalculateOutputImageIdx()

cboot_error_t updateCalculateOutputImageIdx	(	UpdateContext *	context,
		uint32_t *	imgIdx
	)

This function calculates the value of the output image index that will be store in external memory. It first retrieve the value of the image that contains the current application in internal memory, then it increment this value by one and save it in the given output index pointer. This function is used only when the UPDATE_SINGLE_BANK_MODE_SUPPORT is activated. In Single Bank mode the update image is processed to check its validity while a new ouput image is generated and stored in external memory. This output image will then be processed by the bootloader to complete the update procedure. The bootloader uses the index of the output image againts the index of the image containing the current application firmware to determine if an update is neeeded or not.

Parameters

[in]	context	Pointer to the IAP context.
[out]	imgIdx	Calculated value of the output image index.

Returns: Error code.

◆ updateConfirm()

cboot_error_t updateConfirm ( void )

Confirm firmware update. It performs :

Firmware integrity or authentification or signature validation.
Flash bank memory swap setup If validation is done successfully the device would be ready for reboot, if not an error will be raised. The firmware validation can only be done if all the image (header, firmware data and check data) has been processed successfully, if not an error will be raised.
Parameters

[in,out] context Pointer to the IAP application context

Returns
Error code

◆ updateCreateBackup()

cboot_error_t updateCreateBackup ( UpdateContext * context )

Save a copy of the running application in the spare update slot. The copy is written in the update image format, encrypted when IMAGE_OUTPUT_ENCRYPTED is enabled, so the bootloader can restore it on a fall back. Without it a fall back is only possible from the second update onwards.

Parameters

[in,out] context Pointer to the update context

Returns: Error code.

◆ updateFinalize()

cboot_error_t updateFinalize ( UpdateContext * context )

Finalize firmware update. It performs :

Firmware integrity or authentification or signature validation.
Flash bank memory swap setup If validation is done successfully the device would be ready for reboot, if not an error will be raised. The firmware validation can only be done if all the image (header, firmware data and check data) has been processed successfully, if not an error will be raised.
Parameters

[in,out] context Pointer to the IAP application context

Returns
Error code

◆ updateGetBootSlot()

cboot_error_t updateGetBootSlot	(	UpdateContext *	context,
		Slot **	slot
	)

This function returns the primary memory slot holding the resident bootloader.

Parameters

[in]	context	Pointer to the IAP context.
[out]	slot	Pointer to the bootloader slot.

Returns: Error code.

◆ updateGetDefaultSettings()

void updateGetDefaultSettings ( UpdateSettings * settings )

Initialize settings with default values.

Parameters

[in,out] settings Structure that contains IAP settings

◆ updateGetUpdateSlot()

cboot_error_t updateGetUpdateSlot	(	UpdateContext *	context,
		Slot **	slot
	)

This function selects the slot that will hold the output image. The choice of the slot depends of the IAP mode: Dual or Single bank mode. In Dual bank mode:

the output image is the new application firmware binary that was in the update image.
the slected slot is always the other flash bank (the one that doesn't hold the current application binary) In Single Bank mode:
the output image is an image stored in external memory, containing the new application binary comming from the update image and generating in a way that the bootloader will be abled to process it.
the selected slot is one of the available slot in external memory. It can be:
- if fallback support is not activated, the first and only one slot in external memory
- otherwise one of the slot among the two slots present in external memory that doesn't hold the backup image of the current running application
  Parameters
  
  [in] context Pointer to IAP context.
  
  [out] slot Pointer to the slot that will be used to hold output image.
  
  Returns

◆ updateGetVersion()

char_t * updateGetVersion ( void )

This function returns the current version of CycloneBOOT IAP.

Returns: String that hold CycloneBOOT version.

◆ updateInit()

cboot_error_t updateInit	(	UpdateContext *	context,
		UpdateSettings *	settings
	)

Initialize IAP Application context.

Parameters

[in,out] context Pointer to the IAP Application context to be initialized

Returns: Status code

◆ updateProcess()

cboot_error_t updateProcess	(	UpdateContext *	context,
		const void *	data,
		size_t	length
	)

Write receive firmware in the unused flash bank.

Parameters

[in,out]	context	Pointer to the IAP application context
[in]	data	Firmware chunck of data to be written in flash bank
[in]	length	Length of the firmware chunck of data to be written

Returns: Status code

◆ updateReboot()

cboot_error_t updateReboot ( UpdateContext * context )

Reboot the device by triggering a system reset. This reboot can only be performed if firmware validation has been done succesfully. If not an error will be raised.

Parameters

[in] context Pointer to the IAP context

Returns: Error code.

◆ updateRegisterRandCallback()

cboot_error_t updateRegisterRandCallback ( IapRandCallback callback )

Register RNG callback function.

Parameters

[in] callback RNG callback function

Returns: Error code

[in]	context	Pointer to IAP context.
[out]	slot	Pointer to the slot that will be used to hold output image.

Macros

Functions

Variables

Detailed Description

License

Function Documentation

◆ updateAcceptUpdateImageCallback()

◆ updateCalculateOutputBootImageIdx()

◆ updateCalculateOutputImageIdx()

◆ updateConfirm()

◆ updateCreateBackup()

◆ updateFinalize()

◆ updateGetBootSlot()

◆ updateGetDefaultSettings()

◆ updateGetUpdateSlot()

◆ updateGetVersion()

◆ updateInit()

◆ updateProcess()

◆ updateReboot()

◆ updateRegisterRandCallback()