mcci_bootloader_platform_types.h File Reference

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

Go to the source code of this file.

Data Structures
struct	McciBootloaderPlatform_ARMv6M_SvcRq_HashBlocks_Arg_t
	argument to McciBootloaderPlatform_ARMv6M_SvcRq_HashBlocks More...
struct	McciBootloaderPlatform_ARMv6M_SvcRq_HashFinish_Arg_t
	argument to McciBootloaderPlatform_ARMv6M_SvcRq_HashFinish More...

Macros
#define	_mcci_bootloader_platform_types_h_   /* prevent multiple includes */

Typedefs
typedef void()	McciBootloaderPlatform_AnnunciatorIndicateStateFn_t(McciBootloaderState_t state)
	Indicate the current state.
typedef void()	McciBootloaderPlatform_AnnunciatorInitFn_t(void)
	Initialize the annuciator system.
typedef void()	McciBootloaderPlatform_ARMv6M_SvcHandlerFn_t(McciBootloaderPlatform_ARMv6M_SvcRq_t svcRequest, McciBootloaderPlatform_ARMv6M_SvcError_t *pErrorCode, uint32_t arg1, uint32_t arg2)
	SVC function interface.
typedef void()	McciBootloaderPlatform_DelayMsFn_t(uint32_t ms)
	delay execution
typedef void()	McciBootloaderPlatform_FailFn_t(McciBootloaderError_t errorCode)
	function for reporting a fatal error
typedef McciBootloaderStorageAddress_t()	McciBootloaderPlatform_GetFallbackStorageAddressFn_t(void)
	get the start address of the fallback image in the storage
typedef McciBootloaderStorageAddress_t()	McciBootloaderPlatform_GetPrimaryStorageAddressFn_t(void)
	get the start address of the primary image in the storage
typedef bool()	McciBootloaderPlatform_GetUpdateFlagFn_t(void)
	Get the "update flag".
typedef void()	McciBootloaderPlatform_PrepareForLaunchFn_t(void)
	function type for preparing to launch an application
typedef void()	McciBootloaderPlatform_SetUpdateFlagFn_t(bool state)
	Set the "update flag".
typedef void()	McciBootloaderPlatform_SpiInitFn_t(void)
	initialize the SPI driver for storage use
typedef void()	McciBootloaderPlatform_SpiTransferFn_t(uint8_t *pRx, const uint8_t *pTx, size_t nBytes, bool fContinue)
	send/receive data over the SPI bus
typedef void()	McciBootloaderPlatform_StorageInitFn_t(void)
	Initialize the storage driver.
typedef bool()	McciBootloaderPlatform_StorageReadFn_t(McciBootloaderStorageAddress_t startAddress, uint8_t *pBuffer, size_t nBuffer)
	Read bytes from the storage.
typedef bool()	McciBootloaderPlatform_SystemFlashEraseFn_t(volatile const void *targetAddress, size_t targetSize)
	Erase a region of internal flash.
typedef bool()	McciBootloaderPlatform_SystemFlashWriteFn_t(volatile const void *pDestination, const void *pSource, size_t nBytes)
	Program a chunk of internal flash.

Enumerations
enum	McciBootloaderPlatform_ARMv6M_SvcError_t { McciBootloaderPlatform_SvcError_OK = 0 , McciBootloaderPlatform_SvcError_VerifyFailure = UINT32_C(-3) , McciBootloaderPlatform_SvcError_InvalidParameter = UINT32_C(-2) , McciBootloaderPlatform_SvcError_Unclaimed = UINT32_C(-1) }
	error codes from SVC handler on ARMv6-M systems & such like More...
enum	McciBootloaderPlatform_ARMv6M_SvcRq_t {   McciBootloaderPlatform_ARMv6M_SvcRq_GetUpdatePointer = UINT32_C(0x01000000) , McciBootloaderPlatform_ARMv6M_SvcRq_HashInit , McciBootloaderPlatform_ARMv6M_SvcRq_HashBlocks , McciBootloaderPlatform_ARMv6M_SvcRq_HashFinish ,   McciBootloaderPlatform_ARMv6M_SvcRq_Verify64 }
	SVC request codes for boot loader on ARMv6-M systems & such like. More...

Functions
	MCCIADK_C_ASSERT (sizeof(McciBootloaderPlatform_ARMv6M_SvcError_t)==sizeof(uint32_t))
	MCCIADK_C_ASSERT (sizeof(McciBootloaderPlatform_ARMv6M_SvcRq_t)==sizeof(uint32_t))
MCCI_BOOTLOADER_BEGIN_DECLS typedef void()	McciBootloaderPlatform_SystemInitFn_t (void)
	function type for platform intialization function

Macro Definition Documentation

_mcci_bootloader_platform_types_h_

#define _mcci_bootloader_platform_types_h_   /* prevent multiple includes */

Definition at line 23 of file mcci_bootloader_platform_types.h.

Typedef Documentation

McciBootloaderPlatform_AnnunciatorIndicateStateFn_t

