1
SPIFFS（SPI Flash File System）是一种专为 SPI NOR Flash
2
设计的嵌入式文件系统，特点：
3

4
┌──────────────────────────────────────────────────────┐
5
│  特性                  说明                           │
6
├──────────────────────────────────────────────────────┤
7
│  磨损均衡（Wear Leveling）│  均匀分布擦写，延长 Flash 寿命 │
8
│  掉电安全                │  写操作不会破坏已有数据       │
9
│  静态开销小              │  RAM 占用仅取决于打开文件数    │
10
│  不支持目录              │  所有文件在根目录，扁平结构    │
11
│  无 POSIX 权限           │  不支持 chmod/chown 等权限    │
12
└──────────────────────────────────────────────────────┘
13

14
工作方式：
15
  直接将 NOR Flash 的一个分区作为文件系统空间，
16
  不需要额外的 Flash Translation Layer（FTL），
17
  SPIFFS 自身直接管理 Flash 页的分配和回收。

1
SPIFFS 分区布局：
2

3
┌────────────────────────────────────────────┐
4
│  逻辑块 0   │ 逻辑块 1   │ ... │ 逻辑块 N-1   │
5
│ (4KB)      │ (4KB)     │     │ (4KB)       │
6
└────────────────────────────────────────────┘
7

8
每个逻辑块内部：
9
┌─────────────────────────────────────────────┐
10
│  页 0 (256B) │ 页 1 │ ... │ 页 15 │
11
└─────────────────────────────────────────────┘
12

13
特点：
14
- 最小分配单元：逻辑页（256 字节）
15
- 最小擦除单元：逻辑块（4KB）
16
- 文件索引存储在 Flash 内部，不需要额外 RAM

1
app_main()                                    [main/main.c]
2
  ├── lcd_init()                              [components/LCD/lcd.c]
3
  │     └── spi2_init()                        [components/SPI/spi.c]
4
  │           └── spi_bus_initialize(SPI2_HOST)
5
  │
6
  ├── ifs_init()                              [components/SPIFFS/ifs.c]
7
  │     └── esp_vfs_spiffs_register(&conf)     [ESP-IDF: esp_spiffs]
8
  │           ├── 根据 partition_label="storage" 找到分区
9
  │           ├── 调用 SPIFFS 库进行文件系统挂载
10
  │           └── 注册 VFS，挂载到 /spiffs 路径
11
  │
12
  ├── fopen("/spiffs/test.txt", "w")          [标准 C 库 → VFS → SPIFFS]
13
  ├── fprintf(f, "%s", test_string)           [标准 C 库 → VFS → SPIFFS]
14
  ├── fclose(f)                               [标准 C 库 → VFS → SPIFFS]
15
  │
16
  ├── fopen("/spiffs/test.txt", "r")          [标准 C 库 → VFS → SPIFFS]
17
  ├── fgets(buf, sizeof(buf), f)              [标准 C 库 → VFS → SPIFFS]
18
  └── fclose(f)                               [标准 C 库 → VFS → SPIFFS]

1
app_main()
2
  │
3
  └── fopen("/spiffs/test.txt", "w")
4
        │
5
        ▼
6
      VFS 层（Virtual File System）
7
        │  ┌───────────────────────────────────────┐
8
        │  │ 根据路径前缀 /spiffs 匹配已注册的        │
9
        │  │ SPIFFS VFS 驱动                       │
10
        │  └───────────────────────────────────────┘
11
        │
12
        ▼
13
      SPIFFS 库（spiffs）
14
        │  逻辑页分配 → 逻辑块管理 → 磨损均衡
15
        │
16
        ▼
17
      SPI Flash 驱动（spi_flash）
18
        │  Flash 读取 / 擦除 / 写入
19
        │
20
        ▼
21
      ESP32-S3 内置 SPI NOR Flash
22
        │  物理介质

1
esp_vfs_spiffs_register(&conf)
2
  │
3
  ├── 1. 查找分区
4
  │     esp_partition_find_first(
5
  │         type=ESP_PARTITION_TYPE_DATA,
6
  │         subtype=ESP_PARTITION_SUBTYPE_DATA_SPIFFS,
7
  │         label="storage"
8
  │     )
9
  │     → 找到 partitions_user.csv 中定义的 storage 分区
10
  │
11
  ├── 2. 调用 SPIFFS 库挂载
12
  │     spiffs_mount(&fs, &cfg, ...)
13
  │     → 读取/验证 SPIFFS 元数据
14
  │     → 如果 format_if_mount_failed=true 且挂载失败，
15
  │       则调用 spiffs_format() 重新格式化
16
  │
17
  ├── 3. 注册到 VFS
18
  │     esp_vfs_register("/spiffs", &vfs, NULL)
19
  │     → 让 fopen("/spiffs/xxx") 路由到 SPIFFS 驱动
20
  │
21
  └── 4. 返回 ESP_OK 或错误码

