AUTOSAR_SWS_EEPROMDriver

七月 02, 2025

Specification of EEPROM Driver

Introduction and functional overview

This specification describes the functionality and API for an EEPROM driver. This specification is applicable to drivers for both internal and external EEPROMs.

The EEPROM driver provides services for reading, writing, erasing to/from an EEPROM. It also provides a service for comparing a data block in the EEPROM with a data block in the memory (e.g. RAM).

The behaviour of those services is asynchronous.

A driver for an internal EEPROM accesses the microcontroller hardware directly and is located in the Microcontroller Abstraction Layer. A driver for an external EEPROM uses handlers (SPI in most cases) or drivers to access the external EEPROM device. It is located in the ECU Abstraction Layer.

The functional requirements and the functional scope are the same for both types of drivers. Hence the API is semantically identical.

Acronyms and Abbreviations

Acronyms and abbreviations which have a local scope and therefore are not contained in the AUTOSAR glossary [1] must appear in a local glossary.

Constraints and assumptions

Limitations

The EEPROM driver does not provide mechanisms for providing data integrity (e.g. checksums, redundant storage, etc.).

The setting of the EEPROM write protection is not provided.

Applicability to safety related environments

This module can be used within safety relevant systems if the upper layer software provides following mechanisms for safety related data:

Checksum protection

Checking integrity before using data

Redundant storage

Verification of data after it has been written to EEPROM. For this, the compare function of the EEPROM driver can be used.

Dependencies to other modules

There are two classes of EEPROM drivers:

EEPROM drivers for onchip EEPROM.

These are part of the Microcontroller Abstraction Layer (see [7]).

EEPROM drivers for external EEPROM devices.

These are part of the ECU Abstraction Layer (see [7]).

[SWS_Eep_00082]

[ ]

The source code of external EEPROM drivers shall be independent of the microcontroller platform.

The internal EEPROM may depend on the system clock, prescaler(s) and PLL. Thus, changes of the system clock (e.g. PLL on - PLL off) may also affect the clock settings of the EEPROM hardware. Module EEPROM Driver do not take care of setting the registers which configure the clock, prescaler(s) and PLL in its init function. This has to be done by the MCU module [8].

A driver for an external EEPROM depends on the API and capabilities of the used onboard communication handler (e.g. SPI Handler/Driver [9]).

EEPROM driver is part of Memory Abstraction Architecture and for this reason some types depend on Memory Interface (MemIf) module [10].

File structure

[SWS_Eep_00228]

[ ]

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

Requirements Tracing

Uptracing to requirements in [11], [12], [13].

Functional specification

General behavior

[SWS_Eep_00088]

[SRS_Eep_12051]

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

[SWS_Eep_00036]

[SRS_Eep_00095]

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.

Note:

when running in production mode it is assumed that the Eep user will never issue jobs concurrently; therefore error handling for this requirement is restricted to development, see [SWS_Eep_00033].

[SWS_Eep_00037]

[SRS_SPAL_12075]

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.

[SWS_Eep_00256]

[SRS_Eep_00087]

[SRS_Eep_00088]

[SRS_Eep_12091]

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.

Error Classification

This section describes how the Eep module has to manage the several error classes that may occur during the life cycle of this basic software.

The general requirements document of AUTOSAR [12] specifies that all basic software modules must distinguish (according to the product life cycle) 3 error types:

Development errors: These errors should be detected and fixed during development phase. In most cases, these errors are software errors.

Runtime errors: These errors are software exceptions that may occur in the production (i.e. series) code, due to software real time.

Production errors: These errors are hardware errors and software exceptions that cannot be avoided and are expected to occur in the production (i.e. series) code.

Development Errors

[SWS_Eep_00000]

[SRS_BSW_00337]

[SRS_BSW_00385]

Runtime Errors

[SWS_Eep_00251]

[ ]

Extended Production Errors

EEP_E_ERASE_FAILED

[SWS_Eep_00242]

[ ]

[SWS_Eep_00255]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

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

[SWS_Eep_00244]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

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

EEP_E_WRITE_FAILED

[SWS_Eep_00243]

[ ]

