AUTOSAR_SWS_FlashDriver

七月 03, 2025

Specification of Flash Driver

Introduction and functional overview

This specification describes the functionality, API and the configuration for the AUTOSAR Basic Software module [1] Flash Driver.

This specification is applicable to drivers for both internal and external flash memory.

The flash driver provides services for reading, writing and erasing flash memory and a configuration interface for setting / resetting the write / erase protection if supported by the underlying hardware.

In application mode of the ECU, the flash driver is only to be used by the Flash EEPROM emulation module for writing data. It is not intended to write program code to flash memory in application mode. This shall be done in boot mode which is out of scope of AUTOSAR.

A driver for an internal flash memory accesses the microcontroller hardware directly and is located in the Microcontroller Abstraction Layer. An external flash memory is usually connected via the microcontroller's data / address busses (memory mapped access), the flash driver then uses the handlers / drivers for those busses to access the external flash memory device. The driver for an external flash memory device is located in the ECU Abstraction Layer.

[SWS_Fls_00088]

[SRS_Fls_12147]

[SRS_Fls_12148]

The functional requirements [2] and the functional scope are the same for both internal and external drivers. Hence the API is semantically identical.

Acronyms and Abbreviations

The glossary below includes acronyms and abbreviations relevant to the Flash Driver module that are not included in the [3, AUTOSAR glossary].

Further definitions of terms used throughout this document

Constraints and assumptions

Limitations

The flash driver only erases or programs complete flash sectors respectively flash pages, i.e. it does not offer any kind of re-write strategy since it does not use any internal buffers.

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

Dependencies to other modules

System clock

If the hardware of the internal flash memory depends on the system clock, changes to the system clock (e.g. PLL on PLL off) may also affect the clock settings of the flash memory hardware [5].

Communication or I/O drivers

If the flash memory is located in an external device, the access to this device shall be enacted via the corresponding communication respectively I/O driver.

Requirements Tracing

The following tables reference the requirements specified in <CITATIONS_OF_CONTRIBUTED_DOCUMENTS> and links to the fulfillment of these. Please note that if column "Satisfied by" is empty for a specific requirement this means that this requirement is not fulfilled by this document.

Functional specification

General design rules

[SWS_Fls_00001]

[SRS_Fls_12134]

[SRS_Fls_12135]

[SRS_Fls_12136]

[SRS_Fls_13301]

The FLS module shall offer asynchronous services for operations on flash memory (read/erase/write).

[SWS_Fls_00002]

[SRS_Fls_12143]

The FLS module shall not buffer data. The FLS module shall use application data buffers that are referenced by a pointer passed via the API.

[SWS_Fls_00003]

[SRS_Fls_12143]

The FLS module shall not ensure data consistency of the given application buffer.

It is the responsibility of the FLS module's environment to ensure consistency of flash data during a flash read or write operation.

[SWS_Fls_00205]

[SRS_BSW_00323]

[SRS_BSW_00167]

[SRS_BSW_00004]

The FLS module shall check static configuration parameters statically (at the latest during compile time) for correctness.

[SWS_Fls_00206]

[SRS_BSW_00323]

[SRS_BSW_00167]

[SRS_BSW_00004]

The FLS module shall validate the version information in the FLS module header and source files for consistency (e.g. by comparing the version information in the module header and source files with a pre-processor macro).

[SWS_Fls_00208]

[SRS_Fls_12132]

The FLS module shall combine all available flash memory areas into one linear address space (denoted by the parameters FlsBaseAddress and FlsTotalSize).

[SWS_Fls_00209]

[SRS_Fls_12132]

[SRS_MemHwAb_14005]

The FLS module shall map the address and length parameters for the read, write, erase and compare functions as "virtual" addresses to the physical addresses according to the physical structure of the flash memory areas.

As long as the restrictions regarding the alignment of those addresses are met, it is allowed that a read, write or erase job crosses the boundaries of a physical flash memory area.

[SWS_Fls_00389]

[SRS_BSW_00483]

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

[SWS_Fls_00390]

[ ]

If more than one instance of the flash driver is used in an ECU, the individual instances have to be given a unique instance ID. This instance ID shall be configured as the parameter FlsDriverIndex. If only one instance of the flash driver is used in an ECU, this instance shall have the parameter FlsDriverIndex configured as 0.

External flash driver

[SWS_Fls_00144]

[SRS_Fls_12107]

During the initialization of the external flash driver, the FLS module shall check the hardware ID of the external flash device against the corresponding published parameter. If a hardware ID mismatch occurs, the FLS module shall report the error code FLS_E_UNEXPECTED_FLASH_ID to the Default Error Tracer (DET), set the FLS module status to FLS_E_UNINIT and shall not initialize itself.

A complete list of required parameters is specified in the SPI Handler/Driver Software Specification [6] (Chapter "Configuration Specification", marked as "SPI User").

Loading, executing and removing the flash access code

Technical background information: Flash technology or flash memory segmentation may require that the routines that access the flash hardware (internal erase and write routines) are executed from RAM because reading the flash - for instruction fetch needed for code execution - is not allowed while programming the flash.

[SWS_Fls_00137]

[SRS_Fls_12193]

The FLS module's implementer shall place the code of the flash access routines into a separate C-module Fls_ac.c.

[SWS_Fls_00215]

[SRS_Fls_12194]

The FLS module's flash access routines shall only disable interrupts and wait for the completion of the erase / write command if necessary (that is if it has to be ensured that no other code is executed in the meantime).

[SWS_Fls_00211]

[SRS_Fls_12194]

