1

MPLAB® Harmony 3 之基础篇（20） -- 如何使用文件系统

Microchip Technology Inc. MCU32 产品部

一、 简介

Harmony3 提供的文件系统（File System）库为嵌入式应用程序开发人员提供了一

个文件系统框架，用于检索和存储来自各种介质的数据。

Harmony3 文件系统库（以下简称 FS）旨在同时支持多个文件系统和多个介质，

并且提供统一的应用程序编程接口（API），用户程序通过该接口请求文件系统的

服务，不需要了解具体文件系统的函数。

FS 功能包括以下内容：

支持多文件系统（FAT，MPFS）

支持多种物理介质（NVM，SPI_FLASH，SD 卡等）

方便移植其他文件系统和物理介质

模块化和分层架构

2

二、 硬件工具和软件平台

硬件：SAM D21 Xplained Pro

软件： MPLAB® X IDE: v5.20 或者更新

XC32： v2.20 或者更新

Harmony 3： v3.4.0 或者更新 (bsp, core, csp)

3

三、 文件系统库的介绍

(一) FS 框架 FS 框架具有模块化和分层架构，如下图所示。

Driver/驱动层 驱动层提供了一个低级接口来访问物理介质，支持多个物理介质实例。驱动有： Memory Driver – 用于访问各种 Flash（QSPI Flash，NVM Flash，EEPROM

Flash） SDCARD Driver – 用于访问 SD 卡

Media driver/介质驱动层 介质驱动层提供了一种以“扇区”的形式访问介质的机制。扇区是文件系统访问

的最小存储元素。通常，每个扇区有 512 个字节。在 Harmony3 的 FS 中，驱动

程序和介质驱动程序组合为一个层。 Media Manager/介质管理层 介质管理层实现了基于扇区和磁盘的介质访问机制。当加载/分离介质时，它还

能执行磁盘的分配/释放，因此可以支持多个磁盘。 Native File System/本地文件系统 本地文件系统实现了文件系统的支持。本地文件系统有：FAT12，FAT32 和 MPFS等。 MPFS 是一个只读文件系统，用于存储不会更改的文件，例如网页，图像等。每

个本机文件系统都有一组通用的 API。 Virtual file system/SYS_FS/虚拟文件系统层 SYS_FS 提供了与本地文件系统无关的文件操作接口。本层将虚拟文件系统调用转

4

换为本地文件系统调用。因此应用程序可以支持多个文件系统。 提供的主要接

口包括： SYS_FS_mount() 挂载文件系统 SYS_FS_open() 打开文件 SYS_FS_read() 读文件 SYS_FS_write() 写文件 SYS_FS_close() 关闭文件

(二) FS 层间的交互 FS 层间交互如下图所示

(三) 介质驱动的挂载 在操作文件之前，必须要先挂载（mount）介质驱动，并且挂载成功后，才能进

行下一步的文件操作。

(四) 文件的操作 当介质驱动挂载成功后，应用程序可以以不同的方式（只读，写等）打开文件，

如果打开文件返回了一个有效的句柄/handle，可以继续下一步的读或者写操作。

5

文件操作结束后，需要关闭文件（关闭句柄）。

6

四、 获取 Harmony 3 的 core 包

如果之前没有下载 Harmony 3 的 core 包，则可以打开 MPLAB X IDE，点击 Tools -> Embedded -> MPLAB Harmony 3 Framework Downloader，然后按提示下载。 详细步骤可参考：“MPLAB® Harmony 3 之基础篇（01） -- Harmony 3 开发环境搭

建”。 成功下载 Harmony 3 的 core 包后，会看到如下类似界面：

以及在 Harmony 3 的安装目录下，会看到 core。

7

五、 文件系统例程介绍

在 Harmony3 安装目录\core\apps\fs\目录下，有文件系统的例程，详细信息见下

表。 例程 描述 nvm_fat 内部 flash 上实现了 FAT 文件系统 nvm_mpfs 内部 flash 上实现了 MPFS 文件系统 nvm_sdmmc_fat_multi_disk 演示利用 SYS_FS 接口访问多种介质（内部 Flash,

SDMMC） nvm_sdspi_fat_multi_disk 演示利用 SYS_FS 接口访问多种介质（内部 Flash,

SDSPI） nvm_sqi_fat 演示利用 SYS_FS 接口访问多种介质（内部 Flash, SQI

Flash） sdmmc_fat 演示利用 SYS_FS 接口以 SDMMC 驱动方式读写 SD

card sdspi_fat 演示利用 SYS_FS 接口以 SDSPI 驱动方式读写 SD card spi_flash_fat 演示利用 SYS_FS 接口以 SPI 驱动方式读写外部 flash sqi_flash_fat 演示利用 SYS_FS 接口以 SQI 驱动方式读写外部 flash

