1. 如何移植

1.1基本注意事项

FatFs模块认为以下可移植性条件。

ANSI C
FatFs模块是一个用ANSI C (C89)编写的中间件。没有平台依赖性，只要编译器符合C89或更高版本。只有exFAT功能需要C99。
整数类型的大小
char类型的大小必须是8bit。
int类型大小，和int的高级形式(integer promotion)（比如unsigned int）必须是16位或32位。
short长度为16位，long长度为32位。(只适用于C89版本)
依赖文件
C89: string.h.
C99: string.h and stdint.h.
可选的: stdarg.h and math.h.

1.2 FatFs API中的整数类型

fatf中使用的整数类型定义在ff.h中，如下所述。它基于Win32 API (windef.h)。这在大多数平台上都不是问题。当与现有定义发生冲突时，必须小心解决。

BYTE : 8比特无符号整数，取值范围为[0, 2^8 - 1]
WORD: 16比特无符号整数，取值范围为[0, 2^16 - 1]
DWORD: 32比特无符号整数，取值范围为[0, 2^32 - 1]
QWORD: 64比特无符号整数，取值范围为[0, 2^64 - 1]
UNIT: unsigned int 的别名，用于表示任意数
WCHAR: WORD(16比特无符号整数)的别名，用于表示一个UTF-16编码单元。
TCHAR: char，WCHAR, DWORD的别名，用于表示一个字符编码单元。
FSIZE_t: DWORD,QWORD的别名，用于寻址文件偏移量和表示文件大小。
LBA_t: DWORD,QWORD的别名，用于在LBA中寻址扇区，并指定扇区数量。

1.3 系统组织

下面显示的依赖关系图是一个典型的，但不是特定的，带有 FatFs 模块的嵌入式系统的配置。

(a) 如果提供了 FatFs 的工作磁盘模块，则不需要其他任何东西。
(b) 要附加具有不同接口的现有磁盘驱动程序，需要一些胶水函数来转换 FatFs 和驱动程序之间的接口。

1.4 所需功能

您只需提供 FatFs 模块所需的 MAI 功能，无需提供其他任何功能。
如果目标系统的工作设备控制模块可用，您只需要编写粘合函数将其附加到 FatFs 模块。
如果没有，则需要移植另一个设备控制模块或从头开始编写。大多数 MAI 功能并不总是需要的。例如，在只读配置中不需要写函数。下表显示了所需的功能取决于配置选项

FatFs 既不关心使用什么样的存储设备，也不关心它是如何实现的。唯一的要求是它是以固定大小的块读取/写入的块设备，可通过上面定义的磁盘 I/O 函数访问。

限制

文件系统类型：FAT、FAT32(rev0.0) 和 exFAT(rev1.0)。
打开的文件数：无限制。（取决于可用内存)
卷数：最多 10。
扇区大小：512、1024、2048 和 4096 字节。
最小卷大小：128 个扇区。
最大卷大小：在 32 位 LBA，2^32 - 1 个扇区。在 32 位 LBA ，在具有 exFAT 的 64 位 LBA 中几乎没有限制。
最大文件大小：FAT 卷上为 2^32 - 1 字节，exFAT 卷上几乎没有限制。
簇（cluster）大小：FAT 卷上最多 128 个扇区，exFAT 卷上最多 16 MB。

存储使用

内存使用量因配置选项而异。

这些是在以下情况下某些目标系统上没有底层的 FatFs 模块的内存使用情况。 V 表示已安装卷的数量，F 表示打开文件的数量。这里的每个示例都在代码大小上进行了优化。

FatFs R0.15 options:
FF_FS_READONLY   0 (R/W, read/write) or 1 (R/O, read only)
FF_FS_MINIMIZE   0 (Def, with all basic functions) or 3 (Min, with fully minimized)
FF_FS_TINY       0 (Default) or 1 (Tiny file object)
并且任何其他选项与原始设置保持不变。

减小模块大小

下表显示了配置选项删除了哪些 API 函数以减小模块大小。要使用 API 函数，函数所在的行必须清楚。

长文件名

