Что такое TARFS?

TARFS - это read-only файловая система для семейства процессоров ESP32, основанная на формате TAR-архивов. TARFS позволяет использовать обычный .tar файл как файловую систему без распаковки - .tar файл записывается в раздел flash также, как туда записывается файловая система FAT/SPIFFS/LittleFS , созданная при помощи соответсвубщих утилит.

Файлы внутри файловой системы, после монтирования будут доступны через POSIX функции (open()/fopen(), read()/fread(), mmap(), opendir() и т.д.).

Почему был выбран формат TAR?

TAR - это последовательный архивный формат с простой структурой хранения данных, не использущющий централизованные таблицы размещения или структуры метаданных. Заголовок каждого файла содержит полный путь к нему, благодаря чему каждая запись архива является самодостаточной и может быть обнаружена независимо от остальных:

Повреждение записи каталога или метаданных не влияет на доступ к другим файлам,
поскольку иерархия каталогов восстанавливается по полным путям файлов, а не по явным связям
между родительскими и дочерними каталогами.

TAR-архивы могут создаваться и обрабатываться стандартными утилитами, что избавляет от необходимости использовать специализированные генераторы образов или утилиты конвертации.

Кроме того, все заголовки TAR выровнены по границе 512 байт, что упрощает анализ поврежденных архивов и позволяет находить записи файлов путем последовательного сканирования образа в поисках корректных заголовков TAR.

Насколько быстро работает TARFS?

Для тестовой файловой системы из 620 файлов и 20 каталогов, общим размером 12 мегабайт результаты тестирования оказались следующими:

Скорость открытия файлов от 21 до 92 микросекунд на каждый open(): в зависимости от того, используется PSRAM или нет
Скорость монтирования файловой системы: 66 миллисекунд
Скорость чтения read() примерно в 8-10 раз выше чем у FAT и LittleFS, в той же конфигурации: скорость чтения составляет 26 мегабайт в секунду для сценария, когда мы читаем 1 большой файл в буффер по одному килобайту.

File system	read()¹	open()	opendir()	readdir()	mount time
TarFS	26 MiB/s¹	21..92 µs²	27..102µs²	49 µs³	66 ms
LittleFS	~2.24 MiB/s	5740 µs	3182 µs	1688 µs	1600 ms

¹ Скорость измерялась при чтении файла размером 4 МБ блоками по 1 КБ в плотном цикле.

² Меньшие значения получены при размещении индекса файлов в DRAM. Большие значения - при размещении индекса в PSRAM. При повторном вызове open() для PSRAM скорость становится такой же, как при работе без PSRAM.

³ Время не зависит от того, находится индекс в DRAM или PSRAM: opendir() "прогревает" кэш, поэтому последующие вызовы readdir() работают уже из кеша.

Тестовая конфигурация

Hardware: ESP32-S3
CPU: 240 MHz
Flash: 16 MiB, Quad SPI
PSRAM: 8 MiB OPI
Filesystem: 12 MiB TAR archive
Entries: 640 total

Как начать пользоваться TARFS?

Создайте файловую систему - TAR-архив с вашими файлами (в примере файлы расположены в каталоге www):

tar cf www.tar www/

При необходимости добавьте проверку целоснтости CRC64:

tarsum www.tar

Прошейте TARFS-раздел во Flash ESP32.
В скетче вызовите:

tarfs_init();

tarfs_mount(Flash_Partition_Name, Mount_Point, NULL, NULL);

tarfs_mount

int tarfs_mount(const char *label, const char *mountpoint, const char *link_rebase, const char *path_rebase)