The FLS module's implementer shall keep the execution time for the flash access code as short as possible.

[SWS_Fls_00140]

[SRS_Fls_12193]

The FLS module's erase routine shall load the flash access code for erasing the flash memory to the location in RAM pointed to by the erase function pointer contained in the flash drivers configuration set if the FLS module is configured to load the flash access code to RAM on job start.

[SWS_Fls_00141]

[SRS_Fls_12193]

The FLS module's write routine shall load the flash access code for writing the flash memory to the location in RAM pointed to by the write function pointer contained in the flash drivers configuration set if the FLS module is configured to load the flash access code to RAM on job start.

[SWS_Fls_00212]

[SRS_Fls_12194]

The FLS module's main processing routine shall execute the flash access code routines.

[SWS_Fls_00213]

[SRS_Fls_12194]

The FLS module's main processing routine shall access the flash access code routines by means of the respective function pointer contained in the FLS module's configuration set (post-compile parameters) regardless whether the flash access code routines have been loaded to RAM or whether they can be executed directly from (flash) ROM.

[SWS_Fls_00143]

[SRS_Fls_13300]

After an erase or write job has been finished or canceled, the FLS module's main processing routine shall unload (i.e. overwrite) the flash access code (internal erase / write routines) from RAM if they have been loaded to RAM by the flash driver.

[SWS_Fls_00214]

[SRS_Fls_12193]

The FLS module shall only load the access code to the RAM if the access code cannot be executed out of flash ROM.

Error Classification

Section "Error Handling" of the document [4] "General Specification of Basic Software Modules" describes the error handling of the Basic Software in detail. Above all, it constitutes a classification scheme consisting of five error types which may occur in BSW modules.

Based on this foundation, the following section specifies particular errors arranged in the respective subsections below.

Development Errors

[SWS_Fls_00004]

[SRS_BSW_00385]

[SWS_Fls_00310]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The following development error codes shall be reported when an API service is called with a wrong parameter: FLS_E_PARAM_CONFIG, FLS_- E_PARAM_ADDRESS, FLS_E_PARAM_LENGTH, FLS_E_PARAM_DATA.

Runtime Errors

[SWS_Fls_91001]

[ ]

[SWS_Fls_00312]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The runtime error code FLS_E_BUSY shall be reported when an API service is called while the module is still busy.

[SWS_Fls_00313]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The runtime error code FLS_E_VERIFY_ERASE_FAILED shall be reported when the erase verification function is enabled (by the compile switch FlsEraseVerificationEnabled) and the erase verification function (blankcheck) failed.

[SWS_Fls_00314]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The runtime error code FLS_E_VERIFY_WRITE_FAILED shall be reported when the write verification function is enabled (by the compile switch FlsWriteVerificationEnabled) and the write verification function (compare) failed.

[SWS_Fls_00361]

[RS_BRF_01076]

The runtime error code FLS_E_TIMEOUT shall be reported when the timeout supervision function is enabled (by the compile switch FlsTimeoutSupervisionEnabled) and the timeout supervision of a read, write, erase or compare job (in hardware) failed.

Transient Faults

[SWS_Fls_91002]

[ ]

[SWS_Fls_00315]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The transient fault code FLS_E_ERASE_FAILED shall be reported when the flash erase function failed (in hardware).

[SWS_Fls_00316]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The transient fault code FLS_E_WRITE_FAILED shall be reported when the flash write function failed (in hardware).

[SWS_Fls_00317]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The transient fault code FLS_E_READ_FAILED shall be reported when the flash read function failed (in hardware).

[SWS_Fls_00318]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The transient fault code FLS_E_COMPARE_FAILED shall be reported when the flash compare function failed (in hardware).

[SWS_Fls_00319]

[SRS_BSW_00337]

[SRS_BSW_00385]

[SRS_BSW_00327]

[SRS_BSW_00331]

The transient fault code FLS_E_UNEXPECTED_FLASH_ID shall be reported when the expected flash ID is not matched (see [SWS_Fls_00144]).

API specification

Imported types

In this chapter all types included from the following files are listed.

[SWS_Fls_00248]

[SRS_BSW_00392]

Type definitions

Fls_ConfigType

[SWS_Fls_00368]

[SRS_BSW_00392]

Fls_AddressType

[SWS_Fls_00369]

[SRS_BSW_00392]

[SWS_Fls_00216]

[SRS_Fls_12132]

[SRS_MemHwAb_14005]

The type Fls_AddressType shall have 0 as lower limit for each flash device.

[SWS_Fls_00217]

[SRS_Fls_12132]

[SRS_MemHwAb_14005]

The FLS module shall add a device specific base address to the address type Fls_AddressType if necessary.

Fls_LengthType

[SWS_Fls_00370]

[SRS_BSW_00392]

Function definitions

Fls_Init

[SWS_Fls_00249]

[SRS_BSW_00101]

[SWS_Fls_00014]

[SRS_BSW_00404]

[SRS_BSW_00405]

[SRS_BSW_00101]

[SRS_SPAL_12057]

The function Fls_Init shall initialize the FLS module (software) and all flash memory relevant registers (hardware) with parameters provided in the given configuration set.

[SWS_Fls_00191]

[SRS_BSW_00101]

The function Fls_Init shall store the pointer to the given configuration set in a variable in order to allow the FLS module access to the configuration set contents during runtime.

[SWS_Fls_00086]

[SRS_BSW_00101]

The function Fls_Init shall initialize all FLS module global variables and those controller registers that are needed for controlling the flash device and that do not influence or depend on other (hardware) modules. Registers that can influence or depend on other modules shall be initialized by a common system module.

