包含 PAL 接口状态、类型定义和用于存储接口例程的结构体。更多……

#include "ota_private.h"

包含 ota_platform_interface.h 的依赖关系图：

此图显示了哪些文件直接或间接包含此文件：

数据结构体
struct	OtaPalInterface_t
	OTA pal 接口结构体。更多……

宏
#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 ) )

Typedef
typedef uint32_t	OtaPalStatus_t
	OTA 平台接口返回状态。由主状态和子状态组成。

typedef uint32_t	OtaPalSubStatus_t
	OTA 平台接口的子状态。

typedef OtaPalStatus_t(*	OtaPalAbort_t) (OtaFileContext_t *const pFileContext)
	中止 OTA 传输。更多……

typedef OtaPalStatus_t(*	OtaPalCreateFileForRx_t) (OtaFileContext_t *const pFileContext)
	在数据块进入时创建新的接收文件。更多……

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)
	按照给定偏移量将数据块写入指定文件。更多……

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)
	重置设备。更多……

typedef OtaPalStatus_t(*	OtaPalSetPlatformImageState_t) (OtaFileContext_t *const pFileContext, OtaImageState_t eState)
	尝试设置 OTA 更新映像的状态。更多……

typedef OtaPalImageState_t(*	OtaPalGetPlatformImageState_t) (OtaFileContext_t *const pFileContext)
	获取 OTA 更新映像的状态。更多……

枚举
enum	OtaPalMainStatus_t { OtaPalSuccess = 0 , OtaPalUninitialized = 0xe0 , OtaPalOutOfMemory , OtaPalNullFileContext , OtaPalSignatureCheckFailed , OtaPalRxFileCreateFailed , OtaPalRxFileTooLarge , OtaPalBootInfoCreateFailed , OtaPalBadSignerCert , OtaPalBadImageState , OtaPalAbortFailed , OtaPalRejectFailed , OtaPalCommitFailed , OtaPalActivateFailed , OtaPalFileAbort , OtaPalFileClose }
	OTA 平台接口主状态。更多……

详细描述

包含 PAL 接口状态、类型定义和用于存储接口例程的结构体。

宏定义文档

◆ OTA_PAL_ERR_MASK

#define OTA_PAL_ERR_MASK 0xffffffUL

PAL 层使用 OTA 错误代码中有符号的低 24 位。

◆ OTA_PAL_SUB_BITS

#define OTA_PAL_SUB_BITS 24U

OTA Agent 的错误代码为该字的最高 8 位。

◆ OTA_PAL_MAIN_ERR

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

用于获取 OTA PAL 主错误代码的帮助程序。

◆ OTA_PAL_SUB_ERR

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

用于获取 OTA PAL 子错误代码的帮助程序。

◆ 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 ) )

用于将 OTA PAL 主错误代码和子错误代码结合的帮助程序。

Typedef 文档

◆ OtaPalAbort_t

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

中止 OTA 传输。

中止对由 OTA 文件上下文 pFileContext 表示的现有打开文件的访问。这仅对已成功启动的作业有效。

注意: 在调用此函数之前，输入 OtaFileContext_t pFileContext 会由 OTA Agent 检查是否为 NULL。此函数可能会在文件打开之前被调用，因此在调用时，文件指针 pFileContext->fileHandle 可能为 NULL。

Parameters

[in] pFileContext OTA 文件上下文信息。

返回: 结合了 OTA PAL 层错误代码和与 MCU 相关的错误代码。请参见 ota.h 中的 OTA Agent 错误代码信息。

在此函数返回后，文件指针将被设置为 NULL。成功中止对打开文件的访问则返回 OtaPalSuccess。未能成功中止对打开文件的访问则返回 OtaPalFileAbort。

◆ OtaPalCreateFileForRx_t

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

在数据块进入时创建新的接收文件。

请注意，: 在 MCU 文件系统中打开 OTA 文件上下文中指定的文件。; 指定的映像下载分区或文件中可能存在先前的映像，因此必须在此例程中完全擦除或覆盖分区或文件。; 在调用此函数之前，输入 OtaFileContext_t pFileContext 会由 OTA Agent 检查是否为 NULL。设备文件路径是 OTA 任务文档中的必填字段，因此在调用此函数之前，OTA Agent 会检查 pFileContext->pFilePath 是否为 NULL。

Parameters

[in] pFileContext OTA 文件上下文信息。

返回: 结合了 OTA PAL 层错误代码和与 MCU 相关的错误代码。请参见 ota.h 中的 OTA Agent 错误代码信息。

成功创建文件则返回 OtaPalSuccess。如果要创建的文件超过设备非易失性存储器的大小限制，则返回 OtaPalRxFileTooLarge。如果创建引导加载程序信息文件失败，则返回 OtaPalBootInfoCreateFailed。对于在设备非易失性存储器中创建文件时发生的其他错误，则返回 OtaPalRxFileCreateFailed。

◆ OtaPalCloseFile_t

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

在指定的 OTA 上下文中验证并关闭底层接收文件。

