PAL update. This file contains the firmware update APIs and is a part of the PAL service API. More...

Data Structures
struct	_palImageHeaderDeails_t

struct	FirmwareHeader

Macros
#define	SIZEOF_SHA256 256/8

#define	FIRMWARE_HEADER_MAGIC 0x5a51b3d4UL

#define	FIRMWARE_HEADER_VERSION 1

#define	ACTIVE_IMAGE_INDEX 0xFFFFFFFF

Typedefs
typedef uint32_t	palImageId_t

typedef struct _palImageHeaderDeails_t	palImageHeaderDeails_t

typedef enum _palImagePlatformData_t	palImagePlatformData_t

typedef enum _palImageEvents_t	palImageEvents_t

typedef void(*	palImageSignalEvent_t) (palImageEvents_t event)

typedef struct FirmwareHeader	FirmwareHeader_t

typedef FirmwareHeader_t	palFirmwareHeader_t

Enumerations
enum	_palImagePlatformData_t { PAL_IMAGE_DATA_FIRST = 0, PAL_IMAGE_DATA_HASH = PAL_IMAGE_DATA_FIRST, PAL_IMAGE_DATA_LAST }

enum	_palImageEvents_t { PAL_IMAGE_EVENT_FIRST = -1, PAL_IMAGE_EVENT_ERROR = PAL_IMAGE_EVENT_FIRST, PAL_IMAGE_EVENT_INIT, PAL_IMAGE_EVENT_PREPARE, PAL_IMAGE_EVENT_WRITE, PAL_IMAGE_EVENT_FINALIZE, PAL_IMAGE_EVENT_READTOBUFFER, PAL_IMAGE_EVENT_ACTIVATE, PAL_IMAGE_EVENT_ACTIVATE_ERROR, PAL_IMAGE_EVENT_GETACTIVEHASH, PAL_IMAGE_EVENT_GETACTIVEVERSION, PAL_IMAGE_EVENT_WRITEDATATOMEMORY, PAL_IMAGE_EVENT_LAST }

Functions
palStatus_t	pal_imageInitAPI (palImageSignalEvent_t CBfunction)
	Sets the callback function that is called before the end of each API except `imageGetDirectMemAccess`. More...

palStatus_t	pal_imageDeInit (void)
	Clears all the resources used by the `pal_update` APIs. More...

palStatus_t	pal_imagePrepare (palImageId_t imageId, palImageHeaderDeails_t *headerDetails)
	Prepares to write an image with an ID (`imageId`) and size (`imageSize`) in a suitable memory region. More...

palStatus_t	pal_imageWrite (palImageId_t imageId, size_t offset, palConstBuffer_t *chunk)
	Writes the data to the chunk buffer with the chunk `bufferLength` in the location of `imageId`, adding the relative offset. More...

palStatus_t	pal_imageFinalize (palImageId_t imageId)
	Flushes the image data and sets the version of `imageId` to `imageVersion`. More...

palStatus_t	pal_imageGetDirectMemoryAccess (palImageId_t imageId, void *imagePtr, size_t imageSizeInBytes)
	Verifies whether the image (`imageId`) is readable and sets `imagePtr` to point to the beginning of the image in the memory and `imageSizeInBytes` to the image size. More...

palStatus_t	pal_imageReadToBuffer (palImageId_t imageId, size_t offset, palBuffer_t *chunk)
	Reads the maximum of chunk (`maxBufferLength`) bytes from the image with relative offset and stores it in the chunk buffer. More...

palStatus_t	pal_imageActivate (palImageId_t imageId)
	Sets an image as the active image used after the device reset. More...

palStatus_t	pal_imageGetActiveHash (palBuffer_t *hash)
	Retrieves the hash value of the active image to the hash buffer with the max size hash (`maxBufferLength`) and sets the hash size to hash `bufferLength`. More...

palStatus_t	pal_imageGetFirmwareHeaderData (palImageId_t imageId, palBuffer_t *headerData)
	Retrieves the data value of the image header. More...

palStatus_t	pal_imageGetActiveVersion (palBuffer_t *version)
	Retrieves the version of the active image to the version buffer with the size set to version `bufferLength`. More...

palStatus_t	pal_imageWriteDataToMemory (palImagePlatformData_t dataId, const palConstBuffer_t *const dataBuffer)
	Writes data to a memory accessible to the bootloader. Currently, only hash is available. More...

char *	pal_imageGetFolder (void)
	This function gets the working directory for the firmware. More...

Detailed Description

PAL update. This file contains the firmware update APIs and is a part of the PAL service API.

It provides the read, write and activation functionalities for the firmware.

Macro Definition Documentation

#define ACTIVE_IMAGE_INDEX 0xFFFFFFFF

#define FIRMWARE_HEADER_MAGIC 0x5a51b3d4UL

#define FIRMWARE_HEADER_VERSION 1

#define SIZEOF_SHA256 256/8

Typedef Documentation

typedef struct FirmwareHeader FirmwareHeader_t

typedef FirmwareHeader_t palFirmwareHeader_t

typedef enum _palImageEvents_t palImageEvents_t

typedef struct _palImageHeaderDeails_t palImageHeaderDeails_t

typedef uint32_t palImageId_t

typedef enum _palImagePlatformData_t palImagePlatformData_t

typedef void(* palImageSignalEvent_t) (palImageEvents_t event)

