Contains PAL interface statuses, type definitions and structure to store interface routines. More...

#include "ota_private.h"

Include dependency graph for ota_platform_interface.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	OtaPalInterface_t
	OTA pal Interface structure. More...

Macros
#define	OtaPalSuccess 0x0U
	OTA platform interface success.

#define	OtaPalUninitialized 0xe0U
	Result is not yet initialized from PAL.

#define	OtaPalOutOfMemory 0xe1U
	Out of memory.

#define	OtaPalNullFileContext 0xe2U
	The PAL is called with a NULL file context.

#define	OtaPalSignatureCheckFailed 0xe3U
	The signature check failed for the specified file.

#define	OtaPalRxFileCreateFailed 0xe4U
	The PAL failed to create the OTA receive file.

#define	OtaPalRxFileTooLarge 0xe5U
	The OTA receive file is too big for the platform to support.

#define	OtaPalBootInfoCreateFailed 0xe6U
	The PAL failed to create the OTA boot info file.

#define	OtaPalBadSignerCert 0xe7U
	The signer certificate was not readable or zero length.

#define	OtaPalBadImageState 0xe8U
	The specified OTA image state was out of range.

#define	OtaPalAbortFailed 0xe9U
	Error trying to abort the OTA.

#define	OtaPalRejectFailed 0xeaU
	Error trying to reject the OTA image.

#define	OtaPalCommitFailed 0xebU
	The acceptance commit of the new OTA image failed.

#define	OtaPalActivateFailed 0xecU
	The activation of the new OTA image failed.

#define	OtaPalFileAbort 0xedU
	Error in low level file abort.

#define	OtaPalFileClose 0xeeU
	Error in low level file close.

#define	OTA_PAL_ERR_MASK 0xffffffUL

#define	OTA_PAL_SUB_BITS 24U

#define	OTA_PAL_MAIN_ERR(err) ( ( OtaPalMainStatus_t ) ( uint32_t ) ( ( uint32_t ) ( err ) >> ( uint32_t ) OTA_PAL_SUB_BITS ) )

#define	OTA_PAL_SUB_ERR(err) ( ( ( uint32_t ) ( err ) ) & ( ( uint32_t ) OTA_PAL_ERR_MASK ) )

#define	OTA_PAL_COMBINE_ERR(main, sub) ( ( ( uint32_t ) ( main ) << ( uint32_t ) OTA_PAL_SUB_BITS ) \| ( uint32_t ) OTA_PAL_SUB_ERR( sub ) )

Typedefs
typedef uint32_t	OtaPalStatus_t
	The OTA platform interface return status. Composed of main and sub status.

typedef uint32_t	OtaPalSubStatus_t
	The OTA platform interface sub status.

typedef uint32_t	OtaPalMainStatus_t
	The OTA platform interface main status.

typedef OtaPalStatus_t(*	OtaPalAbort_t) (OtaFileContext_t *const pFileContext)
	Abort an OTA transfer.

typedef OtaPalStatus_t(*	OtaPalCreateFileForRx_t) (OtaFileContext_t *const pFileContext)
	Create a new receive file for the data chunks as they come in.

typedef OtaPalStatus_t(*	OtaPalCloseFile_t) (OtaFileContext_t *const pFileContext)
	Authenticate and close the underlying receive file in the specified OTA context.

typedef int16_t(*	OtaPalWriteBlock_t) (OtaFileContext_t const pFileContext, uint32_t offset, uint8_t const pData, uint32_t blockSize)
	Write a block of data to the specified file at the given offset.

typedef OtaPalStatus_t(*	OtaPalActivateNewImage_t) (OtaFileContext_t *const pFileContext)
	Activate the newest MCU image received via OTA.

typedef OtaPalStatus_t(*	OtaPalResetDevice_t) (OtaFileContext_t *const pFileContext)
	Reset the device.

typedef OtaPalStatus_t(*	OtaPalSetPlatformImageState_t) (OtaFileContext_t *const pFileContext, OtaImageState_t eState)
	Attempt to set the state of the OTA update image.

typedef OtaPalImageState_t(*	OtaPalGetPlatformImageState_t) (OtaFileContext_t *const pFileContext)
	Get the state of the OTA update image.

Detailed Description

Contains PAL interface statuses, type definitions and structure to store interface routines.

Macro Definition Documentation

◆ OTA_PAL_ERR_MASK

#define OTA_PAL_ERR_MASK 0xffffffUL

The PAL layer uses the signed low 24 bits of the OTA error code.

