NVRAM Manager(NVM)模块详细介绍

前言

存储协议栈负责ECU中非易失性数据的存储管理。存储协议栈的分享包括NVM、MemI、Ea、Fea、Eep、Fls模块的详细介绍及代码分析，具体的项目实战请关注本号的后续文章，本篇为NVRAM Manager(NVM)模块详细介绍篇（三）。

正文

4.API详解

如下表所示，NVM的API接口主要分为几大类型。

4.1同步请求函数 Synchronous requests

4.1.1NvM_Init

函数原型：

void NvM_Init(

const NvM_ConfigType* ConfigPtr

)

函数参数：

ConfigPtr：指向选定配置集的指针。

函数描述：用来重置所有内部变量的服务。

函数NvM_Init应将所有内部变量，例如队列、请求标志、状态机，重置为其初始值。它应在内部发出“初始化完成”的信号，例如，以启用作业处理和队列管理。

函数NvM_Init不应修改永久RAM块内容或调用显式同步回调，因为这将在NvM_ReadAll上完成。

函数NvM_Init应将NVM_BLOCK_DATASET类型的所有NVRAM块的数据集索引设置为零。

函数NvM_Init不得初始化其他模块（假设底层层已经初始化）。

提示:耗时的NVRAM块初始化和根据块描述符设置应该由NvM_ReadAll请求完成。

4.1.2 NvM_SetBlockProtection

函数原型：

Std_ReturnType NvM_SetBlockProtection(

NvM_BlockIdType BlockId,

boolean ProtectionEnabled

)

函数返回值：

E_OK: The block was enabled/disabled as requested

E_NOT_OK: An error occured.

函数参数：

BlockId：块标识符唯一地标识一个NVRAM块描述符。NVRAM块描述符包含有关单个NVRAM块的所有所需信息。

ProtectionEnabled：TRUE: Write protection shall be enabled

FALSE: Write protection shall be disabled

函数描述：用于设置/重置NV块的写入保护的服务。

功能NvM_SetBlockProtection通过在相应的NVRAM块的管理部分设置写保护属性，为相应的NV块设置/重置写保护。

NvM模块的环境应在调用函数NvM_SetBlockProtection之前已初始化NvM模块。

4.1.3 NvM_GetErrorStatus

函数原型：

Std_ReturnType NvM_GetErrorStatus(

NvM_BlockIdType BlockId,

NvM_RequestResultType* RequestResultPtr

)

函数返回值：

E_OK：已成功读取与块相关的错误/状态信息。

E_NOT_OK：发生错误。

函数参数：

BlockId：块标识符唯一地标识一个NVRAM块描述符。NVRAM块描述符包含有关单个NVRAM块的所有所需信息。

函数描述：提供以下服务来读取与块相关的错误/状态信息。

函数NvM_GetErrorStatus应在NVRAM块的管理部分中读取与块相关的错误/状态信息。NVRAM块的状态/错误信息应由以前或当前的异步请求来设置。

NvM模块的环境应在调用函数NvM_GetErrorStatus之前已初始化NvM模块。

4.1.4 NvM_CancelJobs

函数原型：

Std_ReturnType NvM_CancelJobs(

NvM_BlockIdType BlockId

)

函数返回值：

E_OK：该作业已被成功地从队列中删除。

E_NOT_OK：在队列中找不到该作业。

函数参数：

BlockId：块标识符唯一地标识一个NVRAM块描述符。NVRAM块描述符包含有关单个NVRAM块的所有所需信息。

函数描述：服务取消所有等待NV块的作业。

函数NvM_CancelJobs应取消指定NV块的队列中所有待定的作业。如果被请求，则对已取消的块的结果类型为NVM_REQ_CANCELED。

当前处理的作业将在NvM_CancelJobs调用之后继续。

如果请求被接受，功能NvM_CancelJobs的工作应提前将指定NVRAM块的块特定请求结果设置为NVM_REQ_CANCELED。

提示:目的只是在清理阶段清空队列，以防终止或重新启动分区，以避免稍后结束作业通知。

4.2异步单块请求 Asynchronous single block requests

4.2.1NvM_ReadBlock

函数原型：

Std_ReturnType NvM_ReadBlock(

NvM_BlockIdType BlockId,

void* NvM_DstPtr

)