typedef void() McciBootloaderPlatform_AnnunciatorIndicateStateFn_t(McciBootloaderState_t state)

Indicate the current state.

Parameters

[in]

state

the current boot state

Update the curent state for use by the annunciator.

Definition at line 273 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_AnnunciatorInitFn_t

typedef void() McciBootloaderPlatform_AnnunciatorInitFn_t(void)

Initialize the annuciator system.

Some boot operations are quite slow. So we allow for a platform to use the tick interrupt and output information to the user as to how things are going. This call is made before any state declarations are made to the annunciator.

Definition at line 261 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_ARMv6M_SvcHandlerFn_t

typedef void() McciBootloaderPlatform_ARMv6M_SvcHandlerFn_t(McciBootloaderPlatform_ARMv6M_SvcRq_t svcRequest, McciBootloaderPlatform_ARMv6M_SvcError_t *pErrorCode, uint32_t arg1, uint32_t arg2)

SVC function interface.

Parameters

[in]	svcRequest	is the request code.
[in]	pErrorCode	points to a cell to be filled with the error code (According to the value of svcRequest, there may additional OUT parameters)
[in]	arg1	is an extra argument, interpreted according to svcRequest
[in]	arg2	is an extra argument, interpreted according to svcRequest

This definition lets us take advantage of the ARMv6-M and related implementations; exception handlers are just like regular subroutines (except that results have to be passed back by modifying the saved registers on the stack). We work around this by passing results back in memory.

Definition at line 370 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_DelayMsFn_t

typedef void() McciBootloaderPlatform_DelayMsFn_t(uint32_t ms)

delay execution

Parameters

[in]

ms

number of milliseconds to delay

The bootloader calls this function in order to delay execution by the specified number of milliseconds. The implementation may delay longer, but apart errors due to clock inaccuracies, it should not return appreciably before the specified number of milliseconds has elapsed.

Definition at line 85 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_FailFn_t

typedef void() McciBootloaderPlatform_FailFn_t(McciBootloaderError_t errorCode)

function for reporting a fatal error

Parameters

[in]

errorCode

failure reason.

If a fatal error occurs during the boot, the bootloader calls this function, which must not return. If possible, the function displays the errorCode in a platform-specific way.

Note

Although it would be nice to decorate the type with "noreturn", that's not possible in C. But we can mark a function that calls this as no-return, and then use __builtin_notreached() in that function.

Definition at line 69 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_GetFallbackStorageAddressFn_t

typedef McciBootloaderStorageAddress_t() McciBootloaderPlatform_GetFallbackStorageAddressFn_t(void)

get the start address of the fallback image in the storage

Definition at line 205 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_GetPrimaryStorageAddressFn_t

typedef McciBootloaderStorageAddress_t() McciBootloaderPlatform_GetPrimaryStorageAddressFn_t(void)

get the start address of the primary image in the storage

Definition at line 197 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_GetUpdateFlagFn_t

typedef bool() McciBootloaderPlatform_GetUpdateFlagFn_t(void)

Get the "update flag".

The bootloader needs to know if an update has been requested; no point in scanning storage if we have not been asked to do so.

Returns

true if we should attempt to update flash from storage, false otherwise.

Definition at line 99 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_PrepareForLaunchFn_t

typedef void() McciBootloaderPlatform_PrepareForLaunchFn_t(void)

function type for preparing to launch an application

The bootloader calls this function just before jumping to the application. The function is required to return the platform to a reset-like state (making the bootloader maximally transparent).

Definition at line 52 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_SetUpdateFlagFn_t

typedef void() McciBootloaderPlatform_SetUpdateFlagFn_t(bool state)

Set the "update flag".

Set the value of the "update flag"

Parameters

[in]

state

true if next boot should attempt to update flash from storage, false otherwise.

See also

McciBootloaderPlatform_getUpdateFlagFn_t

Definition at line 114 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_SpiInitFn_t

typedef void() McciBootloaderPlatform_SpiInitFn_t(void)

initialize the SPI driver for storage use

Note

This API is only called if a driver decides it intends to use SPI.

Definition at line 215 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_SpiTransferFn_t

typedef void() McciBootloaderPlatform_SpiTransferFn_t(uint8_t *pRx, const uint8_t *pTx, size_t nBytes, bool fContinue)

send/receive data over the SPI bus

Parameters

[out]	pRx	points to the receive data buffer, if not NULL.
[in]	pTx	points to the transmit data buffer, if not NULL.
[in]	nBytes	is the number of bytes to transfer.
[in]	fContinue	indicates whether the chip select is to be left active after the operation. If true, then the chip select is left active, otherwise it's made inactive.

This API writes and reads data from the SPI bus, optionally leaving the target device selected.

nBytes bytes of data are transferred from the buffer at pTx to the SPI bus, and at the same time are received from the SPI bus to the buffer at pRx.

The parameters pRx and pTx are optional. If NULL, bytes are discarded or zeroes inserted, respectively.