FatFs 模块支持 FAT 文件系统的长文件名 (LFN) 扩展。
文件的两个不同文件名，短文件名 (SFN) 和 LFN，在 API 上是透明的。
默认情况下禁用对 LFN 功能的支持。
要启用 LFN，请将 FF_USE_LFN 设置为 1、2 或 3，并将 ffunicode.c 添加到项目中。
LFN 功能需要一定的工作缓冲区。缓冲区大小可以根据可用内存由 FF_MAX_LFN 配置。
LFN 的长度最多可达 255 个字符，因此对于任何现有文件名，FF_MAX_LFN 都应设置为 255。
如果工作缓冲区的大小不足以容纳输入文件名，则文件函数将失败并返回 FR_INVALID_NAME。
当在 RTOS 环境中使用具有 LFN 特性的 API 的任何重入时，FF_USE_LFN 必须设置为 2 或 3。在这种情况下，文件函数在堆栈或堆上分配工作缓冲区。当启用 exFAT 时，LFN 工作缓冲区占用 (FF_MAX_LFN + 1) * 2 个字节和额外的 (FF_MAX_LFN + 44) / 15 * 32 个字节。

对模块尺寸的影响

启用长文件名 (LFN) 后，模块大小将增加，具体取决于配置的代码页。下表显示了某些代码页中代码大小的增量。特别是在 CJK 地区，正在使用数万个字符。不幸的是，它需要一个巨大的 OEM-Unicode 双向转换表，并且模块大小将急剧增加，如表中所示。

因此，具有启用了 DBCS 代码页的 LFN 的 FatF 将无法移植到大多数 8 位 MCU 系统上。如果目标系统是无遗留系统，仅使用 Unicode 并且根本不使用任何 ANSI/OEM 代码，则代码页设置将变得毫无意义。您将能够通过使用任何 SBCS 代码页为 Unicode API 配置 FatFs 来减少代码大小。

开源项目使用长文件名 (LFN) 有一些限制，因为 FAT 文件系统上的 LFN 扩展是微软公司的专利。但是相关专利都已过期，任何项目都可以免费使用 LFN 功能。

Unicode API

默认情况下，FatFs 使用 API 上设置的 ANSI/OEM 代码，即使在 长文件名 (LFN) 配置中也是如此。 FatFs 还可以通过配置选项 FF_LFN_UNICODE 将 API 上的字符编码切换为 Unicode。这意味着 FatFs 符合全功能 长文件名 (LFN) 规范。 数据类型 TCHAR 在 API 上指定路径名字符串是 char（ANSI/OEM 或 UTF-8）、WCHAR（UTF-16）或 DWORD（UTF-32）的别名，具体取决于该选项。 有关详细信息，请参阅文件名中的说明。

请注意，当为 Unicode API 配置 FatFs 时，代码页 FF_CODE_PAGE 的设置实际上没有任何意义。应设置为 437 以减小模块大小。但是，当 FF_STRF_ENCODE == 0 时，它仍然会影响字符串 I/O 函数的代码转换，并且还会向后兼容遗留系统。在这种情况下，如果认为代码页有问题，则可能需要正确配置代码页。

exFAT文件系统

exFAT（Microsoft’s Extended File Allocation Table）文件系统是FAT/FAT32文件系统的继承，广泛应用于嵌入式系统、消费类设备和便携式存储介质。 SDA（SD 协会）采用它作为 SDXC 卡的文件系统，64 GB 或更大，并且它们以这种格式提供。因此 exFAT 和 FAT 一样是可移动媒体的标准文件系统之一。
exFAT 文件系统允许文件大小超过 FAT 文件系统允许的 4 GB 限制，并且一些文件系统开销，尤其是集群分配延迟，也减少了。这些功能允许记录大数据而无需划分为一些文件并提高文件的写入吞吐量。
请注意，exFAT 文件系统是 Microsoft Corporation 的专利。 FatFs的exFAT特性是基于US. Pat. App. Pub. No. 2009/0164440 A1.。
FatFs 模块可以通过配置选项 FF_FS_EXFAT 打开或关闭 exFAT。为商业产品启用 exFAT 时，将需要 Microsoft 的许可证，具体取决于产品的最终目的地。
备注：启用 exFAT 会放弃 C89 兼容性，它需要 C99，因为需要 64 位整数类型。

64-bit LBA