Enumeration Type Documentation

enum _palImageEvents_t

Enumerator
PAL_IMAGE_EVENT_FIRST
PAL_IMAGE_EVENT_ERROR
PAL_IMAGE_EVENT_INIT
PAL_IMAGE_EVENT_PREPARE
PAL_IMAGE_EVENT_WRITE
PAL_IMAGE_EVENT_FINALIZE
PAL_IMAGE_EVENT_READTOBUFFER
PAL_IMAGE_EVENT_ACTIVATE
PAL_IMAGE_EVENT_ACTIVATE_ERROR
PAL_IMAGE_EVENT_GETACTIVEHASH
PAL_IMAGE_EVENT_GETACTIVEVERSION
PAL_IMAGE_EVENT_WRITEDATATOMEMORY
PAL_IMAGE_EVENT_LAST

enum _palImagePlatformData_t

Enumerator
PAL_IMAGE_DATA_FIRST
PAL_IMAGE_DATA_HASH
PAL_IMAGE_DATA_LAST

Function Documentation

palStatus_t pal_imageActivate ( palImageId_t imageId )

Sets an image as the active image used after the device reset.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in] imageId The image ID.

palStatus_t pal_imageDeInit ( void )

Clears all the resources used by the pal_update APIs.

Returns: PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.

palStatus_t pal_imageFinalize ( palImageId_t imageId )

Flushes the image data and sets the version of imageId to imageVersion.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in] imageId The image ID.

Returns: PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.

palStatus_t pal_imageGetActiveHash ( palBuffer_t * hash )

Retrieves the hash value of the active image to the hash buffer with the max size hash (maxBufferLength) and sets the hash size to hash bufferLength.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[out] hash A struct containing the hash and actual size of hash read.

palStatus_t pal_imageGetActiveVersion ( palBuffer_t * version )

Retrieves the version of the active image to the version buffer with the size set to version bufferLength.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[out] version A struct containing the version and actual size of version read.

palStatus_t pal_imageGetDirectMemoryAccess	(	palImageId_t	imageId,
		void **	imagePtr,
		size_t *	imageSizeInBytes
	)

Verifies whether the image (imageId) is readable and sets imagePtr to point to the beginning of the image in the memory and imageSizeInBytes to the image size.

In case of failure, sets imagePtr to NULL and returns the relevant palStatus_t error.

Parameters

[in]	imageId	The image ID.
[out]	imagePtr	A pointer to the beginning of the image.
[out]	imageSizeInBytes	The size of the image.

Returns: PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.

palStatus_t pal_imageGetFirmwareHeaderData	(	palImageId_t	imageId,
		palBuffer_t *	headerData
	)

Retrieves the data value of the image header.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in]	imageId	The image ID.
[out]	headerData	A struct containing the headerData and actual size of header.

char* pal_imageGetFolder ( void )

This function gets the working directory for the firmware.

Returns: full path of the firmware working folder

palStatus_t pal_imageInitAPI ( palImageSignalEvent_t CBfunction )

Sets the callback function that is called before the end of each API except imageGetDirectMemAccess.

WARNING: Do not change this function! This function loads a callback function received from the upper layer, the service. The callback should be called at the end of each function except pal_plat_imageGetDirectMemAccess. The callback receives the event type that just occurred, defined by the ENUM palImageEvents_t.

If you do not call the callback at the end, the service behavior will be undefined. The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in] CBfunction A pointer to the callback function.

Returns: PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.

palStatus_t pal_imagePrepare	(	palImageId_t	imageId,
		palImageHeaderDeails_t *	headerDetails
	)

Prepares to write an image with an ID (imageId) and size (imageSize) in a suitable memory region.

The space available is verified and reserved. The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in]	imageId	The image ID.
[in]	headerDetails	The size of the image.

Returns: PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.

palStatus_t pal_imageReadToBuffer	(	palImageId_t	imageId,
		size_t	offset,
		palBuffer_t *	chunk
	)

Reads the maximum of chunk (maxBufferLength) bytes from the image with relative offset and stores it in the chunk buffer.

Also sets the chunk bufferLength value to the actual number of bytes read.

Note: Use this API in case an image is not directly accessible via the imageGetDirectMemAccess function.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in]	imageId	The image ID.
[in]	offset	The offset to start reading from.
[out]	chunk	A struct containing the data and actual bytes read.

palStatus_t pal_imageWrite	(	palImageId_t	imageId,
		size_t	offset,
		palConstBuffer_t *	chunk
	)

Writes the data to the chunk buffer with the chunk bufferLength in the location of imageId, adding the relative offset.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in]	imageId	The image ID.
[in]	offset	The offset to write the data into.
[in]	chunk	A pointer to struct containing the data and the data length to write.

Returns: PAL_SUCCESS(0) in case of success, or a negative value indicating a specific error code in case of failure.

palStatus_t pal_imageWriteDataToMemory	(	palImagePlatformData_t	dataId,
		const palConstBuffer_t *const	dataBuffer
	)

Writes data to a memory accessible to the bootloader. Currently, only hash is available.

The function must call g_palUpdateServiceCBfunc before completing an event.

Parameters

[in]	dataId	The data to be written to memory. One of the members of the `palImagePlatformData_t` enum.
[in]	dataBuffer	A struct containing the data and actual bytes to be written.

Documentation

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation