• This repository has been archived on 12/May/2022
  • Stars
    star
    130
  • Rank 277,525 (Top 6 %)
  • Language
    C
  • License
    Apache License 2.0
  • Created over 6 years ago
  • Updated over 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Flash Abstraction Layer implentment. Manage flash device and partition.

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;

FAL framework

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.

FAL API

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.

fal port

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:

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_PART_HAS_TABLE_CFG */

The detailed description of the above partition table is as follows:

Partition name Flash device name Offset address Size Description
"bl" "stm32_onchip" 0 64KB Bootloader
"app" "stm32_onchip" 64*1024 704KB Application
"easyflash" "norflash0" 0 1MB EasyFlash parameter storage
"download" "norflash0" 1024*1024 1MB OTA download area

The partition parameters that users need to modify include: partition name, associated Flash device name, offset address (relative to the internal Flash device), and size. Pay attention to the following points:

  • Partition name guarantee cannot be repeated;
  • The associated Flash device must have been defined in the Flash device table, and the name is the same, otherwise there will be an error that the Flash device cannot be found;
  • The starting address and size of the partition cannot exceed the address range of the Flash device, otherwise it will cause packet initialization errors;

Note: When defining each partition, in addition to filling in the parameter attributes described above, you need to add the attribute FAL_PART_MAGIC_WORD at the front and add 0 at the end (currently used for reserved functions)

3. FinSH/MSH test command

FAL provides a wealth of test commands, and the project only needs to enable the Finsh/MSH function on RT-Thread. These commands will be very useful when doing some Flash-based application development and debugging. It can accurately write or read the original Flash data at the specified location, quickly verify the integrity of the Flash driver, and even perform performance tests on the Flash.

The specific functions are as follows: enter fal to see the complete command list

msh />fal
Usage:
fal probe [dev_name|part_name]   - probe flash device or partition by given name
fal read addr size               - read 'size' bytes starting at 'addr'
fal write addr data1 ... dataN   - write some bytes 'data' starting at 'addr'
fal erase addr size              - erase 'size' bytes starting at 'addr'
fal bench <blk_size>             - benchmark test with per block size

msh />

3.1, Specify the Flash device or Flash partition to be operated

When using the fal command for the first time, directly inputting fal probe will display the partition table information. You can specify the object to be operated as a partition in the partition table or a flash device.

After the partition or Flash is successfully selected, some of its attributes will be displayed. The general effect is as follows:

msh />fal probe    
No flash device or partition was probed.
Usage: fal probe [dev_name|part_name]   - probe flash device or partition by given name.
[I/FAL] ==================== FAL partition table ====================
[I/FAL] | name      | flash_dev    |   offset   |    length  |
[I/FAL] -------------------------------------------------------------
[I/FAL] | bl        | stm32_onchip | 0x00000000 | 0x00010000 |
[I/FAL] | app       | stm32_onchip | 0x00010000 | 0x000b0000 |
[I/FAL] | ef        | norflash0    | 0x00000000 | 0x00100000 |
[I/FAL] | download  | norflash0    | 0x00100000 | 0x00100000 |
[I/FAL] =============================================================
msh />
msh />fal probe download
Probed a flash partition | download | flash_dev: norflash0 | offset: 1048576 | len: 1048576 |.
msh />

3.2, Erase data

Enter fal erase first, followed by the starting address and length of the data to be erased. The following command is: erase 4096 bytes of data from address 0 (relative to Flash or partition)

Note: According to the Flash characteristics, the erase action will be processed according to sector alignment. Therefore, if the erase operation address or length is not aligned with the flash sector, the entire sector data associated with it will be erased.

msh />fal erase 0 4096
Erase data success. Start from 0x00000000, size is 4096.
msh />

3.3, Write data

Enter fal write first, followed by N pieces of data to be written, separated by spaces. The following command is: Write 1, 2, 3, 4, 5, 5 bytes of data from address 8

msh />fal write 8 1 2 3 4 5
Write data success. Start from 0x00000008, size is 5.
Write data: 1 2 3 4 5.
msh />

3.4, Read data

Enter fal read first, followed by the starting address and length of the data to be read. The following command is: read 64 bytes of data from address 0

msh />fal read 0 64
Read data success. Start from 0x00000000, size is 64. The data is:
Offset (h) 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
[00000000] FF FF FF FF FF FF FF FF 01 02 03 04 05 FF FF FF
[00000010] FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
[00000020] FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
[00000030] FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF

msh />

3.5, Performance test

The performance test will test the erasing, writing and reading speed of the Flash. At the same time, the accuracy of writing and reading data will be tested to ensure the consistency of the writing and reading data of the entire Flash or the entire partition.

Enter fal bench first, followed by the sector size of the Flash to be tested (please check the corresponding Flash manual, SPI Nor Flash is generally 4096). Since the performance test will lose the data of the entire Flash or the entire partition, the command must be followed by yes at the end.