[SWS_Fls_00015]

[SRS_Fls_12143]

If development error detection for the module Fls is enabled: the function Fls_Init shall check the (hardware specific) contents of the given configuration set for being within the allowed range. If this is not the case, it shall raise the development error FLS_E_PARAM_CONFIG.

[SWS_Fls_00323]

[SRS_Fls_12143]

The function Fls_Init shall set the FLS module state to MEMIF_ IDLE after having finished the FLS module initialization.

[SWS_Fls_00324]

[SRS_BSW_00406]

The function Fls_Init shall set the flash job result to MEMIF_ JOB_OK after having finished the FLS module initialization.

[SWS_Fls_00268]

[SRS_Fls_12132]

If runtime error detection for the module Fls is enabled: the function Fls_Init shall check module initialization status. If the module has already been initialized, the function Fls_Init shall raise the development error FLS_E_ALREADY_INITIALIZED.

[SWS_Fls_00048]

[SRS_Fls_12132]

If supported by hardware, the function Fls_Init shall set the flash memory erase/write protection as provided in the configuration set.

Fls_Erase

[SWS_Fls_00250]

[SRS_Fls_12136]

[SWS_Fls_00218]

[SRS_Fls_12136]

The job of the function Fls_Erase shall erase one or more complete flash sectors.

[SWS_Fls_00327]

[SRS_Fls_12136]

The function Fls_Erase shall copy the given parameters to FLS module internal variables and initiate an erase job.

[SWS_Fls_00328]

[SRS_Fls_12136]

After initiating the erase job, the function Fls_Erase shall set the FLS module status to MEMIF_BUSY.

[SWS_Fls_00329]

[SRS_Fls_12136]

After initiating the erase job, the function Fls_Erase shall set the job result to MEMIF_JOB_PENDING.

[SWS_Fls_00330]

[SRS_Fls_12136]

After initiating the erase job, the function Fls_Erase shall return with E_OK.

[SWS_Fls_00220]

[SRS_Fls_12136]

[SRS_Fls_12144]

The FLS module shall execute the job of the function Fls_Erase asynchronously within the FLS module's main function.

[SWS_Fls_00221]

[SRS_Fls_12136]

The job of the function Fls_Erase shall erase a flash memory block starting from the flash memory base address + TargetAddress of size Length.

Note:

Length will be rounded up to the next full sector boundary since only complete flash sectors can be erased.

[SWS_Fls_00020]

[SRS_BSW_00323]

[SRS_Fls_12136]

[SRS_Fls_12159]

If development error detection for the module Fls is enabled: the function Fls_Erase shall check that the erase start address (flash memory base address + TargetAddress) is aligned to a flash sector boundary and that it lies within the specified lower and upper flash address boundaries. If this check fails, the function Fls_Erase shall reject the erase request, raise the development error FLS_E_PARAM_ADDRESS and return with E_NOT_OK.

[SWS_Fls_00021]

[SRS_BSW_00323]

[SRS_Fls_12136]

[SRS_Fls_12159]

If development error detection for the module Fls is enabled: the function Fls_Erase shall check that the erase length is greater than 0 and that the erase end address (erase start address + length) is aligned to a flash sector boundary and that it lies within the specified upper flash address boundary. If this check fails, the function Fls_Erase shall reject the erase request, raise the development error FLS_E_PARAM_LENGTH and return with E_NOT_OK.

[SWS_Fls_00065]

[SRS_BSW_00406]

If development error detection for the module Fls is enabled: the function Fls_Erase shall check that the FLS module has been initialized. If this check fails, the function Fls_Erase shall reject the erase request, raise the development error FLS_E_UNINIT and return with E_NOT_OK.

[SWS_Fls_00023]

[SRS_Fls_12143]

If runtime error detection for the module Fls is enabled: the function Fls_Erase shall check that the FLS module is currently not busy. If this check fails, the function Fls_Erase shall reject the erase request, raise the development error FLS_E_BUSY and return with E_NOT_OK.

[SWS_Fls_00145]

[SRS_Fls_12136]

If possible, e.g. with interrupt controlled implementations, the FLS module shall start the first round of the erase job directly within the function Fls_Erase to reduce overall runtime.

Fls_Write

[SWS_Fls_00251]

[SRS_Fls_12135]

[SWS_Fls_00223]

[SRS_Fls_12135]

The job of the function Fls_Write shall write one or more complete flash pages to the flash device.

[SWS_Fls_00331]

[SRS_Fls_12135]

The function Fls_Write shall copy the given parameters to Fls module internal variables and initiate a write job.

[SWS_Fls_00332]

[SRS_Fls_12135]

After initiating the write job, the function Fls_Write shall set the FLS module status to MEMIF_BUSY.

[SWS_Fls_00333]

[SRS_Fls_12135]

After initiating the write job, the function Fls_Write shall set the job result to MEMIF_JOB_PENDING.

[SWS_Fls_00334]

[SRS_Fls_12135]

After initiating the write job, the function Fls_Write shall return with E_OK.

[SWS_Fls_00225]

[SRS_Fls_12135]

[SRS_Fls_12144]

The FLS module shall execute the write job of the function Fls_Write asynchronously within the FLS module's main function.

[SWS_Fls_00226]

[SRS_Fls_12135]

The job of the function Fls_Write shall program a flash memory block with data provided via SourceAddressPtr starting from the flash memory base address + TargetAddress of size Length.

[SWS_Fls_00026]

[SRS_BSW_00323]

[SRS_Fls_12135]

[SRS_Fls_12159]

If development error detection for the module Fls is enabled: the function Fls_Write shall check that the write start address (flash memory base address + TargetAddress) is aligned to a flash page boundary and that it lies within the specified lower and upper flash address boundaries. If this check fails, the function Fls_Write shall reject the write request, raise the development error FLS_E_PARAM_ADDRESS and return with E_NOT_OK.

[SWS_Fls_00027]

[SRS_BSW_00323]

[SRS_Fls_12135]

[SRS_Fls_12159]

If development error detection for the module Fls is enabled: the function Fls_Write shall check that the write length is greater than 0, that the write end address (write start address + length) is aligned to a flash page boundary and that it lies within the specified upper flash address boundary. If this check fails, the function Fls_Write shall reject the write request, raise the development error FLS_E_PARAM_LENGTH and return with E_NOT_OK.

[SWS_Fls_00066]

[SRS_BSW_00406]

If development error detection for the module Fls is enabled: the function Fls_Write shall check that the FLS module has been initialized. If this check fails, the function Fls_Write shall reject the write request, raise the development error FLS_E_UNINIT and return with E_NOT_OK.

[SWS_Fls_00030]

[SRS_Fls_12143]

If runtime error detection for the module Fls is enabled: the function Fls_Write shall check that the FLS module is currently not busy. If this check fails, the function Fls_Write shall reject the write request, raise the development error FLS_E_BUSY and return with E_NOT_OK.

[SWS_Fls_00157]

[SRS_BSW_00323]

If development error detection for the module Fls is enabled: the function Fls_Write shall check the given data buffer pointer for not being a null pointer. If the data buffer pointer is a null pointer, the function Fls_Write shall reject the write request, raise the development error FLS_E_PARAM_DATA and return with E_NOT_OK.

[SWS_Fls_00146]

[SRS_Fls_12135]

If possible, e.g. with interrupt controlled implementations, the FLS module shall start the first round of the write job directly within the function Fls_Write to reduce overall runtime.

Fls_Cancel

[SWS_Fls_00252]

[SRS_Fls_12137]

[SWS_Fls_00229]

[SRS_Fls_12137]

The function Fls_Cancel shall cancel an ongoing flash read, write, erase or compare job.

[SWS_Fls_00230]

[SRS_Fls_12137]

The function Fls_Cancel shall abort a running job synchronously so that directly after returning from this function a new job can be started.

Note:

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

[SWS_Fls_00335]

[SRS_Fls_12137]

The function Fls_Cancel shall reset the FLS module's internal job processing variables (like address, length and data pointer).

[SWS_Fls_00336]

[SRS_Fls_12137]

The function Fls_Cancel shall set the FLS module state to MEMIF_IDLE.

[SWS_Fls_00033]

[SRS_Fls_12137]

[SRS_Fls_12143]

The function Fls_Cancel shall set the job result to MEMIF_JOB_ CANCELED if the job result currently has the value MEMIF_JOB_PENDING. Otherwise the function Fls_Cancel shall leave the job result unchanged.

[SWS_Fls_00147]

[RS_BRF_01064]

If configured, the function Fls_Cancel shall call the error notification function to inform the caller about the cancellation of a job.

Note:

The content of the affected flash memory cells will be undefined when canceling an ongoing job with the function Fls_Cancel.

[SWS_Fls_00183]

[SRS_BSW_00171]

[SRS_Fls_12137]

The function Fls_Cancel shall be pre-compile time configurable On/Off by the configuration parameter FlsCancelApi.

[SWS_Fls_00356]

[SRS_BSW_00406]

If development error detection for the module Fls is enabled: the function Fls_Cancel shall check that the FLS module has been initialized. If this check fails, the function Fls_Cancel shall raise the development error FLS_E_UNINIT and return.

Fls_GetStatus

[SWS_Fls_00253]

[SRS_Fls_12138]

[SWS_Fls_00034]

[SRS_Fls_12138]

The function Fls_GetStatus shall return the FLS module state synchronously.

[SWS_Fls_00184]

[SRS_Fls_12138]

[SRS_BSW_00171]

The function Fls_GetStatus shall be pre-compile time configurable On/Off by the configuration parameter FlsGetStatusApi.

Note:

The function Fls_GetStatus may be called before the module has been initialized in which case it shall return MEMIF_UNINIT.

Fls_GetJobResult

[SWS_Fls_00254]

[SRS_Fls_12134]

[SRS_Fls_12135]

[SRS_Fls_12136]

[SRS_Fls_12137]

[SWS_Fls_00035]

[SRS_Fls_12134]

[SRS_Fls_12135]

[SRS_Fls_12136]

[SRS_Fls_12137]

The function Fls_GetJobResult shall return the result of the last job synchronously

[SWS_Fls_00036]

[SRS_Fls_12143]

The erase, write, read and compare functions shall share the same job result, i.e. only the result of the last job can be queried. The FLS module shall overwrite the job result with MEMIF_JOB_PENDING if the FLS module has accepted a new job.

[SWS_Fls_00185]

[SRS_BSW_00171]

The function Fls_GetJobResult shall be pre-compile time configurable On/Off by the configuration parameter FlsGetJobResultApi.

[SWS_Fls_00358]

[SRS_BSW_00406]

If development error detection for the module Fls is enabled: the function Fls_GetJobResult shall check that the FLS module has been initialized. If this check fails, the function Fls_GetJobResult shall raise the development error FLS_E_UNINIT and return with MEMIF_JOB_FAILED.

