EEPROM Driver (Eep)

Service for EEPROM initialization.

Sets the mode.

Reads from EEPROM.

Writes to EEPROM.

Service for erasing EEPROM sections.

Compares a data block in EEPROM with an EEPROM block in the memory.

Cancels a running job.

Returns the EEPROM status.

This service returns the result of the last job.

Service to get the version information of this module.

Service to perform the processing of the EEPROM jobs (read/write/erase/compare) .

This callback function provided by the module user is called when a job has been completed with a positive result.

This callback function provided by the module user is called when a job has been canceled or finished with negative result.

This is the type of the external data structure containing the initialization data for the EEPROM driver.

Used as address offset from the configured EEPROM base address to access a certain EEPROM memory area.

Specifies the number of bytes to read/write/erase/compare.

Type of error Related error code Error value Invalid configuration set selection EEP_E_INIT_FAILED 0x10 Invalid configuration set selection EEP_E_PARAM_ADDRESS 0x11 Invalid configuration set selection EEP_E_PARAM_DATA 0x12 Invalid configuration set selection EEP_E_PARAM_LENGTH 0x13 API service called without module initialization EEP_E_UNINIT 0x20 API service called with a NULL pointer EEP_E_PARAM_POINTER 0x23

The function Eep_Init shall initialize all EEPROM relevant reg- isters with the values of the structure referenced by the parameter ConfigPtr .

After having finished the module initialization, the function Eep_- Init shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_OK .

The function Eep_Read shall copy the given parameters, initiate a read job, set the EEPROM status to MEMIF_BUSY , set the job result to MEMIF_- JOB_PENDING and return.

The Eep module shall execute the read job asynchronously within the Eep module's job processing function. During job processing the Eep module shall read a data block of size Length from EepromAddress + EEPROM base address to * DataBufferPtr . The function Eep_Read checks the API parameters according to requirements [SWS_Eep_00016], [SWS_Eep_00017], [SWS_Eep_00018]. The function Eep_Read checks the EEPROM state according to requirement [SWS_Eep_00033].

The function Eep_Write shall copy the given parameters, initiate a write job, set the EEPROM status to MEMIF_BUSY , set the job result to MEMIF_- JOB_PENDING and return.

The Eep module shall execute the write job asynchronously within the Eep module's job processing function. During job processing the Eep module shall write a data block of size Length from * DataBufferPtr to EepromAddress + EEP- ROM base address. The function Eep_Write checks the API parameters according to requirements [SWS_Eep_00016], [SWS_Eep_00017], [SWS_Eep_00018]. The function Eep_Write checks the EEPROM state according to requirement [SWS_Eep_00033].

If development error detection for the module Eep is enabled: the functions Eep_Read() , Eep_Write() , Eep_Compare() and Eep_Erase() shall check that DataBufferPtr is not NULL. If DataBufferPtr is NULL, they shall raise development error EEP_E_PARAM_DATA , otherwise (if no development error detection is enabled) it shall return with E_NOT_OK .

If development error detection for the module Eep is enabled: the functions Eep_Read() , Eep_Write() , Eep_Compare() and Eep_Erase() shall check that EepromAddress is valid. If EepromAddress is not within the valid EEP- ROM address range they shall raise development error EEP_E_PARAM_ADDRESS , oth- erwise (if no development error detection is enabled) it shall return with E_NOT_OK .

If development error detection for the module Eep is enabled: the functions Eep_Read() , Eep_Write() , Eep_Compare() and Eep_Erase() shall check that the parameter Length is within the specified minimum and maximum val- ues: • Min.: 1 • Max.: EepSize - EepromAddress If the parameter Length is not within the specified minimum and maximum values, they shall raise development error EEP_E_PARAM_LENGTH , otherwise (if no development error detection is enabled) it shall return with E_NOT_OK .

The function Eep_Erase shall copy the given parameters, initiate an erase job, set the EEPROM status to MEMIF_BUSY , set the job result to MEMIF_- JOB_PENDING and return.

The Eep module shall execute the erase job asynchronously within the Eep module's job processing function. The Eep module shall erase an EEP- ROM block starting from EepromAddress + EEPROM base address of size Length . The function Eep_Erase checks the API parameters according to requirements [SWS_Eep_00016], [SWS_Eep_00017], [SWS_Eep_00018]. The function Eep_Erase checks the EEPROM state according to requirement [SWS_Eep_00033].

