Flash EEPROM Emulation (Fee)

Fee maps the logical blocks of an emulated EEPROM onto flash memory and serves the jobs issued by the NVRAM Manager via MemIf. Read, write, and erase jobs are merely accepted and then processed asynchronously in Fee_MainFunction [SWS_Fee_00097]. Progress and result are indicated by Fee_GetStatus and Fee_GetJobResult. After Fee_Init, the module may initially be busy with internal management (MEMIF_BUSY_INTERNAL), but already accepts jobs SWS Fee p. 42. Write jobs always affect the entire block.

more ›

Fee maps the logical blocks of an emulated EEPROM onto flash memory. The BlockNumber simultaneously designates the start address of the block [SWS_Fee_00087]. Calls originate from the NVRAM Manager via the Memory Abstraction Interface, which selects the appropriate service via DeviceIndex SWS MemIf p. 18. Underneath operates the flash driver Fls. Fee provides feedback directly to the NVRAM Manager via NvM_JobEndNotification and NvM_JobErrorNotification [SWS_Fee_00098], [SWS_Fee_00099].

Context diagram: Fee between MemIf and Fls, initialized by EcuM, cyclically triggered by SchM, with feedback directly to NvM. Sources: [SWS_Fee_00085], [SWS_Fee_00097], [SWS_Fee_00105].

EcuM calls Fee_Init with the selected configuration set; R20-11 lists this service as asynchronous [SWS_Fee_00085]. Thereafter, the status is set to MEMIF_BUSY_INTERNAL, but jobs are already accepted. Only repeated calls to Fee_MainFunction conclude internal management and lead to MEMIF_IDLE SWS Fee p. 42. Fee_GetStatus indicates the module state, Fee_GetJobResult the result of the last accepted job [SWS_Fee_00090], [SWS_Fee_00091].

State diagram: Module status from MEMIF_UNINIT via MEMIF_BUSY_INTERNAL to MEMIF_IDLE and MEMIF_BUSY; the return after regular job completion is an assumption. Sources: [SWS_Fee_00090], SWS Fee p. 28.

Read, write, invalidation, and erase jobs only report their acceptance with E_OK; they are processed asynchronously in Fee_MainFunction [SWS_Fee_00097]. Fee_Read reads arbitrary sections of a block, Fee_Write always the entire block with offset zero SWS Fee p. 28. During writing, the block is internally considered "corrupted". This marking is to be distinguished from invalidation by Fee_InvalidateBlock SWS Fee p. 21.

Fee_Cancel is synchronous in R20-11 and cancels a pending job via the flash driver [SWS_Fee_00089]. Without a pending job, it reports FEE_E_INVALID_CANCEL [SWS_Fee_91002]. Flash errors are detected by the driver. Fee reports them in two ways depending on the configuration: as MEMIF_JOB_FAILED for querying or via NvM_JobErrorNotification. Recovery is handled by the NVRAM Manager ErrorDescription p. 40. Fee reports incorrect operations such as missing initialization or invalid block numbers as development errors [SWS_Fee_00010].

more ›

Role in the NV memory stack: Flash memory as emulated EEPROM

Flash EEPROM Emulation (Fee) provides logical blocks to the upper layer and maps them onto flash memory. The BlockNumber simultaneously designates the start address of the block in memory [SWS_Fee_00087], [SWS_Fee_00088]. The NVRAM Manager does not call Fee directly, but via the Memory Abstraction Interface. MemIf_Read and MemIf_Write call the function of the abstraction module selected via DeviceIndex and forward its return value SWS MemIf p. 18, SWS MemIf p. 19. Downwards, Fee relies on the flash driver Fls. From there, it imports Fls_AddressType and Fls_LengthType, and from MemIf the status, result, and mode types [SWS_Fee_00084].

Feedback bypasses MemIf. MemIf itself provides no callbacks; the callback routines for the underlying abstraction modules are provided by the NVRAM Manager SWS MemIf p. 24. For this purpose, Fee calls NvM_JobEndNotification and NvM_JobErrorNotification [SWS_Fee_00098], [SWS_Fee_00099]. Conversely, the driver reports the end of its jobs to Fee via Fee_JobEndNotification and Fee_JobErrorNotification [SWS_Fee_00095], [SWS_Fee_00096]. Fee is initialized by EcuM and cyclically triggered by the Basic Software Scheduler SWS Fee p. 42.