函数返回值：

E_OK：请求已被接受。

E_NOT_OK：请求未被接受

函数参数：

BlockId：块标识符唯一地标识一个NVRAM块描述符。NVRAM块描述符包含有关单个NVRAM块的所有所需信息。

NvM_DstPtr:指向RAM数据块的指针

函数描述：将NV块的数据复制到其相应的RAM块的服务。

函数NvM_ReadBlock将接管给定的参数，将读请求放入作业队列中并返回。

4.2.2NvM_WriteBlock

函数原型：

Std_ReturnType NvM_WriteBlock(

NvM_BlockIdType BlockId,

const void* NvM_SrcPtr

)

函数返回值：

E_OK：请求已被接受。

E_NOT_OK：请求未被接受

函数参数：

BlockId：块标识符唯一地标识一个NVRAM块描述符。NVRAM块描述符包含有关单个NVRAM块的所有所需信息。

NvM_SrcPtr:指向RAM数据块的指针

函数描述：将RAM块的数据复制到其相应的NV块的服务。

NvM_WriteBlock函数应测试相应RAM块管理部分的NV块的写入保护属性。如果出现故障，应报告NVM_E_WRITE_PROTECTED/（在生产过程中）错误。

4.2.3 NvMEraseNvBlock

函数原型：

Std_ReturnType NvM_EraseNvBlock(

NvM_BlockIdType BlockId

)

函数返回值：

E_OK：请求已被接受。

E_NOT_OK：请求未被接受

函数参数：

BlockId：块标识符唯一地标识一个NVRAM块描述符。NVRAM块描述符包含有关单个NVRAM块的所有所需信息。

函数描述：要擦除NV块的服务。

4.3异步多块请求 Asynchronous multi block requests

4.3.1NvM_ReadAll

函数原型：

void NvM_ReadAll(

void

)

函数描述：启动一个多块读取请求。

多块服务NvM_ReadAll应提供两种不同的功能:

-- 初始化所有NVRAM块的管理数据

-- 将数据复制到永久RAM块，或为相应配置的NVRAM块调用显式同步回调（NvM_ReadRamBlockFromNvm）。

函数NvM_ReadAll将向NvM模块发出请求信号并返回。NVRAM Manager将延迟处理请求的ReadAll直到所有单个块作业队列为空。

4.3.2 NvM_WriteAll

函数原型：

void NvM_ReadAll(

void

)

函数描述：启动一个多块写入请求。

函数NvM_WriteAll的作业应将永久RAM块的内容同步到它们相应的NV块上，或者在关闭时调用显式同步回调（NvM_WriteRamBlockToNvm）。

如果NVRAM block ID 1(包含内存布局的配置ID)被标记为“在NvM_WriteAll期间写入”，则NvM_WriteAll函数的作业将在最后一步(最后一次写操作)写入该block，以防止在写操作过程中发生掉电故障时内存布局不匹配。

函数NvM_WriteAll应向NvM模块发出请求信号并返回。NVRAM管理器应延迟请求的处理，直到所有单个块作业队列为空。

4.3.2NvM_CancelWriteAll

函数原型：

void NvM_CancelWriteAll(

void

)

函数描述：

取消正在运行的NvM_WriteAll请求。

4.4回调函数

4.4.1 NvM_JobEndNotification

函数原型：

void NvM_JobEndNotification(

void

)

函数描述：底层内存抽象使用该函数表示作业结束，没有错误。

回调函数NvM_JobEndNotification被底层内存抽象用来指示作业结束。

注：作业结束时关于内存抽象的通知成功：

- -- Read finished & OK

- -- Write finished & OK

- -- Erase finished & OK

这个例程可以在中断上下文中被调用，这取决于调用函数。所有内存抽象模块都应该配置为使用相同的模式(回调/轮询)。

如果通过NvMPollingMode禁用了轮询模式，NvM模块只能提供回调函数NvM_JobEndNotification。NvM_JobEndNotification功能受常用配置参数的影响。

4.5期望的接口 Expected Interfaces

4.5.1必需的接口

4.5.2可配置的接口

Single block job end notification

函数原型：

Std_ReturnType NvM_SingleBlockCallbackFunction(

uint8 ServiceId,

NvM_RequestResultType JobResult

)

