4.10. FLS¶
4.10.1. About This Document¶
Document Title |
User Guide of MCAL FLS Driver |
Document Version |
Version 1.2 |
Company |
Texas Instruments |
Document Name |
AUTOSAR FLS User Guide |
4.10.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
26 April 2022 |
Initial Version |
Approved |
Version 1.1 |
30 June 2022 |
Version |
Approved |
Version 1.2 |
15 Sep 2023 |
Configuration parameters updated |
Approved |
4.10.3. Table of contents¶
4.10.4. Acronyms and Definitions¶
Acronyms and Definitions used are presented in below table.
Acronyms |
Descriptions |
|---|---|
BSW |
Basic Software |
DET |
Default Error Tracer |
FLS |
Flash Driver |
MCU |
Micro Controller Unit |
OS |
Operating System |
API |
Application Programming Interface |
HW |
Hardware |
SW |
Software |
4.10.5. Functional Overview¶
4.10.5.1. Brief Overview¶
This document describes MCAL FLS Driver functionality, its application interfaces and configuration details as per AUTOSAR version 4.3.1 .
Supported AUTOSAR Release |
4.3.1 |
Supported Configuration Variants |
Pre-Compile, Post-build |
Vendor ID |
FLS_VENDOR_ID (44) |
Module ID |
FLS_MODULE_ID (92) |
Supported Platform |
AM273x |
The Flash Driver provides services for reading, writing, erasing flash memory for external Flash device.
4.10.5.1.1. FLS Driver Architecture¶
The FLS driver has architecture as shown in below figure from the AUTOSAR specification.
Figure 1: FLS in AUTOSAR architecture.
The below figure shows typical connection of the QSPI module to the external quad-SPI flash memory
Figure_2: QSPI connected to an external Quad SPI flash memory
4.10.5.1.2. Initialization¶
The driver FLS is initialized by calling Fls_Init() function and takes FlsConfigSet as input and Initializes Flash and QSPI. This will also make driver status to IDLE.
4.10.5.1.3. States¶
The Fls driver maintains states for:
MEMIF_UNINIT -> This is the state when hardware is not initialized.
MEMIF_IDLE -> when FLS driver initialized, it will go to IDLE state.
MEMIF_BUSY: In case of any on-going operation i.e., Erase OR read OR write, the state will be maintained as busy until the operation is completed.
MEMIF_BUSY_INTERNAL is not supported.
4.10.5.2. Features Supported and Not Supported¶
AUTOSAR features:
Supported |
Not Supported |
|---|---|
Only one QSPI instance will support |
Only one instance of Fls module supported at one time. |
Perform storage mode applications
|
Access To Address beyond 8MB is not supported in MemMap mode. |
Configure error detection (DET) |
DMA mode not supported |
Only normal mode is supported. |
Relevant features not supported
|
4.10.5.3. IP Specific features:¶
None
4.10.5.4. Assumptions¶
None
4.10.5.5. Limitations¶
Only 1S-1S-4S mode is supported for QSPI.
4.10.5.6. Design overview (Link to the Architecture document and Design Document)¶
Will be available in future release.
4.10.5.7. File Structure¶
Description of static files is provided below:
Static source and header files |
Description |
|---|---|
Fls.c |
Contains the pre-complier switches. |
Fls.h |
Contains the APIs of the FLS driver to be used by upper layers. |
Fls_Irq.h |
Contains ISR function definitions |
Fls_Cfg.c |
Contains device specific a function definition, data types and definations. |
Fls_NOR_<flash_device>.h |
Contains device specific configuration parameters. |
Fls_Brd_Nor_Qspi.c |
Contains internal functions and data structures. |
Fls_Qspi.c |
Contains internal functions and data structures. |
Fls_Brd_Nor.h |
Contains internal functions and data structures. |
Fls_Qspi.h |
Contains internal functions and data structures. |
Description of generated files is provided below:
Plugin Files |
Descriptions |
|---|---|
Fls_Cfg.h |
Contains the pre-complier switches. |
Fls_PBcfg.c |
Contains all Post-Build Configured parameters. |
Fls_Cfg.c |
Contains all Pre-Compile Configured parameters. |
Figure 4: FLS header file include structure
4.10.6. Deviations to requirements (Requirement Traceability)¶
4.10.6.1. Module Requirements¶
Will be updated in future release
4.10.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.10.7. Integration Details¶
4.10.7.1. Dependency on Other Software Modules¶
4.10.7.1.1. The FLS Driver dependent modules¶
4.10.7.1.1.1. MCU¶
The Fls Modules expects the MCU modules to enable the QSPI clock through the configuration. Required parameter for clock enabling:
Module ID: MCU_CLKSRC_MODULE_ID_QSPI
Source ID: MCU_CLKSRC_4
Divider value: 4
4.10.7.1.2. PORT¶
The Fls Modules expects that pinmux is set correctly to configure the Data line, Chip select and Clock pins for QSPI module. This is done by the PORT driver.
4.10.7.1.3. MemIf¶
This implementation depends on MemIf module and uses its imported types such as MemIf_JobResultType, MemIf_ModeType and MemIf_StatusType.
4.10.7.1.4. Fee¶
This implementation depends on Fee module for callback notification to notify the module environment about job end and job error.
4.10.7.1.5. Error Handling module¶
4.10.7.1.6. DET¶
The module FLS depends on the DET (by default) in order to report development errors. Detection and reporting of development errors can be enabled or disabled by the switch FLS_DEV_ERROR_DETECT = STD_ON in the Fls_Cfg.h
The following table represents the service IDs:
Service ID |
code |
Service |
|---|---|---|
FLS_SID_INIT |
0x00 |
Fls_Init |
FLS_SID_ERASE |
0x01 |
Fls_Erase |
FLS_SID_WRITE |
0x02 |
FLS_Write() |
FLS_SID_CANCEL |
0x03 |
FLS_Cancel() |
FLS_SID_GET_STATUS |
0x04 |
FLS_GetStatus() |
FLS_SID_GET_JOB_RESULT |
0x05 |
Fls_GetJobResult() |
FLS_SID_READ |
0x07 |
FLS_Read() |
FLS_SID_COMPARE |
0x08 |
FLS_Compare() |
FLS_SID_GET_VERSION_INFO |
0x10 |
Fls_GetVersionInfo() |
FLS_SID_BLANK_CHECK |
0xA |
FLS_BlankCheck() |
FLS_SID_MAIN_FUNCTION |
0x06 |
FLS_MainFunction() |
The errors reported to DET module are described in the following table:
Error Code |
Error Macro |
Description |
|---|---|---|
[0x01] |
FLS_E_PARAM_CONFIG |
API service called with wrong parameter |
[0x02] |
FLS_E_PARAM_ADDRESS |
API service called with wrong parameter |
[0x03] |
FLS_E_PARAM_LENGTH |
API service called with wrong parameter |
[0x04] |
FLS_E_PARAM_DATA |
API service called with wrong parameter |
[0x05] |
FLS_E_UNINIT |
API service used without module initialization |
[0x06] |
FLS_E_BUSY |
API called when module is busy |
[0x0A] |
FLS_E_PARAM_POINTER |
API called with a Null Pointer |
The run time errors reported to DET module are described in the following table:
Error Code |
Error Macro |
Description |
|---|---|---|
[0x07] |
FLS_E_VERIFY_ERASE_FAILED |
Erase verification (blank check) failed |
[0x08] |
FLS_E_VERIFY_WRITE_FAILED |
Write verification (compare) failed |
AUTOSAR requires that API functions check the validity of their parameters. The check in below table shows the various Development Error Reporting: Assignment of checks to services are internal parameter checks of the API functions. These checks are for development error reporting and can be enabled or disabled. The following table shows which parameter checks are performed on which services:
Check Services |
FLS_E_PARAM_CONFIG |
FLS_E_PARAM_ADDRESS |
FLS_E_PARAM_LENGTH |
FLS_E_PARAM_DATA |
FLS_E_UNINIT |
FLS_E_BUSY |
FLS_E_PARAM_POINTER |
|---|---|---|---|---|---|---|---|
Fls_Init |
x |
x |
|||||
Fls_Erase |
x |
x |
x |
x |
|||
Fls_Read |
x |
x |
x |
x |
x |
||
Fls_Write |
x |
x |
x |
x |
x |
||
Fls_Compare |
x |
x |
x |
x |
x |
||
Fls_BlankCheck |
x |
x |
x |
x |
|||
Fls_GetJobResult |
x |
||||||
Fls_GetVersionInfo |
x |
||||||
Fls_MainFunction |
x |
||||||
Fls_Cancel |
x |
4.10.7.1.6.1. DEM¶
FLS modules does not report DEM errors.
4.10.7.1.7. Callback Functions¶
The FLS driver does not provide any call back functions.
4.10.7.2. Main Functions¶
The function Fls_MainFunction perform the processing of the flash read, write, erase and compare jobs. When a job has been initiated, the FLS module’s environment shall call the function Fls_MainFunction cyclically until the job is finished.
4.10.7.3. Fls Set Erase Function¶
This function is called from example app based on the macros enabled in application itself. Implementation of this function is done to allow user to select one or more erase types based on the requirement. The function Fls_SetEraseType sets the parameters like data size, data_value, erase type(sector/block/chip), “typeoferase” for Fls_DrvObj, based on the erase type parameter passed to this function while calling from example app. These parameters are required in example app.
4.10.7.4. Callback Notification¶
Notifications:
This implementation depends on Fee module for callback notification to notify the module environment about job end and job error
4.10.7.5. Scheduling Strategy¶
4.10.7.5.1. SchM¶
This implementation requires one level of exclusive access to guard critical sections. Invokes SchM_Enter_Fls_FLS_EXCLUSIVE_AREA_0 (), SchM_Exit_Fls_FLS_EXCLUSIVE_AREA_0 () to enter critical section and exit.
4.10.7.5.2. Critical Sections¶
There is only one critical section in this driver. Within these sections all read /modify / write accesses to internal FLS status variables must be protected. Therefore, switching to tasks that also access FLS must be avoided and all FLS interrupts must be suspended. This is managed internally by Fls Driver
4.10.8. API Description¶
4.10.8.1. Description of the API’s (Can be referred to Api Guide spec)¶
Refer the AUTOSAR SWS for API documentation and Type definition.
4.10.8.2. API’s with Service ID¶
The following table presents the service IDs and the related services:
Autosar API’s Supported:
Service ID |
Service |
|---|---|
0x00 |
Fls_Init |
0x01 |
Fls_Erase |
0x02 |
FLS_Write |
0x03 |
FLS_Cancel |
0x04 |
FLS_GetStatus |
0x05 |
Fls_GetJobResult |
0x07 |
FLS_Read |
0x08 |
FLS_Compare |
0x10 |
Fls_GetVersionInfo |
0x0A |
FLS_BlankCheck |
0x06 |
FLS_MainFunction |
Autosar API’s not Supported:
Service ID |
Service |
|---|---|
0x09 |
Fls_SetMode |
Refer Autosar SWS for API description mentioned in above table.
4.10.9. Configuration Description¶
4.10.9.1. Configuration Variants¶
The Fls can be configured as Post-Build or Pre-Compile variant, using EB tresos tool.
Variants |
Generated Files |
|---|---|
PostBuild |
Fls_PBcfg.c , Fls_Cfg.h |
Pre-Compile |
Fls_Cfg.c , Fls_Cfg.h |
4.10.9.2. Parameter Description¶
4.10.9.2.1. Standard Configuration¶
Standard Parameters |
Description |
Default Value |
Range |
Unit |
|---|---|---|---|---|
FlsJobEndNotification |
Mapped to the job end notification routine provided by some upper layer module, typically the Fee module. |
NA |
NA |
FUNCTION-NAME |
FlsJobErrorNotification |
Mapped to the job error notification routine provided by some upper layer module, typically the Fee module. |
NA |
NA |
FUNCTION-NAME |
FlsMaxReadNormalMode |
The maximum number of bytes to read or compare in one cycle of the flash driver's job processing function in normal mode. |
768 |
0 .. 4294967295 |
INTEGER |
FlsMaxWriteNormalMode |
The maximum number of bytes to write in one cycle of the flash driver's job processing function in normal mode. |
768 |
0 .. 4294967295 |
INTEGER |
FlsNumberOfSectors |
Number of continuous sectors with identical configuration |
32 |
0..65535 |
INTEGER |
FlsPageSize |
Size of one page of this sector. |
256 |
0 .. 4294967295 |
INTEGER |
FlsSectorSize |
Size of this sector. |
4096 |
0 .. 4294967295 |
INTEGER |
FlsSectorStartaddress |
Start address of this sector. |
0 |
0 .. 4294967295 |
INTEGER |
FlsBlankCheckApi |
Compile switch to enable/disable the Fls_BlankCheck function. |
FALSE |
FALSE |
BOOLEAN |
FlsCancelApi |
Compile switch to enable and disable the Fls_Cancel function. Cancel API currently not supported. |
TRUE |
TRUE |
BOOLEAN |
FlsCompareApi |
Compile switch to enable and disable the Fls_Compare function. |
TRUE |
TRUE |
BOOLEAN |
FlsDevErrorDetect |
Switches the development error detection and notification on or off. |
FALSE |
FALSE |
BOOLEAN |
FlsDriverIndex |
Index of the driver, used by FEE. |
0 |
0..254 |
INTEGER |
FlsEraseVerificationEnabled |
Compile switch to enable erase verification. Currently not supported. |
FALSE |
FALSE |
BOOLEAN |
FlsGetJobResultApi |
Compile switch to enable and disable the Fls_GetJobResult function. |
TRUE |
TRUE |
BOOLEAN |
FlsGetStatusApi |
Compile switch to enable and disable the Fls_GetStatus function. |
TRUE |
TRUE |
BOOLEAN |
FlsSetModeApi |
Compile switch to enable and disable the Fls_SetMode function. Not relevant as only one mode supported. |
FALSE |
FALSE |
BOOLEAN |
FlsTimeoutSupervisionEnabled |
Compile switch to enable timeout supervision. Currently, not supported. |
FALSE |
FALSE |
BOOLEAN |
FlsUseInterrupts |
Job processing triggered by hardware interrupt. |
FALSE |
FALSE |
BOOLEAN |
FlsVersionInfoApi |
Pre-processor switch to enable / disable the API to read out the modules version information. |
FALSE |
FALSE |
BOOLEAN |
4.10.9.2.2. IP Specific Configuration¶
Standard Parameters |
Description |
Default Value |
Range |
Unit |
|---|---|---|---|---|
FlsMemMapMode |
This parameter is used to specify if the flash read operation should occur using the external flash memory map. |
TRUE |
TRUE/FALSE |
BOOLEAN |
FlsBaudRateDiv |
To Select the baud rate divider values |
0 |
0..4294967295 |
INTEGER |
FlsQspiCtrlBaseAddr |
This parameter used to select the QSPI base Address |
3355443200 |
0..4294967295 |
INTEGER |
FlsOsCounterRef |
This parameter contains a reference to the OsCounter, which is used by the FLS driver. |
– |
– |
– |
FlsIrqType |
Type of Isr function void functionname(void) CAT1 see description in oil tool : interrupt void func(void) CAT2 see description in oil tool : ISR(func) |
FLS_ISR_CAT1 |
FLS_ISR_VOID FLS_ISR_CAT1 FLS_ISR_CAT2 |
ENUMERATION |
FlsDefaultOSCounterId |
Default Os Counter Id if node reference to OsCounter ref FlsOsCounterRef is not set |
0 |
0..16 |
INTEGER |
FlsDeviceVariant |
Select required Device Variant |
AM273x |
– |
ENUMERATION |
FlsBaseAddress |
The flash memory start address (see also SWS_Fls_00208 and SWS_Fls_00209). |
3321888768 |
0..4294967295 |
INTEGER |
FlsTotalSize |
The total amount of flash memory in bytes (see also SWS_Fls_00208 and SWS_Fls_00209). |
1073741824 |
0 .. 4294967295 |
INTEGER |
FlsWriteVerificationEnabled |
Compile switch to enable write verification. Currenly, not supported. |
FALSE |
TRUE / FALSE |
BOOLEAN |
FlsErasedValue |
The contents of an erased flash memory cell. |
255 |
0 .. 4294967295 |
INTEGER |
FlsEraseTime |
Maximum time to erase one complete flash sector. |
1000 |
0..INFINITY |
FLOAT |
FlsExpectedHwId |
Unique identifier of the hardware device that is expected by this driver (the device for which this driver has been implemented). |
23322 |
– |
STRING |
FlsSpecifiedEraseCycles |
Number of erase cycles specified for the flash device (usually given in the device data sheet). |
0 |
0..4294967295 |
INTEGER |
FlsWriteTime |
Maximum time to program one complete flash page. |
1000 |
0..INFINITY |
FLOAT |
4.10.9.3. Configuration rules and constraints to enable plausibility checks¶
Will be updated in future release
4.10.10. Memory Mapping¶
Memory Mapping Sections |
Compiler Abstraction Definitions |
|||
|---|---|---|---|---|
FLS_CODE |
FLS_CODE_ISR |
FLS_VAR_NO_INIT |
FLS_CFG |
|
FLS_START_SEC_ISR_CODE (.text) |
x |
|||
FLS_STOP_SEC_ISR_CODE |
||||
FLS_START_SEC_VAR_NO_INIT_UNSPECIFIED (.data) |
x |
|||
FLS_STOP_SEC_VAR_NO_INIT_UNSPECIFIED |
||||
FLS_START_SEC_CODE(.text) |
x |
|||
FLS_START_SEC_CODE |
||||
FLS_START_SEC_CONFIG_DATA (.data) |
x |
|||
FLS_STOP_SEC_CONFIG_DATA |
4.10.11. Memory footprint¶
Please refer Memory Footprint for more details.
4.10.12. Performance¶
Will be updated in future release
4.10.13. Example Usage¶
4.10.13.1. Steps to build and run example¶
FLS example application demonstrating the MCAL Fls driver features is in folder <MCAL_ROOT>/examples/Fls.
This application can be built from the root folder by giving gmake –s fls_app PLATFORM=am273.
after the build is completed we get a binary file,which is loaded in our controller and executed.
4.10.13.2. Example Logs¶
FlsApp: Sample Application - STARTS !!!
FLS_APP: Variant - Pre Compile being used !!!
FLS MCAL version info:9.0.1
FLS MCAL Module/Driver:92.44
FLS_APP:Executing Sector configuration number : 1
FLS_APP:Number of sector/blocks to erase/read/write: 1
FLS_APP:Total data size: 0x1000
FLS_APP:Offset is 0x0
FLS_APP: Erasing
FLS_APP: Job Processing in Progress.
FLS_APP: Job Ends: SUCCESS
FLS_APP: Blank Checking
FLS_APP: Job Processing in Progress.
FLS_APP: Job Ends: SUCCESS
FLS_APP: Writing
FLS_APP: Job Processing in Progress.
FLS_APP: Job Ends: SUCCESS
FLS_APP: Reading
FLS_APP: Job Processing in Progress.
FLS_APP: Job Ends: SUCCESS
FLS_APP: Write Compare
FLS_APP: Job Processing in Progress.
FLS_APP: Job Ends: SUCCESS
FLS_APP: Read Compare
FLS_APP: Job Processing in Progress.
FLS_APP: Job Ends: SUCCESS
FLS_APP:
FLS_APP: Job Cancel
FLS_APP: 1. Writing
FLS_APP: 2. Canceling
FLS_APP: Job Canceled (SUCCESS) !
FLS_APP:
FLS_APP:
FLS_APP: ---------- FLS Sample application Done !! ----------
4.10.14. FAQ’s¶
None
4.10.15. Test Report (Link to test report)¶
Will be updated in future release
4.10.16. References¶
Autosar SWS 4.3.1 will be updated in future release.
4.10.17. TI Disclaimer¶
Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.
TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.
Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.
TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm
Mailing Address: Texas Instruments Post Office Box 655303 Dallas, Texas 75265