NVRAM Manager (NvM)

Usage and Call Context

The function NvM_Init serves to synchronously reset all internal variables of the NVRAM Manager [SWS_NvM_00447]. It expects a pointer to the selected configuration data set as parameter ConfigPtr and has no return value [SWS_NvM_00447]. As a type 4 API, it is part of configuration classes 2 and 3 [SWS_NvM_00560], [SWS_NvM_00561]. The function is non-reentrant and may exclusively be called by the BSW Mode Manager [SWS_NvM_00447], [SWS_NvM_00693].

Initialization tasks

During the call, the function performs the following actions:

• Resetting all internal variables, including state machines, job queues, and request flags, to their initial values [SWS_NvM_00399].
• Setting the record index of all NVRAM blocks of type NVM_BLOCK_DATASET to zero [SWS_NvM_00192].
• Internally setting the signal "INIT DONE", which is the prerequisite for job processing, queue management, and CRC recalculation in the module [SWS_NvM_00257], [SWS_NvM_00399].

Restrictions and Interaction

Due to strict ECU startup time requirements, NvM_Init does not initialize any configured NVRAM blocks [SWS_NvM_00091]. Permanent RAM block contents are not modified and synchronization callbacks are not called; this is reserved for the function NvM_ReadAll [SWS_NvM_00400]. Furthermore, NvM_Init initializes neither underlying drivers nor the memory hardware abstraction or external modules, as their initialization by the BSW Mode Manager is assumed [SWS_NvM_00157], [SWS_NvM_00193].

Usage and Semantics

The synchronous and reentrant function NvM_SetBlockProtection serves to set or reset the write protection for an NVRAM block via the corresponding attribute in the administrative block [SWS_NvM_00450], [SWS_NvM_00016]. It is assigned to API configuration class 3 [SWS_NvM_00560]. The environment of the NvM module can selectively enable or disable write protection via parameter ProtectionEnabled [SWS_NvM_00578]. The function returns E_OK upon successful execution and E_NOT_OK in case of an error [SWS_NvM_00450].

Restrictions and Concurrency

Changing the write protection is only permitted for blocks where NvMWriteBlockOnce is configured to FALSE, regardless of the value of parameter NvMBlockWriteProt [SWS_NvM_00325]. If NvMWriteBlockOnce is configured to TRUE, write protection must neither be enabled nor disabled [SWS_NvM_00398], [SWS_NvM_00577]; this protection cannot be removed even after read operations [SWS_NvM_00314], [SWS_NvM_00316], [SWS_NvM_00784]. Furthermore, a locked state set via NvM_SetBlockLockStatus cannot be modified by NvM_SetBlockProtection [SWS_NvM_00754]. As long as a single-block job is active or queued for the same block, the call is not permitted [SWS_NvM_00704].

Error handling

When development error detection (DET) is enabled, the function reports specific error states:

• NVM_E_UNINIT if the NvM module is not yet initialized [SWS_NvM_00606].
• NVM_E_PARAM_BLOCK_ID if the passed BlockId is out of the valid range [SWS_NvM_00609].
• NVM_E_BLOCK_PENDING if an operation is already active or queued for the block [SWS_NvM_00607].
• NVM_E_BLOCK_CONFIG if the block is configured with NvMWriteBlockOnce = TRUE [SWS_NvM_00608].
• NVM_E_BLOCK_LOCKED if the block is locked [SWS_NvM_00759].

The synchronous and reentrant function NvM_SetRamBlockStatus serves to set the RAM block status for permanent RAM blocks or for blocks with explicit synchronization [SWS_NvM_00453]. It is available in API configuration classes 2 and 3 [SWS_NvM_00561], [SWS_NvM_00560], provided it has been enabled via the configuration parameter NvMSetRamBlockStatusApi [SWS_NvM_00408].

Parameter BlockChanged controls whether the block is marked as valid and changed (TRUE) or as invalid and unchanged (FALSE) [SWS_NvM_00453], [SWS_NvM_00406]. When passing TRUE, the module assumes the validity of the data [SWS_NvM_00241]. The function returns E_OK upon a successful status change and E_NOT_OK in case of an error [SWS_NvM_00453].

If BlockChanged is set to TRUE, the function requests a checksum recalculation in NvM_MainFunction in the background if NvMCalcRamBlockCrc is configured [SWS_NvM_00121]. For blocks without permanent RAM with explicit synchronization, this job uses the write callback to obtain data [SWS_NvM_00906]. If this fails, configured retries occur per call of NvM_MainFunction [SWS_NvM_00907], [SWS_NvM_00908]. If all attempts remain unsuccessful, the job is nevertheless considered finished and the block remains marked as changed [SWS_NvM_00909].

Before the call, the NvM module must be initialized [SWS_NvM_00711]. If development error detection is active, the function reports NVM_E_UNINIT if the module is uninitialized [SWS_NvM_00643], NVM_E_PARAM_BLOCK_ID in case of invalid BlockId [SWS_NvM_00645], and NVM_E_BLOCK_PENDING if jobs are already running or queued [SWS_NvM_00644]. As long as a single-block job is active, the function must not be called for this block [SWS_NvM_00704]. A block lock set via NvM_SetBlockLockStatus cannot be modified via this [SWS_NvM_00754].

Usage and Call Context

The synchronous and reentrant function NvM_SetBlockLockStatus serves to lock (BlockLocked = TRUE) or unlock (BlockLocked = FALSE) a permanently configured RAM block or the explicit synchronization of an NVRAM block [SWS_NvM_00548]. It belongs to the functional scope of API configuration classes 2 and 3 [SWS_NvM_00561], [SWS_NvM_00560]. The function is not included in the ServicePort interface and is primarily called by the DCM as well as by complex device drivers (CDD) [SWS_NvM_00732].

Restrictions and Interaction

The call affects only NVRAM blocks with a permanent RAM block or configured explicit synchronization; for all other blocks, it remains without effect [SWS_NvM_00732]. If a block is locked (BlockLocked = TRUE), the NvM ensures that the associated NV data are not modified: The block is skipped during NvM_WriteAll, and the services NvM_WriteBlock, NvM_WritePRAMBlock, NvM_InvalidateNvBlock as well as NvM_EraseNvBlock are rejected [SWS_NvM_00751]. During the next startup, the NvM is guaranteed to load the block from NV memory during NvM_ReadBlock or NvM_ReadPRAMBlock [SWS_NvM_00752]. The set lock status cannot be modified via NvM_SetRamBlockStatus nor via NvM_SetBlockProtection [SWS_NvM_00754]. Passing BlockLocked = FALSE restores regular processing [SWS_NvM_00753].