msh />fal bench 4096 yes
Erasing 1048576 bytes data, waiting...
Erase benchmark success, total time: 2.674S.
Writing 1048576 bytes data, waiting...
Write benchmark success, total time: 7.107S.
Reading 1048576 bytes data, waiting...
Read benchmark success, total time: 2.716S.
msh />

4. Common applications

5. Common problems

1. When using FAL, the header file fal_cfg.h cannot be found

fal_cfg.h is the configuration file of the fal software package, which needs to be created manually by the user and defines the relevant partition table information. Please place the file in the port folder of the BSP or the port folder of the project directory (if not, create a new port folder), and add the path of the header file to the project, see "2.2. Define the Flash Device Table " section.

6. Contact

More Repositories

1

at_device

AT component porting or samples for different devices
C
214
star
2

freemodbus

A Modbus ASCII/RTU and TCP implementation
C
211
star
3

nimble

An Apache open-source Bluetooth 5.0 stack porting on RT-Thread
C
128
star
4

rt-robot

a platform in creating new exciting robots
C
112
star
5

kernel-sample

RT-Thread kernel samples
C
81
star
6

netutils

IoT networking utilities for RT-Thread. Such as: ping, tftp, iperf, netio, ntp, telnet and tcpdump.
C
71
star
7

webclient

http client library by RT-Thread
C
67
star
8

ota_downloader

The firmware downloader which using on RT-Thread OTA component.
C
65
star
9

gui_engine

Graphics Engine (GE) in RT-Thread
C
53
star
10

wiznet

WIZnet TCP/IP chips (such as W5500/W5100..) SAL framework implement.
C
49
star
11

webnet

A lightweight, customizable embedded Web Server for RT-Thread
C
48
star
12

paho-mqtt

Eclipse Paho MQTT C/C++ client for Embedded platforms
C
43
star
13

ppp_device

lwIP PPP porting for GSM modem (like sim800)
C
39
star
14

mbedtls

An open source, portable, easy to use, readable and flexible SSL library
C
36
star
15

tinycrypt

A simple and configurable crypt library
C
34
star
16

quicklz

the world's fastest compression library
C
33
star
17

qrcode

A simple library for generating QR codes in C.
C
31
star
18

ali-iotkit

Ali Cloud SDK for IoT platform
C
30
star
19

cmux

connection multiplexing protocol for RT-Thread, support GSM0710 .etc
C
30
star
20

umqtt

A light weight, powerful, customizable, easy-to-use and embeddable mqtt client for RT-Thread
C
27
star
21

miniLZO

A mini subset of the LZO real-time data compression library
C
26
star
22

mpu-6xxx

a package of mpu6xxx driver library, compatible with mpu6000, mpu6050, mpu6500, mpu9250 and other chips.
C
25
star
23

FreeRTOS-Wrapper

RT-Thread操作系统的FreeRTOS兼容层 | FreeRTOS Application Compatibility Layer (ACL) for RT-Thread
C
25
star
24

wavplayer

Minimal music player for wav file.
C
23
star
25

peripheral-sample

RT-Thread peripheral samples
C
22
star
26

cJSON

Ultralightweight JSON parser in ANSI C
C
21
star
27

jerryscript

JerryScript port for RT-Thread
C
18
star
28

samples

RT-Thread kernel and components samples.
C
18
star
29

bsal

蓝牙协议栈抽象层
C
16
star
30

vi

The screen-oriented text editor for RT-Thread.
C
16
star
31

SQLite

SQLite is a self-contained, high-reliability, embedded, full-featured, public-domain, SQL database engine.
C
15
star
32

coap

CoAP on RT-Thread
C
13
star
33

TJpgDec

a generic JPEG image decompressor module.
C
12
star
34

CMSIS

CMSIS(Cortex Microcontroller Software Interface Standard) package on RT-Thread
C
12
star
35

network-sample

RT-Thread network samples
C
11
star
36

aht10

digital humidity and temperature sensor AHT10 driver library
C
11
star
37

nopoll

ASPLes/nopoll - OpenSource WebSocket toolkit for RT-Thread
C
11
star
38

lv_demo_music

LVGL music player demo for RT-Thread | LVGL音乐播放器演示示例(RT-Thread定制版)
C
11
star
39

fastlz

lightning-fast compression library
C
10
star
40

nanopb

Protocol Buffers for Embedded Systems
C
9
star
41

rw007

RW007 (SPI Wi-Fi module) driver for RT-Thread
C
9
star
42

SEGGER_SystemView

SEGGER SystemView
C
9
star
43

CMSIS_RTOS2

RT-Thread操作系统的CMSIS-RTOS2兼容层 | CMSIS-RTOS2 Application Compatibility Layer (ACL) for RT-Thread
C
8
star
44