[SWS_Eep_00249]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The production error code EEP_E_WRITE_FAILED shall be reported with FAILED when the Eeprom write function failed

[SWS_Eep_00248]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

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

EEP_E_READ_FAILED

[SWS_Eep_00244]

[ ]

[SWS_Eep_00250]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

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

[SWS_Eep_00252]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

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

EEP_E_COMPARE_FAILED

[SWS_Eep_00245]

[ ]

[SWS_Eep_00253]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

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

[SWS_Eep_00254]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

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

Error detection

For details refer to the chapter 7.3 "Error Detection" in [6].

API parameter checking

[SWS_Eep_00016]

[SRS_BSW_00323]

[SRS_SPAL_12448]

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.

[SWS_Eep_00017]

[SRS_BSW_00323]

[SRS_SPAL_12448]

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 EEPROM address range they shall raise development error EEP_E_PARAM_ADDRESS, otherwise (if no development error detection is enabled) it shall return with E_NOT_OK.

[SWS_Eep_00018]

[SRS_BSW_00323]

[SRS_SPAL_12448]

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 values:

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.

EEPROM state checking

[SWS_Eep_00033]

[SRS_BSW_00406]

[SRS_BSW_00369]

[SRS_SPAL_12064]

[SRS_SPAL_12448]

[SRS_Eep_00095]

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).

EEPROM job encounters Hardware Failure

[SWS_Eep_00200]

[SRS_BSW_00337]

The production error code EEP_E_ERASE_FAILED shall be reported when the EEPROM erase function failed.

[SWS_Eep_00201]

[SRS_BSW_00337]

The production error code EEP_E_WRITE_FAILED shall be reported when the EEPROM write function failed.

[SWS_Eep_00202]

[SRS_BSW_00337]

The production error code EEP_E_READ_FAILED shall be reported when the EEPROM read function failed.

[SWS_Eep_00203]

[SRS_BSW_00337]

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

Timeout Supervision

[SWS_Eep_00234]

[ ]

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

Error notification

For details refer to the chapter 7.2 "Error classification" in [6].

Processing of jobs - general requirements

[SWS_Eep_00128]

[ ]

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

[SWS_Eep_00129]

[ ]

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.

Hint:

The function Eep_MainFunction is still required for processing of jobs without hardware interrupt support (e.g. for read and compare jobs) and for timeout supervision.

[SWS_Eep_00246]

[ ]

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

Additional general requirements only applicable for SPI EEPROM drivers:

[SWS_Eep_00056]

[ ]

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].

[SWS_Eep_00052]

[SRS_Eep_12157]

[SRS_Eep_12124]

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.

[SWS_Eep_00053]

[SRS_Eep_12157]

[SRS_Eep_12124]

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.

[SWS_Eep_00055]

[SRS_Eep_12072]

[SRS_Eep_12124]

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.

[SWS_Eep_00073]

[SRS_Eep_12072]

[SRS_Eep_12124]

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.

Processing of read jobs

[SWS_Eep_00130]

[SRS_Eep_12156]

The Eep module shall provide two different read modes:

normal mode

fast mode

[SWS_Eep_00132]

[SRS_Eep_12156]

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).

[SWS_Eep_00051]

[SRS_Eep_12157]

[SRS_Eep_12050]

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

Example:

EepNormalReadBlockSize = 4

Number of bytes to read: 21

Required number of job processing cycles: 6

Resulting read pattern: 4-4-4-4-4-1

[SWS_Eep_00054]

[SRS_Eep_12072]

[SRS_Eep_12050]

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

Example:

EepFastReadBlockSize = 32

Number of bytes to read: 110

Required number of job processing cycles: 4

Resulting read pattern: 32-32-32-14

[SWS_Eep_00058]

[ ]

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.

[SWS_Eep_00068]

[ ]

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.

Processing of write jobs

[SWS_Eep_00057]

[SRS_Eep_12050]

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.

[SWS_Eep_00133]

[ ]

The Eep module shall provide two different write modes:

normal mode

fast mode

[SWS_Eep_00134]

[ ]

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).

[SWS_Eep_00097]

[ ]

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

Example:

EepNormalWriteBlockSize = 1

Number of bytes to write: 4

Required number of job processing cycles: 4

