前言

存儲協議棧負責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:啟用寫校驗功能。

審核編輯：劉清