The function Eep_Cancel shall abort a running job syn- chronously so that directly after returning from this function a new job can be requested by the upper layer.

The function Eep_GetJobResult shall synchronously return the result of the last job that has been accepted by the Eep module.

The function Eep_Compare shall copy the given parameters, ini- tiate a compare job, set the EEPROM status to MEMIF_BUSY , set the job result to MEMIF_JOB_PENDING and return.

The Eep module shall execute the compare job asynchronously within the Eep module's job processing function. During job processing the Eep module shall compare the EEPROM data block at EepromAddress + EEPROM base address of size Length with the data block at * DataBufferPtr of the same length. The service Eep_Compare checks the API parameters according to requirements [SWS_Eep_00016], [SWS_Eep_00017], [SWS_Eep_00018]. The service Eep_Compare checks the EEPROM state according to requirement [SWS_Eep_00033].

The function Eep_Cancel shall set the EEP module state to MEMIF_IDLE .

The function Eep_Cancel shall set the job result to MEMIF_- JOB_CANCELED if the job result currently has the value MEMIF_JOB_PENDING . Other- wise it shall leave the job result unchanged.

The function Eep_GetStatus shall return the EEPROM status synchronously.

The function Eep_MainFunction shall perform the processing of the EEPROM read, write, erase and compare jobs.

When a job has been initiated, the Eep's user shall call the func- tion Eep_MainFunction cyclically until the job is finished.

The function Eep_MainFunction shall return without action if no job is pending.

The functions Eep_SetMode() , Eep_Read() , Eep_Write() , Eep_Compare() and Eep_Erase() shall check the EEPROM state for being MEMIF_IDLE . If the EEPROM state is not MEMIF_IDLE , the called function shall • raise the development error EEP_E_UNINIT if the module has not been initialized yet and if development error detection for the module Eep is enabled • raise the runtime error EEP_E_BUSY according to the EEPROM state • reject the service with E_NOT_OK (except Eep_SetMode() because this service has no return value).

The Eep module shall not buffer jobs. The Eep module shall accept only one job at a time. During job processing, the Eep module shall accept no other job.

The Eep module shall not buffer data to be read or written. The Eep module shall use application data buffers that are referenced by a pointer passed via the API.

The function Eep_SetMode shall set the EEPROM operation mode to the given Mode parameter. The function Eep_SetMode checks the EEPROM state according to requirement [SWS_Eep_00033].

The function Eep_Init shall set the EEPROM mode to the con- figured default mode.

The Eep module shall call the callback function defined in the configuration parameter EepJobEndNotification when a job has been completed with a positive result: • Read finished & OK • Write finished & OK • Erase finished & OK • Compare finished & data blocks are equal

The Eep module shall call the callback function defined in the configuration parameter EepJobErrorNotification when a job has been canceled or aborted with negative result: • Read aborted • Write aborted or failed • Erase aborted or failed • Compare aborted or data blocks are not equal.

Notification callback functions are configurable through their cor- responding configuration parameters. If no callback function is configured, there shall be no asynchronous notification.

In normal EEPROM mode, the Eep module shall read within one job processing cycle a number of bytes specified by the parameter EepNormalRead- BlockSize .

For an Eep module driving an external EEPROM through SPI: In normal EEPROM mode, the Eep module shall access the external EEPROM by usage of SPI channels that are configured for normal access to the SPI EEPROM.

For an Eep module driving an external EEPROM through SPI: The Eep's configuration shall be such that the value of the configuration parameter EepNormalReadBlockSize fits to the number of bytes that are readable in normal SPI mode.

In fast EEPROM mode, the Eep module shall read within one job processing cycle a number of bytes specified by the parameter EepFastReadBlock- Size .

For an Eep module driving an external EEPROM through SPI: In fast EEPROM mode, the Eep module shall access the external EEPROM by usage of SPI channels that are configured for burst access to the SPI EEPROM.

For an Eep module driving an external EEPROM through SPI: If the SPI access fails, the Eep module shall behave as specified in [SWS_Eep_00068].

The Eep module shall only write (and erase) as many bytes to the EEPROM as supported by the EEPROM hardware within one job processing cycle. For internal EEPROMs, usually 1 data word can be written per time. Some external EEPROMs provide a RAM buffer (e.g. page buffer) that allows writing many bytes in one step.