Resulting write pattern: 1-1-1-1

[SWS_Eep_00098]

[ ]

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

Example:

EepFastWriteBlockSize = 16

Number of bytes to write: 55

Required number of job processing cycles: 4

Resulting write pattern: 16-16-16-7

[SWS_Eep_00060]

[SRS_Eep_00092]

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

[SWS_Eep_00059]

[ ]

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

[SWS_Eep_00063]

[SRS_Eep_00088]

[SRS_Eep_00094]

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.

[SWS_Eep_00090]

[SRS_Eep_00088]

[SRS_Eep_00094]

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.

[SWS_Eep_00064]

[SRS_Eep_00092]

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

[SWS_Eep_00219]

[ ]

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.

[SWS_Eep_00222]

[ ]

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.

Note:

The verification of data written to EEPROM is not done within the write job processing function. If this is required for a data block, the compare function has to be called after the write job has been finished. This optimizes write speed, because data verification (read back and comparing data after writing) is only done where required.

Processing of erase jobs

[SWS_Eep_00069]

[SRS_Eep_12050]

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

[SWS_Eep_00070]

[SRS_Eep_00089]

[SRS_Eep_00094]

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.

[SWS_Eep_00072]

[SRS_Eep_00089]

[SRS_Eep_00094]

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

[SWS_Eep_00220]

[ ]

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.

[SWS_Eep_00223]

[ ]

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.

Processing of compare jobs

For processing of compare jobs, the following EEPROM mode related requirements are applicable: [SWS_Eep_00130], [SWS_Eep_00132], [SWS_Eep_00051], [SWS_Eep_00054].

[SWS_Eep_00221]

[ ]

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 configuration parameter EepJobEndNotification.

[SWS_Eep_00224]

[ ]

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.

[SWS_Eep_00075]

[ ]

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

Requirements only applicable for SPI EEPROM drivers:

For processing of compare jobs, the following read job requirements are applicable: [SWS_Eep_00052], [SWS_Eep_00053], [SWS_Eep_00055], [SWS_Eep_00073].

Version check

For details refer to the chapter 5.1.8 "Version Check" in [6].

API specification

Imported types

In this chapter all types included from the following modules are listed:

[SWS_Eep_00138]

[SRS_BSW_00335]

[SRS_BSW_00357]

[SRS_BSW_00377]

Type definitions

Eep_ConfigType

[SWS_Eep_00225]

[ ]

Eep_AddressType

[SWS_Eep_00226]

[ ]

[SWS_Eep_00113]

[ ]

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

[SWS_Eep_00217]

[ ]

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

Eep_LengthType

[SWS_Eep_00227]

[ ]

Function definitions

Eep_Init

[SWS_Eep_00143]

[ ]

[SWS_Eep_00004]

[SRS_BSW_00101]

[SRS_SPAL_12057]

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

[SWS_Eep_00006]

[SRS_BSW_00406]

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.

[SWS_Eep_00044]

[ ]

The function Eep_Init shall set the EEPROM mode to the configured default mode.

[SWS_Eep_00115]

[ ]

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

Eep_SetMode

[SWS_Eep_00144]

[ ]

[SWS_Eep_00042]

[SRS_Eep_12156]

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].

[SWS_Eep_00116]

[ ]

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

Eep_Read

[SWS_Eep_00145]

[ ]

[SWS_Eep_00009]

[SRS_Eep_00087]

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.

[SWS_Eep_00013]

[SRS_Eep_00087]

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].

[SWS_Eep_00117]

[ ]

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

[SWS_Eep_00118]

[ ]

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

Eep_Write

[SWS_Eep_00146]

[ ]

[SWS_Eep_00014]

[SRS_Eep_00088]

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.

[SWS_Eep_00015]

[SRS_Eep_00088]

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 + EEPROM 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].

[SWS_Eep_00119]

[ ]

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

[SWS_Eep_00120]

[ ]

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

Eep_Erase

[SWS_Eep_00147]

[ ]

[SWS_Eep_00019]

[SRS_Eep_00089]

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.

[SWS_Eep_00020]

[SRS_Eep_00089]

The Eep module shall execute the erase job asynchronously within the Eep module's job processing function. The Eep module shall erase an EEPROM 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].