Fls_Read

[SWS_Fls_00256]

[SRS_Fls_12134]

[SWS_Fls_00236]

[SRS_Fls_12134]

The function Fls_Read shall read from flash memory.

[SWS_Fls_00337]

[SRS_Fls_12134]

The function Fls_Read shall copy the given parameters to FLS module internal variables and initiate a read job.

[SWS_Fls_00338]

[SRS_Fls_12134]

After initiating a read job, the function Fls_Read shall set the FLS module status to MEMIF_BUSY.

[SWS_Fls_00339]

[SRS_Fls_12134]

After initiating a read job, the function Fls_Read shall set the FLS module job result to MEMIF_JOB_PENDING.

[SWS_Fls_00340]

[SRS_Fls_12134]

After initiating a read job, the function Fls_Read shall return with E_OK.

[SWS_Fls_00238]

[SRS_Fls_12134]

[SRS_Fls_12144]

The FLS module shall execute the read job of the function Fls_Read asynchronously within the FLS module's main function.

[SWS_Fls_00239]

[SRS_Fls_12134]

The read job of the function Fls_Read shall copy a continuous flash memory block starting from the flash memory base address + SourceAddress of size Length to the buffer pointed to by TargetAddressPtr.

[SWS_Fls_00097]

[SRS_BSW_00323]

[SRS_Fls_12134]

[SRS_Fls_12159]

If development error detection for the module Fls is enabled: the function Fls_Read shall check that the read start address (flash memory base address + SourceAddress) lies within the specified lower and upper flash address boundaries. If this check fails, the function Fls_Read shall reject the read job, raise development error FLS_E_PARAM_ADDRESS and return with E_NOT_OK.

[SWS_Fls_00098]

[SRS_BSW_00323]

[SRS_Fls_12134]

[SRS_Fls_12159]

If development error detection for the module Fls is enabled: the function Fls_Read shall check that the read length is greater than 0 and that the read end address (read start address + length) lies within the specified upper flash address boundary. If this check fails, the function Fls_Read shall reject the read job, raise the development error FLS_E_PARAM_LENGTH and return with E_NOT_OK.

[SWS_Fls_00099]

[SRS_BSW_00406]

If development error detection for the module Fls is enabled: the function Fls_Read shall check that the driver has been initialized. If this check fails, the function Fls_Read shall reject the read request, raise the development error FLS_E_UNINIT and return with E_NOT_OK.

[SWS_Fls_00100]

[SRS_Fls_12143]

If runtime error detection for the module Fls is enabled: the function Fls_Read shall check that the driver is currently not busy. If this check fails, the function Fls_Read shall reject the read request, raise the development error FLS_E_BUSY and return with E_NOT_OK.

[SWS_Fls_00158]

[SRS_BSW_00323]

If development error detection for the module Fls is enabled: the function Fls_Read shall check the given data buffer pointer for not being a null pointer. If the data buffer pointer is a null pointer, the function Fls_Read shall reject the read request, raise the development error FLS_E_PARAM_DATA and return with E_NOT_ OK.

[SWS_Fls_00240]

[SRS_BSW_00406]

The FLS module's environment shall only call the function Fls_Read after the FLS module has been initialized.

Fls_Compare

[SWS_Fls_00257]

[SRS_Fls_13301]

[SWS_Fls_00241]

[SRS_Fls_13301]

The function Fls_Compare shall compare the contents of an area of flash memory with that of an application data buffer.

[SWS_Fls_00341]

[SRS_Fls_13301]

The function Fls_Compare shall copy the given parameters to Fls module internal variables and initiate a compare job.

[SWS_Fls_00342]

[SRS_Fls_13301]

After initiating the compare job, the function Fls_Compare shall set the status to MEMIF_BUSY.

[SWS_Fls_00343]

[SRS_Fls_13301]

After initiating the compare job, the function Fls_Compare shall set the job result to MEMIF_JOB_PENDING.

[SWS_Fls_00344]

[SRS_Fls_13301]

After initiating the compare job, the function Fls_Compare shall return with E_OK.

[SWS_Fls_00243]

[SRS_Fls_13301]

[SRS_Fls_12144]

The FLS module shall execute the job of the function Fls_Compare asynchronously within the FLS module's main function.

[SWS_Fls_00244]

[SRS_Fls_13301]

The job of the function Fls_Compare shall compare a continuous flash memory block starting from the flash memory base address + SourceAddress of size Length with the buffer pointed to by TargetAddressPtr.

[SWS_Fls_00150]

[SRS_Fls_13301]

If development error detection for the module Fls is enabled: the function Fls_Compare shall check that the compare start address (flash memory base address + SourceAddress) lies within the specified lower and upper flash address boundaries. If this check fails, the function Fls_Compare shall reject the compare job, raise the development error FLS_E_PARAM_ADDRESS and return with E_NOT_OK.

[SWS_Fls_00151]

[SRS_Fls_13301]

If If development error detection for the module Fls is enabled: the function Fls_Compare shall check that the given length is greater than 0 and that the compare end address (compare start address + length) lies within the specified upper flash address boundary. If this check fails, the function Fls_Compare shall reject the compare job, raise the development error FLS_E_PARAM_LENGTH and return with E_ NOT_OK.

[SWS_Fls_00152]

[SRS_Fls_13301]

If development error detection for the module Fls is enabled: the function Fls_Compare shall check that the driver has been initialized. If this check fails, the function Fls_Compare shall reject the compare job, raise the development error FLS_E_UNINIT and return with E_NOT_OK.