Error handling

When development error detection (DET) is enabled, the function reports specific development errors:

• NVM_E_UNINIT, if the NvM module is not yet initialized at the time of the call [SWS_NvM_00728].
• NVM_E_PARAM_BLOCK_ID, if the parameter BlockId is outside the permissible range [SWS_NvM_00731].
• NVM_E_BLOCK_CONFIG, provided that the referenced NVRAM block is configured with the parameter NvMWriteBlockOnce = TRUE [SWS_NvM_00730].

Usage and Semantics

The function NvM_CancelJobs, available via NvM.h, serves to synchronously cancel all queued jobs for a specific NVRAM block [SWS_NvM_00535], [SWS_NvM_00536]. The function is designed as reentrant and expects as a parameter the BlockId, which uniquely identifies the block descriptor of the NVRAM block concerned [SWS_NvM_00535]. The call returns E_OK if queued jobs could be successfully removed from the queue, and E_NOT_OK if no job was found in the queue for the specified block [SWS_NvM_00535].

Sequence and concurrency

A job that is already actively being processed at the time of the function call is not interrupted by NvM_CancelJobs, but continues to run until the end [SWS_NvM_00537]. If the cancellation request for waiting jobs is accepted, the service pre-sets the block-specific request result to NVM_REQ_CANCELED [SWS_NvM_00225], [SWS_NvM_00536]. The purpose of this cleanup is to clear the queue, for example upon termination or restart of a partition, and thus prevent subsequent notifications about completed jobs [SWS_NvM_00225].

Error Handling and Configuration

When development error detection (DET) is enabled, the function checks the preconditions: If the module is not yet initialized, the error NVM_E_UNINIT is reported [SWS_NvM_00648]. If the passed BlockId is outside the valid range, the DET message NVM_E_PARAM_BLOCK_ID is issued [SWS_NvM_00649]. NvM_CancelJobs is classified as a Type 2 API and is available in API configuration classes 2 and 3 [SWS_NvM_00561], [SWS_NvM_00560].

Usage and Semantics

The function NvM_ReadBlock serves for asynchronously copying user data from NV memory into the associated RAM block [SWS_NvM_00010], [SWS_NvM_00454]. The call is reentrant [SWS_NvM_00454]. It accepts the parameters, queues the read request into the internal job queue, and immediately returns E_OK upon successful acceptance or E_NOT_OK upon rejection [SWS_NvM_00195], [SWS_NvM_00454].

If a pointer NvM_DstPtr is passed, data can be read into a temporary RAM buffer deviating from the block configuration; an invalid NULL pointer leads to a DET error in this scenario [SWS_NvM_00196], [SWS_NvM_00278]. A configured permanent RAM block is marked as invalid directly upon queuing or at the start of job processing [SWS_NvM_00198]. Only after a successful copy operation is the RAM block considered valid as well as unchanged [SWS_NvM_00200], and the job result changes to NVM_REQ_OK [SWS_NvM_00206].

Error Handling and Data Integrity

If a checksum is enabled for the block (NvMCalRamBlockCrC == TRUE), the job requests a recalculation after copying [SWS_NvM_00201]:

• In the case of CRC errors, NVM_E_INTEGRITY_FAILED is reported to the DEM [SWS_NvM_00203]. If available, default values are loaded and the result is set to NVM_REQ_RESTORED_DEFAULTS [SWS_NvM_00202]. If ROM data and initialization callbacks are missing, NVM_REQ_INTEGRITY_FAILED results [SWS_NvM_00204].
• If the memory driver reports MEMIF_JOB_FAILED and no replacement values are available, the job ends with NVM_REQ_NOT_OK [SWS_NvM_00359].

Special Features of the Block Types

• Redundant: If reading the first copy fails, the second NV copy is automatically used [SWS_NvM_00199]. If both copies are invalid, the overall block is invalidated [SWS_NvM_00317].
• Dataset: If the block selected via the dataset index is marked as invalid, copying to the RAM is omitted [SWS_NvM_00355].
• Write-Once: Consistently read blocks with NVM_WRITE_BLOCK_ONCE set become permanently write-protected [SWS_NvM_00316].

The function NvM_WriteBlock serves to copy data of a RAM block to the assigned NV block [SWS_NvM_00455], [SWS_NvM_00410]. The call is executed reentrantly and asynchronously: The function accepts the passed parameters BlockId and NvM_SrcPtr, queues the write job in the internal job queue, and returns immediately [SWS_NvM_00208]. The return value indicates successful acceptance with E_OK or rejection of the job with E_NOT_OK [SWS_NvM_00455].

Regarding parameterization and data source, the following specifications apply:

• If a valid RAM address is passed via NvM_SrcPtr, the write job uses this buffer [SWS_NvM_00210]. This also allows saving temporary RAM blocks for blocks that are actually permanently configured or have explicit synchronization [SWS_NvM_00280].
• A configured permanent RAM block is assumed to be valid or is automatically validated before the copying process [SWS_NvM_00303].
• If a checksum is configured for the NV block, the job requests a CRC recalculation before the write operation [SWS_NvM_00212].
• For dataset blocks (NVM_BLOCK_DATASET), the target is selected via the data index stored in the administrative block [SWS_NvM_00338].
• For redundant blocks (NVM_BLOCK_REDUNDANT), the job completes with NVM_REQ_OK as soon as at least one copy has been successfully written [SWS_NvM_00284].
• If NvMWriteBlockOnce == TRUE is set, the job immediately enables write protection in the administrative block after successful writing [SWS_NvM_00328].
• Write jobs for the reserved block ID 1 are only permitted when NvMDynamicConfiguration is enabled [SWS_NvM_00311].

Error handling and concurrency:

• If development detection is active, NvM_WriteBlock reports the DET error NVM_E_UNINIT when the module is uninitialized [SWS_NvM_00619] as well as NVM_E_BLOCK_PENDING if the same block is already being processed or is queued [SWS_NvM_00620]. A missing source pointer for temporary buffers results in a DET parameter error [SWS_NvM_00280].
• Negative responses from the memory interface increment the retry counter; after exceeding NVM_MAX_NUM_OF_WRITE_RETRIES, the job ends with NVM_REQ_NOT_OK [SWS_NvM_00213], [SWS_NvM_00216].
• If the block is configured with immediate priority, NvM_WriteBlock destructively aborts a currently running job so that the write job is processed next [SWS_NvM_00300].

