Boot Mailbox mangement functions. More...

#include <stddef.h>
#include "boot_config.h"
#include "core/cboot_error.h"
#include "image/image_format.h"
#include "debug.h"
#include "os_port.h"

Classes
struct	BOOT_MBX_PACK_ATTR
	Bootloader shared RAM mailbox structure. More...

Macros
#define	BOOT_MBX_VERSION (uint32_t) 0x00010001

#define	BOOT_MBX_SIGNATURE 0x1b241671

#define	BOOT_MBX_NVM_MAGIC 0xBEEF

#define	BOOT_MBX_NVM_FLAG_UPDATE_REQUESTED 0xF00D

#define	BOOT_MBX_NVM_FLAG_UPDATE_PERFORMED 0xC0DE

#define	BOOT_MBX_NVM_FLAG_UPDATE_CONFIRMED 0xFEED

#define	BOOT_MBX_NVM_FLAG_FALLBACK_REQUESTED 0xB105

#define	BOOT_MBX_NVM_FLAG_FALLBACK_PERFORMED 0xDEAD

#define	BOOT_MBX_NVM_FLAG_FALLBACK_AVAILABLE 0x0BAC

#define	BOOT_MBX_NVM_FLAG_REPAIR_PERFORMED 0xB007

#define	BOOT_MBX_PSK_MAX_SIZE 32

#define	BOOT_MBX_PACK_BEGIN

#define	BOOT_MBX_PACK_END

#define	BOOT_MBX_PACK_ATTR

#define	BOOT_MBX_STATIC_ASSERT_CAT_(a, b) a ## b

#define	BOOT_MBX_STATIC_ASSERT_CAT(a, b) BOOT_MBX_STATIC_ASSERT_CAT_(a, b)

#define	BOOT_MBX_STATIC_ASSERT(cond, msg) typedef char BOOT_MBX_STATIC_ASSERT_CAT(boot_mbx_static_assert_, __LINE__)[(cond) ? 1 : -1]

Enumerations
enum	{ UPDATE_REQUESTED = 1 << 0 , UPDATE_PERFORMED = 1 << 1 , UPDATE_CONFIRMED = 1 << 2 , FALLBACK_REQUESTED = 1 << 3 , FALLBACK_PERFORMED = 1 << 4 , FALLBACK_AVAILABLE = 1 << 5 , REPAIR_PERFORMED = 1 << 6 }

Functions
	BOOT_MBX_STATIC_ASSERT (sizeof(BootMailBox)==132, "BootMailBox RAM layout changed (must stay 132 bytes)")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, version)==0, "BootMailBox.version offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, signature)==4, "BootMailBox.signature offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, pskSize)==8, "BootMailBox.pskSize offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, psk)==12, "BootMailBox.psk offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, flags)==44, "BootMailBox.flags offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, boot_counter)==48, "BootMailBox.boot_counter offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, fsbVersion)==52, "BootMailBox.fsbVersion offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, ssbVersion)==60, "BootMailBox.ssbVersion offset changed")

	BOOT_MBX_STATIC_ASSERT (offsetof(BootMailBox, reserved)==68, "BootMailBox.reserved offset changed")

cboot_error_t	mailBoxInit (void)
	Initializes the shared bootloader mailbox if signature is not valid. The NVM flag storage is initialized on every call when BOOT_MAILBOX_NVM_SUPPORT is enabled.

bool_t	mailBoxIsUpdateRequested (void)
	Checks whether UPDATE_REQUESTED message is present in the mailbox.

void	mailBoxSetUpdateRequested (bool_t state)
	Posts UPDATE_REQUESTED message to the mailbox.

bool_t	mailBoxIsUpdatePerformed (void)
	Checks whether UPDATE_PERFORMED message is present in the mailbox.

void	mailBoxSetUpdatePerformed (bool_t state)
	Posts UPDATE_PERFORMED message to the mailbox.

bool_t	mailBoxIsUpdateConfirmed (void)
	Checks whether UPDATE_CONFIRMED message is present in the mailbox.

void	mailBoxSetUpdateConfirmed (bool_t state)
	Posts UPDATE_REQUESTED message to the mailbox.

bool_t	mailBoxIsFallbackRequested (void)
	Checks whether FALLBACK_REQUESTED message is present in the mailbox.