[SWS_Fls_00153]

[SRS_Fls_13301]

If runtime error detection for the module Fls is enabled: the function Fls_Compare shall check that the driver is currently not busy. If this check fails, the function Fls_Compare shall reject the compare job, raise the development error FLS_E_BUSY and return with E_NOT_OK.

[SWS_Fls_00273]

[RS_BRF_01064]

If development error detection for the module Fls is enabled: the function Fls_Compare shall check the given data buffer pointer for not being a null pointer. If the data buffer pointer is a null pointer, the function Fls_Compare shall reject the request, raise the development error FLS_E_PARAM_DATA and return with E_NOT_OK.

[SWS_Fls_00186]

[SRS_BSW_00171]

[SRS_Fls_13301]

The function Fls_Compare shall be pre-compile time configurable On/Off by the configuration parameter FlsCompareApi.

Fls_SetMode

[SWS_Fls_00258]

[SRS_Fls_13302]

[SWS_Fls_00155]

[SRS_Fls_13302]

The function Fls_SetMode shall set the FLS module's operation mode to the given "Mode" parameter.

[SWS_Fls_00156]

[SRS_Fls_13302]

If runtime error detection for the module Fls is enabled: the function Fls_SetMode shall check that the FLS module is currently not busy. If this check fails, the function Fls_SetMode shall reject the set mode request and raise the development error code FLS_E_BUSY.

[SWS_Fls_00187]

[SRS_BSW_00171]

[SRS_Fls_13302]

The function Fls_SetMode shall be pre-compile time configurable On/Off by the configuration parameter FlsSetModeApi.

Fls_GetVersionInfo

[SWS_Fls_00259]

[SRS_BSW_00407]

[SWS_Fls_00363]

[SRS_BSW_00323]

If development error detection for the module Fls is enabled: the function Fls_GetVersionInfo shall raise the development error FLS_E_PARAM_POINTER if the argument is a NULL pointer and return without any action.

Fls_BlankCheck

[SWS_Fls_00371]

[RS_BRF_01076]

[SWS_Fls_00373]

[RS_BRF_01076]

The function Fls_BlankCheck shall verify, whether a given memory area has been erased but not (yet) re-programmed.

[SWS_Fls_00374]

[SRS_Fls_12144]

The function Fls_BlankCheck shall copy the given parameters to FLS module internal variables and initiate the verification job.

[SWS_Fls_00375]

[SRS_Fls_12144]

After initiating the verification job, the function Fls_BlankCheck shall set the FLS module status to MEMIF_BUSY.

[SWS_Fls_00376]

[SRS_Fls_12144]

After initiating the verification job, the function Fls_BlankCheck shall set the FLS module job result to MEMIF_JOB_PENDING.

[SWS_Fls_00377]

[SRS_Fls_12144]

After initiating the verification job, the function Fls_BlankCheck shall return with E_OK.

[SWS_Fls_00378]

[SRS_Fls_12144]

The FLS module shall execute the verification job of the function Fls_BlankCheck asynchronously within the FLS module's main function.

[SWS_Fls_00379]

[SRS_Fls_12144]

The verification job of the function Fls_BlankCheck shall check, that the continuous flash memory area starting from the flash memory base address + TargetAddress of size Length is erased.

[SWS_Fls_00380]

[SRS_Fls_12159]

If development error detection for the module FLS is enabled; the function Fls_BlankCheck shall check that the verification start address (flash memory base address + TargetAddress) lies within the specified lower and upper flash address boundaries. If this check fails, the function Fls_BlankCheck shall reject the verification job, raise the development error FLS_E_PARAM_ADDRESS and return with E_NOT_OK.

[SWS_Fls_00381]

[SRS_Fls_12159]

If development error detection for the module FLS is enabled: the function Fls_BlankCheck shall check that the given length is greater than 0 and that the verification end address (verification start address + length) lies within the specified upper flash address boundary. If this check fails, the function Fls_BlankCheck shall reject the verification job, raise the development error FLS_E_PARAM_LENGTH and return with E_NOT_OK.

[SWS_Fls_00382]

[SRS_BSW_00406]

If development error detection for the module FLS is enabled: the function Fls_BlankCheck shall check that the driver has been initialized. If this check fails, the function Fls_BlankCheck shall reject the verification request, raise the development error FLS_E_UNINIT and return with E_NOT_OK.

[SWS_Fls_00383]

[SRS_BSW_00406]

If runtime error detection for the module FLS is enabled: the function Fls_BlankCheck shall check that the driver is currently not busy. If this check fails, the function Fls_BlankCheck shall reject the verification request, raise the development error FLS_E_BUSY and return with E_NOT_OK.

Callback notifications

This is a list of functions provided for other modules.

Note:

There are no callback functions to lower layer modules provided by the Flash Driver since this module is at the lowest (software) layer [7].

[SWS_Fls_00193]

[SRS_BSW_00164]

[SRS_BSW_00325]

Depending on implementation, callback routines provided and/or invoked by the FLS module may be called on interrupt level. The module providing those routines has therefore to make sure that their runtime is reasonably short, i.e. since callbacks may be propagated upward through several software layers.

Scheduled functions

This chapter lists all functions provided by the Fls module and called directly by the Basic Software Module Scheduler. The following functions shall have no return value and no paramete. All functions shall be non reentrant.

[SWS_Fls_00269]

[SRS_BSW_00432]

The Fls module shall provide only one scheduled function. Reading from / writing to flash memory cannot usually be done simultaneously and the overhead for synchronizing two scheduled functions would outweigh the benefits.