LBA（Logical Block Addressing） 是一种寻址方法，用于指定数据块（称为扇区）在存储介质上的位置。它是一个简单的线性地址，从 0 作为第一个扇区开始，1 作为第二个扇区，依此类推。
主机系统不需要考虑数据块在存储设备中是如何定位和管理的。 FatFs 仅支持 LBA 进行媒体访问。
32 位 LBA 是大多数 LBA 方案中的常见大小。它最多可以寻址 2^32 个扇区，2 TB，512 字节/扇区。 当使用大于 2 TB 的存储设备时，将需要更大的扇区大小或 64 位 LBA 来寻址存储设备的整个扇区。

默认情况下，FatFs 在 32 位 LBA（Logical Block Addressing) 中工作以进行媒体访问。
FatFs 还可以通过配置选项 FF_LBA64 将其切换为 64 位 LBA。
它还为存储设备上的分区管理启用 GPT（GUID 分区表）。有关 GPT 的更多信息，请参阅 f_mkfs 和 f_fdisk 函数。

重入 Re-entrancy

两个任务对彼此不同卷的文件操作始终是可重入的，并且无论配置如何，它都可以在没有任何互斥的情况下同时工作，除非使用静态工作缓冲区 (FF_USE_LFN = 1) 启用了 LFN。

默认情况下，两个任务对同一卷的文件操作不是线程安全的。 FatFs 也可以通过选项 FF_FS_REENTRANT 配置为线程安全。
当另一个任务正在访问卷时调用文件函数时，卷的文件函数将被挂起，直到该任务离开文件函数。如果等待时间超过 FF_TIMEOUT 定义的时间，文件函数将中止并返回 FR_TIMEOUT。某些操作系统可能不支持超时功能。要启用此功能，需要将依赖于操作系统的同步控制函数 ff_mutex_create/ff_mutex_delete/ff_mutex_take/ff_mutex_give 添加到项目中。 ffsystem.c 中有一些操作系统的示例代码。

请注意，f_mount 和 f_mkfs 函数的重新进入存在异常。你会知道为什么会这样。这些卷管理函数对于正在处理的卷始终不是线程安全的。使用这些功能时，其他任务需要避免访问相应的卷。

备注：本节介绍FatFs模块本身的重入。 FF_FS_REENTRANT 选项仅允许独占使用每个文件系统对象，而 FatFs 不会阻止重新进入存储设备控制功能。因此，当为不同的卷重新输入 FatFs API 时，设备控制层需要始终是线程安全的。上表显示了在某些情况下重新进入 FatFs API 时可以重新进入哪个控制函数。

打开重复的文件

FatFs模块不支持文件重复打开的读写冲突控制。 只有当文件的每个打开方法都是读取模式时才允许重复打开。 始终禁止以一种或多种写入方式重复打开文件，并且打开的文件不得重命名或删除。违反这些规则可能会导致数据崩溃。

文件锁定控制可以通过 FF_FS_LOCK 选项启用。 option 的值定义了要同时管理的打开对象的数量。在这种情况下，如果尝试违反上述文件共享规则打开、重命名或删除，文件功能将被拒绝并返回 FR_LOCKED。如果打开的对象、文件和子目录的数量等于 FF_FS_LOCK，则额外的 f_open/f_opendir 函数将失败并返回 FR_TOO_MANY_OPEN_FILES。

高效的文件访问

为了在内存大小有限的小型嵌入式系统上获得良好的读/写吞吐量，应用程序程序员应该考虑在 FatFs 模块中完成什么过程。卷上的文件数据通过 f_read 函数按以下顺序传输。

图 1. 扇区未对齐读取（短）

图 2. 扇区未对齐读取（长）

图 3. 完全扇区对齐读取

文件 I/O 缓冲区是一个扇区缓冲区，用于读取/写入扇区上的部分数据。扇区缓冲区是每个文件对象上的文件专用扇区缓冲区或文件系统对象中的共享扇区缓冲区。缓冲区配置选项 FF_FS_TINY 决定哪个扇区缓冲区用于文件数据传输。选择微型缓冲区配置 (1) 时，每个文件对象的数据内存消耗减少 FF_MAX_SS 字节。在这种情况下，FatFs 模块仅使用文件系统对象中的一个扇区缓冲区来进行文件数据传输和 FAT/目录访问。 tiny buffer 配置的缺点是：缓存在扇区缓冲区中的 FAT 数据会因文件数据传输而丢失，并且必须在每个簇边界处重新加载。然而，从体面的性能和低内存消耗的角度来看，它将适用于大多数应用程序。

图 1 显示了部分扇区，即文件的扇区未对齐部分，通过文件 I/O 缓冲区传输。在图 2 所示的长数据传输中，覆盖一个或多个扇区的传输数据的中间直接传输到应用程序缓冲区。 图 3 显示了全部的传输数据与扇区边界对齐的情况。在这种情况下，不使用文件 I/O 缓冲区。在直接传输中，一次使用 disk_read 函数读取最大范围的扇区，但多扇区传输在簇边界处被分割，即使它是连续的。

因此，努力实现扇区对齐的读/写访问可以消除缓冲数据传输，从而提高读/写性能。 除此之外，缓存的FAT数据在tiny配置下不会被文件数据传输刷新，因此它可以实现与非tiny配置相同的性能，内存占用小。

闪存介质的注意事项

为了使SDC、CFC、U盘等闪存介质的写入性能最大化，必须结合其特性进行控制。

使用多扇区写入

闪存介质的写入吞吐量在单扇区写入事务中变得最差。写入吞吐量随着每个写入事务的扇区数量增加而增加，如图 6 所示。这种效果在更快的接口速度下更明显，并且性能比通常变得大于 10。这个结果清楚地解释了多块写入（W：16K，32 个扇区）比单块写入（W：100，1 个扇区）有多快，而且较大的卡在单块写入时往往很慢。写入事务的数量也会影响闪存介质的使用寿命。当比较相同数量的写入数据时，上面图 6 中的单个扇区写入对闪存介质的磨损是下面图 6 中的多个扇区写入的 16 倍。单扇区写入对于闪存介质来说非常痛苦。

因此应用程序应该尽可能大块地写入数据。理想的写块大小和对齐方式是扇区大小，簇大小是最好的。当然，应用程序和存储设备之间的所有层都必须考虑多扇区写入，但是大多数开源存储卡驱动程序都没有。不要将多扇区写入请求拆分为单个扇区写入事务，否则写入吞吐量会变差。请注意，FatFs 模块及其示例磁盘驱动程序支持多扇区读/写操作。

强制内存擦除

当使用 f_unlink 函数删除文件时，该文件占用的数据簇在 FAT 上被标记为“空闲”。但是包含文件数据的数据扇区并没有应用任何处理，因此剩下的文件数据占据了闪存阵列的一部分作为“活动块”。
如果删除文件时可以擦除文件数据，则这些数据块将变成空闲块池。这可能会在下一次写入操作时跳过对数据块的内部块擦除操作。因此，写入性能可能会得到改善。 FatFs 可以通过将 FF_USE_TRIM 设置为 1 来管理此功能。请注意，由于此效果来自存储设备内部过程的预期，因此并不总是有效。大多数应用程序不需要此功能。此外，f_unlink 函数在删除大文件时可能需要一些时间。

临界区

如果对FAT卷的写操作由于意外故障而中断，例如突然停电、错误的介质移除和不可恢复的磁盘错误，卷上的FAT结构可能会被破坏。下图显示了FatFs模块的关键部分。

红色部分的中断会导致交联;因此，被更改的对象可能会丢失。如果黄色部分发生中断，下面列出了一种或多种可能性。

正在重写的文件数据被折叠。
追加的文件返回初始状态。
新建的文件消失了。
创建为新的或被覆盖的文件保留，但没有内容。
由于丢失了集群，磁盘使用效率变得更差。

每种情况不影响任何未以写模式打开的文件。为了最小化数据丢失的风险，可以通过最小化以写模式打开文件的时间或使用f_sync函数来最小化临界区，如图5所示。

FatFs项目的各种可用功能

这些是fatf api扩展使用的例子。当发现有用的代码示例时，将添加新的项目。

打开或创建追加文件(由R0.12添加的FA_OPEN_APPEND标志取代): http://elm-chan.org/fsw/ff/res/app1.c
删除非空子目录(适用于R0.12及以后版本): http://elm-chan.org/fsw/ff/res/app2.c
创建连续文件（被R0.12添加的f_expand函数取代）: http://elm-chan.org/fsw/ff/res/app3.c
测试文件是否连续: http://elm-chan.org/fsw/ff/res/app5.c
存储设备控制模块的兼容性检查器: http://elm-chan.org/fsw/ff/res/app4.c
存储设备控制模块的性能检查器: http://elm-chan.org/fsw/ff/res/app6.c
FAT 容器镜像文件创造器（预创建内置FAT卷）: http://elm-chan.org/fsw/ff/res/mkfatimg.zip
虚拟驱动器功能（请参阅ffsample.zip中的lpc176x/）: http://elm-chan.org/fsw/ff/ffsample.zip
嵌入式Unicode字符串实用程序（OEMxxx→Unicode、Unicode→OEMxxx、Unicode→Unicode）: http://elm-chan.org/fsw/ff/res/uniconv.zip