1
void app_main(void)
2
{
3
    const char *test_string = "Hello SPIFFS!";
4

5
    // 1. 初始化 LCD（底层依赖 SPI 总线）
6
    lcd_init();
7

8
    // 2. 初始化 SPIFFS（挂载 Flash 文件系统）
9
    ifs_init();
10

11
    // 3. 写文件
12
    lcd_show_string(1, 1, "read_buf:", GREEN, BLACK);
13
    FILE *f = fopen("/spiffs/test.txt", "w");
14
    if (f != NULL)
15
    {
16
        fprintf(f, "%s", test_string);
17
        fclose(f);
18
    }
19

20
    // 4. 短暂延时（确保文件写完）
21
    vTaskDelay(pdMS_TO_TICKS(10));
22

23
    // 5. 读文件并显示到 LCD
24
    f = fopen("/spiffs/test.txt", "r");
25
    if (f != NULL)
26
    {
27
        char buf[128];
28
        fgets(buf, sizeof(buf), f);
29
        fgets(buf, sizeof(buf), f);
30
        lcd_show_string(2, 1, buf, BLUE, BLACK);
31
        fclose(f);
32
    }
33

34
    while(1) { vTaskDelay(1000); }
35
}

1
1. lcd_init()           → 初始化 SPI2 总线 + LCD 控制器（参考第 7 章笔记）
2

3
2. ifs_init()           → 挂载 SPIFFS 到 /spiffs
4
    └── esp_vfs_spiffs_register()
5

6
3. fopen("/spiffs/test.txt", "w")
7
    ├── VFS 匹配 /spiffs 路径前缀
8
    ├── SPIFFS 在 Flash 中创建/打开文件
9
    └── 返回 FILE*，可写
10

11
4. fprintf(f, "%s", "Hello SPIFFS!")
12
    ├── 标准 C 格式化写入
13
    └── 数据经 VFS → SPIFFS → spi_flash 驱动写入 Flash
14

15
5. fclose(f)            → 关闭文件，刷新缓冲区
16

17
6. vTaskDelay(10ms)     → 确保文件系统完成写入操作
18

19
7. fopen("/spiffs/test.txt", "r")
20
    └── 以只读方式重新打开同一文件
21

22
8. fgets() × 2
23
    → 第一次 fgets 读取文件内容
24
    → 第二次 fgets 返回 NULL（文件已读完）
25
    → buf 中保留第一次读取到的字符串
26

27
9. lcd_show_string(2, 1, buf, BLUE, BLACK)
28
    → LCD 第 2 行第 1 列显示 "Hello SPIFFS!"（蓝色字）
29

30
10. fclose(f) + while(1) → 关闭文件并进入空闲循环

1
esp_vfs_spiffs_register() 的内部逻辑：
2

3
     挂载 SPIFFS 分区
4
          │
5
          ▼
6
     ┌─────────────┐
7
     │  挂载成功？  │──── 是 ──→ 返回 ESP_OK
8
     └──────┬──────┘
9
            │ 否
10
            ▼
11
     ┌────────────────────┐
12
     │ format_if_mount_   │
13
     │ failed == true ？  │──── 否 ──→ 返回 ESP_FAIL
14
     └──────┬─────────────┘
15
            │ 是
16
            ▼
17
     ┌─────────────────┐
18
     │ 格式化 SPIFFS 分区│
19
     │ 然后重新挂载     │
20
     └────────┬────────┘
21
              │
22
              ▼
23
         返回 ESP_OK

1
SPIFFS 方案（本章 19_SPIFFS）：
2
┌──────────────┐     ┌──────────┐     ┌──────────────┐
3
│   app_main   │────→│   VFS    │────→│   SPIFFS     │
4
│ fopen/fgets  │     │ /spiffs  │     │   库          │
5
└──────────────┘     └──────────┘     └──────┬───────┘
6
                                             │
7
                                    ┌────────▼───────┐
8
                                    │  spi_flash 驱动 │
9
                                    └────────┬───────┘
10
                                             │
11
                                    ┌────────▼───────┐
12
                                    │ 内置 SPI NOR    │
13
                                    │ Flash (16MB)    │
14
                                    └────────────────┘
15

16
SD 卡方案（第 17 章 17_SPITF）：
17
┌──────────────┐     ┌──────────┐     ┌──────────────┐
18
│   app_main   │────→│   VFS    │────→│   FatFs      │
19
│ fopen/fgets  │     │ /sdcard  │     │   库          │
20
└──────────────┘     └──────────┘     └──────┬───────┘
21
                                             │
22
                                    ┌────────▼───────┐
23
                                    │  sdmmc 协议层   │
24
                                    └────────┬───────┘
25
                                             │
26
                                    ┌────────▼───────┐
27
                                    │  SPI 主机驱动   │
28
                                    └────────┬───────┘
29
                                             │
30
                                    ┌────────▼───────┐
31
                                    │  外置 SD 卡     │
32
                                    │ (GPIO 2/35/36/37)│
33
                                    └────────────────┘