Memory Abstraction Interface (MemIf)

MemIf forwards the memory jobs of the NVRAM Manager to Fee or Ea modules and hides their number behind a uniform API SWS MemIf p. 7. The parameter DeviceIndex selects the module; if only one is configured, it is ignored and MemIf is implemented as a macro set SWS MemIf p. 17. The services accept jobs synchronously and pass the return value along, while the memory operation executes asynchronously underneath. Status and result are provided by MemIf_GetStatus and MemIf_GetJobResult. If development error detection is active, faulty calls return E_NOT_OK and MEMIF_JOB_FAILED, respectively.

more ›

The Memory Abstraction Interface replaces the former driver interface layers for Flash and EEPROM. It allows the NVRAM Manager to address multiple abstraction modules via a uniform API: the Flash EEPROM Emulation (Fee) and the EEPROM Abstraction (Ea) SRS MemHwAb p. 5. MemIf hides the number of these modules and provides virtual segmentation on a linear address space SWS MemIf p. 7.

Context diagram: MemIf mediates between NvM and Fee/Ea; completion notifications go directly from Fee/Ea to the NvM. Sources: SWS Fee p. 6, [SWS_MemIf_00047]

MemIf has no memory logic of its own. The parameter DeviceIndex selects the module; if only one is configured, it is ignored and MemIf is implemented as a macro set. If there are multiple modules, dispatching is performed, for example, via function pointer tables SWS MemIf p. 17. In R20-11, DeviceIndex is of type uint8 [SWS_MemIf_00039]; later versions use uint16.

The services accept jobs synchronously and pass the module's return value along [SWS_MemIf_00040]. The memory operation then runs asynchronously in the lower layer's main function. The NvM is notified of completion via callback from Fee/Ea or by polling MemIf_GetJobResult SWS Fee p. 48. MemIf_GetStatus reports UNINIT, IDLE, BUSY, or BUSY_INTERNAL [SWS_MemIf_00064]. The job result always refers to the last job and distinguishes, among others, canceled, inconsistent, and invalid blocks [SWS_MemIf_00065]. MemIf_SetMode affects all modules simultaneously [SWS_MemIf_00038].

Sequence diagram: synchronous acceptance via MemIf, asynchronous execution in the driver, completion via callback or polling. Sources: SWS Ea p. 41, [SWS_MemIf_00040]

In case of error, MemIf reports invalid device indices and NULL pointers as development errors [SWS_MemIf_00006]. The services then return E_NOT_OK, and MemIf_GetJobResult returns MEMIF_JOB_FAILED SWS MemIf p. 21. Runtime errors of the memory are detected by Fee or Ea; the NvM reads them in polling mode as MEMIF_JOB_FAILED and is responsible for rectification ErrorDescription p. 58.

more ›

Role in the Memory Stack: Switch between NvM and Fee/Ea

The Memory Abstraction Interface (MemIf) replaces the former driver interface layers for Flash and EEPROM. It allows the NVRAM Manager (NvM) to address multiple memory abstraction modules via a single API: the Flash EEPROM Emulation (Fee) and the EEPROM Abstraction (Ea) SRS MemHwAb p. 5. Towards upper layers, MemIf hides how many Fee and Ea modules lie underneath. It provides virtual segmentation on a uniform linear address space SWS MemIf p. 7. Fee and Ea provide block-based addressing and a "virtually unlimited" number of erase-write cycles. Therefore, the NvM does not need to be modified when the driver or device changes SRS MemHwAb p. 5.

MemIf itself contains no memory logic. Its API must be mapped to the API of the abstraction modules, and the functional behavior is defined by their specifications or those of the memory drivers SWS MemIf p. 17. Accordingly, MemIf requires the services of the abstraction modules, for Ea such as Ea_Read, Ea_Cancel, Ea_GetStatus, and Ea_GetJobResult [SWS_MemIf_00047]. Optionally, it uses Det_ReportError [SWS_MemIf_00048]. The types MemIf_StatusType, MemIf_JobResultType, and MemIf_ModeType defined in MemIf.h form the shared vocabulary of the stack [SWS_MemIf_00064] [SWS_MemIf_00065] [SWS_MemIf_00066]. For instance, Fls_GetJobResult directly returns MemIf_JobResultType SWS Fls p. 36.

The figures of more recent releases additionally show the modules MemAcc and Mem below Ea and Fee SWS Ea p. 42. For R20-11, the older overview is presumably authoritative, in which Fee builds on the Flash driver and Ea on the EEPROM driver SWS Fee p. 6. For MemIf, the difference is irrelevant because it only forwards up to the abstraction level SWS MemIf p. 17. Question Q-3c74a6029dd0d159 (open)

Context diagram: MemIf lies between NvM and the abstraction modules Fee/Ea; completion notifications reach the NvM directly from Fee/Ea. Sources: SWS Fee p. 6, SRS MemHwAb p. 5, [SWS_MemIf_00047], [SWS_MemIf_00048]

