4.11. FLS

4.11.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.11.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

25 Aug 2023

Document release version column removed

Approved

4.11.3. Table of contents

  1. Acronyms and Definitions

  2. Functional Overview

  3. Deviations to requirements (Requirement Traceability)

  4. Integration Details

  5. API Description

  6. Configuration Description

  7. Memory Mapping

  8. Memory footprint

  9. Performance

  10. Example Usage

  11. FAQ’s

  12. Test Report (Link to test report)

  13. References

  14. Disclaimer

4.11.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.11.5. Functional Overview

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

AM263x

The Flash Driver provides services for reading, writing, erasing flash memory for external Flash device.

4.11.5.1.1. FLS Driver Architecture

The FLS driver has architecture as shown in below figure from the AUTOSAR specification.

../_images/fls_image2.png

Figure 1: FLS in AUTOSAR architecture.

The below figure shows typical connection of the QSPI module to the external quad-SPI flash memory

../_images/fls_image3.png

Figure_2: QSPI connected to an external Quad SPI flash memory

4.11.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.11.5.1.3. States

The Fls driver maintains states for:

  1. MEMIF_UNINIT -> This is the state when hardware is not initialized.

  2. MEMIF_IDLE -> when FLS driver initialized, it will go to IDLE state.

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

  4. MEMIF_BUSY_INTERNAL is not supported.

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

  1. Read from flash.

  2. Write to flash.

  3. Erase Flash.

  4. Cancel job is supported.

  5. Compare and Blank Check flash memory location

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

  1. FlsSetModeAPI

  2. FlsDefaultMode

  3. FlsMaxReadFastMode

  4. FlsMaxWriteFastMod

  5. FlsAcLoadOnJobStart

  6. FlsAcErase

  7. FlsAcWrite

  8. FlsAcWrite

4.11.5.3. IP Specific features:

None

4.11.5.4. Assumptions

None

4.11.5.5. Limitations

Only 1S-1S-4S mode is supported for QSPI.

4.11.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.
../_images/fls_image7.png

Figure 4: FLS header file include structure

4.11.6. Deviations to requirements (Requirement Traceability)

4.11.6.1. Module Requirements

Will be updated in future release

4.11.6.2. Deviation of requirements against AUTOSAR specification requirements

Will be updated in future release

4.11.7. Integration Details

4.11.7.1. Dependency on Other Software Modules

4.11.7.1.1. The FLS Driver dependent modules

4.11.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:

  1. Module ID: MCU_CLKSRC_MODULE_ID_QSPI

  2. Source ID: MCU_CLKSRC_4

  3. Divider value: 4

4.11.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.11.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.11.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.11.7.1.5. Error Handling module

4.11.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.11.7.1.6.1. DEM

FLS modules does not report DEM errors.

4.11.7.1.7. Callback Functions

The FLS driver does not provide any call back functions.

4.11.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.11.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.11.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.11.7.5. Scheduling Strategy

4.11.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.11.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.11.8. API Description

4.11.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.11.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.11.9. Configuration Description

4.11.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.11.9.2. Parameter Description

Will be updated in future release

4.11.9.3. Configuration rules and constraints to enable plausibility checks

Will be updated in future release

4.11.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.11.11. Memory footprint

Please refer Memory Footprint for more details.

4.11.12. Performance

Will be updated in future release

4.11.13. Example Usage

4.11.13.1. Steps to build and run example

  1. FLS example application demonstrating the MCAL Fls driver features is in folder <MCAL_ROOT>/examples/Fls.

  2. This application can be built from the root folder by giving gmake –s fls_app PLATFORM=am263.

  3. after the build is completed we get a binary file,which is loaded in our controller and executed.

4.11.13.2. Example Logs

[HSM_CLIENT] New Client Registered with Client Id = 0
Starting QSPI Bootloader ...
[BOOTLOADER_PROFILE] Boot Media       : NOR SPI FLASH
[BOOTLOADER_PROFILE] Boot Media Clock : 80.000 MHz
[BOOTLOADER_PROFILE] Boot Image Size  : 219 KB
[BOOTLOADER_PROFILE] Cores present    :
r5f0-0
[BOOTLOADER PROFILE] System_init                      :        304us
[BOOTLOADER PROFILE] Drivers_open                     :         82us
[BOOTLOADER PROFILE] LoadHsmRtFw                      :       8768us
[BOOTLOADEFLS_APP: Job Ends: SUCCESS
FlsApp: Sample Application - STARTS !!!
FLS CHIP ERASE !!!
FLS_APP: Variant - Pre Compile being used !!!
FLS MCAL version info:8.6.2
FLS MCAL Module/Driver:92.44
FLS_APP: DATA SIZE TEST is 0x10000
FLS_APP: Offset is 0x0
FLS_APP: Erasing
FLS_APP: Erasing full chip..please wait..
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.11.14. FAQ’s

None

4.11.16. References

Autosar SWS 4.3.1 will be updated in future release.

Technical Reference Manual

4.11.17. Disclaimer

Will be updated in future release