bool_t	mailBoxIsFallbackPerformed (void)
	Checks whether FALLBACK_PERFORMED message is present in the mailbox.

void	mailBoxSetFallbackRequested (bool_t state)
	Posts FALLBACK_REQUESTED message to the mailbox.

void	mailBoxSetFallbackPerformed (bool_t state)
	Posts FALLBACK_PERFORMED message to the mailbox.

bool_t	mailBoxIsFallbackAvailable (void)
	Checks whether a fall back to a previous firmware is possible.

void	mailBoxSetFallbackAvailable (bool_t state)
	Posts FALLBACK_AVAILABLE message to the mailbox.

bool_t	mailBoxIsRepairPerformed (void)
	Tells whether the bootloader already reinstalled a candidate to repair the application.

void	mailBoxSetRepairPerformed (bool_t state)
	Posts REPAIR_PERFORMED message to the mailbox.

void	mailBoxSetFirstStageVersion (const ImageVersion *version)
	Publish the first-stage version for later stages (HDP/HDPL-safe).

const ImageVersion *	mailBoxGetFirstStageVersion (void)
	Get the first-stage version published in the mailbox.

void	mailBoxSetSecondStageVersion (const ImageVersion *version)
	Publish the second-stage version for the application to read.

const ImageVersion *	mailBoxGetSecondStageVersion (void)
	Get the second-stage version published in the mailbox.

void	mailBoxIncrementBootCounter (void)
	Increments the boot counter in the mailbox.

uint32_t	mailBoxGetBootCounter (void)
	Returns the current value of the boot counter in the mailbox.

void	mailBoxClearBootCounter (void)
	Clears the current value of the boot counter in the mailbox.

void	mailBoxSetPsk (const uint8_t *psk, size_t pskSize)
	Set Pre-Shared Key value of the mailbox.

void	mailBoxGetPsk (uint8_t psk, size_t pskSize)
	Returns a copy of Pre-Shared Key value of the mailbox.

void	mailBoxClearPsk (void)
	Clear the Pre-Shared Key from the mailbox.

Detailed Description

Boot Mailbox mangement functions.

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

◆ mailBoxGetFirstStageVersion()

const ImageVersion * mailBoxGetFirstStageVersion ( void )

Get the first-stage version published in the mailbox.

Returns: First-stage image version

◆ mailBoxGetPsk()

void mailBoxGetPsk	(	uint8_t *	psk,
		size_t *	pskSize
	)

Returns a copy of Pre-Shared Key value of the mailbox.

Parameters

[in]	psk	pointer to a buffer where pre-shared key will be copied
[in]	pskSize	pointer to a variable where the length of the pre-shared key will be copied

◆ mailBoxGetSecondStageVersion()

const ImageVersion * mailBoxGetSecondStageVersion ( void )

Get the second-stage version published in the mailbox.

Returns: Second-stage image version

◆ mailBoxIncrementBootCounter()

void mailBoxIncrementBootCounter ( void )

Increments the boot counter in the mailbox.

Note: The boot counter is RAM-only; it is not persisted to NVM even when BOOT_MAILBOX_NVM_SUPPORT is enabled (unlike the event flags).

◆ mailBoxInit()

cboot_error_t mailBoxInit ( void )

Initializes the shared bootloader mailbox if signature is not valid. The NVM flag storage is initialized on every call when BOOT_MAILBOX_NVM_SUPPORT is enabled.

Returns: Status code, the NVM initialization result when it is enabled

◆ mailBoxIsFallbackAvailable()

bool_t mailBoxIsFallbackAvailable ( void )

Checks whether a fall back to a previous firmware is possible.

Note: Published by the bootloader each boot; read by the application to decide whether to offer a fall back.

Returns: TRUE or FALSE

◆ mailBoxIsFallbackPerformed()

bool_t mailBoxIsFallbackPerformed ( void )

Checks whether FALLBACK_PERFORMED message is present in the mailbox.

Returns: TRUE or FALSE

◆ mailBoxIsFallbackRequested()

bool_t mailBoxIsFallbackRequested ( void )

Checks whether FALLBACK_REQUESTED message is present in the mailbox.

Returns: TRUE or FALSE

◆ mailBoxIsRepairPerformed()

bool_t mailBoxIsRepairPerformed ( void )