[SWS_Eep_00121]

[ ]

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

[SWS_Eep_00122]

[ ]

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

Eep_Compare

[SWS_Eep_00148]

[ ]

[SWS_Eep_00025]

[SRS_Eep_12091]

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

[SWS_Eep_00026]

[SRS_Eep_12091]

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].

[SWS_Eep_00123]

[ ]

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

[SWS_Eep_00124]

[ ]

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

Eep_Cancel

[SWS_Eep_00149]

[ ]

[SWS_Eep_00215]

[SRS_Eep_00090]

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

[SWS_Eep_00021]

[SRS_Eep_00090]

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

Note:

The function Eep_Cancel is synchronous in its behavior but at the same time asynchronous w.r.t. the underlying hardware. The job of the Eep_Cancel function (i.e. make the module ready for a new job request) is finished when it returns to the caller (hence it is synchronous), but on the other hand e.g. an erase job might still be ongoing in the hardware device (hence it is asynchronous w.r.t. the hardware).

[SWS_Eep_00027]

[SRS_Eep_00090]

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

[SWS_Eep_00216]

[SRS_Eep_00090]

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

[SWS_Eep_00028]

[SRS_Eep_00090]

The function Eep_Cancel shall set the job result to MEMIF_JOB_CANCELED if the job result currently has the value MEMIF_JOB_PENDING. Otherwise it shall leave the job result unchanged.

[SWS_Eep_00136]

[ ]

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 preempted by another task.

Note:

The states and data of the affected EEPROM cells will be undefined when canceling an ongoing write or erase job with the function Eep_Cancel.

Only the NVRAM Manager is authorized to use the function Eep_Cancel.

Canceling any job on-going with the service Eep_Cancel in an external EEPROM device might set this one in a blocking state.

Eep_GetStatus

[SWS_Eep_00150]

[ ]

[SWS_Eep_00029]

[SRS_SPAL_00157]

[SRS_Eep_00091]

The function Eep_GetStatus shall return the EEPROM status synchronously.

Eep_GetJobResult

[SWS_Eep_00151]

[ ]

[SWS_Eep_00024]

[SRS_SPAL_00157]

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

The services read/write/compare/erase share the same job status. Only the result of the last accepted job can be queried. Every new job that has been accepted by the EEPROM driver overwrites the job result with MEMIF_JOB_PENDING.

Eep_GetVersionInfo

[SWS_Eep_00152]

[ ]

[SWS_Eep_00239]

[ ]

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.

Callback notifications

This chapter lists all functions provided by the Eep module to lower layer modules.

The EEPROM Driver is specified for either an internal microcontroller peripheral or an SPI external device. In the first case, the module belongs to the lowest layer of AUTOSAR Software Architecture hence this module specification has not identified any callback functions. In the second case, the module belongs to the ECU abstraction layer of AUTOSAR Software Architecture hence this module should provide callback notifications according to the SPI Handler/Driver specification requirements but those can not be specified here because they depend on module detailed design. That means, they depend on number of SPI Jobs and SPI Sequences that will be used.

[SWS_Eep_00137]

[ ]

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.

Scheduled functions

This chapter lists all functions provided by the Eep module and called directly by the Basic Software Module Scheduler.

Eep_MainFunction

[SWS_Eep_00153]

[ ]

[SWS_Eep_00030]

[SRS_Eep_12047]

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

[SWS_Eep_00031]

[ ]

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

Note:

The function Eep_MainFunction may also be called cyclically if no job is currently pending.

[SWS_Eep_00084]

[ ]

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

[SWS_Eep_00032]

[SRS_Eep_12047]

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

[SWS_Eep_00204]

[ ]

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.

[SWS_Eep_00205]

[ ]

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.

[SWS_Eep_00206]

[ ]

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.

[SWS_Eep_00207]

[ ]

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.

[SWS_Eep_00235]

[ ]

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

[SWS_Eep_00236]

[ ]

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

[SWS_Eep_00237]

[ ]

The function Eep_MainFunction shall check whether the expected 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.

Note:

