在主机上生成和解析 FATFS

本章主要面向 Python 工具 fatfsgen.py 和 fatfsparse.py 的开发人员、对这些工具感兴趣的用户、和对在 ESP-IDF 中实现 FAT 文件系统感兴趣的用户。如果你对这些工具感兴趣，请参考 FatFs 分区生成器。

FAT 文件系统由多个逻辑单元组成。这些单元用于存储有关文件系统、分配、文件内容、目录以及文件元数据的一般信息。 fatfsgen.py 和 fatfsparse.py 工具用于实现 FAT 文件系统，该工具会考虑上述所有逻辑单元，并且支持磨损均衡。

FAT 文件系统生成器及解析器的设计

本节介绍了 FAT 文件系统生成器和解析器设计的特定单元，设计这些单元是为了创建一个专注于宏操作的有效 FAT 结构模型，用于生成和解析整个分区，而无需在运行（挂载）过程中进行修改。

FAT 文件系统生成器及解析器设计架构

FATFS 类

FATFS 类是建立 FAT 文件系统模型最常用的实体，由 FATFSState （保存元数据和引导扇区）、 FAT （保存文件分配表）和 Directory （表示 FAT12 和 FAT16 所需的根目录）组成。该类可以处理分区的所有要求，分析用于将其转换为二进制映像的本地文件夹，并生成本地文件夹的内部表示。然后，该类就能从内部 FAT 文件系统模型中生成二进制映像。

WLFATFS 类

WLFATFS 类扩展了 FATFS 类的功能，可在磨损均衡中添加虚拟扇区（用于平衡负载的冗余扇区，参见 磨损均衡）、配置扇区和状态扇区，从而对文件系统进行封装。WLFATFS 类还能生成带有初始化的磨损均衡层的二进制 FATFS 分区，并提供了完全删除磨损均衡的选项，用于进一步分析。该类可由 wl_fatfsgen.py 脚本进行实例化并调用。

BootSectorState 类

BootSectorState 实例包含了构建引导扇区和 BPB（BIOS 参数块）所需的元数据。构件引导扇区主要是为了实现跨平台兼容，即当 ESP 芯片组连接到其他平台时，会始终遵守所有的 FAT 文件系统标准。但是，在分区生成期间，芯片并不消耗此引导扇区的数据和其他所需数据，因为这些数据是不变的常量。换句话说，一般无需更改前缀为 "BS" 的字段，且更改通常没有作用。如需添加新功能，应关注前缀为 "BPB" 的字段。 BootSectorState 类还有一个重要作用，即在整个类系统中共享对元数据和二进制镜像的访问。因此，系统中的每个类都可以访问这一单例。

FATFSState 类

FATFSState 类未来可能会被弃用，开发人员可以将其功能转移到 BootSectorState 中。该类包含对 BootSectorState 的引用，并且在创建引导扇区时，会用一些未知或不必要的信息（例如在文件系统支持长文件名时生成的信息）扩展引导扇区数据。

FAT 类

FAT (File Allocation Table) 代表文件分配表，是分布在一个或多个扇区上的字节序列。扇区数由簇数决定，并由 utils.py 中的函数 get_fat_sectors_count 计算得出，因为在引用文件系统中的物理簇时，每个 FAT 的扇区数应越少越好。FAT 的工作方式如下：对于每个位于 i * some_constant 地址的物理簇，FAT 在第 i 个位置有一个条目，表示文件链中下一个簇的地址。每个 FAT 文件系统版本使用的 FAT 条目大小不同。FAT12 每个条目大小为 12 位，因此每 2 个条目占据 3 个字节。FAT16 的每个条目为 16 位，因此每 1 个条目占据 2 个字节。FAT32 的 每个 FAT 条目为 32 位，因此每 1 个条目占据 4 个字节。所有条目都按小字节顺序排列。

第 i 个条目处的所有 0 表示相应的簇为空闲状态，第 i 个条目处的所有 1 表示相应簇已占用，并且是文件链中的最后一个簇。 第 i 个条目处的其他数字表示下一个簇在文件链中的地址。这些簇并不一定存储在内存中的相邻位置，而通常会分散在整个数据区域中。

在生成分区时，文件会被分为几个部分以适应簇的大小。注意，文件的结构分配是一个链表。文件分配链中的每个簇在 FAT 中都有一个条目指向下一个簇，或文件链中最后一个簇的信息。如前所述，FAT12 的每个 FAT 条目有 12 位，因此最多可以枚举 4096 个簇，因为在 12 位（一个半字节）条件下最多可以列出 4096 个簇。但实际上由于其他开销，FAT12 最多可以有 4085 个簇。同样，FAT16 最多可以有 65525 个簇，而 FAT32 最多可以有 268435445 个簇，因为实际上每个条目只用了 32 位中的 28 位。即便文档中声称可行，但实际上目前的实现方式不允许将簇数少于 4085 的 FAT 文件系统强制重新定义为 FAT16。反之亦然，将具有 4085 个以上簇的 FAT 文件系统强制重新定义为 FAT12 也是没有意义的，否则将无法访问某些地址超出范围的簇。