When a read job is finished successfully, the Eep module shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_- OK . If configured, the Eep module shall call the notification defined in the configuration parameter EepJobEndNotification .

The Eep module shall erase an EEPROM cell before writing to it if this is not done automatically by the EEPROM hardware.

If the value to be written to an EEPROM cell is already contained in the EEPROM cell, the Eep module should 1 skip the programming of that cell if it is configured to do so through the configuration parameter EepWriteCycleReduc- tion .

The Eep module shall preserve data of affected EEPROM cells by performing read – modify – write operations, if the number of bytes to be written are smaller than the erasable and/or writeable data units.

The Eep module shall keep the number of read – modify – write operations during writing a data block as small as possible.

When an error is detected during read job processing, the Eep module shall abort the job, shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_FAILED . If configured, the Eep module shall call the notification defined in the configuration parameter EepJobErrorNotification .

The Eep module shall erase only as many bytes to the EEPROM as supported by the EEPROM hardware within one job processing cycle.

The Eep module shall use block erase commands if supported by the EEPROM hardware and if the given parameters ( EepromAddress and Length ) are aligned to erasable blocks.

The Eep module shall preserve the contents of affected EEP- ROM cells by using read – modify – write operations, if the given erase parameters ( EepromAddress and Length ) do not align with the erasable data units.

For an Eep module driving an external EEPROM through SPI: The Eep's configuration shall be such that the value of the configuration parameter EepFastReadBlockSize fits to the number of bytes that are readable in burst SPI mode.

When it is detected during compare job processing that the com- pared data areas are not equal, the EEPROM driver shall abort the job, set the EEP- ROM state to MEMIF_IDLE and the job result to MEMIF_BLOCK_INCONSISTENT . If configured, the callback function Eep_JobErrorNotification shall be called.

The source code of external EEPROM drivers shall be indepen- dent of the microcontroller platform.

The configuration parameter EepMainFunctionPeriod (see [ECUC_Eep_00170]) shall be used for internal timing of the EEPROM driver (dead- line monitoring, write and erase timing etc.) if needed by the implementation and/or the underlying hardware.

The Eep SWS shall be valid both for internal and external EEP- ROMs. The Eep SWS defines asynchronous services for EEPROM operations (read/write/ erase/compare).

The Eep module shall preserve data of affected EEPROM cells by performing read – modify – write operations, if the given parameters ( EepromAddress and Length ) do not align with the erasable/writeable data units.

file (see [SWS_Eep_00095]). • All required SPI channels • All required SPI sequences • All required SPI jobs

file (see EEP038): • All SPI channels that are required for EEPROM access (read, write, erase). • Those channels shall be linked to construct SPI jobs that are linked with chip selected handling. This depends on the specific EEPROM device. • Those jobs shall be assigned to SPI sequences to be scheduled for SPI transfer. A complete list of required parameters is specified in the SPI Handler/Driver Software Specification.

In normal EEPROM mode, the Eep module shall write (and erase) within one job processing cycle a number of bytes specified by the parameter EepNor- malWriteBlockSize .

In fast EEPROM mode, the Eep module shall write (and erase) within one job processing cycle a number of bytes specified by the parameter Eep- FastWriteBlockSize .

The type Eep_AddressType shall have 0 as lower limit for each EEPROM device.

The Eep's user shall not call the function Eep_Init during a running operation.

The Eep's user shall not call the function Eep_SetMode during a running operation.

The Eep's user shall only call Eep_Read after the Eep module has been been initialized.

The Eep's user shall not call the function Eep_Read during a running Eep module job (read/write/erase/compare).

The Eep module's user shall only call the function Eep_Write after the Eep module has been initialized.

The Eep module's user shall not call the function Eep_Write during a running Eep module job (read/write/erase/compare).

The Eep module's user shall only call the function Eep_Erase after the Eep module has been initialized.

The Eep module's user shall not call the function Eep_Erase during a running Eep job (read/write/erase/compare).

The Eep module's user shall only call the function Eep_Compare after the Eep module has been initialized.

The Eep module's user shall not call the function Eep_Compare during a running Eep job (read/write/erase/compare).

The callback function defined in the configuration parameter EepJobEndNotification shall be callable on interrupt level.

The callback function defined in the configuration parameter EepJobErrorNotification shall be callable on interrupt level.