The expected maximum write time depends on the current mode of the Eep module (see [SWS_Eep_00144]), the configured number of bytes to write in this mode (see [ECUC_Eep_00174] and [ECUC_Eep_00169] respectively), the size of a EEPROM write data unit (see [ECUC_Eep_00186]) and last the maximum time to write one data unit (see [ECUC_Eep_00185]). The number of bytes to write divided by the size of one EEPROM data unit yields the number of data units to write in one cycle. This multiplied with the maximum write time for one EEPROM data unit gives the expected maximum write time.

[SWS_Eep_00238]

[ ]

The function Eep_MainFunction shall check whether the expected 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.

Note:

There are currently no published parameters standardized for read / compare timings; these are difficult to standardize as they mostly depend on whether the EEPROM device is internal or external e.g. connected via SPI. Depending on the exact configuration being used, the implementation may use vendor-specific parameters similar as described for write jobs above. The configured number of bytes to read (and to compare) is coupled to the expected read / compare times which should be supervised by the Eep_MainFunction.

Expected interfaces

This chapter lists all functions the Eep module requires from other modules. 8.6.1

Mandatory interfaces

This chapter defines all interfaces which are required to fulfill the core functionality of the module.

[SWS_Eep_00154]

[ ]

Optional interfaces

This chapter defines all interfaces which are required to fulfill an optional functionality of EEPROM Driver module.

[SWS_Eep_00155]

[ ]

Configurable interfaces

In this chapter all interfaces are listed where the target function could be configured. The target function is usually a call-back function. The name of these interfaces is not fixed because they are configurable.

[SWS_Eep_00049]

[SRS_SPAL_12056]

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

Note:

The EEP implementation needs to be able to cope with the use case that post build configuration does not specify a callback, in case no notification is required. This may internally be realized by setting the callback function pointer in the initialization data structure to null.

End Job Notification

[SWS_Eep_00045]

[SRS_SPAL_00157]

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

[SWS_Eep_00157]

[ ]

[SWS_Eep_00126]

[ ]

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

Error Job Notification

[SWS_Eep_00046]

[SRS_SPAL_00157]

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.

[SWS_Eep_00158]

[ ]

[SWS_Eep_00127]

[ ]

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

Sequence diagrams

Initialization

Read/write/erase/compare

The following sequence diagram shows the write function as an example. The sequence for read, compare and erase is the same, only the processed block sizes may vary.

Cancelation of a running job

Configuration specification

How to read this chapter

For details refer to the chapter 10.1 "Introduction to configuration specification" in [6].

Containers and configuration parameters

The following chapters summarize all configuration parameters. The detailed meanings of the parameters describe Chapter 7 and Chapter 8. Further hardware / implementation specific parameters can be added if necessary.

Eep

EepGeneral

EepInitConfiguration

EepDemEventParameterRefs

EepExternalDriver

SPI specific extension

[SWS_Eep_00094]

[SRS_BSW_00390]

[SRS_BSW_00398]

In case of an external SPI EEPROM device, the following parameters shall also be located or referenced (according to the configuration methodology) in the external data structure of type Eep_ConfigType (see [ECUC_Eep_00039]). They shall be used as API parameters for accessing the SPI Handler/Driver API services. The symbolic names for those parameters are published in the module's description file (see [SWS_Eep_00095]).

All required SPI channels

All required SPI sequences

All required SPI jobs

Published parameters

Basic subset

For details refer to the chapter 10.3 "Published Information" in [6].

SPI specific extension

[SWS_Eep_00095]

[SRS_BSW_00390]

[SRS_BSW_00402]

In case of an external SPI EEPROM device, the following parameters shall be published additionally in the module's description 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.

EepPublishedInformation

Configuration example - external SPI EEPROM device

The following chapter shall provide a better understanding of how and where configuration parameters are defined and used. For the following use case a detailed implementation and configuration example is given:

Use case

Implement and configure a driver for operating an external EEPROM device accessed over SPI.

Use the AUTOSAR SPI Handler/Driver, utilizing internal buffers (IB) for command communication and external buffers (EB) for data.

Configure and perform an SPI read command.

