frogfs

Über Frosch

FROGFS (FAST SEAL-READLY General-Purple-Dateisystem) ist ein schreibgeschütztes Dateisystem für die eingebettete Verwendung. Es kann leicht mit einem CMAKE-Projekt verwendet werden-einschließlich ESP-IDF. Es verfügt über integrierte Filter, um Platz zu sparen. Die Dateien in frogfs-clockwise-demo werden mit den Standardfiltern um etwa die Hälfte reduziert. Hier finden Sie Links zu den Beispiel -Repositories:

• Frogfs-Standalone-Demo
• Frogfs-Uhrzeigersinn

Die Transformationsfilter umfassen:

• Babel-Convert
• Babel-Minify
• Deflate
• gzip
• Brotli
• HTML-MINIFIER
• umbenennen
• beenden
• Uglify-Js
• Uglifycss

Kompressionsfilter umfassen:

• keiner
• gzip
• Hitzeschild
• Zlib

Transformationsfilter sollen Kompilierungszeitabläufe sein, bei denen keine Laufzeitkosten anfallen, während die Komprimierungsfilter voraussichtlich eine Dekompressionskosten für Laufzeiten verursachen.

Dies bedeutet für einen HTTP -Server, ZLIB (Deflate), Brotli (BR) oder GZIP -komprimierte Dateien können unberührt übergeben werden! Dies spart die Verarbeitungszeit und Bandbreite. Achten Sie jedoch darauf, dass einige Browser keinen Brotli -Inhalt an anderen HTTP (nur HTTPS) akzeptieren.

Erste Schritte mit ESP-IDF

Um diese Komponente mit ESP-IDF in Ihrem Projektverzeichnis zu verwenden

 idf.py add-dependency jkent/frogfs

Einbettung eines Frogfs -Bildes

Einbetten Sie Frogfs in Ihr Projekt Binär mit der Lobus -CMake -Funktion ein:

 target_add_frogfs(<target> [CONFIG yaml] [NAME name])

Wenn die Konfiguration nicht angegeben ist, wird frogfs.yaml verwendet. Wenn der Name nicht angegeben ist, wird er standardmäßig an frogfs angegeben.

Als Beispiel für ESP-IDF in den Toplevel-Cmakelists Ihres Projekts.txt:

 cmake_minimum_required ( VERSION 3.16)

include ( $ENV{IDF_PATH} /tools/cmake/project.cmake)
project (my_project)

target_add_frogfs( ${PROJECT_NAME} .elf)

In C führt dies dazu, dass diese beiden globalen Symbole Ihrer Anwendung zur Verfügung stehen:

 extern const uint8_t frogfs_bin [];
extern const size_t frogfs_bin_len ;

Machen Sie ein Frosches binär und blinken Sie es

Sie haben die Möglichkeit, eine Binärdatei zu erstellen, ohne es mit Ihrer Anwendung zu verknüpfen. Eine CMAKE -Funktion wird bereitgestellt, um ein Binärdatum mit Target generate_${name} .

 declare_frogfs_bin(path [CONFIG yaml] [NAME name])

Wenn die Konfiguration nicht angegeben ist, wird frogfs.yaml verwendet. Wenn der Name nicht spezifisch ist, wird frogfs verwendet.

Hier ist ein Beispiel dafür, was Sie zu Ihrem Toplevel Cmakelists hinzufügen können.

 set (FROGFS_NAME frogfs)
declare_frogfs_bin( NAME ${FROGFS_NAME} )

idf_component_get_property(main_args esptool_py FLASH_ARGS)
idf_component_get_property(sub_args esptool_py FLASH_SUB_ARGS)
esptool_py_flash_target( ${FROGFS_NAME} -flash " ${main_args} " " ${sub_args} " ALWAYS_PLAINTEXT)

esptool_py_flash_to_partition( ${FROGFS_NAME} -flash storage ${BUILD_DIR} /CMakeFiles/ ${FROGFS_NAME} .bin)
add_dependencies ( ${FROGFS_NAME} -flash generate_ ${FROGFS_NAME} _bin)