Cluster 类

Cluster 类用于访问 FAT 条目和相应的物理簇。 FAT 类是特定数量 Cluster 实例的集合。每个簇具有一个唯一 ID，用于确定其在 FAT 中的位置和在数据区中的相应扇区。分配簇时，分配链中的第一个簇会指向一个文件或目录。每个簇中包含该簇是否为空的信息，以及该簇是否为文件分配链中的最后一个簇。如果不是最后一个簇，则指向链表中下一个簇。在实际应用中，簇不需要访问其中的文件，而是反过来由 文件 或 目录 访问对应的簇，以检索链上可能的全部内容。

Directory 类

Directory 类表示文件系统目录。 Directory 的实例包含对相应 Cluster 实例的引用，该实例中有给定目录的分配链中的第一个簇。根目录较为特殊，其扇区数量不同，实例化过程也有所不同。不过，根目录仍然是此类的实例，也是分别与 FATFS 类和 WLFATFS 类相关联的唯一 Directory 实例。 Directory 类（除根目录外）与在父目录中定义其条目的 Entry 类一对一的关联。此外，由于每个目录都包含由实际目录内容组成（如别名、文件和目录）的多个条目，因此，它还有一个与 Entry 类关联的聚合。

File 类

与 Directory 类似， File 代表文件系统中的单个文件。此类与其分配链中的第一个簇一对一关联。通过这个簇， File 类可以访问相应的物理地址，从而修改其内容。每个文件还与属于其父目录的 Entry 实例具有一对一关联。

Entry 类

Entry 类封装了在相应父目录数据区中的文件名或目录名信息。每个文件系统实体（文件/目录）都有一个条目。如果使用符号进行连接，可以让实体具有多个条目。目录使用条目来访问其后代文件和子目录，并实现对树状结构的遍历。此外， Entry 还保存了所用文件名（长文件名或 8.3 文件名）相关的名称、扩展名、大小等信息。

fatfsgen.py

组件 fatfsgen.py 在主机上生成 FAT 文件系统。

fatfsgen.py 递归式地遍历给定文件夹的目录结构，将文件和（或）目录添加到二进制分区中。用户可以设置脚本生成的分区是否支持磨损均衡和长文件名，以及是否保留原始文件夹在主机上的修改日期和时间。

./fatfsgen.py Espressif 命令默认生成一个简单的二进制分区。这里 Espressif 是生成二进制映像的本地文件夹（包含文件和/或子目录）。

fatfsgen.py 和 wl_fatfsgen.py 脚本都可以用于此目的，二者的区别在于， wl_fatfsgen.py 首先用 fatfsgen.py 生成分区，然后再初始化磨损均衡。

脚本命令行参数如下:

fatfsgen.py [-h] [--output_file OUTPUT_FILE] [--partition_size PARTITION_SIZE] [--sector_size {4096}] [--long_name_support] [--use_default_datetime] input_directory

--output_file：生成的二进制分区的路径
--partition_size：定义二进制分区大小（十进制、十六进制或二进制）
--sector_size：扇区大小
--long_name_support：flag，表示支持长文件名
--use_default_datetime：flag，强制使用默认的日期和时间 (date == 0x2100, time == 0x0000)，不使用参数保留原始文件系统元数据
input_directory：必填参数，编码到二进制分区 fat-compatibile 的目录名称

fatfsparse.py

fatfsparse.py 将二进制映像转换成内部表示，并在主机上生成具有等效内容的文件夹。如果要求解析分区具有初始化磨损均衡， fatfsparse.py 会使用 wl_fatfsgen.py 提供的 remove_wl 函数删除磨损均衡扇区。删除扇区后，对分区的解析和没有初始磨损均衡的情况相同。

./fatfsparse.py fatfs_image.img 命令会生成与二进制数据映像 fatfs_image.img 具有等效内容的目录。

脚本命令行参数如下:

fatfsparse.py [-h] [--wl-layer {detect,enabled,disabled}] input_image

--wl-layer：表示是否启用、禁用或应检测磨损均衡（模糊检测）
input_image：二进制映像的路径

长文件名可以自动检测，但无法 100% 检测出磨损均衡，因为根据用户的上下文，一个分区在有或没有磨损均衡的情况下都是有效的。脚本找到磨损均衡扇区（cfg 和 state）时，会假设磨损均衡已启用，但实际不一定启用。

支持功能

FAT12/FAT16