Fls_MainFunction

[SWS_Fls_00255]

[SRS_Fls_12144]

[SWS_Fls_00037]

[SRS_Fls_12144]

The function Fls_MainFunction shall perform the processing of the flash read, write, erase and compare jobs.

[SWS_Fls_00038]

[SRS_Fls_12144]

When a job has been initiated, the FLS module's environment shall call the function Fls_MainFunction cyclically until the job is finished.

Note:

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

[SWS_Fls_00039]

[SRS_Fls_12144]

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

[SWS_Fls_00040]

[SRS_Fls_13303]

[SRS_Fls_13304]

[SRS_Fls_12145]

[SRS_Fls_12184]

The function Fls_MainFunction shall only process as much data in one call cycle as statically configured for the current job type (read, write or compare) and the current FLS module's operating mode (normal, fast).

[SWS_Fls_00104]

[SRS_BSW_00339]

[SRS_BSW_00385]

[SRS_BSW_00466]

The function Fls_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code FLS_E_ERASE_FAILED to the DET if a flash erase job fails due to a hardware error.

[SWS_Fls_00105]

[SRS_BSW_00339]

[SRS_BSW_00385]

[SRS_BSW_00466]

The function Fls_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code FLS_E_WRITE_FAILED to the DET if a flash write job fails due to a hardware error.

[SWS_Fls_00106]

[SRS_BSW_00339]

[SRS_BSW_00385]

[SRS_BSW_00466]

The function Fls_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code FLS_E_READ_FAILED to the DET if a flash read job fails due to a hardware error.

[SWS_Fls_00154]

[SRS_BSW_00339]

[SRS_BSW_00385]

[SRS_BSW_00466]

The function Fls_MainFunction shall set the job result to MEMIF_JOB_FAILED and report the error code FLS_E_COMPARE_FAILED to the DET if a flash compare job fails due to a hardware error.

[SWS_Fls_00385]

[SRS_Fls_12135]

[SRS_Fls_12159]

If the underlying flash 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 Fls_MainFunction shall internally compensate for this missing alignment, that is the function Fls_MainFunction shall provide byte-wise read access to the flash memory, regardless of any alignment restrictions imposed by the Hardware.

[SWS_Fls_00200]

[SRS_Fls_12141]

The function Fls_MainFunction shall set the job result to MEMIF_BLOCK_INCONSISTENT if the compared data from a flash compare job are not equal.

[SWS_Fls_00022]

[SRS_Fls_12160]

If erase verification is enabled (compile switch FlsEraseVerificationEnabled set to TRUE): After a flash block has been erased, the function Fls_MainFunction shall compare the contents of the addressed memory area against the value of an erased flash cell to check that the block has been completely erased. If this check fails, the function Fls_MainFunction shall set the FLS module's job result to MEMIF_JOB_FAILED and raise the runtime error FLS_E_VERIFY_ERASE_FAILED.

[SWS_Fls_00055]

[SRS_Fls_12141]

If erase verification is enabled (compile switch FlsEraseVerificationEnabled set to TRUE): Before writing a flash block, the function Fls_MainFunction shall compare the contents of the addressed memory area against the value of an erased flash cell to check that the block has been completely erased. If this check fails, the function Fls_MainFunction shall set the FLS module's job result to MEMIF_JOB_FAILED and raise the runtime error FLS_E_VERIFY_ERASE_FAILED.c (SRS_Fls_12158)

[SWS_Fls_00056]

[SRS_Fls_12144]

If write verification is enabled (compile switch FlsWriteVerificationEnabled set to TRUE): After writing a flash block, the function Fls_MainFunction shall compare the contents of the reprogrammed memory area against the contents of the provided application buffer to check that the block has been completely reprogrammed. If this check fails, the function Fls_MainFunction shall set the FLS module's job result to MEMIF_JOB_FAILED and raise the runtime error FLS_E_VERIFY_WRITE_FAILED.

[SWS_Fls_00345]

[SRS_Fls_12144]

After a read, erase, write or compare job has been finished, the function Fls_MainFunction shall set the FLS module's job result to MEMIF_JOB_ OK if it is currently in state MEMIF_JOB_PENDING. Otherwise, it shall leave the result unchanged.

[SWS_Fls_00346]

[SRS_BSW_00164]

After a read, erase, write or compare job has been finished, the function Fls_MainFunction shall set the FLS module's state to MEMIF_IDLE and call the job end notification function if configured (see [ECUC_Fls_00307]).

[SWS_Fls_00232]

[RS_BRF_01144]

The configuration parameter FlsUseInterrupts shall switch between interrupt and polling controlled job processing if this is supported by the flash memory hardware.

[SWS_Fls_00233]

[RS_BRF_01144]

The FLS module's implementer shall locate the interrupt service routine in Fls_Irq.c.

[SWS_Fls_00234]

[SRS_Fls_12144]

If interrupt controlled job processing is supported and enabled with the configuration parameter FlsUseInterrupts, the interrupt service routine shall reset the interrupt flag, check for errors reported by the underlying hardware, reload the hardware finite state machine for the next round of the pending job or call the appropriate notification routine if the job is finished or aborted.

[SWS_Fls_00235]

[SRS_Fls_12144]

[RS_BRF_01076]

The function Fls_MainFunction shall process jobs without hardware interrupt support (e.g. read jobs).

[SWS_Fls_00272]

[SRS_Fls_12144]

[RS_BRF_01076]

If timeout supervision is enabled (compile switch FlsTimeoutSupervisionEnabled set to TRUE): the function Fls_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_Fls_00359]