Context diagram: Fee is situated between MemIf and Fls. It is initialized by EcuM, cyclically triggered by SchM, and reports job completions directly to NvM. Sources: [SWS_Fee_00085], [SWS_Fee_00097], [SWS_Fee_00098], [SWS_Fee_00104], [SWS_Fee_00105], SWS MemIf p. 18.

As required driver services, R20-11 lists, among others, the following functions [SWS_Fee_00105]:

• Fls_Read, Fls_Write, Fls_Erase, and Fls_Compare,
• Fls_Cancel, Fls_GetStatus, Fls_GetJobResult, and Fls_SetMode,
• Det_ReportRuntimeError.

Optionally, Det_ReportError and Fls_BlankCheck are added [SWS_Fee_00104]. A later version of the same requirement lists MemAcc_BlankCheck instead SWS Fee p. 40. For R20-11, the Fls variant remains normative.

Startup: From Fee_Init to readiness for acceptance

EcuM calls Fee_Init with a pointer to the selected configuration set [SWS_Fee_00085]. The type Fee_ConfigType is a structure with implementation-specific elements [SWS_Fee_00188]. Remarkably, R20-11 lists Fee_Init as asynchronous [SWS_Fee_00085]. According to the change history, the initialization does not have to be completed within Fee_Init, and the state machine was adapted accordingly SWS Fee p. 4.

The sequence diagram of the specification shows the sequence SWS Fee p. 42:

1. After Fee_Init, the module status is set to MEMIF_BUSY_INTERNAL.
2. Jobs can already be accepted in this state.
3. The scheduler calls Fee_MainFunction until the internal management is completed.

A later version specifies that Fee_MainFunction then sets the status from MEMIF_BUSY_INTERNAL to MEMIF_IDLE. Management can take more than one call in this process SWS Fee p. 38. The older version of the diagram only shows the synchronous call by EcuM SWS Fee p. 38.

Sequence diagram: Fee_Init transitions the module into MEMIF_BUSY_INTERNAL. Only repeated calls to Fee_MainFunction conclude internal management and lead to MEMIF_IDLE. Sources: [SWS_Fee_00085], [SWS_Fee_00097], SWS Fee p. 42.

Fee_MainFunction processes the requested read, write, and erase jobs as well as the internal management operations [SWS_Fee_00097]. As a scheduled function, it is called directly by the Basic Software Scheduler. It has neither parameters nor a return value and is non-reentrant SWS Fee p. 40.

Module status and job result as control variables

The upper layer controls its calls via two synchronous queries. Fee_GetStatus returns one of four values [SWS_Fee_00090]:

• MEMIF_UNINIT: The module is not initialized.
• MEMIF_IDLE: The module is idle.
• MEMIF_BUSY: A job of the upper layer is in progress.
• MEMIF_BUSY_INTERNAL: An internal management operation is running.

As an example of an internal management operation, the specification mentions the reorganization of the used flash memory (garbage collection) SWS Fee p. 30. New jobs are accepted in both MEMIF_IDLE and MEMIF_BUSY_INTERNAL and lead to MEMIF_BUSY SWS Fee p. 28. After regular job completion, the status is likely to fall back to MEMIF_IDLE. Question Q-beae785a1ba1cbec (open) The return to MEMIF_IDLE is explicitly documented here only for cancellation SWS Fee p. 29.

State diagram: Life cycle of the module status from MEMIF_UNINIT via MEMIF_BUSY_INTERNAL to MEMIF_IDLE and MEMIF_BUSY. The transition upon regular job completion is marked as an assumption. Sources: [SWS_Fee_00090], SWS Fee p. 42, SWS Fee p. 28, SWS Fee p. 29.

Fee_GetJobResult refers to the most recently accepted job [SWS_Fee_00091], SWS Fee p. 31. It distinguishes six results:

• MEMIF_JOB_OK: The job finished successfully.
• MEMIF_JOB_PENDING: The job is still pending or running.
• MEMIF_JOB_CANCELED: The job was canceled.
• MEMIF_JOB_FAILED: The job has failed.
• MEMIF_BLOCK_INCONSISTENT: The block potentially contains corrupted data.
• MEMIF_BLOCK_INVALID: The block has been invalidated; reading is not possible.

The status therefore describes the module, whereas the result describes the individual job; both are to be queried separately [SWS_Fee_00090].

Read, Write, and Block Management Jobs