支持 FAT12 和 FAT16。对于较小的分区，使用 FAT12 即可。具体选择根据检测簇数决定，用户无法进行更改。如果分区簇数小于 4085，会选择 FAT12（FAT 的条目为 12 位）。如果分区簇数在 4085 到 65526 之间（不包括 4085 和 65526），会选择 FAT16。目前 fatfsgen.py 或 fatfsparse.py 不能处理簇数超过 65525 的文件系统。

磨损均衡

与磨损均衡层相关的操作有两个，即初始化磨损均衡记录，和在生成及解析 FAT 文件系统映像时删除磨损均衡记录。

1. 初始化磨损均衡

生成支持磨损均衡的新映像时，脚本会初始化磨损均衡功能所需的几个额外扇区。

• 虚拟扇区：位于分区起始位置的空扇区，文件系统挂载时会被忽略。虚拟扇区复制下一个扇区的内容，在特定数量的擦除周期后，与下一个扇区交换位置（如果虚拟扇区已是最后一个扇区，则与第一个扇区交换位置）。这样，每个 FAT 文件系统扇区会遍历整个 flash 分区，而与此扇区对应的擦除周期也会分布在整个 flash 上。

• 状态扇区：状态扇区存储了 64 字节的数据。

  • pos：虚拟扇区的位置

  • max_pos：分区中的扇区数（不包括配置扇区和状态扇区）

  • move_count：表示虚拟扇区遍历整个 flash 的次数

  • access_count：虚拟扇区交换位置前的扇区擦除周期数

  • max_count：等于 wl_config_t::updaterate

  • block_size：等于 wl_config_t::page_size

  • version：等于 wl_config_t::version

  • device_id：在状态扇区次初始化时随机生成

  • reserved：7 x 32 位，设置为 0

  • crc32：前面所有字段的 crc32，包括保留字段

此外，状态扇区会对每个 pos 值增加 16 字节的 pos update record。该记录会帮助确定虚拟扇区的位置。

由于状态扇区的 erase + write 不是原子操作，在 “erase” 和 “write” 之间断电可能会导致数据丢失。不过状态扇区保留了两份副本，可以在断电后帮助复原。每次更新时两份副本都会更新，因此，断电后可以恢复原来的有效状态扇区。

• 配置扇区：此扇区包含磨损均衡层使用的分区信息。

  • start_addr：分区的起始地址（始终为 0）

  • full_mem_size：分区大小，包括数据、虚拟、状态 x 2 和配置扇区，单位为字节

  • page_size：等于扇区大小（通常为 4096）

  • sector_size：对于 ESP-IDF 支持的 NOR flash 类型，始终为 4096

  • updaterate：ESP-IDF 始终将此值设置为 16。需要时可将其用作配置选项

  • wr_size：始终设置为 16

  • version：当前版本为 2

  • temp_buff_size：始终设置为 32（实际不应该存储在 flash 中）

  • crc：之前所有值的 crc32

2. 删除磨损均衡 删除磨损均衡记录时，须找到虚拟扇区的位置以及分区的原始有效顺序（因为遍历虚拟扇区会打乱分区）。脚本可以从分区中删除其他磨损均衡扇区。删除磨损均衡记录的步骤如下：

• 找到虚拟扇区位置 pos。该位置由状态扇区中 pos update records 的数量决定。

• 删除虚拟扇区并合并虚拟扇区前后的剩余扇区，从而创建新映像。

• 删除分区末尾的磨损均衡状态扇区和配置扇区。

• 对新映像重新排序以获得其原始顺序。 move_count 可以找到分区的起点。分区会从 end_of_partition - move_count 位置开始，因此删除磨损均衡扇区后，分区的起始位置是 partition[end_of_partition - (move_count*page_size)]。

文件名编码

FAT 协议支持两种类型的文件名。

短文件名 (SFN)

文件名必须遵循 SFN 规范。SFN 指 8.3 文件名规范，即文件名为 8 个字符，扩展名为 3 个字符。这种模式不区分大小写，但在生成器的内部表示中，所有文件名都会改为大写。描述短文件名的条目长 32 字节，其结构如下:

Offset:   00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
0x000000: 46 49 4C 45 4E 41 4D 45 45 58 54 20 18 00 00 00    FILENAMEEXT.....
0x000010: 21 00 21 00 00 00 00 00 21 00 02 00 1E 00 00 00    !.!.....!.......

该条目表示当前文件名遵循 8.3 文件名规范 ("FILENAME.EXT") (0x00/00-0A)，文件名大小为 0x1E = 30 字节 (0x10/0x0C)，默认修改和创建时间为 (0x0021) (0x10/00，02 和 08)。文件相关的簇位于 0x02 (0x10/0A)。注意，每个字符用 1 个字节编码（例如，0x46 == 'F'）。