关于FatFs许可证

FatFs已被开发为作者ChaN的个人项目。它不受任何其他人在当前版本中编写的代码的影响。下面的代码块显示了源文件中包含的FatFs许可证文档的副本。

/*----------------------------------------------------------------------------/
/  FatFs - 通用FAT文件系统模块  Rx.xx                               /
/-----------------------------------------------------------------------------/
/
/ Copyright (C) 20xx, ChaN, all right reserved.
/
/ FatFs模块是一个开源软件。只要满足以下条件，允许以源和二进制
/ 形式重新分发和使用FatFs，无论是否进行修改：/ 1. 重新分发源代码必须保留上述版权声明、本条件和以下免责声
/    明。/ 本软件由版权持有人和贡献者“按原样”提供，与本软件相关的任何
/ 保证均不承担。版权所有人或贡献者对使用本软件造成的任何损害
/ 不承担责任。
/----------------------------------------------------------------------------*/

FatFs Module Application Note的翻译相关推荐

PyMOTW-3 (Python 3 Module of the Week) 翻译团队召集
自翻译起始已经一个月过去了,目前翻译进度三分之一,PyMOTW 篇幅很大,翻译 PyMOTW 是一个偏大的工程,大概 140 篇文章,并且每篇文章里内容详实,例如这篇正则表达式的文章: https:/ ...
HUAWEI MH5000-31 5G LGA Module Application Guide-(V100R001_01, English)
本文档旨在为客户选择适当的命令序列以更快的方式开始使用MH5000-31模块提供参考. 本文件还载有实例相关的描述. 1.2基本的AT指令处理原则 1.2.2 AT Command Processi ...
音乐社会计算机英语,计算机音乐技术应用,Computer music technology application,音标,读音,翻译,英文例句,英语词典...
补充资料:计算机音乐计算机音乐 computer music J ISUQn,1 ylnyUe计算机音乐(c伽mputer~ic)利用计算机进行音乐信息处理的技术.计算机具有强大的信息处理能力,而音 ...
LTE Module User Documentation（翻译6）——物理误差模型、MIMO模型、天线模型
LTE用户文档 (如有不当的地方,欢迎指正!) 9 PHY Error Model 物理误差模型包含数据误差模型和下行控制误差模型,两者默认为激活.可以使用 ns-3 属性系统去激活,具体为: C ...
LTE Module User Documentation（翻译5）——Mobility Model with Buildings
LTE用户文档 (如有不当的地方,欢迎指正!) 8 Mobility Model with Buildings 我们现在通过例子解释如何在 ns-3 仿真程序中使用 buildings 模型(特别是 ...
LTE Module User Documentation（翻译7）——无线环境地图（REM）、AMC 模型和 CQI 计算...
LTE用户文档 (如有不当的地方,欢迎指正!) 12 Radio Environment Maps 通过使用类 RadioEnvironmentMapHelper 是可能输出文件 Radio Env ...
LTE Module User Documentation（翻译12）——X2切换（X2-based handover）
LTE用户文档 (如有不当的地方,欢迎指正!) 18 X2-based handover 正如 3GPP 定义的,切换是改变用户服务小区的连接方式的过程.这一过程中涉及的两个基站通常称为源基站和目 ...
linux模块移植到freertos,FATFS在嵌入式操作系统FreeRTOS中的移植与应用
摘要: FreeRTOS作为一款免费的实时操作系统,系统内核小.裁剪方便.移植性好,广泛应用于对成本敏感的小型嵌入式系统中,但是FreeRTOS本身不带文件管理功能,不便于很多需要经常进行文件存储与 ...
3.1、CUBEMX使用FATFS读写SPI_FLASH
所需工具 CUBEMX5.6 STM32F103ZET6开发板(正点原子战舰) LINK及其他线束 1.CUBEMX设置设置RCC 切记选择第三个,否则串口无法使用. 设置串口设置SPI_FLAS ...

FatFs Module Application Note的翻译