API Reference

Normative

The memory driver API contract. A conformant driver MUST provide these types and functions with the behavior described. Signatures and member documentation are extracted from the driver headers with Doxygen/Breathe. Keywords per Requirement Keywords; behavioral rules in Mem — Requirements; error codes in Errors.

Data types at a glance

Type

Kind

Purpose

Mem_ConfigType

struct

Root configuration (build-time; Mem_Init takes NULL_PTR).

Mem_InstanceIdType

typedef

Identifies a memory instance.

Mem_AddressType / Mem_LengthType

typedef

32-bit device address / length.

Mem_DataType

typedef

Read/write buffer element.

Mem_JobResultType

enum

Asynchronous job status / result.

Mem_HwServiceIdType

typedef

Selector for a hardware-specific service.

Mem_BinaryHeaderType

struct

Binary-image header + service function-pointer table.

E_MEM_SERVICE_NOT_AVAIL extends Std_ReturnType for optional services that a device does not implement.

API at a glance

Function

Group

Purpose

Mem_Init

Initialization and shutdown

Initialize the driver.

Mem_DeInit

Initialization and shutdown

Cancel any job and de-initialize.

Mem_Read

Memory jobs

Start an asynchronous read.

Mem_Write

Memory jobs

Start an asynchronous write.

Mem_Erase

Memory jobs

Start an asynchronous erase.

Mem_VerifyBlank

Memory jobs

Start an asynchronous blank check.

Mem_GetJobResult

Job control and status

Read the most recent job result.

Mem_SuspendJob

Job control and status

Suspend the active job.

Mem_ResumeJob

Job control and status

Resume a suspended job.

Mem_OnError

Job control and status

ECC-handler entry point (cancels the job).

Mem_HwSpecificService

Hardware service and scheduling

Dispatch a hardware-specific service.

Mem_PollFunction

Hardware service and scheduling

Advance asynchronous jobs.

The only integrator-provided interface is LogM_Report (and, where used, the critical-section services), documented in the general reference.

Data types
Mem_ConfigType
struct Mem_ConfigType

Runtime-Selectable configuration structure type.

Configuration variants are selected at build time; Mem_Init currently takes NULL_PTR. Available via: Mem.h

Mem_InstanceIdType
typedef uint8 Mem_InstanceIdType

Identifies the memory instance.

Available via: MemIf_DriverTypes.h

Mem_AddressType
typedef uint32 Mem_AddressType

Physical memory device address type.

Available via: MemIf_DriverTypes.h

Mem_LengthType
typedef uint32 Mem_LengthType

Physical memory device length type.

Available via: MemIf_DriverTypes.h

Mem_DataType
typedef uint8 Mem_DataType

Read data user buffer type.

Available via: MemIf_DriverTypes.h

Mem_JobResultType
enum Mem_JobResultType

Asynchronous job result type.

Values:

enumerator MEM_JOB_FINISHED = 0x00

The last job has been finished successfully

enumerator MEM_JOB_PENDING = 0x01

A job is currently being processed

enumerator MEM_JOB_FAILED = 0x02

Job failed for some unspecific reason

enumerator MEM_JOB_PAGE_INCONSISTENT = 0x03

The checked page is not blank

enumerator MEM_JOB_ERROR_ECC_UNCORRECTED = 0x04

Uncorrectable ECC errors occurred during memory access

enumerator MEM_JOB_ERROR_ECC_CORRECTED = 0x05

Correctable ECC errors occurred during memory access

Available via: MemIf_DriverTypes.h

Mem_HwServiceIdType
typedef uint8 Mem_HwServiceIdType

Hardware specific service request identifier type.

A plain identifier; the set of valid ids is implementation-defined. Available via: MemIf_DriverTypes.h

Mem_BinaryHeaderType
struct Mem_BinaryHeaderType

This structure contains elements for accessing the Mem driver service functions and consistency information.

Public Members

uint64 uniqueId

Unique ID

uint64 flags

Header flags

uint32 header

Address of Mem driver header structure

uint32 delimiter

Address of Mem driver delimiter field