Actual mount procedure We expect sane label pointer (ASCIIZ) and a sane mountpoint (i....

Definition fs.c:449

После этого все ваши файлы будут доступны через TARFS.

Как добавить защиту CRC64 в .tar файл?

Запустите утилиту tarsum:

tarsum filesystem.tar output.tar

Затем включите проверку целостности, раскомментировав следующую строку в src/config.h:

#define CONFIG_TARFS_INTEGRITY 1

Если CONFIG_TARFS_INTEGRITY отключен, встроенные контрольные суммы CRC64 будут проигнорированы при монтировании.

Утилита tarsum может быть собрана в Linux и Windows (Cygwin) с помощью команды make, выполненной в каталоге tarsum.

Я запустил tarsum два раза для одного и того же файла. Будет ли он монтироваться?

Да, будет.

Tarsum обнаруживает уже существующие записи CRC64 и обновляет их вместо создания дубликатов.

Есть ли простой способ определить, содержит ли TAR-архив контрольные суммы CRC64?

Да.

Откройте архив в текстовом или hex-редакторе и выполните поиск ASCII-строки "C64". TAR-архив, обработанный утилитой tarsum, будет содержать несколько таких сигнатур C64.

Примечание: Сигнатура C64 предназначена только для диагностических целей. TARFS игнорирует её при монтировании и всегда использует встроенное поле CRC64, если включена опция CONFIG_TARFS_INTEGRITY.

Как прошить TARFS image в ESP32?

На Windows:

esptool.exe --chip esp32 --port COM5 --baud 921600 write_flash 0x310000 tarfile.tar

На Linux

esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 921600 write_flash 0x310000 tarfile.tar

Замените:

COM5 или /dev/ttyUSB0 на реальный порт
0x310000 на реальное смещение из файла partitions.csv.

Что такое partitions.csv?

partitions.csv - это описание расположения разделов Flash ESP32.

В нем указано:

где находится приложение;
где NVS;
где OTA;
где находится ваш TARFS image;
размер каждого раздела.

ESP-IDF использует этот файл для создания бинарной таблицы разделов. (Espressif Documentation) Пример файла находится в examples/tarfs/partitions.csv

Где должен находиться partitions.csv?

Arduino IDE

Положите partitions.csv рядом с вашим .ino файлом:

MySketch/
│
├── MySketch.ino
│
└── partitions.csv

Arduino ESP32 framework автоматически использует этот файл при сборке. (Поддержка пользовательских CSV-разделов основана на механизме таблиц разделов ESP-IDF.) (Espressif Documentation)

ESP-IDF

Обычно файл находится в корне проекта:

my_project/
│
├── main/
│   └── main.c
│
├── partitions.csv
│
└── CMakeLists.txt

В menuconfig нужно выбрать:

Partition Table

Custom partition table CSV

и указать имя файла. (Espressif Documentation)

Нужно ли распаковывать TAR перед прошивкой?

Нет.

TARFS работает непосредственно с TAR-архивом.

Flash
 |
 +-- TARFS partition
       |
       +-- filesystem.tar
              |
              +-- file1.txt
              +-- image.png
              +-- index.html

Можно ли использовать обычные TAR-инструменты?

Да.

Создание архива:

tar cf fs.tar directory/

Просмотр содержимого:

tar tf fs.tar

Извлечение:

tar xf fs.tar

Можно ли писать в TARFS?

Нет.

Я все сделал, как написано в документации, но ничего не работает

Отредактируйте файл src/config.h библиотеки tarsf, расскоментируйте строку #define CONFIG_TARFS_LOG 1, пересоберите свой проект. Теперь в терминал будут попадать отладочные сообщения, по которым можно попытаться определить причину неудач

Сколько RAM занимает TARFS?

TARFS использует небольшой индекс файлов.

Размер зависит от количества файлов.

Например:

несколько сотен файлов - обычно несколько килобайт RAM;
тысячи файлов - порядка десятков килобайт.

А что с многопоточностью?

Дополнительная синхронизация не нужна - в файловой системе все уже сделано: C11 Atomics и reference counters.

Портируем ли TARFS на другие платформы?

Да. TARFS написан на стандартном C11, не использует специфичных для GCC расширений языка и компилируется без изменений в окружении Cygwin.

Для портирования TARFS на другую архитектуру необходимо реализовать файл os_<arch>.c. В качестве примеров предоставлены реализации для ESP32 и STM32 — os_esp32.c и os_stm32.c. Реализация для STM32 приведена главным образом для иллюстрации принципа портирования.

Основная функция, которую необходимо реализовать, — tarfs_os_map_tarfile(). Эта функция должна возвращать адрес, по которому располагается TAR-архив. Кроме того, она может выполнять отображение адресного пространства Flash в RAM, как это реализовано в os_esp32.c.

Такая абстракция позволяет TARFS работать с TAR-архивами независимо от того, где физически хранятся исходные данные.