Usage and Semantics

The function NvM_RestoreBlockDefaults restores default data in the associated RAM block ([SWS_NvM_00456], [SWS_NvM_00012]). It operates asynchronously: after being called, it accepts the parameters, queues the request into the internal job queue, and returns immediately with E_OK upon successful acceptance or with E_NOT_OK upon rejection ([SWS_NvM_00456], [SWS_NvM_00224]). If a valid RAM address is passed via the output parameter NvM_DestPtr, this is used as the target address ([SWS_NvM_00435]). To copy ROM data into a temporary RAM block even though a permanent RAM block or synchronization callbacks are configured, the caller must mandatory pass a pointer not equal to NULL ([SWS_NvM_00436]).

Error Handling and Boundary Conditions

The function is non-reentrant ([SWS_NvM_00456]) and part of API configuration classes 2 and 3 ([SWS_NvM_00561], [SWS_NvM_00560]). If development error detection (DET) is active, it reports NVM_E_UNINIT if the module is still uninitialized ([SWS_NvM_00625]), NVM_E_PARAM_BLOCK_ID for an invalid BlockId ([SWS_NvM_00630]), and a parameter error if no valid target pointer is passed for temporary copying in permanently configured blocks ([SWS_NvM_00436]). The function fails synchronously with E_NOT_OK if the block is of type NVM_BLOCK_DATASET, at least one ROM block exists, and the current data index points to an NV block ([SWS_NvM_00353]).

Job Processing and Interaction

As part of asynchronous job processing, the service loads default values from a configured ROM block ([SWS_NvM_00267]). If a permanent RAM block is requested or an explicit synchronization callback (NvMReadRamBlockFromNvCallback) is used, the RAM block is invalidated prior to the copy operation or prior to the callback invocation ([SWS_NvM_00227]). After a successful copy operation or after the synchronization callback returns with E_OK, the RAM block is validated and marked as changed ([SWS_NvM_00228]). If a checksum is configured for the block, the job finally requests a CRC recalculation ([SWS_NvM_00229]). The same recovery logic is also used by NvM_ReadBlock and NvM_ReadAll as a fallback mechanism in case of faulty memory read access or CRC errors ([SWS_NvM_00202], [SWS_NvM_00293], [SWS_NvM_00657]).

The reentrant, asynchronous function NvM_EraseNvBlock ([SWS_NvM_00457]) of API configuration class 3 ([SWS_NvM_00560]) serves for erasing a non-volatile memory block based on the passed BlockId. If no write protection is active, the function accepts the parameters, queues the erase job into the internal job queue, and returns immediately ([SWS_NvM_00231], [SWS_NvM_00418]). The return value E_OK signals the successful acceptance of the job, while E_NOT_OK indicates rejection ([SWS_NvM_00457]).

Before the call, the NvM module must be fully initialized ([SWS_NvM_00715]). After queuing, write protection is not checked again before the job is retrieved from the queue ([SWS_NvM_00662]). For redundant blocks of type NVM_BLOCK_REDUNDANT, the erase operation is only considered successful once both redundant NV blocks have been erased ([SWS_NvM_00269]). The data content of an associated RAM block always remains unchanged by the job processing ([SWS_NvM_00416]).

A call is rejected if a ROM block of a dataset block is addressed ([SWS_NvM_00661]) or the block is locked via NvM_SetBlockLockStatus ([SWS_NvM_00751]). With development error detection (DET) activated, the function reports NVM_E_UNINIT if the module is uninitialized ([SWS_NvM_00631]), NVM_E_PARAM_BLOCK_ID for an invalid BlockId ([SWS_NvM_00635]), and NVM_E_BLOCK_LOCKED for a blocked block ([SWS_NvM_00757]). If the block does not have immediate priority or standard priority is configured, error NVM_E_BLOCK_CONFIG is reported and E_NOT_OK is returned if DET is active ([SWS_NvM_00357], [SWS_NvM_00636]). If the subsequent asynchronous execution fails, the request status is set to NVM_REQ_NOT_OK ([SWS_NvM_00271]) and NVM_E_REQ_FAILED is reported to the DEM ([SWS_NvM_00663]).

The function NvM_InvalidateNvBlock is an asynchronous and reentrant service of API configuration class 3 for invalidating an NV block [SWS_NvM_00459], [SWS_NvM_00560]. The call prerequisite is that the NvM module must previously have been initialized by the module environment [SWS_NvM_00717]. The call accepts parameter BlockId, queues the request into the queue when write protection is deactivated, and returns with E_OK [SWS_NvM_00239], [SWS_NvM_00424]. If the job cannot be accepted, the function returns E_NOT_OK [SWS_NvM_00459].

A call is rejected synchronously with E_NOT_OK if a ROM block of a dataset block is specified via BlockId [SWS_NvM_00664]. If the block was previously locked via NvM_SetBlockLockStatus, the NvM rejects the job [SWS_NvM_00751] and reports the DET error NVM_E_BLOCK_LOCKED if the development error interface is active [SWS_NvM_00756]. If the block is already queued or in execution, the DET message NVM_E_BLOCK_PENDING is issued [SWS_NvM_00639].

The actual asynchronous job invalidates the referenced NV block [SWS_NvM_00421] taking the following constraints into account:

• For redundant blocks (NVM_BLOCK_REDUNDANT), the job result is only set to NVM_REQ_OK once both redundant NV blocks have been successfully invalidated [SWS_NvM_00274]; the same mechanism is also used for NvM_FirstInitAll [SWS_NvM_00919], [SWS_NvM_00920].
• For blocks with NVM_WRITE_BLOCK_ONCE, the job leaves the write protection unchanged [SWS_NvM_00960]. If no read operation preceded, the job reports the DET error NVM_E_WRITE_ONCE_STATUS_UNKNOWN [SWS_NvM_00958].
• If an error occurs during asynchronous processing, the request result is set to NVM_REQ_NOT_OK [SWS_NvM_00275] and the production error NVM_E_REQ_FAILED is transmitted to the DEM [SWS_NvM_00666].

use