gt9147

gt9147 touch driver
C
8
star
45

infrared_framework

Infrared framework based on RT-Thread's pin,pwm and hwtimer driver.
C
8
star
46

stm32_sdio

STM32 SDIO peripheral universal driver library
C
8
star
47

filesystem-sample

RT-Thread filesystem samples
C
8
star
48

ulog_file

ulog file backend
C
8
star
49

onenet

China Mobile OneNet cloud SDK for RT-Thread
C
8
star
50

zlib

general purpose data compression library
C
7
star
51

joylink

Joylink Cloud SDK for IoT platform
C
7
star
52

bmi160_bmx160

The device driver package for BMX160 and BMI160.
C
7
star
53

LPM

逻辑分区管理(Logical partition management),支持动态创建、删除、查找、读写物理存储设备上的逻辑分区。
C
7
star
54

tlsf

TLSF is a dynamic memory allocation algorithm with predictable execution time and low fragmentation.
C
7
star
55

atsrv_socket

C
7
star
56

icm20608

a 3-axis gyroscope and a 3-axis accelerometer driver library. Compatible with MPU6050, MPU6500, MPUxxxx etc
C
6
star
57

wlan-wiced

wlan driver from WICED.
C
6
star
58

dstr

dynamic string in C
C
6
star
59

GAgent

GAgent of Gizwits in RT-Thread
C
6
star
60

vsensor

虚拟传感器
C
6
star
61

uffs

UFFS is a file system that uses NAND flash in a small memory environment
C
6
star
62

azure-iot-sdk

Microsoft azure cloud SDK for RT-Thread
C
6
star
63

lsm6dsl

This is the LSM6DSL sensor driver package, support: accelerometer, gyroscope, step.
C
6
star
64

rdb

RT-Thread Debug Bridge
C
5
star
65

logmgr

log system manager
C
5
star
66

jffs2

JFFS2 is a log file system implemented on MTD devices
C
5
star
67

ap3216c

digital ambient light and a proximity sensor ap3216c driver library
C
5
star
68

rti

RT-Thread insight, a probe tool for RT-Thread to help to analyze internal behavior of the system.
C
5
star
69

sht2x

digital humidity and temperature sensor SHT2x driver library
C
4
star
70

minimp3

MPEG Audio Layer III decoder from the FFmpeg libavcodec library.
C
4
star
71

iperf

iperf-liked network performance tool in RT-Thread.
C
4
star
72

event_recorder

A lightweight event record and replay tools for debug and test.
C
4
star
73

st7789

st7789 lcd driver
C
4
star
74

persimmon

Persimmon UI for RT-Thread.
C++
4
star
75

mlibc

mlibc - A small libc for MCU and RT-Thread
4
star
76

spl0601

The Digital Air Pressure Sensor SPL06-01 driver package.
C
4
star
77

bma400

This is the BMA400 sensor driver package, support: accelerometer, step.
C
3
star
78

kdb

kernel debug log tool
C
3
star
79

partition

A simple partition on block device.
C
3
star
80

ft6206

ft6206 touch driver
C
3
star
81

pcf8574

Remote 8-bit I/O expander for I2C-bus
C
3
star
82

kendryte_sdk

Kendryte K210 SDK
Python
3
star
83

ft6236

C
3
star
84

MultiButton

A compact and easy to use event-driven button driver module for RT-Thread. | 一个小巧易用的事件驱动按钮驱动模块.
C
3
star
85

libsodium-legacy

A modern and easy-to-use crypto library.
C
2
star
86

CMSIS_RTOS1

RT-Thread操作系统的CMSIS-RTOS1兼容层 | CMSIS-RTOS1 Application Compatibility Layer (ACL) for RT-Thread
C
2
star
87

jsmn

Jsmn is a world fastest JSON parser/tokenizer.
C
2
star
88

ezXML

An XML parser C library that's simple and easy to use.
C
2
star
89

pms

pms :power management system
2
star
90

trusted-firmware-m

ARM trusted-firmware-m porting for RT-Thread
Python
2
star
91

cairo

Multi-platform 2D graphics library
C
2
star
92

fdt

Device Tree package in RT-Thread
C
2
star
93

qianxun

C
2
star
94

gdbstub

gdbstub on RT-Thread
C
2
star
95

yaffs2

yaffs2 file system for RT-Thread
1
star
96

micro-ecc

micro-ecc package
Python
1
star
97

lsm303agr

This is the LSM303AGR sensor driver package, support: accelerometer, magnetometer.
C
1
star
98

duktape

Duktape - embeddable Javascript engine with a focus on portability and compact footprint, port for RT-Thread
1
star
99

player

Multi-Media Audio Stream Player for RT-Thread
1
star
100

snippets

Some code snippets for RT-Thread
Python
1
star