Mem_InitFuncType initFunc

Mem_Init function pointer

Mem_DeInitFuncType deInitFunc

Mem_DeInit function pointer

Mem_PollFunctionFuncType pollFunctionFunc

Mem_PollFunction function pointer

Mem_GetJobResultFuncType getJobResultFunc

Mem_GetJobResult function pointer

Mem_ReadFuncType readFunc

Mem_Read function pointer

Mem_WriteFuncType writeFunc

Mem_Write function pointer

Mem_EraseFuncType eraseFunc

Mem_Erase function pointer

Mem_OnErrorFuncType onErrorFunc

Mem_OnError function pointer

Mem_VerifyBlankFuncType verifyBlankFunc

Mem_VerifyBlank function pointer

Mem_SuspendJobFuncType suspendJobFunc

Mem_SuspendJob function pointer

Mem_ResumeJobFuncType resumeJobFunc

Mem_ResumeJob function pointer

Mem_HwSpecificServiceFuncType hwSpecificServiceFunc

Hardware specific service function pointer

The binary-image header and service function-pointer table (see Concepts). Each API has a matching Mem_*FuncType function-pointer type. Available via: MemIf_DriverTypes.h

Initialization and shutdown
Mem_Init
void Mem_Init(const void *configPtr)

Initialization function - initializes all variables and sets the module state to initialized.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x01

Development error(s):

Parameters:

configPtr – [in]

Pointer to the configuration structure. This parameter is intended for future extensions to support runtime-selectable configuration variants, which allow the selection and initialization of specific variants during runtime. As this functionality is not currently supported, a NULL_PTR SHALL be provided.

Note:To support the common function pointer type definitions, this parameter is given as void pointer even though the actual type is |<Mip>|_ConfigType.

Returns:

None.

When to call: once, before any other memory function. configPtr MUST be NULL_PTR. Effect: initialises the driver; each instance’s job result becomes MEM_JOB_FINISHED. Errors: see Errors. Available via: Mem.h

Mem_DeInit
void Mem_DeInit(void)

De-initialize module. If there is still an access job pending, it is immediately terminated (using hardware cancel operation) and the Mem driver module state is set to uninitialized. Therefore, Mem must be re-initialized before it will accept any new job requests after this service is processed.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x0b

Parameters:

None –

Returns:

None.

Effect: cancels any pending job (via the hardware) and de-initialises the driver. Available via: Mem.h

Memory jobs
Mem_Read
Std_ReturnType Mem_Read(Mem_InstanceIdType instanceId, Mem_AddressType address, Mem_DataType *dataPtr, Mem_LengthType length)

Triggers a read job to copy the data from the source address into the referenced destination data buffer. The result of this service can be retrieved using the Mem_GetJobResult API. If the read operation was successful, the result of the job is MEM_JOB_FINISHED. If the read operation failed, the result of the job is either MEM_JOB_FAILED in case of a general error or MEM_JOB_ERROR_ECC_CORRECTED/MEM_JOB_ERROR_ECC_UNCORRECTED in case of a correctable/uncorrectable ECC error.

Sync/Async:

Asynchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x05

Development error(s):

Parameters:

  • instanceId – [in] ID of the related memory driver instance.

  • address – [in] Physical address to read data from.

  • length – [in] Read length in bytes.

  • dataPtr – [out] Destination memory pointer to store the read data.

Return values:

  • E_OK – The requested job has been accepted by the module.

  • E_NOT_OK – The requested job has not been accepted by the module.

  • E_MEM_SERVICE_NOT_AVAIL – The service

Returns:

Std_ReturnType

Effect: starts an asynchronous read of length bytes into dataPtr. Returns E_OK if accepted. The caller MUST keep dataPtr valid until the job finishes. Errors: see Errors. Available via: Mem.h

Mem_Write
Std_ReturnType Mem_Write(Mem_InstanceIdType instanceId, Mem_AddressType address, const Mem_DataType *dataPtr, Mem_LengthType length)