The example assumes a certain fixed format and order of SPI commands to read from the external EEPROM device. The SPI API functions have been chosen for operating this exemplary device in order to demonstrate the basic principles of SPI bus interaction. When implementing a driver for a real-life device, the sequence of operation will most likely differ. The detailed selection of SPI API functions and parameters to be used and configured needs to be derived from studying the device's data sheet in combination with the SPI handler/driver specification [9].

Be aware that the use of the SPI API functions is exemplary; their exact signatures and configuration may change. The valid reference is always the current SPI SWS.

External SPI EEPROM device usage scenario

The following scenario is assumed in this example:

The external EEPROM device is an SPI slave device, the EEPROM driver to be implemented uses the SPI handler/driver module for the SPI master. The external device is addressed by a dedicated Chip Select line which will be asserted by the SPI master whenever a job operating on the device is being executed.

The external EEPROM uses serial op-code processing: After the device is selected with its Chip Select line going low, the first byte will be transmitted over the device's SI line. This byte contains an 8-bit Read-operation op-code (0x03), immediately followed by an 8-bit address byte. Upon completion, any data on the SI line will be ignored. The data (D7-D0) at the specified address is then shifted out onto the SO line. If only one byte is to be read, the CS line shall be driven high after the data comes out, otherwise the read sequence will be continued, with the address being automatically incremented and data shifted out on consecutive data.

Whenever the EEPROM driver's user wants to read data, the EEPROM driver forwards the read request to the SPI handler/driver via a number of selected SPI API calls. In order to follow the request/response behavior described above, the SPI needs to be configured exactly to fit the expected communication protocol. Therefore, an important development task consists in correctly configuring the SPI driver for communication with the external EEPROM device. Based on this configuration, the actual implementation of the EEPROM driver uses the SPI API functions in combination with the configured handle IDs for assigning jobs to the SPI handler/driver:

The EEPROM driver implementation may use a combination of external and internal SPI buffers for achieving the communication with the SPI handler:

Upon reception of an Eep_Read() request, the EEPROM driver writes the EEPROM source address in an SPI-channel internal buffer using Spi_WriteIB(). Next, it sets up an SPI external buffer specifying the requested number of bytes to be read using Spi_SetupEB(). It then calls Spi_AsyncTransmit() in order to initiate an SPI sequence EepReadSequence configured to match exactly the hardware access protocol outlined above.

Once the SPI read sequence has finished, the SPI handler/driver notifies the EEPROM driver by calling Spi_SeqEndNotification. The driver can now safely access the EEPROM data through the assigned external buffer and in turn finish the EEPROM read job.

Configuration of SPI parameters

In order to use the SPI handler/driver, the EEPROM driver implementer needs to create an SPI configuration, containing a complete set of SPI configuration containers such that the required functionality is configured.

Following a top-down view, an SpiSequence EepReadSequence configuration container handles one complete read sequence. EepReadSequence in turn uses an SpiJob EepReadJob for handling the details of a read job. This includes a reference to an SpiExternalDevice representing the EEPROM device with its specified Chip Select line as well as logic level characteristics like e.g. Baud Rate, Polarity or DataShiftEdge.

EepReadJob is further broken down into an ordered list of SpiChannels which when executed in order will perform the required SPI bus communication with the external device:

EepChCommand is used for sending the ReadCommand byte, using a default data constant for the read op-code.

EepChAddress is used for sending the device read address utilizing an internal buffer.

EepChReadData is used for reading the requested EEPROM data into an externally (to SPI) provided buffer.

Roughly, the work flow of configuring the SPI module for an EEPROM read command contains the following steps:

In the EcuConfiguration for Spi, create a container EepDriver of type SpiDriver representing the external EEPROM driver. It will hold sub containers of type SpiExternalDevice, SpiChannel, SpiJob and SpiSequence to be created in the steps below.

Look up the external device's SPI characteristics in its data sheet and set up a container EepDevice of type SpiExternalDevice accordingly. Specify the Chip Select line to be used in EepDevice.

Look up the details of the SPI read command sequence in the device's data sheet.

Within EepDriver, define one SpiChannel each for transmitting the Read command opcode, the EEPROM source address and for receiving the data transmitted by the device in response to the request, e.g.

EepChCommand

EepChAddress

EepChReadData