◆ OTA_PAL_SUB_BITS

#define OTA_PAL_SUB_BITS 24U

The OTA Agent error code is the highest 8 bits of the word.

◆ OTA_PAL_MAIN_ERR

#define OTA_PAL_MAIN_ERR ( err ) ( ( OtaPalMainStatus_t ) ( uint32_t ) ( ( uint32_t ) ( err ) >> ( uint32_t ) OTA_PAL_SUB_BITS ) )

Helper to get the OTA PAL main error code.

◆ OTA_PAL_SUB_ERR

#define OTA_PAL_SUB_ERR ( err ) ( ( ( uint32_t ) ( err ) ) & ( ( uint32_t ) OTA_PAL_ERR_MASK ) )

Helper to get the OTA PAL sub error code.

◆ OTA_PAL_COMBINE_ERR

#define OTA_PAL_COMBINE_ERR	(	main,
		sub
	)	( ( ( uint32_t ) ( main ) << ( uint32_t ) OTA_PAL_SUB_BITS ) \| ( uint32_t ) OTA_PAL_SUB_ERR( sub ) )

Helper to combine the OTA PAL main and sub error code.

Typedef Documentation

◆ OtaPalAbort_t

typedef OtaPalStatus_t(* OtaPalAbort_t) (OtaFileContext_t *const pFileContext)

Abort an OTA transfer.

Aborts access to an existing open file represented by the OTA file context pFileContext. This is only valid for jobs that started successfully.

Note: The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this function is called. This function may be called before the file is opened, so the file pointer pFileContext->fileHandle may be NULL when this function is called.

Parameters

[in] pFileContext OTA file context information.

Returns: The OTA PAL layer error code combined with the MCU specific error code. See OTA Agent error codes information in ota.h.

The file pointer will be set to NULL after this function returns. OtaPalSuccess is returned when aborting access to the open file was successful. OtaPalFileAbort is returned when aborting access to the open file context was unsuccessful.

◆ OtaPalCreateFileForRx_t

typedef OtaPalStatus_t(* OtaPalCreateFileForRx_t) (OtaFileContext_t *const pFileContext)

Create a new receive file for the data chunks as they come in.

Note: Opens the file indicated in the OTA file context in the MCU file system.; The previous image may be present in the designated image download partition or file, so the partition or file must be completely erased or overwritten in this routine.; The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this function is called. The device file path is a required field in the OTA job document, so pFileContext->pFilePath is checked for NULL by the OTA agent before this function is called.

Parameters

[in] pFileContext OTA file context information.

Returns: The OTA PAL layer error code combined with the MCU specific error code. See OTA Agent error codes information in ota.h.

OtaPalSuccess is returned when file creation is successful. OtaPalRxFileTooLarge is returned if the file to be created exceeds the device's non-volatile memory size constraints. OtaPalBootInfoCreateFailed is returned if the bootloader information file creation fails. OtaPalRxFileCreateFailed is returned for other errors creating the file in the device's non-volatile memory.

◆ OtaPalCloseFile_t

typedef OtaPalStatus_t(* OtaPalCloseFile_t) (OtaFileContext_t *const pFileContext)

Authenticate and close the underlying receive file in the specified OTA context.

Note: The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this function is called. This function is called only at the end of block ingestion. prvPAL_CreateFileForRx() must succeed before this function is reached, so pFileContext->fileHandle(or pFileContext->pFile) is never NULL. The certificate path on the device is a required job document field in the OTA Agent, so pFileContext->pCertFilepath is never NULL. The file signature key is required job document field in the OTA Agent, so pFileContext->pSignature will never be NULL.

If the signature verification fails, file close should still be attempted.

Parameters

[in] pFileContext OTA file context information.

Returns: The OTA PAL layer error code combined with the MCU specific error code. See OTA Agent error codes information in ota.h.

OtaPalSuccess is returned on success. OtaPalSignatureCheckFailed is returned when cryptographic signature verification fails. OtaPalBadSignerCert is returned for errors in the certificate itself. OtaPalFileClose is returned when closing the file fails.

◆ OtaPalWriteBlock_t

typedef int16_t(* OtaPalWriteBlock_t) (OtaFileContext_t *const pFileContext, uint32_t offset, uint8_t *const pData, uint32_t blockSize)

Write a block of data to the specified file at the given offset.

