LSFS 文件系统操作示例
源码位置: samples/subsys/fs/lsfs 查看源码
功能说明
演示 LSFS (LiSa File System) 文件系统的基本操作，包括挂载 SD 卡、文件读写、目录遍历等核心功能。
LSFS 是 ARCS SDK 提供的轻量级文件系统抽象层，支持多种文件系统类型（FatFS 等）和存储介质（SD 卡、Flash、RAM Disk）。本示例展示如何在 SD 卡上使用 FatFS 文件系统进行基本的文件操作。
硬件连接
SDMMC0 接口：连接 SD 卡模块
具体引脚定义参见板级配置文件
示例步骤
初始化 SD 卡和磁盘子系统
初始化 LSFS 框架
挂载 SD 卡文件系统（挂载失败时自动格式化）
写入测试文件（
/SD:/sdmmc.txt）读取文件内容并验证
遍历根目录，列出所有文件和目录
卸载文件系统
编译
重要提示：在编译前，请先确认您使用的开发板型号。SDK 目前支持以下开发板：
arcs_evb - ARCS EVB 评估板
arcs_mini - ARCS Mini 开发板
根据您的开发板型号，选择对应的编译命令：
在示例目录下执行编译:
# 使用 arcs_evb 开发板
./build.sh -C -DBOARD=arcs_evb
# 或使用 arcs_mini 开发板
./build.sh -C -DBOARD=arcs_mini
Note
如果在 SDK 根目录执行，需要指定示例路径:
# 使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb
# 或使用 arcs_mini 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_mini
Note
确保已安装对应的工具链。
烧录
编译完成后，使用 SDK tools 目录下的 cskburn 工具烧录固件:
./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs
Note
烧录参数说明：
-s /dev/ttyUSB0：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是/dev/ttyUSB0或/dev/ttyACM0- 可通过ls /dev/tty*命令查看可用串口设备 - 不同开发板或 USB 转串口芯片可能使用不同的设备名-b 3000000：烧录波特率（3Mbps）0x0：烧录起始地址build/arcs.bin：编译生成的固件路径-C arcs：芯片类型
注意事项：
确保开发板已正确连接到电脑
如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口
预期输出
终端输出：
=== LSFS Sample ===
Mounted /SD: successfully
Write 12 bytes to /SD:/test.txt
Read 12 bytes: Hello, LSFS!
Listing directory: /SD:/
12 test.txt
Unmounted /SD:
核心 API
API |
说明 |
|---|---|
|
初始化 SD 卡设备 |
|
初始化磁盘子系统 |
|
初始化 LSFS 框架 |
|
挂载文件系统到指定挂载点 |
|
格式化文件系统 |
|
打开或创建文件 |
|
写入数据到文件 |
|
从文件读取数据 |
|
关闭文件 |
|
打开目录 |
|
读取目录项 |
|
关闭目录 |
|
卸载文件系统 |
文件操作说明
打开模式标志
LSFS_O_READ // 只读模式
LSFS_O_WRITE // 只写模式
LSFS_O_RDWR // 读写模式
LSFS_O_CREATE // 文件不存在则创建
LSFS_O_APPEND // 追加模式
LSFS_O_TRUNC // 打开时清空文件
错误处理
挂载失败处理：示例中实现了自动格式化机制，当挂载失败时尝试格式化后重新挂载
返回值规则：
成功：返回
0或正数（read/write 返回字节数）失败：返回负的 errno 值（如
-EINVAL,-ENOENT）
关键代码
挂载点定义
#define SDMMC_DEVICE "SD:"
#define SDMMC_MOUNT_POINT "/SD:"
static struct lsfs_mount_t sdmmc_lsfs_mnt = {
.type = LSFS_FATFS, // 使用 FatFS 文件系统
.mnt_point = "/SD:", // 挂载点路径
.fs_data = NULL, // 文件系统私有数据
};
挂载流程（含自动格式化）
int ret = lsfs_mount(&sdmmc_lsfs_mnt);
if (ret != 0) {
// 挂载失败，尝试格式化
ret = lsfs_mkfs(LSFS_FATFS, "SD:", NULL, 0);
if (ret == 0) {
ret = lsfs_mount(&sdmmc_lsfs_mnt); // 重新挂载
}
}
文件读写操作
struct lsfs_file_t file;
// 初始化文件对象
lsfs_file_t_init(&file);
// 写入文件
lsfs_open(&file, "/SD:/sdmmc.txt", LSFS_O_CREATE | LSFS_O_TRUNC | LSFS_O_WRITE);
lsfs_write(&file, data, strlen(data));
lsfs_close(&file);
// 读取文件
lsfs_file_t_init(&file);
lsfs_open(&file, "/SD:/sdmmc.txt", LSFS_O_READ);
lsfs_read(&file, buffer, sizeof(buffer) - 1);
lsfs_close(&file);
目录遍历
struct lsfs_dir_t dir;
struct lsfs_dirent entry;
lsfs_dir_t_init(&dir);
lsfs_opendir(&dir, "/SD:/");
while (1) {
ret = lsfs_readdir(&dir, &entry);
if (ret != 0 || entry.name[0] == 0)
break; // 遍历结束
if (entry.type == LSFS_DIR_ENTRY_DIR) {
// 目录
} else {
// 文件
printf("%10lu %s\n", entry.size, entry.name);
}
}
lsfs_closedir(&dir);
配置说明
必需的配置项（prj.conf）
CONFIG_FILE_SYSTEM=y # 使能文件系统支持
CONFIG_FATFS_FILESYSTEM=y # 使能 FatFS 文件系统
CONFIG_DISK_DRIVER=y # 使能磁盘驱动
CONFIG_DISK_DRIVER_SDMMC=y # 使能 SD/MMC 磁盘驱动
CONFIG_LSFS=y # 使能 LSFS 抽象层
CONFIG_LSFS_FAT=y # 使能 LSFS 的 FatFS 支持
注意事项
初始化顺序：必须按照以下顺序初始化
先调用
lisa_sdmmc_probe()初始化 SD 卡设备再调用
disk_init()初始化磁盘子系统然后调用
lsfs_init()初始化 LSFS 框架最后调用
lsfs_mount()挂载文件系统
文件对象初始化：每次使用前必须调用
lsfs_file_t_init()或lsfs_dir_t_init()初始化对象挂载点命名规则：
必须以
/开头通常以
:结尾（如/SD:）完整文件路径格式：
/SD:/dir/file.txt
及时关闭文件：使用完文件或目录后立即调用
lsfs_close()或lsfs_closedir()释放资源线程安全：LSFS API 是线程安全的，但同一个文件对象不应在多线程间共享
扩展功能
LSFS 支持更多高级功能，详见组件文档 modules/fs/README.md：
多存储介质：同时挂载 RAM Disk、Flash Disk、SD Card
POSIX 兼容接口：通过 LVFS 层使用标准 POSIX API（
open,read,write等）目录操作：创建目录（
lsfs_mkdir）、删除（lsfs_unlink）、重命名（lsfs_rename）文件定位：
lsfs_seek,lsfs_tell,lsfs_truncate文件系统信息：查询文件信息（
lsfs_stat）和磁盘空间（lsfs_statvfs）系统掉电保护：LSFS 冻结功能（
lsfs_freeze_freeze）