The job services operate asynchronously: E_OK only indicates that the job was accepted [SWS_Fee_00087], [SWS_Fee_00088]. Fee_Read calculates the read address from the block start address and BlockOffset. Offset and length may take any value within their type range. This allows reading any number of bytes starting from any location within a block SWS Fee p. 26. If Fls_BlankCheck is configured in the flash driver, Fee_Read uses it to check in advance whether the area is readable. This avoids, for instance, erased but unprogrammed cells triggering ECC errors [SWS_Fee_00187].

In contrast, Fee_Write always writes the entire block; the offset is fixed to zero SWS Fee p. 28. This follows from the higher-level requirement that erase and write jobs always start at the virtual 64K boundary: A block is written completely or not at all RS MemHwAb p. 24. Upon acceptance, Fee sets the status to MEMIF_BUSY and the result to MEMIF_JOB_PENDING and returns E_OK. The same acceptance condition applies to Fee_Read SWS Fee p. 26.

To keep interrupted write operations detectable, Fee maintains internal correctness information for each block SWS Fee p. 21. At the start of a write operation, the block is marked as \"corrupted\", and after successful completion it is marked as \"not corrupted\" again. This information must be strictly separated from the validity that the upper layer sets with Fee_InvalidateBlock.

Sequence diagram: A write job is accepted synchronously, but completed asynchronously via Fee_MainFunction and the driver feedback. In the process, the block is first marked as \"corrupted\" and finally as \"not corrupted\" again. Sources: [SWS_Fee_00088], [SWS_Fee_00095], [SWS_Fee_00098], SWS Fee p. 28, SWS Fee p. 21, SWS Fee p. 37.

Fee_InvalidateBlock declares a logical block invalid [SWS_Fee_00092]. To do so, it calls the erase function of the driver and/or modifies internal management information, which itself must be stored non-volatilely SWS Fee p. 32. If the upper layer reads such a block later, Fee_MainFunction sets the result to MEMIF_BLOCK_INVALID. If configured, it also calls the error notification of the upper layer SWS Fee p. 38.

Fee_EraseImmediateBlock [SWS_Fee_00094] is intended for diagnostic or similar system services. They use it to erase the area for immediate data in advance if needed. Whether a physical erase is performed is determined by the implementation SWS Fee p. 35. For Fee_InvalidateBlock and Fee_EraseImmediateBlock, R20-11 explicitly specifies the return value E_NOT_OK only when DET is enabled [SWS_Fee_00092], [SWS_Fee_00094].

Notifications, Cancellation, and Mode Switch

The flash driver reports the successful completion of a driver job via Fee_JobEndNotification [SWS_Fee_00095]. Fee then performs the necessary block management and, if configured, calls the job end notification of the upper layer. A result still set to MEMIF_JOB_PENDING is set to MEMIF_JOB_OK SWS Fee p. 37. Depending on the architecture of the memory stack, callbacks can execute at interrupt level and propagate upward across multiple layers. Their execution time must therefore remain short; whether calls at interrupt level are permissible is determined by the system design SWS Fee p. 36.

Fee_Cancel calls the cancel function of the flash driver [SWS_Fee_00089]. The upper layer reaches the service via MemIf_Cancel SWS MemIf p. 20. Cancellation takes effect only in the MEMIF_BUSY status: Fee calls the driver cancellation, resets its internal variables, and returns to MEMIF_IDLE. If DET is enabled, Fee checks beforehand whether the module is initialized SWS Fee p. 29.

Releases diverge regarding Fee_Cancel. The cited later version classifies the service as asynchronous, whereas R20-11 classifies it as synchronous [SWS_Fee_00089]. For R20-11, the synchronous classification is authoritative.

Activity diagram: Fee_Cancel branches according to DET check and module status. Only a pending job is cancelled; otherwise FEE_E_INVALID_CANCEL is reported. Sources: [SWS_Fee_00089], [SWS_Fee_91002], [SWS_Fee_00010], SWS Fee p. 29.

Fee_SetMode switches the operating mode of the underlying flash driver [SWS_Fee_00086]. The corresponding diagram shows the call chain NvM → MemIf_SetMode → Fee_SetMode → Fls_SetMode SWS Fee p. 39. Fee_GetVersionInfo is the only reentrant Fee service [SWS_Fee_00093]. If DET is enabled, it checks the passed pointer for NULL SWS Fee p. 34.

Configuration and Integration