Tells whether the bootloader already reinstalled a candidate to repair the application.

Returns: TRUE or FALSE

◆ mailBoxIsUpdateConfirmed()

bool_t mailBoxIsUpdateConfirmed ( void )

Checks whether UPDATE_CONFIRMED message is present in the mailbox.

Returns: TRUE or FALSE

◆ mailBoxIsUpdatePerformed()

bool_t mailBoxIsUpdatePerformed ( void )

Checks whether UPDATE_PERFORMED message is present in the mailbox.

Returns: TRUE or FALSE

◆ mailBoxIsUpdateRequested()

bool_t mailBoxIsUpdateRequested ( void )

Checks whether UPDATE_REQUESTED message is present in the mailbox.

Returns: TRUE or FALSE

◆ mailBoxSetFallbackAvailable()

void mailBoxSetFallbackAvailable ( bool_t state )

Posts FALLBACK_AVAILABLE message to the mailbox.

Parameters

[in] state state of the flag, TRUE or FALSE

◆ mailBoxSetFallbackPerformed()

void mailBoxSetFallbackPerformed ( bool_t state )

Posts FALLBACK_PERFORMED message to the mailbox.

Parameters

[in] state state of the flag, TRUE or FALSE

◆ mailBoxSetFallbackRequested()

void mailBoxSetFallbackRequested ( bool_t state )

Posts FALLBACK_REQUESTED message to the mailbox.

Parameters

[in] state state of the flag, TRUE or FALSE

◆ mailBoxSetFirstStageVersion()

void mailBoxSetFirstStageVersion ( const ImageVersion * version )

Publish the first-stage version for later stages (HDP/HDPL-safe).

Parameters

[in] version First-stage image version

◆ mailBoxSetPsk()

void mailBoxSetPsk	(	const uint8_t *	psk,
		size_t	pskSize
	)

Set Pre-Shared Key value of the mailbox.

Parameters

[in]	psk	pointer to the pre-shared key
[in]	pskSize	length of the pre-shared key

◆ mailBoxSetRepairPerformed()

void mailBoxSetRepairPerformed ( bool_t state )

Posts REPAIR_PERFORMED message to the mailbox.

Parameters

[in] state state of the flag, TRUE or FALSE

◆ mailBoxSetSecondStageVersion()

void mailBoxSetSecondStageVersion ( const ImageVersion * version )

Publish the second-stage version for the application to read.

Parameters

[in] version Second-stage image version

◆ mailBoxSetUpdateConfirmed()

void mailBoxSetUpdateConfirmed ( bool_t state )

Posts UPDATE_REQUESTED message to the mailbox.

Parameters

[in] state state of the flag, TRUE or FALSE

◆ mailBoxSetUpdatePerformed()

void mailBoxSetUpdatePerformed ( bool_t state )

Posts UPDATE_PERFORMED message to the mailbox.

Parameters

[in] state state of the flag, TRUE or FALSE

◆ mailBoxSetUpdateRequested()

void mailBoxSetUpdateRequested ( bool_t state )

Posts UPDATE_REQUESTED message to the mailbox.

Parameters

[in] state state of the flag, TRUE or FALSE

Classes

Macros

Enumerations

Functions

Detailed Description

License

Function Documentation

◆ mailBoxGetFirstStageVersion()

◆ mailBoxGetPsk()

◆ mailBoxGetSecondStageVersion()

◆ mailBoxIncrementBootCounter()

◆ mailBoxInit()

◆ mailBoxIsFallbackAvailable()

◆ mailBoxIsFallbackPerformed()

◆ mailBoxIsFallbackRequested()

◆ mailBoxIsRepairPerformed()

◆ mailBoxIsUpdateConfirmed()

◆ mailBoxIsUpdatePerformed()

◆ mailBoxIsUpdateRequested()

◆ mailBoxSetFallbackAvailable()

◆ mailBoxSetFallbackPerformed()

◆ mailBoxSetFallbackRequested()

◆ mailBoxSetFirstStageVersion()

◆ mailBoxSetPsk()

◆ mailBoxSetRepairPerformed()

◆ mailBoxSetSecondStageVersion()

◆ mailBoxSetUpdateConfirmed()

◆ mailBoxSetUpdatePerformed()

◆ mailBoxSetUpdateRequested()