Быстрый старт

TARFS хранит файловую систему в виде обычного архива POSIX TAR. Никаких специальных утилит для создания образов не требуется — достаточно стандартной GNU tar, с помощью которой можно создавать, изменять и распаковывать образы TARFS.

1. Создайте каталог файловой системы

На своей хост-машине создайте каталог, который станет корнем файловой системы. Его имя одновременно станет точкой монтирования.

Например: mkdir tarfs или в Windows средствами Проводника Windows

tarfs/

2. Заполните файловую систему

Скопируйте в этот каталог нужные файлы, подкаталоги, символические ссылки, жёсткие ссылки или (в Windows) - directory junctions.

Примечание

Будьте осторожны при создании символических ссылок с длинными именами в UTF-8. В зависимости от локали системы утилита tar может заменить не-ASCII символы на ??? внутри архива. Это ограничение самой программы-архиватора, а не TARFS.

Пример структуры файловой системы:

tarfs/
├── www/
│   └── index.html
└── ftp/
    └── pub/
        ├── drivers.tgz
        ├── docs.tgz
        └── runme!.exe

3. Создайте TAR-архив

Выполните команду:

tar -cf tarfile.tar tarfs

Она создаст архив tarfile.tar из каталога tarfs.

4. Запишите tarfile.tar в соответствующий раздел ESP с помощью esptool:

В ESP32 файловая система TARFS хранится в отдельном разделе Flash-памяти.

Для этого необходимо добавить соответствующий раздел в файл partitions.csv, после чего записать TAR-архив в этот раздел с помощью esptool.py. Если вы пользуетесь средой Arduino IDE, то файл partitions.csv должен находиться в каталоге вашего проекта, вместе с исходным кодом:

Main window

В настройках же IDE следует указать раскладку флеша - custom

Main window

Создайте файл partitions.csv в каталоге вашего скетча. Добавьте в partitions.csv раздел типа data.

Пример для 16MiB флеш, под файловую систему отдано примерно 13 мегабайт:

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x5000,
otadata,  data, ota,     0xe000,  0x2000,
app0,     app,  ota_0,   0x10000, 0x300000,
tarfs,    data, 0xF0,     0x310000,0xCE0000,

Поля имеют следующее назначение:

Поле	Описание
Name	Имя раздела. Используется при монтировании файловой системы.
Type	Должно быть data.
SubType	Любое значение для разделов типа data. Рекомендуется использовать 0xF0.
Offset	Адрес раздела во Flash-памяти.
Size	Максимальный размер TAR-архива.

Размер раздела должен быть не меньше размера создаваемого TAR-архива.

Запишите образ во Flash В Windows это делается командой

esptool.py --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.

5. Что дальше?

Теперь пишите свой скетч: Не забудьте добавить #include "tarfs.h" в исходный код своего .ino файла, а в функции setup() вызовете tarfs_init() и tarfs_mount() так же, как это делается в скетче-примере examples/tarfs/tarfs.ino

Если вы дочитали до этой строчки, значит шансы на успех весьма велики.

Выбор точки монтирования

Точка монтирования определяется автоматически по содержимому архива, но может быть так же задана вручную. ВНИМАНИЕ: если файловая система окажется повреждена, то автоматическое определение точки монтирования может не работать, поэтому, всегда следует указывать точку монтирования вручную, по крайней мере на "боевом" устройстве.

Для корректного автоопределения точки монтирования всегда создавайте корневой каталог (как описано в шаге 1), а затем размещайте внутри него всё содержимое файловой системы - имя этого каталога и станет точкой монтирования. В случае, если такая логика работы не подъодит, точка монтирования может быть переопределена при вызове функции tarfs_mount().

Контроль целостности данных

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

По умолчанию защищаются только заголовки TAR (метаданные inode). Каждый заголовок содержит стандартную контрольную сумму TAR, благодаря чему TARFS может обнаружить повреждение метаданных во время монтирования без каких-либо собственных расширений формата.

Если требуется более надёжная проверка, можно воспользоваться утилитой tarsum:

./tarsum input.tar [output.tar]

Как ее скомпилировать (она компилируется под Linux и Cygwin) Написано в README.md.

Она записывает дополнительный 8-байтный хеш в неиспользуемую область заполнения каждого TAR-заголовка. Хеш вычисляется на основе CRC64/ECMA182 и полностью незаметен для обычных TAR-утилит, поскольку эти байты игнорируются форматом TAR.

При монтировании архива, обработанного tarsum, TARFS автоматически обнаруживает встроенные хеши и проверяет целостность файловой системы. Эту проверку можно отключить, если важнее минимальное время монтирования.

ВАЖНО! Не забудьте раскомментировать #define CONFIG_TARFS_INTEGRITY 1 в src/config.h, после того, как вы прошьете ваш архив с CRC64 во флешку. Если не раскомментировать, то проверка целостности выполнятся не будет.

ВАЖНО! Если включена опция проверки целостности CONFIG_TARFS_INTEGRITY, то Tarfs ожидает файловую систему с контрольными суммами. Отсутствие контрольных сумм будет интерпретировано как битые данные.

Переписывание путей и ссылок

В зависимости от платформы и версии tar архив может содержать абсолютные пути или абсолютные адреса символических ссылок.

Например, вместо:

tarfs/file.txt

в архив может попасть:

/home/user/work/project/tarfs/file.txt

В этом случае TARFS воспримет каталог /home как корень файловой системы вместо tarfs.

Похожая ситуация возможна и в Windows (особенно при использовании Cygwin), где символические ссылки могут выглядеть так:

/??/C:/Users/John/tarfs/link_name

вместо:

tarfs/link_name

Для решения этой проблемы TARFS предоставляет необязательный параметр монтирования:

link_rebase

Он задаёт префикс пути, который будет отрезан при монтировании файловой системы.

Например,

link_rebase = "/??/C:/Users/John"

преобразует

/??/C:/Users/John/tarfs/link

в

/tarfs/link

Типичные ошибки и замечания по безопасности

Не делайте раздел Flash-памяти значительно больше, чем сам TAR-архив. TARFS пытается смонтировать всё содержимое в пределах указанного диапазона Flash. Такое поведение сделано намеренно: оно повышает вероятность успешного восстановления файловой системы при её повреждении (например, из-за сбойного сектора Flash), однако заставляет TARFS тратить дополнительное время на анализ посторонних данных.
Если вы записываете новый TAR-архив, который меньше предыдущего, убедитесь, что размер раздела соответствует размеру нового архива. В противном случае TARFS может принять оставшиеся данные от старого архива за корректные TAR-заголовки и смонтировать файлы, которых уже не должно существовать.
Всегда проверяйте коды возврата функций. В случае ошибки анализируйте значение errno, чтобы определить её причину.
Если TARFS не работает или работает не так, как ожидается, включите подробное журналирование, установив опцию CONFIG_TARFS_LOG в файле config.h. Это приведёт к появлению большого количества отладочной информации, включая вызовы API, их результаты и подробности процесса монтирования.

Например, в журнале могут появиться сообщения о невозможности нормализации символической ссылки (floating link) с путём вида:

/??/D:/Users/John/tarfs/file.txt

Обычно это означает, что необходимо скорректировать параметр link_rebase, передаваемый в tarfs_mount(). Например, если задать:

/??/D:/Users/John/

то абсолютный префикс пути будет удалён, и внутри архива останутся только корректные относительные пути.