函数返回值：

E_OK：回调函数已成功处理

任何其他：回调函数已处理失败

函数参数：

ServiceId: NVRAM Manager服务的唯一服务ID。

JobResult: 覆盖以前处理的单块作业的请求结果。

函数描述：每个块回调例程通知上层异步单块请求已经完成。

Multi block job end notification

函数原型：

void NvM_MultiBlockCallbackFunction(

uint8 ServiceId,

NvM_RequestResultType JobResult

)

函数参数：

ServiceId: NVRAM Manager服务的唯一服务ID。

JobResult: 覆盖以前处理的单块作业的请求结果。

函数描述：公共回调例程，通知上层一个异步的多块请求已经完成。

Callback function for block initialization

函数原型：

Std_ReturnType InitBlockCallbackFunction(

void

)

函数返回值：

E_OK：回调函数已成功处理

任何其他：回调函数已处理失败

函数描述：每个块回调例程，当需要在RAM中恢复默认数据时，NvM模块将调用该块回调例程，即使配置了ROM块。

注意:在这里，如果没有配置ROM块，应用程序应该将默认数据复制到RAM块，并且/或者它可以设置一些标志来知道默认数据已经恢复。

5.服务接口 Service Interfaces

本章是对NvM模块规范的补充。尽管该规范的其他部分定义了相应的基本软件模块的行为和c接口，但本章以SWC模板的形式指定了相应的AUTOSAR服务。这里描述的接口将在VFB上可见，并用于生成应用程序软件和NvM模块之间的RTE。

5.1 Client-Server-Interfaces

5.1.1 NvM_Admin

5.1.2 NvM_Mirror

5.1.3 NvM_NotifyInitBlock

5.1.4 NvM_NotifyJobFinished

5.1.5 NvM_Service

5.2 Implementation Data Types

5.2.1 NvM_RequestResultType

5.2.2 NvM_BlockIdType

5.2.3 ConstVoidPtr

5.3 Ports

5.3.1 NvM_PAdmin_{Block}

5.3.2 NvM_PM_{Block}

5.3.3 NvM_PNIB_{Block}

5.3.4 NvM_PNJF_{Block}

5.3.5 NvM_PS_{Block}

6.NVM配置

NvMBlockDescriptor: 容器的管理结构，配置组成一个给定的NVRAM块管理类型。它的多样性描述了配置的NVRAM块的数量，每一个块需要配置。NVRAM块描述符压缩在NVRAM块描述符表中。

NvMCommon: 通用配置选项的容器。配置NVM模块的公共属性。

NvmDemEventParameterRefs: DemEventParameter元素的引用容器，当发生相应的错误时，应该使用API Dem_SetEventStatus调用该元素。EventId取自引用的DemEventParameter的DemEventId符号值。标准化错误在此容器中提供，可以通过特定于供应商的错误引用进行扩展。实际项目中基本不配置。

6.1NvMCommon

NvMApiConfigClass: 预处理器开关，启用一些与NVM API配置类相关的API调用。

NvMBswMMultiBlockJobStatusInformation: 该参数指定是否告知BswM多块作业的当前状态。

True:如果ReadAll和WriteAll被启动、完成、取消，调用BswM_NvM_CurrentJobMode

False:完全不通知BswM

NvMCompiledConfigId: NV内存布局的配置ID。这个配置ID应该被发布，例如，一个SW-C应该有可能把它写入NV内存。

NvMCrcNumOfBytes: 如果为至少一个NVRAM块配置了CRC校验，则该参数定义了一个作业处理周期内需要处理的最大字节数。

NvMDatasetSelectionBits: 定义在内存硬件抽象接口内为NVRAM块的特定数据集寻址时应使用的最低有效位数。

0 . .8:用于数据集或冗余块寻址的位数。

0:不配置数据集或冗余NVRAM块，不需要选择位。

1:配置了冗余NVRAM块，但没有配置dataset NVRAM块

NvMDrvModeSwitch: 在执行NvM_ReadAll和NvM_WriteAll时，预处理器开关使内存驱动切换到快速模式。

true: Fast mode enabled.

false: Fast mode disabled.

NvMDynamicConfiguration: 预处理器开关，启用由NvM_ReadAll请求处理的动态配置管理。