Triggers a write job to store the passed data to the provided address area with given address and length. The result of this service can be retrieved using the Mem_GetJobResult API. If the write operation was successful, the job result is MEM_JOB_FINISHED. If there was an issue writing the data, the result is MEM_JOB_FAILED.

Sync/Async:

Asynchronous

Reentrancy:

Non Reentrant

Service ID [hex]:

0x06

Development error(s):

Parameters:

  • instanceId – [in] ID of the related memory driver instance.

  • address – [in] Physical write address (aligned to page size)

  • dataPtr – [in] Source data pointer

  • length – [in] Write length in bytes (aligned to page size).

Return values:

  • E_OK – The requested job has been accepted by the module.

  • E_NOT_OK – The requested job has not been accepted by the module.

  • E_MEM_SERVICE_NOT_AVAIL – The service function is not implemented.

Returns:

Std_ReturnType

Effect: starts an asynchronous write; address and length MUST be write-page aligned. The caller MUST keep dataPtr valid until the job finishes. Errors: see Errors. Available via: Mem.h

Mem_Erase
Std_ReturnType Mem_Erase(Mem_InstanceIdType instanceId, Mem_AddressType address, Mem_LengthType length)

Triggers an erase job of the given sector/sector batch defined by address and length. The result of this service can be retrieved using the Mem_GetJobResult API. If the erase operation was successful, the result of the job is MEM_JOB_FINISHED. If the erase operation failed, e.g. due to a hardware issue, the result of the job is MEM_JOB_FAILED.

Sync/Async:

Asynchronous

Reentrancy:

Non Reentrant

Service ID [hex]:

0x07

Development error(s):

Parameters:

  • instanceId – [in] ID of the related memory driver instance.

  • address – [in] Physical erase address (aligned to sector size).

  • length – [in] Erase length in bytes (aligned to sector size)

Return values:

  • E_OK – The requested job has been accepted by the module.

  • E_NOT_OK – The requested job has not been accepted by the module.

  • E_MEM_SERVICE_NOT_AVAIL – The service function is not implemented.

Returns:

Std_ReturnType

Effect: starts an asynchronous erase; address and length MUST be sector aligned. Errors: see Errors. Available via: Mem.h

Mem_VerifyBlank
Std_ReturnType Mem_VerifyBlank(Mem_InstanceIdType instanceId, Mem_AddressType address, Mem_LengthType length)

Triggers a job to check the erased state of the page which is referenced by address. The result of this service can be retrieved using the Mem_GetJobResult API. If the checked page is blank, the result of the job is MEM_JOB_FINISHED. Otherwise, if the page is not blank, the result is MEM_JOB_PAGE_INCONSISTENT.

Sync/Async:

Asynchronous

Reentrancy:

Non Reentrant

Service ID [hex]:

0x9

Development error(s):

Parameters:

  • instanceId – [in] ID of the related memory driver instance.

  • address – [in] Physical blank check address.

  • length – [in] Blank check length.

Return values:

  • E_OK – The requested job has been accepted by the module.

  • E_NOT_OK – The requested job has not been accepted by the module.

  • E_MEM_SERVICE_NOT_AVAIL – The service function is not implemented.

Returns:

Std_ReturnType

Effect: starts an asynchronous blank check; a non-blank area yields MEM_JOB_PAGE_INCONSISTENT. Errors: see Errors. Available via: Mem.h

Job control and status
Mem_GetJobResult
Mem_JobResultType Mem_GetJobResult(Mem_InstanceIdType instanceId)

Service to return result of the most recent job.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x04

Development error(s):

Parameters:

instanceId – [in] ID of the related memory driver instance.

Return values:

  • MEM_JOB_FINISHED – The last job has been finished successfully.

  • MEM_JOB_PENDING – A job is currently being processed.

  • MEM_JOB_FAILED – Job failed for some unspecific reason.

  • MEM_JOB_PAGE_INCONSISTENT – The checked page is not blank.

  • MEM_JOB_ERROR_ECC_UNCORRECTED – Uncorrectable ECC errors occurred during memory access.

  • MEM_JOB_ERROR_ECC_CORRECTED – Correctable ECC errors occurred during memory access.