The asynchronous and reentrant function [SWS_NvM_00764] serves to copy data of an NV block into the associated permanent RAM block. The call takes over the BlockId, enqueues the read request into the internal job queue, and returns immediately [SWS_NvM_00766]. The return value E_OK confirms the acceptance of the job, whereas E_NOT_OK signals a rejection [SWS_NvM_00764]. The function belongs to the functional scope of API configuration classes 2 and 3 [SWS_NvM_00560], [SWS_NvM_00561].

Sequence and Synchronization

Upon successful enqueuing of the job or start of processing, the permanent RAM block is invalidated immediately [SWS_NvM_00767]. If an explicit synchronization is set up for the block, the application is allowed to modify the RAM block until the synchronization routine arrives; in this case, invalidation takes place directly before the call of NvMReadRamBlockFromNvCallback [SWS_NvM_00706], [SWS_NvM_00767]. If the NV data were transferred into the RAM without errors, the job completes with the status NVM_REQ_OK [SWS_NvM_00765], [SWS_NvM_00775].

Error Handling and Redundancy

For blocks of type NVM_BLOCK_REDUNDANT, the job automatically starts a read attempt on the second block if the first read attempt fails [SWS_NvM_00768]. For datasets (NVM_BLOCK_DATASET), copying is prevented if the NV block selected via the index is inconsistent [SWS_NvM_00771]; if the index references ROM data, these are loaded and the result is set to NVM_REQ_OK [SWS_NvM_00772]. If default data are configured and the NV block cannot be read while the RAM state is invalid, an implicit restoration takes place [SWS_NvM_00575], which classifies the RAM block as valid as well as changed [SWS_NvM_00774]; without configured default values, restoration is omitted [SWS_NvM_00572]. If NvM_SetBlockLockStatus was previously active, reloading from NV memory is enforced [SWS_NvM_00752].

The reentrant, asynchronous function NvM_WritePRAMBlock initiates writing the data of a permanent RAM block into the associated NV block [SWS_NvM_00793], [SWS_NvM_00794]. The function is available in API configuration classes 2 and 3 [SWS_NvM_00561], [SWS_NvM_00560]. The reserved block ID 1 may only be passed if NvMDynamicConfiguration is set to TRUE [SWS_NvM_00311].

Upon passing, the function provides E_OK on successful acceptance or E_NOT_OK [SWS_NvM_00793]. If the referenced block is locked, the call fails with E_NOT_OK and the module reports a DET error [SWS_NvM_00797]. Block protection is already checked upon enqueuing into the job queue and is not validated again prior to job execution [SWS_NvM_00799]. If the NVRAM block has immediate priority, a running job is immediately destructively aborted and this write job is processed next [SWS_NvM_00800].

Prior to the actual transfer into the NV memory, the job requests a CRC recalculation, provided that the block is configured with CRC [SWS_NvM_00801]. A still invalid permanent RAM block is automatically validated [SWS_NvM_00803]. For redundant blocks (NVM_BLOCK_REDUNDANT), both NV blocks are written, beginning with the one that was not read during preceding read jobs [SWS_NvM_00807], [SWS_NvM_00808]. In the event of write errors, the number of retries is limited by NVM_MAX_NUM_OF_WRITE_RETRIES [SWS_NvM_00806]; in the event of an overflow, the NvM sets the job result to NVM_REQ_NOT_OK [SWS_NvM_00804] and reports NVM_E_REQ_FAILED to the DEM [SWS_NvM_00805].

With respect to concurrency, the following applies: With implicit synchronization, the application must no longer modify the buffer data after the call until the end of the job; read access remains permitted [SWS_NvM_00698]. With explicit synchronization, the buffer may be modified until the callback routine NvMWriteRamBlockToNvCallback is called [SWS_NvM_00705].

Usage and Semantics

The function NvM_RestorePRAMBlockDefaults restores default data in the associated permanent RAM block ([SWS_NvM_00813], [SWS_NvM_00814]). The service operates asynchronously and accepts the identifier of the NVRAM block descriptor via the parameter BlockId ([SWS_NvM_00813]). Upon the call, the request is enqueued into the internal job queue ([SWS_NvM_00815]). The return value E_OK signals successful acceptance, whereas E_NOT_OK indicates a rejection ([SWS_NvM_00813]). If a ROM block is configured, the data are loaded from it within the scope of the asynchronous processing ([SWS_NvM_00816]).

Error Handling and Boundary Conditions

If neither ROM default data nor a callback routine NvMInitBlockCallback are configured for the block, the block status remains unchanged and the call provides E_NOT_OK ([SWS_NvM_00884]). When development error detection (DET) is enabled, specific errors are reported:

• NVM_E_UNINIT: The module is not yet initialized ([SWS_NvM_00831]).
• NVM_E_PARAM_BLOCK_ID: The passed BlockId is out of the valid range ([SWS_NvM_00834]).
• NVM_E_BLOCK_PENDING: A job is already queued or in progress for the block ID ([SWS_NvM_00832]).
• NVM_E_BLOCK_WITHOUT_DEFAULTS: Neither ROM default data nor an initialization callback exist ([SWS_NvM_00886]).
• NVM_E_PARAM_ADDRESS: Neither a permanent RAM block nor explicit synchronization is configured ([SWS_NvM_00894]).

Concurrency and Interaction

The service is specified as non-reentrant ([SWS_NvM_00813]) and is available in API configuration classes 2 and 3 ([SWS_NvM_00561], [SWS_NvM_00560]). The same restoration logic is additionally used internally during NvM_ReadPRAMBlock if the underlying read operation fails ([SWS_NvM_00789], [SWS_NvM_00882]).

The function NvM_ReadAll asynchronously triggers a multi-block read job to initialize the RAM data blocks [SWS_NvM_00460], [SWS_NvM_00158]. It has no parameters, provides no return value, and is non-reentrant [SWS_NvM_00460]. The call signals the request to the NvM module and returns immediately; actual processing, however, is delayed until all single-block job queues are empty [SWS_NvM_00243].

At the beginning, the job validates the configuration ID during system startup by comparing the stored value with the compiled value [SWS_NvM_00073], [SWS_NvM_00246]:

• If they match, standard preparation takes place for all configured blocks [SWS_NvM_00247].
• A configuration difference is ignored if NvMDynamicConfiguration == FALSE is set [SWS_NvM_00248].
• If NvMDynamicConfiguration == TRUE and NvMResistantToChangedSw == FALSE, an extended preparation is executed in case of a mismatch [SWS_NvM_00249].