This API is provided so we can write portable storage chip drivers that use the SPI bus. It's not used directly by the outer logic of the bootloader.

Definition at line 245 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_StorageInitFn_t

typedef void() McciBootloaderPlatform_StorageInitFn_t(void)

Initialize the storage driver.

The bootloader calls this prior to doing the first storage access. Portable drivers can use the SPI APIs to do their work, and should in turn initialize the SPI driver.

See also

McciBootloader_SpiInitFn

Definition at line 166 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_StorageReadFn_t

typedef bool() McciBootloaderPlatform_StorageReadFn_t(McciBootloaderStorageAddress_t startAddress, uint8_t *pBuffer, size_t nBuffer)

Read bytes from the storage.

Parameters

[in]	startAddress	starting byte address on the storage of data to be read.
[in]	pBuffer	pointer to buffer to be filled.
[in]	nBuffer	number of bytes to read.

This API is implemented by the storage chip drivers. Often, the storage chip will have restrictions in terms of address offset and block read length. The parameters fed to the boot loader and the fact that it reads 4k blocks (only) should allow most constraints to be honored.

Returns

true if all data was successfully read, false if there was an error

Definition at line 187 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_SystemFlashEraseFn_t

typedef bool() McciBootloaderPlatform_SystemFlashEraseFn_t(volatile const void *targetAddress, size_t targetSize)

Erase a region of internal flash.

Parameters

[in]	targetAddress	base address of region to erase
[in]	targetSize	number of bytes to erase

targetAddress and targetSize must match the alignment restritctons of the platform hardware.

Returns

true if region was successfully erased.

Definition at line 130 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_SystemFlashWriteFn_t

typedef bool() McciBootloaderPlatform_SystemFlashWriteFn_t(volatile const void *pDestination, const void *pSource, size_t nBytes)

Program a chunk of internal flash.

Parameters

[in]	pDestination	base address of region to program
[in]	pSource	base address of data to write (in RAM, for maximum portability)
[in]	nBytes	number of bytes to copy

pDestination and nBytes must match the alignment restritctons of the platform hardware. 4k is normally a good block size.

Returns

true if region was successfully programmed.

Definition at line 150 of file mcci_bootloader_platform_types.h.

Enumeration Type Documentation

McciBootloaderPlatform_ARMv6M_SvcError_t

enum McciBootloaderPlatform_ARMv6M_SvcError_t

error codes from SVC handler on ARMv6-M systems & such like

Enumerator
McciBootloaderPlatform_SvcError_OK	successful processing
McciBootloaderPlatform_SvcError_VerifyFailure	error: verify failure
McciBootloaderPlatform_SvcError_InvalidParameter	error: invalid parameter to SVC
McciBootloaderPlatform_SvcError_Unclaimed	error: SVC isn't just unimplemented, it's unkown to the bootloader

Definition at line 296 of file mcci_bootloader_platform_types.h.

McciBootloaderPlatform_ARMv6M_SvcRq_t

enum McciBootloaderPlatform_ARMv6M_SvcRq_t

SVC request codes for boot loader on ARMv6-M systems & such like.

Enumerator
McciBootloaderPlatform_ARMv6M_SvcRq_GetUpdatePointer	Fetch pointer to uint32_t "update" flag in EEPROM. arg1 is pointer to cell to receive pointer.
McciBootloaderPlatform_ARMv6M_SvcRq_HashInit	Call mcci_tweetnacl_hashblocks_sha512_init(). arg1 is pointer to hash block.
McciBootloaderPlatform_ARMv6M_SvcRq_HashBlocks	Call mcci_tweetnacl_hashblocks_sha512(). arg1 points to argument. See also McciBootloaderPlatform_ARMv6M_SvcRq_HashBlocks_Arg_t
McciBootloaderPlatform_ARMv6M_SvcRq_HashFinish	Call mcci_tweetnacl_hashblocks_finish(). arg1 points to argument. See also McciBootloaderPlatform_ARMv6M_SvcRq_HashFinish_Arg_t
McciBootloaderPlatform_ARMv6M_SvcRq_Verify64	Call mcci_tweetnacl_verify64(). arg1 and arg2 are the pointers; result is set to verifyFailure for failure.

Definition at line 312 of file mcci_bootloader_platform_types.h.

Function Documentation

MCCIADK_C_ASSERT() [1/2]

MCCIADK_C_ASSERT

(

sizeof(McciBootloaderPlatform_ARMv6M_SvcError_t)

= =sizeof(uint32_t)

)

MCCIADK_C_ASSERT() [2/2]

MCCIADK_C_ASSERT

(

sizeof(McciBootloaderPlatform_ARMv6M_SvcRq_t)

= =sizeof(uint32_t)

)

McciBootloaderPlatform_SystemInitFn_t()

MCCI_BOOTLOADER_BEGIN_DECLS typedef void() McciBootloaderPlatform_SystemInitFn_t

(

void

)

function type for platform intialization function

Functions of this type are called by the bootloader after RAM has been initialized. The function should set the system clock speed set up any "always needed" peripherals.