Attention

⚠️ This repository is no longer maintained any more. Please move to: https://github.com/RT-Thread/rt-thread/tree/master/components/fal

FAL：Flash Abstraction Layer

Chinese | English

1. Introduction to FAL

The Flash abstraction layer is an abstraction layer for the management and operation of Flash and Flash-based partitions. The upper layer unifies the Flash and partition operation API (the framework diagram is shown below), and has the following characteristics:

• Supports static and configurable partition table and can associate multiple Flash devices;
• The partition table supports automatic loading. Avoid the problem that the partition table is defined multiple times in multiple firmware projects;
• The code is streamlined, no dependency on the operating system, and can run on bare metal platforms, such as Bootloader that has certain requirements for resources;
• Unified operation interface. Ensure the file system, OTA, NVM (for example: EasyFlash) and other components that have certain dependencies on Flash, and the reusability of the underlying Flash driver;
• Comes with Finsh/MSH-based test commands, which can be operated in byte addressing mode (read, write, and erase) Flash or partition through Shell, which is convenient for developers to debug and test;

1.1,Open FAL

To use fal package, you need to select it in the RT-Thread package manager. The specific path is as follows:

RT-Thread online packages
    system packages --->
        --- fal: Flash Abstraction Layer implement. Manage flash device and partition.
        [*] Enable debug log output
        [*] FAL partition table config has defined on'fal_cfg.h'
        (onchip) The flash device which saving partition table
        (65536) The patition table end address relative to flash device offset.
        [ ] FAL uses SFUD drivers
        (norflash0) The name of the device used by FAL (NEW)
                version (latest) --->

The configuration instructions for each function are as follows:

• Enable debug log output (enabled by default);

• Whether the partition table is defined in fal_cfg.h (enabled by default). If you turn off this option, fal will automatically go to the specified location of the designated Flash to retrieve and load the partition table. For the specific configuration, see the following two options;

  • Flash device storing the partition table;
  • The end address of the partition table is located at the offset on the Flash device. fal will retrieve the partition table from this address and read it directly to the top of the Flash. If you are not sure about the specific location of the partition table, you can also configure it as the end address of the Flash, fal will retrieve the entire Flash, and the retrieval time may increase.

• Enable FAL migration files for SFUD (closed by default);

  • The name of the FLASH device passed in when calling the rt_sfud_flash_probe function should be entered (you can also check the name of the Block Device through the list_device command). This name corresponds to the Flash name in the partition table. Only when the device name is set correctly can the read and write operations on FLASH be completed.

Then let the RT-Thread package manager automatically update, or use the pkgs --update command to update the package to the BSP.

1.2, FAL directory

| Name | Description | | ------- | ---------- | | inc | Header file directory | | src | Source Code Directory | | samples | Sample catalog |

1.3, FAL API

The FAL-related API is shown in the figure, click here to view the detailed API parameters.

1.4, License

The fal package complies with the Apache-2.0 license, see the LICENSE file for details.

1.5, Dependency

It has no dependence on RT-Thread and can also be used on bare metal.

Test command function needs to rely on RT-Thread FinSH/MSH

2. Use FAL

The basic steps for using FAL are as follows:

1. Open FAL: Open the fal software package from Env and download it to the project.
2. FAL migration: define flash device, define flash device table, define flash partition table. Step 2 is mainly explained below.
3. Call fal_init() to initialize the library: After the migration is completed, it can be called in the application layer, such as in the main function.

2.1, Define flash device

Before defining the Flash device table, you need to define the Flash device first. It can be on-chip flash or off-chip spi flash based on SFUD:

• Refer to fal_flash_stm32f2_port.c to define the on-chip flash device.
• Refer to fal_flash_sfud_port.c to define off-chip spi flash device.

To define specific Flash device objects, users need to implement the operation functions of init, read, write, and erase according to their own Flash conditions:

• static int init(void): Optional initialization operation.
• static int read(long offset, uint8_t *buf, size_t size): read operation.