Note: This function must always write a complete file block before returning. So the number of bytes written will be equal to the size of the file block. Exception only in case of last block where the number of bytes written will be equal or less than the size of the file block.; The input OtaFileContext_t pFileContext is checked for NULL by the OTA agent before this function is called. The file pointer/handle pFileContext->pFile, is checked for NULL by the OTA agent before this function is called. pData is checked for NULL by the OTA agent before this function is called. blockSize is validated for range by the OTA agent before this function is called. offset is validated by the OTA agent before this function is called.

Parameters

[in]	pFileContext	OTA file context information.
[in]	offset	Byte offset to write to from the beginning of the file.
[in]	pData	Pointer to the byte array of data to write.
[in]	blockSize	The number of bytes to write.

Returns: The number of bytes written on a success, or a negative error code from the platform abstraction layer.

◆ OtaPalActivateNewImage_t

typedef OtaPalStatus_t(* OtaPalActivateNewImage_t) (OtaFileContext_t *const pFileContext)

Activate the newest MCU image received via OTA.

This function shall do whatever is necessary to activate the newest MCU firmware received via OTA. It is typically just a reset of the device.

Note: This function SHOULD not return. If it does, the platform does not support an automatic reset or an error occurred.

Returns: The OTA PAL layer error code combined with the MCU specific error code. See OTA Agent error codes information in ota.h.

◆ OtaPalResetDevice_t

typedef OtaPalStatus_t(* OtaPalResetDevice_t) (OtaFileContext_t *const pFileContext)

Reset the device.

This function shall reset the MCU and cause a reboot of the system.

Note: This function SHOULD not return. If it does, the platform does not support an automatic reset or an error occurred.

Returns: The OTA PAL layer error code combined with the MCU specific error code. See OTA Agent error codes information in ota.h.

◆ OtaPalSetPlatformImageState_t

typedef OtaPalStatus_t(* OtaPalSetPlatformImageState_t) (OtaFileContext_t *const pFileContext, OtaImageState_t eState)

Attempt to set the state of the OTA update image.

Do whatever is required by the platform to Accept/Reject the OTA update image (or bundle). Refer to the PAL implementation to determine what happens on your platform.

Parameters

[in]	pFileContext	File context of type OtaFileContext_t.
[in]	eState	The desired state of the OTA update image.

Returns: The OtaPalStatus_t error code combined with the MCU specific error code. See ota.h for OTA major error codes and your specific PAL implementation for the sub error code.

Major error codes returned are:

OtaPalSuccess on success. OtaPalBadImageState: if you specify an invalid OtaImageState_t. No sub error code. OtaPalAbortFailed: failed to roll back the update image as requested by OtaImageStateAborted. OtaPalRejectFailed: failed to roll back the update image as requested by OtaImageStateRejected. OtaPalCommitFailed: failed to make the update image permanent as requested by OtaImageStateAccepted.

◆ OtaPalGetPlatformImageState_t

typedef OtaPalImageState_t(* OtaPalGetPlatformImageState_t) (OtaFileContext_t *const pFileContext)

Get the state of the OTA update image.

We read this at OTA_Init time and when the latest OTA job reports itself in self test. If the update image is in the "pending commit" state, we start a self test timer to assure that we can successfully connect to the OTA services and accept the OTA update image within a reasonable amount of time (user configurable). If we don't satisfy that requirement, we assume there is something wrong with the firmware and automatically reset the device, causing it to roll back to the previously known working code.

If the update image state is not in "pending commit," the self test timer is not started.

Parameters

[in] pFileContext File context of type OtaFileContext_t.

Returns: An OtaPalImageState_t. One of the following: OtaPalImageStatePendingCommit (the new firmware image is in the self test phase) OtaPalImageStateValid (the new firmware image is already committed) OtaPalImageStateInvalid (the new firmware image is invalid or non-existent)

NOTE: OtaPalImageStateUnknown should NEVER be returned and indicates an implementation error.

Data Structures

Macros

Typedefs

Detailed Description

Macro Definition Documentation

◆ OTA_PAL_ERR_MASK

◆ OTA_PAL_SUB_BITS

◆ OTA_PAL_MAIN_ERR

◆ OTA_PAL_SUB_ERR

◆ OTA_PAL_COMBINE_ERR

Typedef Documentation

◆ OtaPalAbort_t

◆ OtaPalCreateFileForRx_t

◆ OtaPalCloseFile_t

◆ OtaPalWriteBlock_t

◆ OtaPalActivateNewImage_t

◆ OtaPalResetDevice_t

◆ OtaPalSetPlatformImageState_t

◆ OtaPalGetPlatformImageState_t