版本：0.3 | 日期：2026-02-27 | 路径： components/xt_fal/

一、概述

xt_fal 是 Flash 抽象层（Flash Abstraction Layer），提供 Flash 设备和分区的统一管理接口。支持多 Flash 设备注册、分区表管理、按名称访问分区，上层无需关心底层 Flash 硬件差异。

1.1 依赖

xt_error.h — 错误码定义

二、核心概念

2.1 Flash 设备与分区

xt_fal 将 Flash 硬件抽象为两层：

Flash 设备 （ xt_fal_flash ）：对应一块物理 Flash 芯片，包含起始地址、大小、块大小、操作函数（read/write/erase）
分区（ xt_fal_partition ）：Flash 设备内的逻辑区域，包含名称、起始地址、大小、标志

2.2 fal_id 编码

fal_id 是分区的统一标识，编码规则：

高 4 位：flash_id（0-15），标识 Flash 设备
低 4 位：分区索引（0-15），标识该设备内的分区

通过 XT_FAL_GET_FLASH_ID() 、 XT_FAL_GET_PARTITION_IDX() 、 XT_FAL_MAKE_ID() 宏进行编解码。

2.3 后端 ops 接口

Flash 设备通过 xt_fal_flash_ops 结构体注册底层操作函数：

ctrl — 控制（初始化/反初始化）
read — 读取
write — 写入
erase — 擦除

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_fal（Flash 抽象层）。

3.1 注册与管理

函数签名	说明
uint8_t xt_fal_register(const struct xt_fal_flash flash, const struct xt_fal_partition part_table, uint32_t part_count)	注册 Flash 设备和分区表
xt_err_t xt_fal_unregister(uint8_t flash_id, const struct xt_fal_flash out_flash, const struct xt_fal_partition out_part_table, uint32_t *out_part_count)	反注册 Flash 设备
xt_err_t xt_fal_init(void)	初始化所有已注册的 Flash 设备
xt_err_t xt_fal_deinit(void)	反初始化所有 Flash 设备

3.2 查询

函数签名	说明
uint8_t xt_fal_get_flash_id_by_name(const char *flash_name)	通过名称获取 flash_id
uint8_t xt_fal_get_id_by_name(const char *part_name)	通过分区名称获取 fal_id
const struct xt_fal_partition *xt_fal_get_partition_by_id(uint8_t fal_id)	通过 fal_id 获取分区指针
const struct xt_fal_flash *xt_fal_get_flash_by_id(uint8_t fal_id)	通过 fal_id 获取 Flash 设备指针

3.3 分区读写

函数签名	说明
int32_t xt_fal_partition_read(uint8_t fal_id, xt_fal_size_t offset, void *dst, xt_fal_size_t size)	读取分区数据
int32_t xt_fal_partition_write(uint8_t fal_id, xt_fal_size_t offset, const void *src, xt_fal_size_t size)	写入分区数据
int32_t xt_fal_partition_erase(uint8_t fal_id, xt_fal_size_t offset, xt_fal_size_t size)	擦除分区

四、常见模式

4.1 注册并使用 Flash 分区

#include "xt_fal.h"
 
// 1. 定义 Flash 设备和分区表
static struct xt_fal_flash my_flash = {
    .name = "internal",
    .addr = 0x08000000,
    .size = 512 * 1024,
    .block_size = 4096,
    .ops = { .ctrl = flash_ctrl, .read = flash_read,
             .write = flash_write, .erase = flash_erase },
};
 
static struct xt_fal_partition my_parts[] = {
    { .name = "app",    .addr = 0,        .size = 256 * 1024 },
    { .name = "lfs",    .addr = 256*1024, .size = 256 * 1024 },
};
 
// 2. 注册
xt_fal_register(&my_flash, my_parts, 2);
xt_fal_init();
 
// 3. 按名称获取分区并操作
uint8_t fal_id = xt_fal_get_id_by_name("lfs");
xt_fal_read(fal_id, 0, buf, sizeof(buf));
xt_fal_erase(fal_id, 0, 4096);
xt_fal_write(fal_id, 0, data, sizeof(data));

五、反模式

反模式	问题	正确做法
写前未擦除	Flash 写入失败	写操作前先擦除对应区域
跨块擦除不对齐	擦除失败	擦除地址和大小必须对齐到 block_size
分区名称重复	查找歧义	每个分区名称必须唯一