| Parameters | Description | | ------ | ------------------------- | | offset | Flash offset address for reading data | | buf | Buffer to store the data to be read | | size | The size of the data to be read | | return | Return the actual read data size |

• static int write(long offset, const uint8_t *buf, size_t size): write operation.

| Parameters | Description | | ------ | ------------------------- | | offset | Flash offset address for writing data | | buf | Buffer to store data to be written | | size | The size of the data to be written | | return | Return the actual written data size |

• static int erase(long offset, size_t size): erase operation.

| Parameters | Description | | ------ | ------------------------- | | offset | Flash offset address of erase area | | size | The size of the erased area | | return | Return the actual erased area size |

Users need to implement these operation functions according to their own Flash conditions. A specific Flash device object is defined at the bottom of the file. The following example defines stm32f2 on-chip flash: stm32f2_onchip_flash

const struct fal_flash_dev stm32f2_onchip_flash =
{
    .name = "stm32_onchip",
    .addr = 0x08000000,
    .len = 1024*1024,
    .blk_size = 128*1024,
    .ops = {init, read, write, erase},
    .write_gran = 8
};

• "stm32_onchip": the name of the flash device.
• 0x08000000: Start address for flash operation.
• 1024*1024: Total size of Flash (1MB).
• 128*1024: Flash block/sector size (because the STM32F2 blocks have uneven sizes, the erase granularity is the largest block size: 128K).
• {init, read, write, erase}: Flash operation functions. If there is no init initialization process, the first operation function position can be left blank.
• 8: Set the write granularity, the unit is bit, 0 means not effective (the default value is 0), this member is a new member whose fal version is greater than 0.4.0. Each flash write granularity is not the same, it can be set through this member, the following are several common Flash write granularities:
  • nor flash: 1 bit
  • stm32f2/f4: 8 bit
  • stm32f1: 32 bit
  • stm32l4: 64 bit

2.2, Define the flash device table

The Flash device table is defined in the header file fal_cfg.h, you need to create a new fal_cfg.h file before defining the partition table. Please place this file in the port folder of the corresponding BSP or project directory, and Add the header file path to the project. fal_cfg.h can refer to Sample file fal/samples/porting/fal_cfg.h to complete.

Flash device table example:

/* ===================== Flash device Configuration ========================= */
extern const struct fal_flash_dev stm32f2_onchip_flash;
extern struct fal_flash_dev nor_flash0;

/* flash device table */
#define FAL_FLASH_DEV_TABLE                                          \
{                                                                    \
    &stm32f2_onchip_flash,                                           \
    &nor_flash0,                                                     \
}

In the Flash device table, there are two Flash objects, one is the STM32F2 on-chip Flash, and the other is the off-chip Nor Flash.

2.3, Define flash partition table

The partition table is also defined in the fal_cfg.h header file. Flash partitions are based on Flash devices. Each Flash device can have N partitions. The collection of these partitions is the partition table. Before configuring the partition table, make sure that the Flash device and device table have been defined. fal_cfg.h can refer to Sample file fal/samples/porting/fal_cfg.h to complete.

Example of partition table:

#define NOR_FLASH_DEV_NAME             "norflash0"
/* ====================== Partition Configuration ========================== */
#ifdef FAL_PART_HAS_TABLE_CFG
/* partition table */
#define FAL_PART_TABLE                                                               \
{                                                                                    \
    {FAL_PART_MAGIC_WORD,        "bl",     "stm32_onchip",         0,   64*1024, 0}, \
    {FAL_PART_MAGIC_WORD,       "app",     "stm32_onchip",   64*1024,  704*1024, 0}, \
    {FAL_PART_MAGIC_WORD, "easyflash", NOR_FLASH_DEV_NAME,         0, 1024*1024, 0}, \
    {FAL_PART_MAGIC_WORD,  "download", NOR_FLASH_DEV_NAME, 1024*1024, 1024*1024, 0}, \
}
#endif /* FAL