Returns:

Mem_JobResultType

Effect: returns the result of the most recent job for the instance (overwritten by each new job). Available via: Mem.h

Mem_SuspendJob
Std_ReturnType Mem_SuspendJob(Mem_InstanceIdType instanceId)

Suspend active memory operation using hardware mechanism.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x0c

Development error(s):

Parameters:

instanceId – [in] ID of the related memory driver instance.

Return values:

  • E_OK – The requested job has been accepted by the module.

  • E_NOT_OK – The requested job has not been accepted by the module.

  • E_MEM_SERVICE_NOT_AVAIL – The service function is not implemented.

Returns:

Std_ReturnType

Effect: suspends the active job via the hardware. Returns E_MEM_SERVICE_NOT_AVAIL where unsupported. Errors: see Errors. Available via: Mem.h

Mem_ResumeJob
Std_ReturnType Mem_ResumeJob(Mem_InstanceIdType instanceId)

Resume suspended memory operation using hardware mechanism.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x0d

Development error(s):

Parameters:

instanceId – [in] ID of the related memory driver instance.

Return values:

  • E_OK – The requested job has been accepted by the module.

  • E_NOT_OK – The requested job has not been accepted by the module.

  • E_MEM_SERVICE_NOT_AVAIL – The service function is not implemented.

Returns:

Std_ReturnType

Effect: resumes a suspended job. Returns E_MEM_SERVICE_NOT_AVAIL where unsupported. Errors: see Errors. Available via: Mem.h

Mem_OnError
void Mem_OnError(Mem_InstanceIdType instanceId)

This service can be used to log an access error in case the MemDrv cannot provide the access error information - typically for ECC faults. It is called by the system ECC handler to notify an ECC error to the memory upper layers.

Sync/Async:

Synchronous

Reentrancy:

Non reentrant

Service ID [hex]:

0x08

Development error(s):

Parameters:

instanceId – [in] ID of the related memory driver instance.

Returns:

None.

When to call: by the system’s ECC handler on an uncorrectable ECC error. Effect: cancels the current job and sets MEM_JOB_ERROR_ECC_UNCORRECTED. Available via: Mem.h

Hardware service and scheduling
Mem_HwSpecificService
Std_ReturnType Mem_HwSpecificService(Mem_InstanceIdType instanceId, Mem_HwServiceIdType hwServiceId, Mem_DataType *dataPtr, Mem_LengthType *lengthPtr)

Triggers a hardware specific memory driver job. dataPtr can be used to pass and return data to/from this service. This service is just a dispatcher to the hardware specific routine implementation referenced by hwServiceId. The result of this service can be retrieved using the Mem_GetJobResult API. If the hardware specific routine was successful, the result of the job is MEM_JOB_FINISHED. If the hardware specific routine failed, the result of the job is MEM_JOB_FAILED.

Sync/Async:

Asynchronous

Reentrancy:

Non Reentrant

Service ID [hex]:

0x0a

Development error(s):

Parameters:

  • instanceId – [in] ID of the related memory driver instance.

  • hwServiceId – [in] Hardware specific service request identifier for dispatching the request.

  • dataPtr – [in] Request specific data pointer.

  • lengthPtr – [in] Size pointer of the data passed by dataPtr.

Return values:

  • E_OK – The requested job has been accepted by the module.

  • E_NOT_OK – The requested job has not been accepted by the module.

  • E_MEM_SERVICE_NOT_AVAIL – The service function is not implemented.

Returns:

Std_ReturnType

Effect: dispatches the device-specific service identified by hwServiceId; an unsupported id returns E_MEM_SERVICE_NOT_AVAIL. Errors: see Errors. Available via: Mem.h

Mem_PollFunction
void Mem_PollFunction(void)

Service to handle the requested jobs and the internal management operations.

Sync/Async:

Synchronous

Reentrancy:

Non Reentrant

Service ID [hex]:

0x03

Parameters:

None –

Returns:

None.

When to call: cyclically while a job is pending; it advances the active job and updates its result. Available via: Mem.h