CycloneBOOT IAP User API. More...

#include "boot_config.h"
#include "core/crc32.h"
#include "core/crypto.h"
#include "core/flash.h"
#include "hash/hash_algorithms.h"
#include "image/image.h"
#include "memory/memory.h"
#include <stdint.h>
#include "security/cipher.h"
#include "core/cboot_error.h"
#include "error.h"
#include "core/verify.h"

Classes
struct	UpdateCryptoSettings
	Update Crypto settings. More...

struct	UpdateSettings
	Update user settings. More...

struct	_UpdateContext
	Update context. More...

Macros
#define	CYCLONE_BOOT_UPDATE_VERSION_STRING "2.6.2"

#define	CYCLONE_BOOT_UPDATE_MAJOR_VERSION 2

#define	CYCLONE_BOOT_UPDATE_MINOR_VERSION 6

#define	CYCLONE_BOOT_UPDATE_REV_NUMBER 2

#define	IMAGE_MAX_CHECK_DATA_SIZE 512

#define	UPDATE_SINGLE_BANK_SUPPORT DISABLED

#define	UPDATE_DUAL_BANK_SUPPORT ENABLED

#define	UPDATE_FALLBACK_SUPPORT DISABLED

#define	UPDATE_AUTO_BACKUP_SUPPORT DISABLED

#define	UPDATE_ANTI_ROLLBACK_SUPPORT DISABLED

#define	UpdateContext struct _UpdateContext

Typedefs
typedef cboot_error_t(*	IapRandCallback) (uint8_t *data, size_t length)
	Random data generation callback function.

Enumerations
enum	UpdateAuthAlgo { UPDATE_AUTH_NONE , UPDATE_AUTH_HMAC }
	Supported authentication algorithms.

enum	UpdateSignAlgo { UPDATE_SIGN_NONE , UPDATE_SIGN_RSA , UPDATE_SIGN_ECDSA }
	Supported signature algorithms.

enum	UpdateState { UPDATE_STATE_IDLE , UPDATE_STATE_RECV_APP_HEADER , UPDATE_STATE_RECV_APP_DATA , UPDATE_STATE_RECV_APP_CHECK , UPDATE_STATE_VALIDATE_APP , UPDATE_STATE_APP_REBOOT , UPDATE_STATE_WRITE_APP_INIT , UPDATE_STATE_WRITE_APP_HEADER , UPDATE_STATE_WRITE_APP_DATA , UPDATE_STATE_WRITE_APP_CHECK , UPDATE_STATE_WRITE_APP_END }
	Update states.

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

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

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 :

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.

uint32_t	mcuGetVtorOffset (void)
	Return mcu vector table offset.

void	mcuSystemReset (void)
	Reset MCU system.

void	mcuJumpToApplication (uint32_t address)
	Jump to the application at the given address.

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

◆ mcuGetVtorOffset()

uint32_t mcuGetVtorOffset ( void )

extern

Return mcu vector table offset.

Returns: VTOR offset value

Return mcu vector table offset.

Returns: VTOR offset value

◆ mcuJumpToApplication()

void mcuJumpToApplication ( uint32_t address )

extern

Jump to the application at the given address.

Parameters

[in] address Application start address

◆ mcuSystemReset()

void mcuSystemReset ( void )

extern

Reset MCU system.

◆ updateAcceptUpdateImageCallback()

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.

◆ 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

◆ updateGetDefaultSettings()

void updateGetDefaultSettings ( UpdateSettings * settings )

Initialize settings with default values.

Parameters

[in,out] settings Structure that contains IAP settings

◆ 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

Classes

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

License

Function Documentation

◆ mcuGetVtorOffset()

◆ mcuJumpToApplication()

◆ mcuSystemReset()

◆ updateAcceptUpdateImageCallback()

◆ updateConfirm()

◆ updateCreateBackup()

◆ updateFinalize()

◆ updateGetDefaultSettings()

◆ updateGetVersion()

◆ updateInit()

◆ updateProcess()

◆ updateReboot()

◆ updateRegisterRandCallback()