8

六、 SAMD21 的 nvm_fat 工程测试

本章节以在 SAMD21 的 NVM(内部 flash)上实现 FAT 的工程 nvm_fat 来介绍文件系

统的使用方法。 (一) 打开 nvm_fat 工程 在 MPLAB X IDE 里点击 File > Open Project，来打开 Harmony3 安装路径\core\apps\fs\nvm_fat\firmware\目录下的 sam_d21_pro.X

(二) 设置工程为 main project 在 projects 窗口右键工程选择 set as main project 如下图，如果已经是 main project则不用设置。

9

(三) 启动 HMC 在 MPLAB X IDE 里点击 Tools > Embeded > MPLAB Harmony 3 Configurator 启动：

点击“Launch”按钮启动 MHC。

10

点击”Open”来打开 MHC 工程。

11

打开成功后，如下图所示。

(四) 配置组件 1. 在 Project Graph 窗口选择“NVMCTRL”组件，然后在“Configuration Options”

窗口可以对 wait states 等参数做一些配置

2. 在 Project Graph 窗口选择“File System”组件，然后在“Configuration Options”

窗口可以设置本地文件系统（本例是 FAT）等

12

(五) 使用 MHC 生成代码 如果 MHC 中没有修改配置，可以不用重新产生代码。 如果在 MHC 中有修改配置，则依次保存并生成代码如下图。具体请参考文档：

“MPLAB® Harmony 3 之基础篇（02） -- 了解 MHC”。

(六) 编译下载测试 用 USB 线将 SAM D21 Xplained Pro 开发板连接到电脑，右键工程选择 properties来打开 project properties 对话框，选择 SAM D21 Xplained Pro EDBG 调试接口和

XC32 编译器。

13

14

(七) 编译下载测试 1. 编译下载 点击下图工具栏按钮来执行编译并下载程序：

编译成功如下图

下载成功如下图

15

按下 SW0 按钮，系统会将 NVM 构建为一个 FAT 文件系统，并将字符串"Hello World"会写入文件"FILE.TXT"，之后 LED0 灯亮起。

七、 Nvm_fat 源代码简介

源代码主要分以下两块， Fat 文件系统的数据 Fat 文件系统的访问

(一) Fat 文件系统的数据 位于 nvm_disk_images.c 的数组 FAT_IMAGE 包含了构建 FAT 文件系统需要的数据，

该数组是 const 类型，因此保存在 nvm 中，即在 nvm 中实现了一个 FAT 文件系统。

(二) Fat 文件系统的访问 文件系统的访问代码主要位于 app.c 文件的 APP_Tasks()函数中，利用状态机依次

调用如下函数。 1. 挂载 nvm SYS_FS_Mount(APP_DEVICE_NAME, APP_MOUNT_NAME, APP_FS_TYPE, 0, NULL)

16

2. 打开文件 appData.fileHandle=SYS_FS_FileOpen(APP_MOUNT_NAME"/"APP_FILE_NAME, SYS_FS_FILE_OPEN_READ_PLUS); 3. 读取文件状态 SYS_FS_FileStat(APP_MOUNT_NAME"/"APP_FILE_NAME, &appData.fileStatus) 4. 读取文件大小 appData.fileSize = SYS_FS_FileSize(appData.fileHandle); 5. 定位到文件结束 SYS_FS_FileSeek(appData.fileHandle, appData.fileSize, SYS_FS_SEEK_SET) 6. 检查是否文件结束/EOF/End of File SYS_FS_FileEOF(appData.fileHandle) 7. 定位到文件开始处 SYS_FS_FileSeek(appData.fileHandle, 0, SYS_FS_SEEK_SET) 8. 读取文件数据 SYS_FS_FileRead(appData.fileHandle, (void *)appData.data, ORIG_DATA_SIZE) 9. 定位文件到读数据之后的位置 SYS_FS_FileSeek(appData.fileHandle, ORIG_DATA_SIZE, SYS_FS_SEEK_SET) 10. 写入数据到文件 SYS_FS_FileWrite(appData.fileHandle, (const void *)writeData, WRITE_DATA_SIZE) 11. 定位文件到写数据之前的位置 SYS_FS_FileSeek(appData.fileHandle, -WRITE_DATA_SIZE, SYS_FS_SEEK_END) 12. 读取文件数据 SYS_FS_FileRead(appData.fileHandle, (void *)appData.data, WRITE_DATA_SIZE) 13. 关闭文件 SYS_FS_FileClose(appData.fileHandle)

17

总结

本文介绍了 Harmony 3 的文件系统库的主要功能，并通过一个例程说明如何使用

文件系统库。更多文档请参考 帮助文档：Harmony3 安装路径\core\doc\ 示例工程：Harmony3 安装路径\ core\apps\fs\