The job then iterates over all user blocks, starting with the lowest block ID (excluding the reserved IDs 0 and 1) [SWS_NvM_00244]. Permanent RAM blocks or blocks with a configured synchronization callback NvM_ReadRamBlockFromNvm are taken into account, provided that NvmSelectBlockForReadall == TRUE is configured [SWS_NvM_00118]. Blocks that are selected but not read receive the result NVM_REQ_BLOCK_SKIPPED [SWS_NvM_00287].

For redundant blocks (NVM_BLOCK_REDUNDANT), the second NV block is automatically read if the first read attempt fails [SWS_NvM_00288]. After successful loading into RAM, the block status is set to "valid/unmodified" and the job result is set to NVM_REQ_OK [SWS_NvM_00251], [SWS_NvM_00290], [SWS_NvM_00291]. For blocks with NvMCalRamBlockCrC == TRUE, the job requests a CRC recalculation [SWS_NvM_00292]. If configured, NvMSingleBlockCallback is called for each block and MultiBlockCallback is called after the last block [SWS_NvM_00281].

Usage and Call Context

The function NvM_WriteAll asynchronously triggers a multi-block write job and has neither parameters nor return values [SWS_NvM_00461]. After the call, the function signals the request to the NvM module and returns immediately [SWS_NvM_00254]. The actual processing is deferred until all queues for single-block jobs are completely processed [SWS_NvM_00254]. The call typically occurs as part of the basic shutdown procedure by the BSW Mode Manager [SWS_NvM_00092].

Sequence and block processing

During shutdown, the job synchronizes permanent RAM blocks with the associated NV blocks or executes the explicit synchronization callback NvM_WriteRamBlockToNvm [SWS_NvM_00018]. Only blocks for which the configuration parameter NvMSelectBlockForWriteAll is set to true are considered [SWS_NvM_00252], as well as block 1 in case of differing configuration IDs when dynamic configuration is active [SWS_NvM_00310]. If a CRC is configured for an NVRAM block, the job requests a recalculation before the write operation and updates the checksum [SWS_NvM_00253]. For blocks with NvMWriteBlockOnce == TRUE, the job immediately sets the write protection flag in the administrative block after successful writing [SWS_NvM_00329].

Concurrency and Error Handling

• Reentrancy: The function is non-reentrant [SWS_NvM_00461].
• Error monitoring: To avoid infinite loops, a retry counter monitors the retries in case of unsuccessful responses from the MemIf module [SWS_NvM_00296].
• Job results: If the processing of at least one block fails, the overall result is set to NVM_REQ_NOT_OK [SWS_NvM_00318]. For configured blocks that were not written, the individual result NVM_REQ_BLOCK_SKIPPED is set [SWS_NvM_00298]. For redundant blocks (NVM_BLOCK_REDUNDANT), the individual job is considered NVM_REQ_OK as soon as at least one of the NV blocks has been written successfully [SWS_NvM_00337].
• Cancellation: A running job can be canceled by NvM_CancelWriteAll [SWS_NvM_00019]. This leads to the overall result NVM_REQ_CANCELED [SWS_NvM_00237], whereby the block currently being processed is completed in a non-destructive and data-consistent manner [SWS_NvM_00238].

Usage and Semantics

The function NvM_CancelWriteAll serves to prematurely abort an ongoing multi-block write operation (NvM_WriteAll) [SWS_NvM_00458], [SWS_NvM_00019]. The call is asynchronous, non-reentrant, takes no parameters, and returns no return value [SWS_NvM_00458]. The function signals the abort request directly to the module and returns immediately [SWS_NvM_00232]. The request is not enqueued in the job queue; only one request of this type can be pending at any time [SWS_NvM_00420]. If no operation is active at the time of calling, the call has no effect [SWS_NvM_00233].

Sequence and Data Consistency

The abort is performed in such a way that the data consistency of the NVRAM block being processed at the time of the abort is not affected [SWS_NvM_00019]. The module completes this active block regularly and sets its status attribute to NVM_REQ_OK or NVM_REQ_NOT_OK depending on success, while all remaining still pending blocks are set to NVM_REQ_CANCELED [SWS_NvM_00236]. The overall result is implicitly predetermined by the result of the aborted operation [SWS_NvM_00235], is stored in a separate variable [SWS_NvM_00393], and can be queried via NvM_GetErrorStatus by specifying the reserved block ID 0 [SWS_NvM_00394]. In addition, an upper-layer callback (NvMMultiBlockCallback) can optionally be notified [SWS_NvM_00260]. If configured via NvMDrvModeSwitch, the job switches the memory devices to slow mode after the abort [SWS_NvM_00681].

Restrictions and Error Handling

Calling NvM_CancelWriteAll is functionally restricted and may only be done by the BSW Mode Manager (BswM) [SWS_NvM_00703]. In addition, the function belongs to API configuration class 2 [SWS_NvM_00561]. The module must have been initialized prior to the call [SWS_NvM_00716]; if development error detection (DET) is activated, calling in an uninitialized state leads to error message NVM_E_UNINIT [SWS_NvM_00637].

The function NvM_ValidateAll initiates the asynchronous validation of multiple NVRAM blocks ([SWS_NvM_00855]) and belongs to API configuration class 3 ([SWS_NvM_00560]). It is non-reentrant, expects no parameters, and provides no return value ([SWS_NvM_00855]). Prior to the call, the NvM module must be initialized ([SWS_NvM_00859]).

Upon the call, the function signals the request to the module and returns immediately ([SWS_NvM_00858]). The actual execution is delayed, however, until all single-block job queues are completely processed ([SWS_NvM_00858]). For multi-block jobs, only a single slot in total is available in the job queue ([SWS_NvM_00380]). The overall result of the asynchronous job is maintained in a separate state variable ([SWS_NvM_00393]).

Within the scope of job processing, both the multi-block result and the results of the affected single blocks are pre-set to NVM_REQ_PENDING ([SWS_NvM_00861]). The processing considers exclusively blocks for which NvMBlockUseAutoValidation is configured to TRUE ([SWS_NvM_00856], [SWS_NvM_00860]):

• Permanent RAM blocks are processed or the explicit synchronization via the callback NvM_WriteRamBlockToNvm is executed ([SWS_NvM_00860]).
• The RAM block status is set to “VALID / CHANGED” ([SWS_NvM_00856]).
• If CRC calculation in RAM is additionally configured, the job requests recalculation in the background, which is processed via NvM_MainFunction ([SWS_NvM_00857]).
• After successful validation of the RAM block, the block-specific result changes to NVM_REQ_OK ([SWS_NvM_00862]).