Define SPI Channel attributes for each channel based on the communication sequence described in the device data sheet. In particular, configure buffers, i.e EepChAddress to use an internal buffer and EepChReadData to use an external buffer. For the fixed read-command opcode, SpiDefaultData can be used.

Define the SpiJob EepReadJob and set it up to work on EepDevice. Specify the ordered list of SpiJobs to be executed for performing the read job. In this example, the job consists of the channel list EepChCommand, EepChAddress, EepChReadData.

Define the SpiSequence EepReadSequence containing the list of SpiJobs required to perform the desired functionality. In this example, EepReadSequence contains only one job, EepReadJob. Fill in the callback function symbols to be provided by the EEPROM driver, e.g. Eep_ReadSequenceEndNotification.

Publish all defined attributes for SPI usage in the EEPROM driver as an XML description file according to SPI SWS.

Generation of SPI configuration data

As part of the SPI configuration described above, each SpiSequence, SpiJob and SpiChannel has been assigned a handle ID. Based on the XML file, an SPI include file will be generated which publishes this information.

#define Spi_EepReadSequence     10
#define Spi_EepReadJob          20
#define Spi_EepChCommand        31
#define Spi_EepChAddress        32
#define Spi_EepChReadData       33

SPI API usage

Upon receiving an Eep_Read() request, the EEPROM driver first needs to transfer the necessary information for executing the read command to the SPI handler/driver. It uses the Spi_WriteIB() function to set the device read address in the internal buffer allocated to the EepChAddress channel:

Spi_WriteIB(Spi_EepChAddress, &EepromAddress);

Next, the external buffer is set up for reading the EEPROM device data to:

Spi_SetupEB(Spi_EepChReadData, NULL, buf_data, length);

Finally, the Read sequence is initiated by calling Spi_AsyncTransmit:

Spi_AsyncTransmit(Spi_EepReadSequence);

After initiating the transfer, Eep_Read() returns.

The rest of the transfer is autonomously handled by the SPI handler/driver. Once the SPI sequence has finished, the SPI handler will notify the EEPROM driver using the callback Spi_SeqEndNotification. The EEPROM driver main function should ensure that either the sequence has finished successfully and in turn finish up the Eep_Read() request accordingly by signaling EepJobEndNotification; or upon reception of an error it should trigger an EepJobErrorNotification and report an EEP_E_READ_FAILED production error to the DEM.

AUTOSAR_SWS_EEPROMDriver

Specification of EEPROM Driver

Introduction and functional overview

Acronyms and Abbreviations

Related documentation

Input documents

Related specification

Constraints and assumptions

Limitations

Applicability to safety related environments

Dependencies to other modules

File structure

Requirements Tracing

Functional specification

General behavior

Error Classification

Development Errors

Runtime Errors

Extended Production Errors

EEP_E_ERASE_FAILED

EEP_E_WRITE_FAILED

EEP_E_READ_FAILED

EEP_E_COMPARE_FAILED

Error detection

API parameter checking

EEPROM state checking

EEPROM job encounters Hardware Failure

Timeout Supervision

Error notification

Processing of jobs - general requirements

Processing of read jobs

Processing of write jobs

Processing of erase jobs

Processing of compare jobs

Version check

API specification

Imported types

Type definitions

Eep_ConfigType

Eep_AddressType

Eep_LengthType

Function definitions

Eep_Init

Eep_SetMode

Eep_Read

Eep_Write

Eep_Erase

Eep_Compare

Eep_Cancel

Eep_GetStatus

Eep_GetJobResult

Eep_GetVersionInfo

Callback notifications

Scheduled functions

Eep_MainFunction

Expected interfaces

Mandatory interfaces

Optional interfaces

Configurable interfaces

End Job Notification

Error Job Notification

Sequence diagrams

Initialization

Read/write/erase/compare

Cancelation of a running job

Configuration specification

How to read this chapter

Containers and configuration parameters

Eep

EepGeneral

EepInitConfiguration

EepDemEventParameterRefs

EepExternalDriver

SPI specific extension

Published parameters

Basic subset

SPI specific extension

EepPublishedInformation

Configuration example - external SPI EEPROM device

External SPI EEPROM device usage scenario