The Eep module shall allow to be configured for inter- rupt or polling controlled job processing (if this is supported by the EEP- ROM hardware) through the configuration parameter EepUseInterrupts (see [ECUC_Eep_00163]).

If interrupt controlled job processing is supported and enabled, the external interrupt service routine located in Eep_Irq.c shall call an additional job processing function.

The Eep module shall provide two different read modes: • normal mode • fast mode

For an Eep module driving an external EEPROM: in case the external EEPROM does not support the burst mode, the Eep module shall accept a selection of fast read mode, but shall behave the same as in normal mode (don't care of mode parameter).

The Eep module shall provide two different write modes: • normal mode • fast mode

For the case of an Eep module driving an external EEPROM: if the external EEPROMs does not provide burst mode, the Eep module shall accept a selection of fast mode, but shall behave the same as in normal mode (don't care of mode parameter).

The Eep module's user shall not call the Eep_Cancel() function during a running Eep_MainFunction() function. [SWS_Eep_00136] can be achieved by one of the following scheduling configurations: • Possibility 1: the job functions of the NVRAM manager and the EEPROM driver are synchronized (e.g. called sequentially within one task) • Possibility 2: the task that calls the Eep_MainFunction function cannot be pre- empted by another task.

In case the Eep module support an SPI external device, the Eep module shall provide additional callback notifications according to the SPI Handler/- Driver specification requirements.

Module Header File Imported Type Rte_Dem_Type.h Dem_EventIdType Dem Rte_Dem_Type.h Dem_EventStatusType MemIf.h MemIf_JobResultType (obsolete) MemIf.h MemIf_ModeType (obsolete) MemIf MemIf.h MemIf_StatusType Std_Types.h Std_ReturnType Std Std_Types.h Std_VersionInfoType

Dem_SetEventStatus Dem.h Called by SW-Cs or BSW modules to report monitor status information to the Dem. BSW modules calling Dem_SetEventStatus can safely ignore the return value. This API will be available only if ({Dem/Dem ConfigSet/DemEventParameter/DemEvent ReportingType} == STANDARD_REPORTING) Det_ReportRuntimeError Det.h Service to report runtime errors. If a callout has been configured then this callout shall be called.

Det_ReportError Det.h Service to report development errors.

The production error code EEP_E_ERASE_FAILED shall be re- ported when the EEPROM erase function failed.

The production error code EEP_E_WRITE_FAILED shall be re- ported when the EEPROM write function failed.

The production error code EEP_E_READ_FAILED shall be re- ported when the EEPROM read function failed.

The production error code EEP_E_COMPARE_FAILED shall be reported when the EEPROM compare function failed.

The function Eep_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code EEP_E_ERASE_FAILED to the DEM if an EEPROM erase job fails due to a hardware error.

The function Eep_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code EEP_E_WRITE_FAILED to the DEM if an EEPROM write job fails due to a hardware error.

The function Eep_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code EEP_E_READ_FAILED to the DEM if an EEPROM read job fails due to a hardware error.

The function Eep_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code EEP_E_COMPARE_FAILED to the DEM if an EEPROM compare job fails due to a hardware error.

The function Eep_Cancel shall cancel an ongoing EEPROM read, write, erase or compare job.

If configured, Eep_Cancel shall call the error notification func- tion defined in EepJobErrorNotification in order to inform the caller about the cancelation of a job.

The EEPROM module shall add a device specific base address to the address type Eep_AddressType if necessary.

When a write job is finished successfully, the Eep module shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_- OK . If configured, the Eep module shall call the notification defined in the configuration parameter EepJobEndNotification .

When an erase job is finished successfully, the Eep module shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_- OK . If configured, the Eep module shall call the notification defined in the configuration parameter EepJobEndNotification .

When a compare job is finished successfully, the Eep module shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_- JOB_OK . If configured, the Eep module shall call the notification defined in the config- uration parameter EepJobEndNotification .

When an error is detected during write job processing, the Eep module shall abort the job, shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_FAILED . If configured, the Eep module shall call the notification defined in the configuration parameter EepJobErrorNotification .

When an error is detected during erase job processing, the Eep module shall abort the job, shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_FAILED . If configured, the Eep module shall call the notification defined in the configuration parameter EepJobErrorNotification .

When an error is detected during compare job processing, the Eep module shall abort the job, shall set the EEPROM state to MEMIF_IDLE and shall set the job result to MEMIF_JOB_FAILED . If configured, the Eep module shall call the notification defined in the configuration parameter EepJobErrorNotification .

If the module implementation uses custom interrupt processing, the interrupt service routines shall be placed in Eep_Irq.c .

The runtime error code EEP_E_TIMEOUT shall be reported when the timeout supervision of a read, write, erase or compare job failed.

The function Eep_MainFunction shall provide a timeout moni- toring for the currently running job. That is it shall supervise the deadline of the read / compare / erase or write job.

The function Eep_MainFunction shall check whether the con- figured maximum erase time (see [ECUC_Eep_00178] EepEraseTime ) has been ex- ceeded. If this is the case, the function Eep_MainFunction shall raise the runtime error EEP_E_TIMEOUT .

The function Eep_MainFunction shall check whether the ex- pected maximum write time (see note below) has been exceeded. If this is the case, the function Eep_MainFunction shall raise the runtime error EEP_E_TIMEOUT .

The function Eep_MainFunction shall check whether the ex- pected maximum read / compare time (see note below) has been exceeded. If this is the case, the function Eep_MainFunction shall raise the runtime error EEP_E_- TIMEOUT .

If development error detection for the module Eep is enabled, and if the function Eep_GetVersionInfo is called with a NULL Pointer, the function Eep_GetVersionInfo shall raise the development error EEP_E_PARAM_POINTER , otherwise (if no development error detection is enabled) it shall return without any action.

Error Name: EEP_E_ERASE_FAILED Short Description: EEPROM erase failed (HW) Long Description: The Eeprom module reports this error when EEPROM erase job fails due to a hardware error. Fail EEPROM erase job failed (see [SWS_Eep_00255]). Detection Criteria: Pass EEPROM erase job finished successfully (see [SWS_Eep_00244]). Secondary Parameters: N/A Time Required: N/A Monitor Frequency: Implementation specific

Error Name: EEP_E_WRITE_FAILED Short Description: EEPROM write failed (HW) Long Description: The Eeprom module reports this error when EEPROM write job fails due to a hardware error. Fail EEPROM write job failed (see [SWS_Eep_00249]). Detection Criteria: Pass EEPROM write job finished successfully (see [SWS_Eep_00248]). Secondary Parameters: N/A Time Required: N/A Monitor Frequency: Implementation specific

The production error code EEP_E_ERASE_FAILED shall be re- ported with PASSED when the Eeprom erase function was executed successfully.

Error Name: EEP_E_COMPARE_FAILED Short Description: EEPROM compare failed (HW) Long Description: The Eeprom module reports this error when EEPROM compare job fails due to a hardware error. Fail EEPROM compare job failed (see [SWS_Eep_00253]). Detection Criteria: Pass EEPROM compare job finished successfully (see [SWS_Eep_00254]). Secondary Parameters: N/A Time Required: N/A Monitor Frequency: Implementation specific

If the underlying EEPROM technology requires a certain align- ment of the read address or length information and if the address and/or length pa- rameter for a read or compare Job are not correctly aligned, the function Eep_Main- Function shall internally compensate for this missing alignment, that is the function Eep_MainFunction shall provide byte-wise read access to the flash memory, regard- less of any alignment restrictions imposed by the Hardware.

The production error code EEP_E_WRITE_FAILED shall be re- ported with PASSED when the Eeprom write function was executed successfully.

The production error code EEP_E_WRITE_FAILED shall be re- ported with FAILED when the Eeprom write function failed

The production error code EEP_E_READ_FAILED shall be re- ported with FAILED when the Eeprom read function failed.

Type of error Related error code Error value API service called while driver still busy EEP_E_BUSY 0x21 Timeout exceeded EEP_E_TIMEOUT 0x22

The production error code EEP_E_READ_FAILED shall be re- ported with PASSED when the Eeprom read function was executed successfully.

The production error code EEP_E_COMPARE_FAILED shall be reported with FAILED when the Eeprom compare function failed.

The production error code EEP_E_COMPARE_FAILED shall be re- ported with PASSED when the Eeprom compare function was executed successfully.

The production error code EEP_E_ERASE_FAILED shall be re- ported with FAILED when the Eeprom erase function failed.

Eep driver shall handle data buffer alignment internally. Instead of imposing any requirements on a RAM buffers' alignments (as they are uint8*) it shall handle passed pointers as being just byte-aligned.

These requirements are not applicable to this specifica- tion.