Device Selection via DeviceIndex: Macros or Dispatch Table

The parameter DeviceIndex selects the abstraction module and thus the memory device. If only one module is configured, it is ignored SWS MemIf p. 17. In this case, MemIf must be implemented as a set of macros, for example #define MemIf_Write(DeviceIndex, BlockNumber, DataPtr) Fee_Write(BlockNumber, DataPtr). If there are multiple modules, the calls must be dispatched via efficient mechanisms; the specification cites tables of function pointers indexed via DeviceIndex as one solution SWS MemIf p. 17. If a vendor-specific library replaces all required Fee and Ea modules, MemIf consists solely of macros SRS MemHwAb p. 5.

In R20-11, DeviceIndex is of type uint8 [SWS_MemIf_00039] [SWS_MemIf_00041]. Later versions of the specification list it as uint16 SWS MemIf p. 18. Normative for this release is uint8.

Activity diagram: The number of configured abstraction modules decides between macro mapping and dispatching via DeviceIndex. Sources: SWS MemIf p. 17, SRS MemHwAb p. 5

Job Sequence: Synchronous Acceptance, Asynchronous Execution

All MemIf services are specified as synchronous. Each calls the identically named function of the selected module and returns its return value, such as Read, Write, and InvalidateBlock [SWS_MemIf_00039] [SWS_MemIf_00040] [SWS_MemIf_00044]. The actual memory operation then runs asynchronously in the cyclically invoked main function of the lower layer. For this, the Ea sequence shows a loop via Eep_MainFunction in the BSW task SWS Ea p. 41. According to the Fee specification, this pattern also applies to the other asynchronous services SWS Fee p. 48.

Depending on the stack configuration, the NvM learns of the job completion in one of two ways. Either the abstraction module calls a callback such as NvM_JobEndNotification or NvM_JobErrorNotification, or the NvM polls MemIf_GetJobResult SWS Fee p. 48 EXP ErrorDescription p. 45. MemIf itself provides no callback function; its API consists of the following services [SWS_MemIf_00038] [SWS_MemIf_00046].

Service	Service ID	return	Effect
MemIf_SetMode	0x01	–	calls SetMode of all abstraction modules [SWS_MemIf_00038]
MemIf_Read	0x02	Std_ReturnType	reads Length bytes of the block starting at BlockOffset into DataBufferPtr [SWS_MemIf_00039]
MemIf_Write	0x03	Std_ReturnType	writes a block [SWS_MemIf_00040]
MemIf_Cancel	0x04	–	cancels the running job [SWS_MemIf_00041]
MemIf_GetStatus	0x05	MemIf_StatusType	module status [SWS_MemIf_00042]
MemIf_GetJobResult	0x06	MemIf_JobResultType	result of the last job [SWS_MemIf_00043]
MemIf_InvalidateBlock	0x07	Std_ReturnType	invalidates a block [SWS_MemIf_00044]
MemIf_GetVersionInfo	0x08	–	version information, reentrant [SWS_MemIf_00045]
MemIf_EraseImmediateBlock	0x09	Std_ReturnType	erases a block [SWS_MemIf_00046]

Sequence diagram: A write job is accepted synchronously via MemIf, executed asynchronously in the driver, and completed via callback or polling. Sources: SWS Ea p. 41, SWS Fee p. 48, ErrorDescription p. 60, [SWS_MemIf_00040]

Status, Job Result, and Operating Mode

MemIf_GetStatus returns the status of the selected module [SWS_MemIf_00042]. Possible are MEMIF_UNINIT, MEMIF_IDLE, MEMIF_BUSY, and MEMIF_BUSY_INTERNAL. In case of MEMIF_BUSY_INTERNAL, the abstraction module is busy with internal management, while the driver can be busy or idle [SWS_MemIf_00064]. The Fee specification substantiates the conditions and cites the reorganization of the flash (garbage collection) as an example of internal management SWS Fee p. 30. For the flash driver, the status may already be queried prior to initialization and is then MEMIF_UNINIT SWS Fls p. 35.

State diagram: Lifecycle of the module status visible via MemIf_GetStatus. Sources: [SWS_MemIf_00064], SWS Fee p. 30

MemIf_GetJobResult returns the result of the last job [SWS_MemIf_00043] [SWS_MemIf_00065]. Read, write, and erase share a single job result, so that only that of the last job can be queried. Upon acceptance of a new job, it is set to MEMIF_JOB_PENDING SWS Fls p. 36; Fee refers to the last accepted job SWS Fee p. 31. In addition to OK, FAILED, and CANCELED, there are two block-related results. MEMIF_BLOCK_INCONSISTENT means that the block is corrupt or not found; MEMIF_BLOCK_INVALID means that it is marked as invalid [SWS_MemIf_00065].

State diagram: An accepted job is in state PENDING and terminates in exactly one of the final results. Sources: [SWS_MemIf_00065], SWS Fls p. 36, SWS Fee p. 31