长文件名 (LFN)

长文件名 LFN 支持 255 个字符，不包括末尾的 NULL。LFN 支持短文件名中的任何字符，以及句点 . 和特殊字符 + , ; = [ ]。LFN 使用 UNICODE，因此每个字符用 2 个字节编码。

使用 LFN 编码的文件名称结构如下:

00003000: 42 65 00 2E 00 74 00 78 00 74 00 0F 00 43 FF FF    Be...t.x.t...C..
00003010: FF FF FF FF FF FF FF FF FF FF 00 00 FF FF FF FF    ................
00003020: 01 74 00 68 00 69 00 73 00 69 00 0F 00 43 73 00    .t.h.i.s.i...Cs.
00003030: 6C 00 6F 00 6E 00 67 00 66 00 00 00 69 00 6C 00    l.o.n.g.f...i.l.
00003040: 54 48 49 53 49 53 7E 31 54 58 54 20 00 00 D6 45    THISIS~1TXT...VE
00003050: 26 55 26 55 00 00 D6 45 26 55 02 00 1C 00 00 00    &U&U..VE&U......

上述示例展示了文件名 thisislongfile.txt 的编码。该记录由多个条目组成，第一个条目包含元数据，相当于 SFN 条目。如果文件名符合 8.3 文件名规范，该条目可能就是最后的条目，使用 SFN 文件名编码结构。否则，生成器会在 SFN 条目上方添加具有上述 LFN 结构的多个条目，其中包含有关文件名及其一致性校验和的信息。每个 LFN 可以容纳 13 个字符（26 字节）。文件名首先会被切分成一定数量的 13 个字符的子串，这些子串会被添加到 SFN 条目上方。

LFN 条目以逆序添加，因此，目录中的第一个条目是文件名的最后一部分，即 SFN 条目。在上述示例中，第一个条目包含文本 e.txt，而另外的条目包含文件名开头部分 thisislongfil。LFN 条目的第一个字节表示顺序或序列号（从 1 开始编号）。要确定 LFN 的第一个条目，第一个字节会被掩码为 0x40 (first_byte =| 0x40)。最后一个条目的值会与 0x40 进行 OR 运算，作为最后一个条目的标记。例如，当记录是 LFN 条目中的第二条也是最后一条时，其第一个字节是 0x42。

LFN 条目在 DIR_Attr 字段的值为 ATTR_READ_ONLY | ATTR_HIDDEN | ATTR_SYSTEM | ATTR_VOLUME_ID （参见文件 long_filename_utils.py ）。SFN 条目在此字段中包含 ATTR_DIRECTORY 或 ATTR_ARCHIVE （LFN 中可能也包含这两个值），分别表示目录或文件。

LFN 条目在 DIR_NTRes 字段上标记为 0x00。这是 SFN 条目在 LFN 记录中的标志，如果条目是一个完整 SFN 记录，值为 0x18。在第一个示例中，该字段中此值为 0x18，因为名称 "FILENAME.EXT" 同样符合 SFN 规范。然而，上一个示例 "thisislongfile.txt" 在最后一个条目的 DIR_NTRes 字段中值为 0x00，这是因为它仅符合 LFN 规范。SFN 须唯一。为此， fatfsgen.py 使用文件名的前 6 个字符，将其与 ~ 和一个 ID 相连接。这一 ID 表示该文件名在相同前缀的文件名中的顺序，范围 在 0 到 127 之间，127 是具有相同前缀的文件的最大数量。

校验和的计算在 utils.py 中由函数 lfn_checksum 描述并实现。 fatfsparse.py 假设 LFN 条目可能不会紧挨彼此，但保留了彼此的相对顺序。这一脚本首先用 DIR_NTRes 字段找到属于某个 LFN 记录的 SFN，然后开始在相应扇区自下而上进行搜索，直至找到 LFN 记录中的最后一个条目（前半字节等于 4 的条目）。脚本通过校验和来区分条目。这一过程结束后，即可组成文件名。

FAT 文件系统中的日期和时间

ESP-IDF 使用的 FAT 文件系统协议不保留芯片介质上的日期或时间，因此，从设备中提取的所有映像都具有相同的默认时间戳，这个时间戳会应用到所有 FAT 相关的日期和时间字段上，包括创建、最后修改时间戳，以及创建、最后修改和最后访问日期。

SFN 条目中有几个描述时间的字段，如 DIR_CrtTime 和 DIR_WrtTime 。ESP-IDF 的 FAT 实现过程会忽略一些字段（参见文件 entry.py），然而 DIR_WrtTime 和 DIR_WrtDate 字段的更改会保留在芯片中。时间和数据条目都是 16 位的，其中时间粒度为 2 秒。