The function NvM_FirstInitAll initiates the asynchronous initial initialization of multiple configured blocks ([SWS_NvM_91001]). The service is non-reentrant, expects no parameters, and provides no return value ([SWS_NvM_91001]). During processing, it is not considered whether a block already exists in non-volatile memory or is valid or corrupted ([SWS_NvM_91001]). The queue length for multi-block jobs (from NvM_FirstInitAll, among others) is one, so that only a single multi-block job can be queued at the same time ([SWS_NvM_00380]).

Processing differs according to the management type of the block:

• NATIVE: If default data is available, the NV block is written with it ([SWS_NvM_00913]). If the block has permanent RAM or explicit synchronization, the RAM is updated with the default data (ROM or init callback) as in NvM_RestoreBlockDefaults ([SWS_NvM_00915]); without permanent RAM and without explicit synchronization, the internal NvM buffer serves as RAM, leaving the RAM state untouched ([SWS_NvM_00914]). If default data is missing ([SWS_NvM_00919]) or a configured init callback fails with a return value other than E_OK ([SWS_NvM_00921]), the block is invalidated.
• REDUNDANT: If default data is present, both block instances are written with it ([SWS_NvM_00916]), and if permanent RAM or explicit synchronization is present, the RAM is updated ([SWS_NvM_00918]); otherwise, the internal buffer is used ([SWS_NvM_00917]). If an init callback does not return E_OK, both instances are invalidated ([SWS_NvM_00922]).
• DATASET: All blocks or NV block instances of this type configured for processing are invalidated without exception ([SWS_NvM_00923], [SWS_NvM_00924]).

If writing a NATIVE block with default data ([SWS_NvM_00925]), invalidating a NATIVE block ([SWS_NvM_00927]), or writing both instances of a REDUNDANT block ([SWS_NvM_00926]) fails, the job sets the overall result to NVM_REQ_NOT_OK.

use

The synchronous callback function NvM_JobEndNotification is called by the underlying memory abstraction to signal the error-free end of a job to the NVRAM Manager [SWS_NvM_00462]. The function has neither parameters nor a return value and is available via the header file NvM_MemIf.h with service ID 0x11 [SWS_NvM_00462]. A successful notification of the memory abstraction includes error-free completed read, write, or erase operations [SWS_NvM_00111].

Concurrency and Limitations

The interface is specified as non-reentrant [SWS_NvM_00462]. Depending on the calling function within the memory abstraction, this routine can be executed in interrupt context [SWS_NvM_00111]. All modules of the memory abstraction should be configured to consistently use the same mode – callback or polling [SWS_NvM_00111].

Configuration and Interaction

The NvM module provides the callback function NvM_JobEndNotification only if polling mode is disabled via the configuration parameter NvMPollingMode [SWS_NvM_00440]. In addition, the function is influenced by general NvM configuration parameters [SWS_NvM_00440].

The callback function NvM_JobErrorNotification ([SWS_NvM_00463]) serves the underlying memory abstraction layer to signal the faulty termination of an asynchronous job to the NVRAM Manager module (NvM). The call is synchronous and is specified as non-reentrant ([SWS_NvM_00463]).

Usage and signature

• Interface: The function declaration is made available via the header file NvM_MemIf.h ([SWS_NvM_00463]).
• Signature: According to void NvM_JobErrorNotification(void), the function has neither input, output, nor input/output parameters and returns no return value ([SWS_NvM_00463]).
• Service ID: The function is identified via the hexadecimal identifier 0x12 ([SWS_NvM_00463]).

Configuration dependency and interaction

The NvM module only provides the callback function NvM_JobErrorNotification if polling mode is disabled via configuration parameter NvMPollingMode ([SWS_NvM_00441]). If polling is used, this notification mechanism is omitted. In addition, the function is influenced by the general configuration parameters according to [SWS_NvM_00028] wording not yet imported ([SWS_NvM_00441]).

Error Handling and Concurrency

The function serves exclusively for error reporting of jobs and defines neither its own error codes nor DET or DEM feedbacks ([SWS_NvM_00463]). Due to the classification as Non Reentrant, it is presumably the responsibility of the caller in the memory abstraction to ensure that no overlapping or interrupting calls occur ([SWS_NvM_00463]). Question Q-5f72d9d605c25922 (open)

use

The function NvM_MainFunction has neither passing parameters nor a return value (void NvM_MainFunction(void)) and is declared via SchM_NvM.h ([SWS_NvM_00464]). It serves for processing NVRAM Manager jobs ([SWS_NvM_00464], [SWS_NvM_00256]). After the completion of an asynchronous service, it executes configured callback routines to notify the upper layer ([SWS_NvM_00347]). In addition, it performs CRC recalculations requested in the background for NVRAM blocks ([SWS_NvM_00333]), such as as a result of NvM_SetRamBlockStatus ([SWS_NvM_00121]) or NvM_ValidateAll ([SWS_NvM_00857]).

Flow Control and Prioritization

If configured, the function monitors the immediate priority queue for requests with immediate priority ([SWS_NvM_00259]). If a regular request was destructively aborted by an immediate job, NvM_MainFunction restarts it after its completion ([SWS_NvM_00258]). If polling mode is active, it checks the status of the jobs passed to the lower layer ([SWS_NvM_00346]). During the processing of NvM_WriteAll, it cyclically polls the state of the memory driver abstraction via MemIf_GetStatus for MEMIF_BROADCAST_ID and holds back callbacks to the upper layer as long as MEMIF_BUSY_INTERNAL is reported ([SWS_NvM_00350]).

Error Handling and Retries

If application-specific callbacks fail, NvM_MainFunction controls the retries:

• If NvMReadRamBlockFromNvCallback returns the value E_NOT_OK, the module repeats the call in the next cycle of NvM_MainFunction ([SWS_NvM_00839]).
• If NvMWriteRamBlockToNvCallback returns E_NOT_OK, the repetition also takes place in the next call of NvM_MainFunction ([SWS_NvM_00840]).
• If the explicit synchronization callback returns E_NOT_OK for NvM_SetRamBlockStatus, the module executes the configured retries with one attempt per call of NvM_MainFunction ([SWS_NvM_00908]).