Fee receives the configuration via the Fee_ConfigType passed to Fee_Init [SWS_Fee_00085], [SWS_Fee_00188]. The include structure of an earlier specification version shows the following partitioning SWS Fee p. 11:

• Fee_Cfg.h includes MemIf_Types.h and Fls.h, optionally also NvM_Cbk.h.
• Fee_Lcfg.c and Fee_PBcfg.c contain the configuration data.
• The scheduler is connected via SchM_Fee.h, DET optionally via Det.h.

For R20-11, this diagram serves for orientation only. If Fee is implemented as a vendor-specific library, the sequence diagrams are binding only for the relationships to EcuM and MemIf, not for the calls to the driver SWS Fee p. 42.

Behavior in the event of an error

Fee defines five codes as development errors [SWS_Fee_00010]:

• FEE_E_UNINIT (0x01): Service called prior to initialization.
• FEE_E_INVALID_BLOCK_NO (0x02): Invalid block number.
• FEE_E_INVALID_BLOCK_OFS (0x03): Invalid block offset.
• FEE_E_PARAM_POINTER (0x04): Invalid data pointer.
• FEE_E_INVALID_BLOCK_LEN (0x05): Invalid length specification.

R20-11 adds two further codes [SWS_Fee_91002]. FEE_E_BUSY (0x06) applies to calls while a user job is being processed. FEE_E_INVALID_CANCEL (0x08) applies to Fee_Cancel without a pending job. Accordingly, a new job issued in the MEMIF_BUSY status is likely to be rejected and answered with E_NOT_OK. Question Q-92062834653929da (open) The associated rule is only incompletely available here SWS Fee p. 28.

Errors of the flash memory are detected by the flash driver; how Fee reacts to them is implementation-specific ErrorDescription p. 40. Depending on the configuration, reporting occurs via one of two paths. Either MemIf queries Fee_GetJobResult and receives MEMIF_JOB_FAILED, or Fee actively calls NvM_JobErrorNotification. Recovery is handled by the NVRAM Manager. The upper layer detects an uninitialized module by MEMIF_UNINIT in Fee_GetStatus ErrorDescription p. 53, [SWS_Fee_00090].

Sequence diagram: A driver error reaches the upper layer either via callback to NvM or via polling of Fee_GetJobResult. Sources: [SWS_Fee_00096], [SWS_Fee_00099], [SWS_Fee_00091], ErrorDescription p. 40.

Regarding data consistency, a diagram from R22-11 describes the information chain ErrorDescription p. 64:

1. Fee checks the consistency of the read data and forwards an error to the NVRAM Manager.
2. The NVRAM Manager reports NVM_E_INTEGRITY_FAILED to DEM.
3. It initiates the configured recoveries: read retry, redundant block, or ROM block.
4. If these fail, it sets the result NVM_REQ_INTEGRITY_FAILED.

On the Fee side, this presumably corresponds to the result MEMIF_BLOCK_INCONSISTENT [SWS_Fee_00091]. Question Q-a1846c349d831e17 (open)

Collaboration diagram: A consistency error is forwarded from Fee to NvM. NvM reports it to DEM, attempts recovery, and sets the NvM result if it fails (as of R22-11). Sources: ErrorDescription p. 64.

Further detailed evidence

Detailed rules covering acceptance conditions, callback behavior, and the main function originate partly from later versions of the specification, e.g., SWS Fee p. 38. Where they differ from R20-11, this is noted above. The key references:

• [SWS_Fee_00085], [SWS_Fee_00188]: Initialization and configuration type, sequence in SWS Fee p. 42.
• [SWS_Fee_00090], [SWS_Fee_00091]: Module status and job result as the basis of the control flow.
• [SWS_Fee_00087], [SWS_Fee_00088], [SWS_Fee_00187]: Read and write jobs, address calculation, and blank check.
• [SWS_Fee_00092], [SWS_Fee_00094]: Invalidation and pre-erasing of blocks.
• [SWS_Fee_00095], [SWS_Fee_00096], [SWS_Fee_00098], [SWS_Fee_00099]: Feedback from the driver and to the NVRAM Manager.
• [SWS_Fee_00089], [SWS_Fee_00086], [SWS_Fee_00097]: Cancellation, mode switch, and main function.
• [SWS_Fee_00010], [SWS_Fee_91002]: Error codes; error paths in ErrorDescription p. 40.
• [SWS_Fee_00084], [SWS_Fee_00104], [SWS_Fee_00105]: Imported types as well as required and optional interfaces.