Sie können den Flash-Prozess aufrufen, indem Sie idf.py frogfs-flash ausführen.

Konfiguration

Frogfs erwartet eine YAML -Konfigurationsdatei. Es gibt 3 verschiedene Abschnitte: Definieren, Sammeln und Filtern. Alles außer Sammeln ist optional.

Define ist eine Liste oder ein Diktieren von variablen Definitionen. Es gibt 2 vordefinierte Variablen: $cwd und $frogfs . Sie können auch Umgebungsvariablen mit der Syntax ${ENV:varname} verweisen.

Sammeln Sie "sammelt" Dateien und Verzeichnisse und platziert sie in die Frogfs -Root. GLIB -Muster sind in der "Basennamen" -Komponente des Pfades zulässig. Es gibt 3 Möglichkeiten, Quellen anzugeben; Sie werden eine Zeichenfolge, eine Liste oder ein Wörterbuch sein. Wenn es sich um eine Zeichenfolge handelt, werden der Pfad zum Stammverzeichnis. Wenn eine Liste, werden die Pfade in der Reihenfolge verschmolzen und werden zum Wurzelverzeichnis. Wenn ein Diktat verwendet wird, werden die Pfade in das Ziel der Wahl verschmolzen. leere Zeichenfolge ist das Root -Verzeichnis. Variablen werden sowohl für Quelle als auch für das Ziel erweitert.

Mit Filter können Sie die Nachbearbeitung in den Dateien durchführen, bevor sie integriert werden. Filter ist eine Liste oder ein Diktat von Diktieren; mit einem Glob -Muster zu einer Liste von Verben. Variibales werden erweitert und alle Muster werden für jede Datei oder jedes Verzeichnis oben nach unten ausgewertet. Transformationen werden zuerst angewendet, dann eine optionale endgültige Komprimierung, bevor die Datei zwischengespeichert wird.

Verben werden in absteigender Reihenfolge angewendet. Sie können eine Transformationen oder das compress -Verb ohne no zum Deaktivieren vorfixieren. Es gibt ein paar spezielle Verben: discard , die Einbeziehung und cache (Standard) verhindert, die die Datei im Build -Cache zwischengeordnet haben. Siehe frogfs_example.yaml zum Beispiel Verwendung.

Verwendung

Es stehen zwei Schnittstellen zur Verfügung: Die bloße API oder bei der Verwendung von IDF gibt es die VFS -Schnittstelle, die sich auf der bloßen API erstellt. Sie sollten die VFS -Schnittstelle in IDF -Projekten verwenden, da die tragbaren und vertrauten posix und stdio -C -Funktionen damit verwendet werden. Es gibt jedoch nichts, was Sie daran hindert, gleichzeitig beide zu mischen und zu entsprechen.

Gemeinsame Initialisierung

Die Konfiguration wird nach einer frogfs_config_t -Struktur definiert und an frogfs_init weitergegeben. Zwei verschiedene Möglichkeiten, um das Dateisystem anzugeben:

1. Eine Speicheradresse unter Verwendung der addr -Variablen:

 frogfs_config_t frogfs_config = {
    . addr = frogfs_bin ,
};

2. Ein Partitionsname mit der part_label -Zeichenfolge:

 frogfs_config_t frogfs_config = {
    . part_label = "storage" ,
};

Dann geht es nur darum, die frogfs_config an die Funktion frogfs_init zu übergeben und die Rückgabebehunde zu überprüfen:

 frogfs_fs_t * fs = frogfs_init ( & frogfs_config );
assert ( fs != NULL );

Wenn Sie fertig sind und alle Dateigriffe geschlossen sind, können Sie frogfs_deinit aufrufen:

 frogfs_deinit ( fs );

VFS -Schnittstelle

Die VFS -Schnittstelle weist eine ähnliche Initialisierungsmethode auf; Sie definieren eine frogfs_vfs_conf_t -Struktur:

• Basis_Path - Pfad zum Mount Frogfs
• fs - eine frogfs_fs_t -Instanz
• max_files - maximale Anzahl von Dateien, die gleichzeitig geöffnet werden können

 frogfs_vfs_conf_t frogfs_vfs_conf = {
    . base_path = "/frogfs" ,
    . fs = fs ,
    . max_files = 5 ,
};
frogfs_vfs_register ( & frogfs_vfs_conf );

Nackte API

Dateisystemfunktionen:

• frogfs_fs_t *frogfs_init (const frogfs_config_t *conf)
• void frogfs_deinit (frogfs_fs_t *fs)

Objektfunktionen:

• const frogfs_entry_t *frogfs_get_entry (const frogfs_fs_t *fs, const char *path)
• char *frogfs_get_name (const frogfs_entry_t *Eintrag)
• char *frogfs_get_path (const frogfs_fs_t *fs, const frogfs_entry_t *Eintrag)
• int frogfs_is_dir (const frogfs_entry_t *Eintrag)
• int frogfs_is_file (const frogfs_entry_t *Eintrag)
• void frogfs_stat (const frogfs_fs_t *fs, const frogfs_entry_t *Eintrag, Frogfs_stat_t *st)
• frogfs_fh_t *frogfs_open (const frogfs_fs_t *fs, const frogfs_entry_t *Eintrag, unsignierte int -Flags)
• void frogfs_close (frogfs_fh_t *fh)
• int frogfs_is_raw (frogfs_fh_t *fh)
• size_t frogfs_read (frogfs_fh_t *fh, void *buf, size_t len)
• SSIZE_T FROGFS_SEEK (FROGFS_FH_T *FH, langer Offset, int -Modus)
• size_t frogfs_tell (frogfs_fh_t *fh)
• size_t frogfs_access (frogfs_fh_t *fh, void ** buf)

Verzeichnisfunktionen:

• frogfs_dh_t *frogfs_opendir (frogfs_fs_t *fs, const frogfs_entry_t *Eintrag)
• void frogfs_closedir (frogfs_dh_t *dh)
• const frogfs_entry_t *frogfs_readdir (frogfs_dh_t *dh)
• void frogfs_seekdir (frogfs_dh_t *dh, long loc)
• Long frogfs_telldir (frogfs_dh_t *dh)

Wie es funktioniert

Unter der Motorhaube befindet sich eine Hash -Tabelle, die aus DJB2 -Pfad -Hashes zu Eintrags -Offsets besteht, die schnelle Lookups mit einem binären Suchalgorithmus ermöglichen. Alle Einträge mit Ausnahme des Stammeintrags haben einen übergeordneten Locator -Offset. Verzeichniseinträge haben eine sortierte Liste von Offsets für Kindereinträge.

Frogfs -Binärdateien können entweder in Ihre Anwendung eingebettet werden oder mit dem von Speicher zugeordneten E/A zugegriffen werden. Es ist (zu diesem Zeitpunkt) nicht möglich, Frogfs ohne das im Datenadressenbereich vorhandene Dateisystem zu verwenden.

Die Erstellung eines Frogfs -Dateisystems wird von einem einzigen Tool, tools/mkfrogfs.py , behandelt. Es verwendet Transformationen im tools -Verzeichnis oder Sie können Ihre eigenen Transformationen hinzufügen, indem Sie ein tools Verzeichnis in Ihrem Projekt-Root-Verzeichnis erstellen, wobei ein Dateiname mit transform- und endet mit .js oder .py . Transformationswerkzeuge nehmen Daten zu Stdin und erzeugen Ausgabe auf STDOut.

Sowohl Transformation als auch Kompresoren können Argumente akzeptieren. Ein Beispiel siehe frogfs_example.yaml .

Geschichte und Anerkennung

Frogfs wurde von Chris Morgan (Chmorgan) 's libesPhttpd-Projekt (MPL 2.0) abgeteilt, das eine Gabel von Jeroen Domburg (Sprite_tm) von libesphttpd (Bierkämpfer) ist. Dieses Projekt hätte ohne sie niemals existiert.

Vielen Dank an alle Mitwirkenden dieses Projekts!