use

The callback routine NvM_SingleBlockCallbackFunction synchronously notifies the upper layer of the completion of a previously initiated asynchronous single-block request [SWS_NvM_00467].

The function processes two passing parameters [SWS_NvM_00467]:

• BlockRequest (type NvM_BlockRequestType): Passes the type of the previously executed block request, such as read or write operations [SWS_NvM_00467].
• JobResult (type NvM_RequestResultType): Reports the overall result of the processed block job [SWS_NvM_00467].

As a return value, the function provides the type Std_ReturnType [SWS_NvM_00467]. Successful execution of the callback is signaled by returning E_OK; any other return value indicates unsuccessful execution [SWS_NvM_00467].

Error Handling and Concurrency

The interface does not specify any dedicated DET or DEM error messages [SWS_NvM_00467]. The result of the preceding job is transferred via the parameter JobResult, whereas errors within the callback processing itself are reported via the function return value [SWS_NvM_00467].

Regarding concurrency, the routine is declared as non-reentrant (Non Reentrant) [SWS_NvM_00467]. It is provided via the header NvM_Externals.h [SWS_NvM_00467]. The call by the NvM module is likely performed synchronously in the task context of the cyclic NvM job processing (interpretation). Question Q-f50640211851274f (open)

The callback routine NvM_MultiBlockCallbackFunction notifies the upper layer that a previously initiated asynchronous multi-block job has been completed [SWS_NvM_00468]. The declaration of the function is provided via the header file NvM_Externals.h [SWS_NvM_00468].

Call Context and Parameters

The call by the NVRAM manager is performed synchronously with the execution in the processing flow [SWS_NvM_00468]. Upon the call, two parameters are passed to the routine:

• MultiBlockRequest (type NvM_MultiBlockRequestType): Identifies the concrete request type of the previously processed multi-block job, such as read or write accesses [SWS_NvM_00468].
• JobResult (type NvM_RequestResultType): Transfers the final result of the processing of the preceding multi-block job to the upper layer [SWS_NvM_00468].

Return value and error handling

The routine returns a value of type Std_ReturnType to the calling module [SWS_NvM_00468]. The return value E_OK indicates that the callback function could be executed successfully; any other return value, however, signals failed processing [SWS_NvM_00468]. Specific error codes, DET or DEM messages are not defined in the scope of the specification for this function. Interpretation: The concrete consequences of a return value other than E_OK are likely implementation-specific, as the standard does not prescribe downstream error handling. Question Q-462dea7f3074ae9c (open)

Concurrency and Limitations

The function is specified as non-reentrant (Non Reentrant) [SWS_NvM_00468]. Within the calling system, it must therefore be ensured that no concurrent or interrupting multiple calls of this callback interface take place.

Usage and Call Context

The user-specific callback routine NvM_InitBlockCallbackFunction is called by the NvM module when default data for an NVRAM block must be restored in RAM and no corresponding ROM block is configured [SWS_NvM_00469]. The call is performed synchronously and the interface is declared via the header NvM_Externals.h [SWS_NvM_00469].

As a passing parameter, the function receives InitBlockRequest of type NvM_InitBlockRequestType [SWS_NvM_00469]. This value informs the routine about the specific request type of the currently processed block, such as reading or restoring data (read, restore) [SWS_NvM_00469].

Return Values and Error Handling

The routine returns a status value of type Std_ReturnType [SWS_NvM_00469]:

• E_OK: Signals to the NvM module that the callback function has successfully initialized and processed the data in RAM [SWS_NvM_00469].
• Any other return value: Indicates that the initialization could not be completed successfully [SWS_NvM_00469].

Specific error codes for DET or DEM are not specified for the interface itself [SWS_NvM_00469].

Concurrency and Execution Constraints

The interface is specified as synchronous and non-reentrant (Non Reentrant) [SWS_NvM_00469]. Because the NVRAM Manager waits synchronously for the return of the function, a blocking execution within the routine is likely to halt the further processing of the NvM immediately (interpretation). Question Q-c0e43c9871c4f2d0 (open)

The block-specific callback function NvM_WriteRamBlockToNvm serves for explicit synchronization to copy application data from the RAM block into the internal RAM mirror of the NvM module [SWS_NvM_00539]. It is declaratively available via NvM_Externals.h and is called synchronously by the NvM [SWS_NvM_00539].

Usage and Parameters

The function passes as an output parameter the pointer NvMBuffer, which represents the destination address of the NvM mirror to which the data must be written [SWS_NvM_00539]. As a return value, the callback routine provides E_OK upon successful processing or any other value in the event of an erroneous course [SWS_NvM_00539].

Concurrency and Limitations

According to the specification, NvM_WriteRamBlockToNvm is designed as non-reentrant (Non Reentrant) [SWS_NvM_00539].

Interplay in the module

• During shutdown, the job NvM_WriteAll synchronizes permanent RAM blocks or calls the callback routine NvM_WriteRamBlockToNvm for explicit synchronization [SWS_NvM_00018], provided that the parameter NvMSelectBlockForWriteAll is configured to true for the NVRAM block [SWS_NvM_00252].
• The write jobs NvM_WriteBlock [SWS_NvM_00303] and NvM_WritePRAMBlock [SWS_NvM_00803] automatically validate a still invalid permanent RAM block after the call of NvM_WriteRamBlockToNvm.

The function NvM_ReadRamBlockFromNvm is a block-specific callback routine declared via NvM_Externals.h [SWS_NvM_00540]. Its purpose is to enable the application to copy data from the internal mirror buffer of the NvM module into the associated RAM block in order to perform an explicit synchronization [SWS_NvM_00540], [SWS_NvM_00118].

Usage and Semantics

• Call context and concurrency: The call is performed synchronously and is specified as non-reentrant (Non Reentrant) [SWS_NvM_00540].
• Parameters: The pointer NvMBuffer (type const void*) serves as the passing parameter. It passes the buffer address from which the data can be read and copied into the RAM block [SWS_NvM_00540].
• Return value and error handling: The callback function returns a Std_ReturnType. The return value E_OK signals successful execution; any other return value indicates unsuccessful processing [SWS_NvM_00540].

Interaction

Within the scope of the multi-block service NvM_ReadAll, NvM_ReadRamBlockFromNvm is called for explicit synchronization for those NVRAM blocks that are configured accordingly and for which NvmSelectBlockForReadall == TRUE applies [SWS_NvM_00118], [SWS_NvM_00356]. This represents the alternative to direct copying into permanent RAM blocks, whereas NvM_ReadAll initializes the administrative data of the blocks [SWS_NvM_00356].