请注意，: 在调用此函数之前，输入 OtaFileContext_t pFileContext 会由 OTA Agent 检查是否为 NULL。此函数仅在块摄取结束时调用。由于在 prvPAL_CreateFileForRx() 成功执行后才会到达此函数，pFileContext->fileHandle（或 pFileContext->pFile）永远不会为 NULL。由于设备上的证书路径是 OTA Agent 中的必填任务文档字段，pFileContext->pCertFilepath 永远不会为 NULL。由于文件签名密钥是 OTA Agent 中的必填任务文档字段，pFileContext->pSignature 永远不会为 NULL。

如果签名验证失败，仍应尝试关闭文件。

参数

[in] pFileContext OTA 文件上下文信息。

返回: 结合了 OTA PAL 层错误代码和与 MCU 相关的错误代码。请参见 ota.h 中的 OTA Agent 错误代码信息。

成功则返回 OtaPalSuccess。加密签名验证失败则返回 OtaPalSignatureCheckFailed。对于证书本身发生的错误，则返回 OtaPalBadSignerCert。关闭文件失败则返回 OtaPalFileClose。

◆ OtaPalWriteBlock_t

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

按照给定偏移量将数据块写入指定文件。

注意: 在调用此函数之前，输入 OtaFileContext_t pFileContext 会由 OTA Agent 检查是否为 NULL。在调用此函数之前，OTA Agent 会检查文件指针/句柄 pFileContext->pFile 是否为 NULL。在调用此函数之前，OTA Agent 会检查 pData 是否为 NULL。在调用此函数之前，OTA Agent 会验证 blockSize 的范围。在调用此函数之前，OTA Agent 会验证偏移量。

Parameters

[in]	pFileContext	OTA 文件上下文信息。
[in]	offset	要从文件开头写入的字节偏移量。
[in]	pData	指向要写入数据的字节数组的指针。
[in]	blockSize	要写入的字节数。

返回值: 成功则返回写入的字节数，否则返回来自平台抽象层的负值错误代码。

◆ OtaPalActivateNewImage_t

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

激活通过 OTA 接收的最新 MCU 映像。

此函数将执行任何必要操作来激活通过 OTA 接收的最新 MCU 固件。通常情况下，重置设备即可。

注意: 此函数不应返回值。如果其返回值，平台将不支持自动重置或者会发生错误。

返回: 结合了 OTA PAL 层错误代码和与 MCU 相关的错误代码。请参见 ota.h 中的 OTA Agent 错误代码信息。

◆ OtaPalResetDevice_t

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

重置设备。

此函数将重置 MCU 并使系统重新启动。

请注意，: 此函数不应返回值。如果其返回值，平台将不支持自动重置或者会发生错误。

返回: 结合了 OTA PAL 层错误代码和与 MCU 相关的错误代码。请参见 ota.h 中的 OTA Agent 错误代码信息。

◆ OtaPalSetPlatformImageState_t

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

尝试设置 OTA 更新映像的状态。

执行平台要求的任何操作以接受/拒绝 OTA 更新映像（或捆绑包）。请参阅 PAL 实现，确定平台上的情况。

参数

[in]	pFileContext	类型 OtaFileContext_t 的文件上下文。
[in]	eState	所需的 OTA 更新映像状态。

返回: OtaPalStatus_t 错误代码和 MCU 特定错误代码。请参见 ota.h 了解 OTA 主错误代码，参见具体的 PAL 实现了解子错误代码。

返回的主错误代码如下：

成功则返回 OtaPalSuccess。OtaPalBadImageState：如果指定的 OtaImageState_t 无效。无子错误代码。OtaPalAbortFailed：未能按 OtaImageStateAborted 的请求回滚更新映像。OtaPalRejectFailed：未能按 OtaImageStateRejected 的请求回滚更新映像。OtaPalCommitFailed：未能按 OtaImageStateAccepted 的请求使更新映像永久化。

◆ OtaPalGetPlatformImageState_t

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

获取 OTA 更新映像的状态。

我们会在 OTA_Init 时以及在最新 OTA 任务报告其正在执行自检时读取此值。如果更新映像处于“挂起的提交”状态，我们将启动自检定时器，确保能够成功连接到 OTA 服务并在合理的时间内（用户可配置）接受 OTA 更新映像。如果这一要求无法得到满足，我们将假定固件出现问题，设备自动重置，导致其回滚到先前已知的工作代码。

如果更新映像未处于“挂起的提交”状态，将不会启动自检定时器。

参数

[in] pFileContext 类型 OtaFileContext_t 的文件上下文。

返回值: OtaPalImageState_t。下列值之一：OtaPalImageStatePendingCommit（新固件映像处于自检阶段）； OtaPalImageStateValid（新固件映像已经提交）； OtaPalImageStateInvalid（新固件映像无效或不存在）

注意：应该永远不会返回 OtaPalImageStateUnknown，否则表明存在实现错误。

数据结构体

宏

Typedef

枚举

详细描述

宏定义文档

◆ OTA_PAL_ERR_MASK

◆ OTA_PAL_SUB_BITS

◆ OTA_PAL_MAIN_ERR

◆ OTA_PAL_SUB_ERR

◆ OTA_PAL_COMBINE_ERR

Typedef 文档

◆ OtaPalAbort_t

◆ OtaPalCreateFileForRx_t

◆ OtaPalCloseFile_t

◆ OtaPalWriteBlock_t

◆ OtaPalActivateNewImage_t

◆ OtaPalResetDevice_t

◆ OtaPalSetPlatformImageState_t

◆ OtaPalGetPlatformImageState_t