true: Dynamic configuration management handling enabled.

false: Dynamic configuration management handling disabled.

该参数会影响所有与ID为1的Block相关的NvM进程，以及所有与抗更改软件相关的NvM进程。如果关闭了Dynamic Configuration, Block 1不能被NvM使用

NvMJobPrioritization: 预处理器开关，以启用作业优先级处理

true: Job prioritization handling enabled.

false: Job prioritization handling disabled.

NvMMultiBlockCallback: 每个异步多块请求终止时调用的公共回调例程的入口地址

NvMPollingMode: 预处理器开关，以启用/禁用NVRAM管理器中的轮询模式，同时禁用/启用底层可使用的回调函数

NvMRepeatMirrorOperations: 定义应用程序在延迟当前作业之前向NvM模块的镜像复制数据或从镜像复制数据的重试次数。

NvMSetRamBlockStatusApi: 预处理器开关，以启用API NvM_SetRamBlockStatus。

NvMSizeImmediateJobQueue: 定义直接优先级作业队列的队列条目数。如果NVM_JOB_PRIORITIZATION被关闭，则该参数应超出作用范围。

NvMSizeStandardJobQueue: 定义标准作业队列的队列条目数。

6.2NvMBlockDescriptor

NvMBlockCrcType: 定义NVRAM块的CRC数据宽度。默认值：NVM_CRC16，即当NVM_BLOCK_USE_CRC==为true时，将使用CRC16

NvMBlockHeaderInclude: 定义头文件，其中NVRAM块的所有者拥有永久RAM数据块、ROM数据块(如果配置)和每个配置回调的回调函数原型的声明。

如果没有配置永久RAM块、ROM块或回调函数，则该配置参数将被忽略。

NvMBlockManagementType: 定义NVRAM块的块管理类型。

NvMBlockUseAutoValidation: 定义在关闭阶段是否自动验证RAM块。

True:使用了自动验证机制。

False:没有使用自动校验机制。

NvMBlockUseCrc: 定义NVRAM块的CRC使用情况，即在RAM和NV内存中保留用于CRC的内存空间。

true:该NVRAM块将使用CRC。

false:该NVRAM块不使用CRC。

NvMBlockUseCRCCompMechanism: 定义在写作业期间是否将RAM块的CRC与最后一个成功读或写作业期间计算的CRC进行比较。

True:使用比较机制，

False:没有使用比较机制

NvMBlockUseSetRamBlockStatus: 定义改块是否使用NvMSetRamBlockStatusApi。

注意:如果NvMSetRamBlockStatusApi被禁用，这个配置参数将被忽略。

true:调用该RAM块的NvMSetRamBlockStatus将设置该RAM块的状态。

false:该RAM块的NvMSetRamBlockStatus调用将被忽略。

NvMBlockUseSyncMechanism: 定义NV块是否使用带有RAM镜像的显式同步机制和用于向NvM模块的RAM镜像传输数据的回调例程。如果使用同步机制，则为True，否则为false。

NvMBlockWriteProt: 定义NV块的初始写保护

true:启用块初始写保护。

false:关闭块初始写保护。

NvMBswMBlockStatusInformation: 此参数指定是否通知BswM指定块的当前状态。

True:在更改时调用BswM_NvM_CurrentBlockMode

Fasle:不通知BswM

NvMCalcRamBlockCrc: 定义永久RAM块或NVRAM块的CRC(重)计算，它们被配置为使用显式同步机制。

true:这个永久RAM块将(重新)计算CRC。

false:不会(重新)为这个永久RAM块计算CRC。

NvMInitBlockCallback: 块特定回调例程的入口地址，如果没有ROM数据可用于NVRAM块的初始化，将调用该回调例程。如果没有配置，则不需要调用特定的回调例程来初始化具有默认数据的NVRAM块。

NvMMaxNumOfReadRetries: 定义读重试的最大次数。

NvMMaxNumOfWriteRetries: 定义一个NVRAM块的写重试的最大次数。无论配置如何，对于请求NvM_WriteAll和NvM_WriteBlock处理的每个块，都会强制执行一致性检查(可能还有写重试)。

NvMNvBlockLength: 以字节为单位定义NV块数据长度。