The enumeration type NvM_MultiBlockRequestType is provided via the header file NvM.h and serves to uniquely identify an executed multi-block request [SWS_NvM_91003]. The type is used when the result or status of a multi-block operation is signaled via a callback function or reported to the BswM module [SWS_NvM_91003].

Value Range and Semantics

The enumeration defines the following values for differentiating multi-block jobs [SWS_NvM_91003]:

• NVM_READ_ALL (0x00): Indicates that NvM_ReadAll was executed.
• NVM_WRITE_ALL (0x01): Indicates that NvM_WriteAll was executed.
• NVM_VALIDATE_ALL (0x02): Indicates that NvM_ValidateAll was executed.
• NVM_FIRST_INIT_ALL (0x03): Indicates that NvM_FirstInitAll was executed.
• NVM_CANCEL_WRITE_ALL (0x04): Indicates that NvM_CancelWriteAll was executed.

Interaction

By passing this type, invoked callbacks as well as the BswM can determine which concrete multi-block service triggered the notification. Interpretation: The feedback to the BswM presumably serves to couple follow-up actions or state transitions in the overall system to the completion of specific multi-block services. Question Q-69b4d985301acfeb (open)

The type NvM_RequestResultType is based on uint8, is available via Rte_NvM_Type.h, and represents the asynchronous request result of read, write, and control jobs of the NVRAM Manager [SWS_NvM_00470]. The result is queried primarily via the API service NvM_GetErrorStatus and can additionally be signaled via a configured callback function [SWS_NvM_00470].

The value range represents various execution states and error cases [SWS_NvM_00470]:

• NVM_REQ_OK (0x00): The last asynchronous job was completed successfully; this is also the default value after a reset.
• NVM_REQ_NOT_OK (0x01): The asynchronous read, write, or control request was not completed successfully.
• NVM_REQ_PENDING (0x02): An asynchronous request is currently still being processed.
• NVM_REQ_INTEGRITY_FAILED (0x03): Data integrity error in NvM_ReadBlock or NvM_ReadAll. In the case of NvM_ReadBlock, the content of the RAM block has been modified, but has become invalid; the application is responsible for renewing and validating the content.
• NVM_REQ_BLOCK_SKIPPED (0x04): The referenced block was skipped during NvM_ReadAll or NvM_WriteAll (e.g. dataset NVRAM blocks in NvM_ReadAll or blocks without a permanently configured RAM block).
• NVM_REQ_NV_INVALIDATED (0x05): The referenced NV block is invalidated.
• NVM_REQ_CANCELED (0x06): Cancellation of NvM_WriteAll by NvM_CancelWriteAll or cancellation of a single-block job (NvM_ReadBlock, NvM_WriteBlock, NvM_EraseNvBlock, NvM_InvalidateNvBlock, NvM_RestoreBlockDefaults) by NvM_CancelJobs.
• NVM_REQ_RESTORED_DEFAULTS (0x08): The default values were successfully copied to the RAM image.

In interaction with redundant blocks (NVM_BLOCK_REDUNDANT), the function NvM_InvalidateNvBlock sets the request result NvM_RequestResultType to NVM_REQ_OK only when both NV blocks have been invalidated [SWS_NvM_00274].

The data type NvM_InitBlockRequestType is based on uint8 and is provided via the header file Rte_NvM_Type.h [SWS_NvM_91123]. It serves to identify the type of request performed on an NVRAM block when this is signaled via a corresponding callback function [SWS_NvM_91123].

The permissible value range comprises four request types [SWS_NvM_91123]:

• NVM_INIT_READ_BLOCK (0x00): Indicates that NvM_ReadBlock or NvM_ReadPRAMBlock was requested for the block [SWS_NvM_91123].
• NVM_INIT_RESTORE_BLOCK_DEFAULTS (0x01): Signals that NvM_RestoreBlockDefaults or NvM_RestorePRAMBlockDefaults was requested for the block [SWS_NvM_91123].
• NVM_INIT_READ_ALL_BLOCK (0x02): Points out that the block is processed within the scope of NvM_ReadAll [SWS_NvM_91123].
• NVM_INIT_FIRST_INIT_ALL (0x03): Identifies block processing during the execution of NvM_FirstInitAll [SWS_NvM_91123].

Using this enumeration value, the invoked application logic can distinguish whether it is an explicit single-block request (reading or restoring default values) or a global collective operation during system startup [SWS_NvM_91123]. Interpretation: The type is likely passed as a parameter to block-related initialization callbacks so that the application can provide default data according to the situation or make specific preparations. Question Q-42d0d469e305728e (open)

The enumeration type NvM_BlockRequestType is based on uint8 and is provided via the header Rte_NvM_Type.h [SWS_NvM_91002]. When notification is provided via a callback function, it serves to convey the type of request that was previously executed on an NVRAM block [SWS_NvM_91002].

The value range comprises six specific block requests [SWS_NvM_91002]:

• NVM_READ_BLOCK (0x00): Signals that NvM_ReadBlock or NvM_ReadPRAMBlock was executed for the block [SWS_NvM_91002].
• NVM_WRITE_BLOCK (0x01): Signals that NvM_WriteBlock or NvM_WritePRAMBlock was executed for the block [SWS_NvM_91002].
• NVM_RESTORE_BLOCK_DEFAULTS (0x02): Signals that NvM_RestoreBlockDefaults or NvM_RestorePRAMBlockDefaults was executed [SWS_NvM_91002].
• NVM_ERASE_NV_BLOCK (0x03): Signals that NvM_EraseNvBlock was executed on the block [SWS_NvM_91002].
• NVM_INVALIDATE_NV_BLOCK (0x04): Signals that NvM_InvalidateNvBlock was executed on the block [SWS_NvM_91002].
• NVM_READ_ALL_BLOCK (0x05): Signals that NvM_ReadAll has finished processing this block [SWS_NvM_91002].

In the application architecture, the value is likely evaluated as a parameter in callback routines to inform higher-level software components differentially about the completion of specific block operations [SWS_NvM_91002]. Question Q-467801b6b5e898a2 (open) In the absence of further specifications in the payload regarding error codes or concurrency, the specification details are limited to the type definition and the value range [SWS_NvM_91002].