4.12. FLS¶
4.12.1. About This Document¶
Document Title |
User Guide of MCAL FLS Driver |
Document Version |
Version 1.0 |
Company |
Texas Instruments |
Document Name |
AUTOSAR FLS User Guide |
4.12.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
21 December 2023 |
Initial Version |
Approved |
4.12.3. Table of contents¶
4.12.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 |
OSPI |
Octal Serial Peripheral Interference |
DAC |
Direct Access Mode |
INDAC |
Indirect Access Mode |
4.12.5. Functional Overview¶
4.12.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 |
AM263px |
The Flash Driver provides services for reading, writing, erasing flash memory for external Flash device.
4.12.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 OSPI module to the flash memory
Figure_2: OSPI connected to an external flash memory
4.12.5.1.2. Initialization¶
The driver FLS is initialized by calling Fls_Init() function and takes FlsConfigSet as input and Initializes Flash and OSPI. This will also make driver status to IDLE.
4.12.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.12.5.2. Features Supported and Not Supported¶
AUTOSAR features:
Supported |
Not Supported |
|---|---|
Only one OSPI instance will support |
XIP Mode is not supported |
Perform storage mode applications
|
PHY Tune Module is not supported |
Configure error detection (DET) |
DMA mode is not supported |
Only polling mode is supported. |
|
DAC and INDAC mode of operation are supported |
|
Interrupt mode is supported (only in INDAC Mode) |
4.12.5.3. IP Specific features:¶
4.12.5.3.1. DAC Mode¶
Direct Access Controller (or DAC) refers to the operation where data interface accesses directly trigger a read or write to Flash memory. It is memory mapped and can be used to both access and directly execute code from external Flash memory. Access that use DAC do not use the embedded SRAM within the OSPI module. DAC mode does not support interrupt handling as it does not involve SRAM for data transfer.
4.12.5.3.2. INDAC Mode¶
Indirect Access Controller (INDAC) uses the internal SRAM of the OSPI module. Data transfers then happen between the SRAM and Flash memory or SRAM and system memory, so no memory mapping is needed. The aim of the indirect mode of operation is to transfer significant numbers of bytes to/from Flash memory. Indirect operations are controlled and triggered by software via specific read/write transfer registers. Bulk transfers take place between system and flash memory in the most efficient manner. Fewest possible write cycles carried out inside flash device to maximize life of device. INDAC supports poll and interrupt based implementation. The embedded SRAM used by INDAC provides interrupt mechanism. Interrupts are triggered when SRAM levels fall below a watermark, and also when a write/read operation finishes from within the SRAM. Design implementation is non-blocking and allows the control to return to the application (CPU) while the data is still transferring in hardware.
4.12.5.3.3. STIG¶
Software Triggered Instruction Generator - While DAC and INDAC are used for data transfer, STIG is used to access the volatile and non-volatile configuration registers, status registers, and for erase functions. This Flash Driver Module Write, Read, Erase, BlankCheck and Compare APIs are asynchronous such that control will return to the application after the job from one of the APIs has been accepted. A “job” describes the action that will perform actual transactions to the hardware. The driver’s Fls_MainFunction () API will do the job processing internally, after the APIs have been called and the job has been accepted. During job processing, the module will perform the programming of the flash device, and will make data transfers between system and flash device.
The below figure shows typical connection of the OSPI module to the flash memory
Figure_2: OSPI connected to an external flash memory
4.12.5.4. Assumptions¶
None
4.12.5.5. Constraints¶
For read and write operation offset should be page alligned
For read and write operation length of operation should be byte alligned.
For interrupt mode to be enabled, indac mode should be enabled.
For interrupt mode to be enabled, maxReadNormalMode and maxWriteNormalMode should be set to pagesize.
For interrupt mode to be enabled, FLS_ERASE_VERIFICATION_ENABLED, FLS_WRITE_VERIFICATION_ENABLED, FLS_TIMEOUT_SUPERVISION_ENABLED macros should be STD_OFF.
4.12.5.6. Design overview (Link to the Architecture document and Design Document)¶
Will be available in future release.
4.12.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_Irq.c |
Contains ISR specific API implementation. |
Fls_Nor_config.h |
Contains device specific configuration parameters. |
Fls_Brd_Nor_Ospi.c |
Contains internal functions and data structures. |
Fls_Ospi.c |
Contains internal functions and data structures. |
Fls_Brd_Nor.h |
Contains internal functions and data structures. |
Fls_Ospi.h |
Contains internal functions and data structures. |
Fls_Nor_config.c |
Contains flash specific commands. |
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.12.6. Deviations to requirements (Requirement Traceability)¶
4.12.6.1. Module Requirements¶
Please refer Software Product Specification document provided as part of CSP.
4.12.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.12.7. Integration Details¶
4.12.7.1. Dependency on Other Software Modules¶
4.12.7.1.1. The FLS Driver dependent modules¶
4.12.7.1.1.1. MCU¶
The Fls Modules expects the MCU modules to enable the OSPI clock through the configuration. Required parameter for clock enabling:
Module ID: MCU_CLKSRC_MODULE_ID_OSPI
Source ID: MCU_CLKSRC_4
Divider value: 2
4.12.7.1.2. PORT¶
The Fls Modules expects that pinmux is set correctly to configure the Data line, Chip select and Clock pins for OSPI module. This is done by the PORT driver.
4.12.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.12.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.12.7.1.5. Error Handling module¶
4.12.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.12.7.1.6.1. DEM¶
FLS modules does not report DEM errors.
4.12.7.1.7. Callback Functions¶
The FLS driver does not provide any call back functions.
4.12.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.12.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.12.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.12.7.5. Scheduling Strategy¶
4.12.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.12.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.12.8. API Description¶
4.12.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.12.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.12.9. Configuration Description¶
4.12.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.12.9.2. Parameter Description¶
Will be updated in future release
4.12.9.3. Configuration rules and constraints to enable plausibility checks¶
Will be updated in future release
4.12.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.12.11. Memory footprint¶
Please refer Memory Footprint for more details.
4.12.12. Performance¶
4.12.12.1. INDAC mode¶
Time Taken to erase sector of size(4096) |
120ms |
Time Taken to write sector of size(4096) |
3053us |
Time Taken to read sector of size(4096) |
289us |
4.12.12.2. DAC mode¶
Time Taken to erase sector of size(4096) |
124ms |
Time Taken to write sector of size(4096) |
23014us |
Time Taken to read sector of size(4096) |
1064us |
4.12.13. Example Usage¶
4.12.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=am263px.
after the build is completed we get a binary file,which is loaded in our controller and executed.
4.12.13.2. Example Logs¶
FlsApp: Sample Application - STARTS !!!
FLS_APP: Variant - Pre Compile being used !!!
FLS MCAL version info:9.1.0
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 !! ----------
FLS_APP:
4.12.14. FAQ’s¶
Q1. What if some flashes also support write enable for non-volatile registers?
Before writing to any register in flash, write enable command is issued to the flash. The Write enable can be issued to both volatile and non volatile registers depending on what the flash supports. Currently the existing flash in the device supports write enable to volatile registers. In case any external flash (e.g. S25FL064LABMFB01X) supports write enable to both volatile and non volatile registers, the user can issue write enable command for non volatile registers using Nor_OspiCmdWrite API. User can also update the fls_config_sfdp_1.cmdWren parameter in Flash_sfdpParams_init API in V2/Fls_Nor_config.c file by following the flash datasheet.
Q2. How to enable interrupt mode in Flash?
To enable interrupt mode, FLS_USE_INTERRUPTS should be set to STD_ON. INDAC mode should be enabled in interrupt mode as ospi controller uses SRAM level to trigger interrupt and INDAC mode of operation uses SRAM for data transfer. Also maxReadNormalMode and maxWriteNormalMode should be set to page size of the flash. Further, FLS_ERASE_VERIFICATION_ENABLED, FLS_WRITE_VERIFICATION_ENABLED and FLS_TIMEOUT_SUPERVISION_ENABLED should be disabled in interrupt mode.
4.12.15. Test Report (Link to test report)¶
Will be updated in future release
4.12.16. References¶
Autosar SWS 4.3.1 will be updated in future release.
4.12.17. Disclaimer¶
Will be updated in future release