NvMNvBlockNum: 根据给定的块管理类型定义连续区域内多个NV块的数量。1-255用于配置块管理类型为nvm_block_datasset .1的NVRAM块配置块管理类型为NVM_BLOCK_NATIVE的NVRAM 2配置块管理类型为nvm_block_redundancy的NVRAM

NvMNvramBlockIdentifier: 通过唯一块标识符标识NVRAM块。实现类型:NvM_BlockIdType。

min = 2 max = 2^(16- NVM_DATASET_SELECTION_BITS)-1预留NVRAM块id:

0 ->通过NvM_GetErrorStatus获得多块请求结果

1 ->冗余NVRAM块，保存配置ID(生成工具应该检查该块从类型、CRC和大小角度正确配置)

NvMNvramDeviceId: 定义NVRAM块所在的NVRAM设备ID。

计算公式: value = TargetBlockReference.[Ea/Fee]BlockConfiguration.[Ea/Fee]DeviceIndex

NvMRamBlockDataAddress: 定义RAM块数据的起始地址。如果不配置，则没有永久RAM数据块可用于所选的块管理类型。

NvMReadRamBlockFromNvCallback: 块特定回调例程的入口地址，为了让应用程序将数据从NvM模块的镜像复制到RAM块，需要调用该回调例程。实现类型:Std_ReturnType

E_OK:拷贝成功

E_NOT_OK:复制不成功，将再次调用回调例程

NvMResistantToChangedSw: 定义一个NVRAM块是否应该被处理为抵抗配置更改。如果在配置时没有可用的缺省数据，则应用程序应负责提供缺省初始化数据。在这种情况下，应用程序必须使用NvM_GetErrorStatus()来区分第一次初始化和损坏的数据。

true: NVRAM块抵抗更改的软件。

false: NVRAM块不抵抗更改的软件。

NvMRomBlockDataAddress: 定义ROM块数据的起始地址。如果不配置，则所选的块管理类型没有可用的ROM块。

NvMBlockDescriptor: 根据给定的块管理类型定义连续区域中的多个ROM块的数量。0 ~ 254用于配置块管理类型为NVM_BLOCK_DATASET的NVRAM块。

0-1配置块管理类型为NVM_BLOCK_NATIVE的NVRAM块0-1配置块管理类型为nvm_block_redundancy的NVRAM块。

NvMSelectBlockForFirstInitAll: 定义一个块是否由NvM_FirstInitAll处理。即使没有永久RAM和/或显式同步，也可以配置块被处理。

TRUE: block将被NvM_FirstInitAll处理

FALSE:块不被NvM_FirstInitAll处理

NvMSelectBlockForReadAll: 定义在NvM_ReadAll期间是否处理NVRAM块。此配置参数仅对配置为具有永久RAM块或配置为使用显式同步机制的NVRAM块有影响。

true: NVRAM块将由NvM_ReadAll处理

false: NvM_ReadAll不处理NVRAM块

NvMSelectBlockForWriteAll: 定义在NvM_WriteAll期间是否处理NVRAM块。此配置参数仅对配置为具有永久RAM块或配置为使用显式同步机制的NVRAM块有影响。

true: NVRAM块将由NvM_WriteAll处理

false: NvM_WriteAll不处理NVRAM块

NvMSingleBlockCallback: 块特定回调例程的入口地址，该例程应在每个异步单个块请求终止时调用

NvMStaticBlockIDCheck: 定义是否启用静态块ID检查。

false:禁用静态块ID检查。

true:启用静态块ID检查。

NvMWriteBlockOnce: 定义首次写后的写保护。NVRAM管理器会在第一次写入NV块之后设置写保护位，或者在对NV块进行读取时，如果该块已经写入并且检测到它是有效的和一致的，那么NVRAM管理器就会设置写保护位。

true:定义首次写后的写保护。

false:定义禁用首次写后的写保护。

NvMWriteRamBlockToNvCallback: 块特定回调例程的入口地址，为了让应用程序将数据从RAM块复制到NvM模块的镜像，需要调用该回调例程。实现类型:Std_ReturnType

E_OK:拷贝成功

E_NOT_OK:复制不成功，将再次调用回调例程

NvMWriteVerification: 定义是否启用写验证。

false:关闭写校验。

true:启用写校验功能。

审核编辑：刘清