[RS_BRF_01076]

If timeout supervision is enabled (compile switch FlsTimeoutSupervisionEnabled set to TRUE): the function Fls_MainFunction shall check, whether the configured maximum erase time (see [ECUC_Fls_00298] FlsEraseTime) has been exceeded. If this is the case, the function Fls_MainFunction shall raise the runtime error FLS_E_TIMEOUT.

[SWS_Fls_00360]

[RS_BRF_01076]

If timeout supervision is enabled (compile switch FlsTimeoutSupervisionEnabled set to TRUE): the function Fls_MainFunction shall check, whether the expected maximum write time (see note below) has been exceeded. If this is the case, the function Fls_MainFunction shall raise the runtime error FLS_E_TIMEOUT.

Note:

The expected maximum write time depends on the current mode of the Fls module (see [SWS_Fls_00258]), the configured number of bytes to write in this mode (see [ECUC_Fls_00278] and [ECUC_Fls_00277] respectively), the size of a single flash page (see [ECUC_Fls_00281]) and last the maximum time to write one flash page (see [ECUC_Fls_00301]). The number of bytes to write divided by the size of one flash page yields the number of pages to write in one cycle. This multiplied with the maximum write time for one flash page gives you the expected maximum write time.

[SWS_Fls_00362]

[RS_BRF_01076]

If timeout supervision is enabled (compile switch FlsTimeoutSupervisionEnabled set to TRUE): the function Fls_MainFunction shall check, whether the expected maximum read / compare time (see note below) has been exceeded. If this is the case, the function Fls_MainFunction shall raise the runtime error FLS_E_TIMEOUT.

Note:

There are no published timings for read / compare (these would mostly depend on whether the flash device is internal or external e.g. connected via SPI). The solution would be similar as 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 Fls_MainFunction. If this is not detailed enough there are two possibilities:

specify expected read / compare times (difficult because of the dependency mentioned above)

leave read / compare jobs out of the timeout supervision (change [SWS_Fls_00272]).

[SWS_Fls_00196]

[SRS_Fls_12144]

The function Fls_MainFunction shall at the most issue one sector erase command (to the hardware) in each cycle.

Note:

The requirement above shall ensure that maximum one sector is erased sequentially within one cycle of the driver's main function. If the hardware is capable of erasing more than one sector in parallel, this shall not be restricted by this specification.

Expected interfaces

In this chapter all interfaces required from other modules are listed.

Mandatory interfaces

Note:

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

[SWS_Fls_00260]

[SRS_BSW_00469]

[SRS_BSW_00339]

Note:

If the flash device is connected via SPI, also the SPI interfaces [6] are required to fulfill the modules core functionality. Which interfaces are needed exactly shall not be detailed further in this specification.

Optional interfaces

This section defines all interfaces, which are required to fulfill an optional functionality of the module.

[SWS_Fls_00261]

[ ]

Configurable interfaces

In this section, all interfaces are listed where the target function could be configured. The target function is usually a callback function. The names of this kind of interfaces are not fixed because they are configurable.

[SWS_Fls_00110]

[RS_BRF_01064]

The callback notifications shall have no parameters and no return value.

[SWS_Fls_00262]

[RS_BRF_01064]

[SWS_Fls_00167]

[RS_BRF_01064]

The FLS module shall call the callback function Fee_JobEndNotification when the module has completed a job with a positive result:

Read job finished & OK

Write job finished & OK

Erase job finished & OK

Compare job finished & memory blocks are the same

[SWS_Fls_00263]

[RS_BRF_01064]

[SWS_Fls_00347]

[RS_BRF_01064]

The FLS module shall call the callback function Fee_JobErrorNotification when the module has finished a job with a negative result:

Read job failed

Write job failed

Erase job failed

Compare job failed

[SWS_Fls_00348]

[RS_BRF_01064]

The FLS module shall call the callback function Fee_JobErrorNotification when the module has canceled an ongoing job:

Read job aborted

Write job aborted

Erase job aborted

Compare job aborted

[SWS_Fls_00349]

[RS_BRF_01064]

The FLS module shall call the callback function Fee_JobErrorNotification when the module has finished a compare job and the memory blocks differ:

Compare job finished and memory blocks differ.

Sequence diagrams

Initialization

Synchronous functions

The following sequence diagram shows the function Fls_GetJobResult as an example for the synchronous functions of this module. The same sequence applies also to the functions Fls_GetStatus and Fls_SetMode.

Asynchronous functions

The following sequence diagram shows the flash write function (with the configuration option FlsAcLoadOnJobStart set) as an example for the asynchronous functions of this module. The same sequence applies to the erase, read and compare jobs, with the only difference that for the read and compare jobs no flash access code needs to be loaded to / unloaded from RAM.

Canceling a running job

Note:

The FLS module's environment shall not call the function Fls_Cancel during a running Fls_MainFunction invocation.

This can be achieved by one of the following scheduling configurations:

Possibility 1: The job functions of the NVRAM manager and the flash driver are synchronized (e.g. called sequentially within one task)

Possibility 2: The task that calls the Fls_MainFunction function can not be preempted by another task.

Configuration specification

In general, this chapter defines configuration parameters and their clustering into containers. In order to support the specification Chapter 10.1 describes fundamentals. It also specifies a template (table) you shall use for the parameter specification. We intend to leave Chapter 10.1 in the specification to guarantee comprehension.

Chapter 10.2 specifies the structure (containers) and the parameters of the module Fls.

Chapter 10.3 specifies published information of the module Fls.