MemIf_SetMode is the only service that does not have a DeviceIndex and calls SetMode of all abstraction modules [SWS_MemIf_00038]. The modes are MEMIF_MODE_SLOW and MEMIF_MODE_FAST [SWS_MemIf_00066]. For the drivers, this represents slow read access or normal SPI access on the one hand, and fast read access or SPI burst on the other hand. Eep_SetMode must not be called during an ongoing operation SWS Eep p. 34. If checking is active, Fls_SetMode rejects a request in the busy state SWS Fls p. 42. Interpretation: Since MemIf_SetMode reaches all modules, it should only be called if all devices report MEMIF_IDLE. Question Q-d6ee630fca619042 (open)

Canceling Running Jobs

MemIf_Cancel calls the cancel function of the selected module [SWS_MemIf_00041]. The cancellation itself is synchronous, but asynchronous with respect to the hardware: The hardware may still continue running when the call has already returned SWS Fee p. 45 SWS Ea p. 44. The job result is then MEMIF_JOB_CANCELED [SWS_MemIf_00065], which Fee explicitly evaluates as a failure SWS Fee p. 31.

For the Flash path, the driver specification shows the chain MemIf_Cancel → Fee_Cancel → Fls_Cancel with subsequent error notifications. It also requires that Fls_Cancel not be called during a running Fls_MainFunction. There are two ways to achieve this: The job functions of NvM and Flash driver are synchronized, or the task of Fls_MainFunction is not interrupted SWS Fls p. 58.

Sequence diagram: The cancellation runs synchronously through all layers, the error notification follows, after which GetJobResult reports CANCELED. Sources: SWS Fls p. 58, SWS Fee p. 45, [SWS_MemIf_00041]

Call Rules, Reentrancy, and Embedding into the BSW

With the exception of MemIf_GetVersionInfo, all services are non-reentrant [SWS_MemIf_00045] [SWS_MemIf_00040]. Parallel calls from multiple contexts must therefore be excluded. Since status and job result per module only reflect the last job, the caller should only issue a new job after completion of the previous one SWS Fls p. 36.

The memory mapping example of an ICC2 cluster "MEM" lists MemIf together with the NvM. There, MemIf_SetMode is modeled as BswCalledEntity, and MemIf has the section prefix MEMIF SWS MemoryMapping p. 50. The BSW Distribution Guide names MEMIF alongside FLS and FEE as an example of "Type I"; the validity range can be restricted to one core via SwAddrMethod with local scope EXP BSWDistributionGuide p. 31. Presumably, MemIf is thus to be operated core-locally in multi-core systems. Question Q-d998fdc58e0bcddd (open)

Behavior in the event of an error

MemIf distinguishes two development errors. MEMIF_E_PARAM_DEVICE (0x01) stands for an incorrect DeviceIndex, MEMIF_E_PARAM_POINTER (0x02) for a NULL pointer [SWS_MemIf_00006]. They are reported via the optional Det_ReportError [SWS_MemIf_00048]. According to the tracing table, specific error codes are not returned via the API SWS MemIf p. 12.

If development error detection is active and an error is detected, Read, Write, InvalidateBlock, and EraseImmediateBlock return E_NOT_OK [SWS_MemIf_00039] [SWS_MemIf_00040] [SWS_MemIf_00044] [SWS_MemIf_00046]. In this case, MemIf_GetJobResult returns MEMIF_JOB_FAILED SWS MemIf p. 21. Otherwise, the value of the module is passed through unchanged.

Activity diagram: Parameter check when development error detection is active and passing through of the module result. Sources: [SWS_MemIf_00006], [SWS_MemIf_00048], SWS MemIf p. 18, SWS MemIf p. 21

Memory runtime errors are not detected by MemIf, but by Fee or Ea; MemIf itself does not react to them ("N/A"). In polling mode, the NvM reads the error via MemIf_GetJobResult as MEMIF_JOB_FAILED, and rectification lies with the NvM ErrorDescription p. 58 ErrorDescription p. 60. A more recent version describes this rectification in more detail. According to it, the NvM increments a retry counter for write jobs, aborts after exceeding it, and reports NVM_E_REQ_FAILED to the DEM EXP ErrorDescription p. 45. For R20-11, this detail is not normatively substantiated here.

Further detailed evidence

• API definitions with service IDs, reentrancy, and return values: [SWS_MemIf_00038] to [SWS_MemIf_00046].
• Data types for status, job result, and mode: [SWS_MemIf_00064], [SWS_MemIf_00065], [SWS_MemIf_00066]; imported types: [SWS_MemIf_00037].
• Mapping rules (macros, DeviceIndex, dispatching): SWS MemIf p. 17.
• Required and optional interfaces: [SWS_MemIf_00047], [SWS_MemIf_00048]; error codes: [SWS_MemIf_00006].
• Sequences for writing and canceling: SWS Fee p. 48, SWS Fls p. 58.
• Error chain up to the NvM in R20-11: ErrorDescription p. 58.