frogfs

À propos de Frogfs

FROGFS (Système de fichiers à usage général rapide en lecture seule) est un système de fichiers en lecture conçu pour une utilisation intégrée. Il peut être facilement utilisé avec un projet CMake - y compris ESP-IDF. Il a des filtres intégrés pour économiser de l'espace. Les fichiers dans frogfs-clockwise-demo sont réduits d'environ la moitié à l'aide des filtres par défaut. Voici des liens vers l'exemple des référentiels:

• Frogfs-standalone-amorce
• amoufré dans le sens horaire

Les filtres de transformation comprennent:

• converti Babel
• babel-minitif
• dégonfler
• gzip
• brotli
• html-minificateur
• rebaptiser
• mettre fin
• uglify-js
• uglifycss

Les filtres de compression comprennent:

• aucun
• gzip
• linge de chaleur
• zrib

Les filtres de transformation sont destinés à être des opérations de temps de compilation qui n'engagent pas un coût d'exécution tandis que les filtres de compression devraient entraîner un coût de décompression d'exécution .

Cela signifie pour un serveur HTTP, ZLIB (Deflate), Brotli (BR) ou les fichiers compressés GZIP peuvent être transmis par intacte! Cela permet de gagner du temps et de la bande passante. Méfiez-vous cependant que certains navigateurs n'acceptent pas le contenu Brotli autre HTTP (uniquement HTTPS).

Commencer avec ESP-IDF

Pour utiliser ce composant avec ESP-IDF, dans votre répertoire de projets

 idf.py add-dependency jkent/frogfs

Incorporer une image Frogfs

Entrez les grenouilles dans votre projet binaire avec la fonction Cake folie:

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

Si la configuration n'est pas spécifiée, frogfs.yaml sera utilisée. Si le nom n'est pas spécifié, il sera par défaut aux frogfs .

À titre d'exemple pour ESP-IDF, dans les cmakelists toplevel de votre projet.txt:

 cmake_minimum_required ( VERSION 3.16)

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

target_add_frogfs( ${PROJECT_NAME} .elf)

En C, cela entraîne la disposition de ces deux symboles globaux: votre application:

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

Faire un grenouille binaire et le clignoter

Vous avez la possibilité de créer un binaire sans le lier à votre application. Une fonction CMake est fournie pour sortir un binaire avec generate_${name} .

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

Si la configuration n'est pas spécifiée, frogfs.yaml est utilisée. Si le nom n'est pas spécifié, frogfs est utilisé.

Voici un exemple de ce que vous pouvez ajouter à vos cmakelists de niveau supérieur.txt:

 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)

Vous pouvez invoquer le processus flash en exécutant idf.py frogfs-flash .

Configuration

Frogfs attend un fichier de configuration YAML. Il y a 3 sections différentes: définir, collecter et filtrer. Tout sauf Collect est facultatif.

Définir est une liste ou un dict de définitions variables. Il existe 2 variables prédéfinies: $cwd et $frogfs . Vous pouvez également référencer les variables d'environnement avec la syntaxe ${ENV:varname} .

Collectez les fichiers et les répertoires «rassemblent les« répertoires et les place dans la racine Frogfs. Les modèles GLOB sont autorisés dans le composant «Basename» du chemin. Il existe 3 façons de spécifier des sources; Ils sont une chaîne, une liste ou un dictionnaire. S'il s'agit d'une chaîne, le (s) chemin (s) devient le répertoire racine. Si une liste, les chemins sont fusionnés dans l'ordre et deviennent le répertoire racine. Si un dict est utilisé, les chemins sont fusionnés dans la destination de choix; String vide étant le répertoire racine. Les variables sont élargies pour la source et la destination.

Le filtre vous permet de faire du post-traitement sur les fichiers avant d'être intégrés. Le filtre est une liste ou un dict de dicts; avec un modèle glob sur une liste de verbes. Les varibes sont élargies et tous les modèles sont évalués pour chaque fichier ou répertoire, en haut. Les transformations sont d'abord appliquées, puis une compression finale en option avant la mise en cache du fichier.

Les verbes sont appliqués par ordre décroissant. Vous pouvez préfixer une transformation ou le verbe compress avec no pour le désactiver. Il y a quelques verbes spéciaux: discard qui empêche l'inclusion et cache (par défaut), qui met en cache le fichier dans le cache de construction. Voir frogfs_example.yaml par exemple utilisation.

Usage

Deux interfaces sont disponibles: l'API nue ou lors de l'utilisation de l'IDF, il y a l'interface VFS qui se construit sur l'API Bare. Vous devez utiliser l'interface VFS dans les projets IDF, car il utilise les fonctions posix et stdio C portables et familières. Rien ne vous empêche de mélanger et de faire correspondre les deux en même temps.

Initialisation partagée

REQUIRES DE CONFIGURATION DÉFINIR UNE STRUCTION frogfs_config_t ET LE PASSE À frogfs_init . Deux façons différentes de spécifier le système de fichiers:

1. Une adresse mémoire utilisant la variable addr :

 frogfs_config_t frogfs_config = {
    . addr = frogfs_bin ,
};

2. un nom de partition utilisant la chaîne part_label :

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

Ensuite, il s'agit simplement de passer la fonction frogfs_config à frogfs_init et de vérifier sa variable de retour:

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

Une fois terminé, et toutes les poignées de fichiers sont fermées, vous pouvez appeler frogfs_deinit :

 frogfs_deinit ( fs );

Interface VFS

L'interface VFS a une méthode d'initialisation similaire; Vous définissez une structure frogfs_vfs_conf_t :

• base_path - chemin vers le mont Frogfs
• FS - une instance frogfs_fs_t
• Max_Files - Nombre maximum de fichiers qui peuvent être ouverts à la fois

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

API nu

Fonctions du système de fichiers:

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

Fonctions d'objet:

• const frogfs_entry_t * frogfs_get_entry (const frogfs_fs_t * fs, const char * path)
• char * frogfs_get_name (const frogfs_entry_t * entrée)
• char * frogfs_get_path (const frogfs_fs_t * fs, const frogfs_entry_t * entrée)
• int frogfs_is_dir (const frogfs_entry_t * entrée)
• int frogfs_is_file (const frogfs_entry_t * entrée)
• void frogfs_stat (const frogfs_fs_t * fs, const frogfs_entry_t * entrée, frogfs_stat_t * st)
• frogfs_fh_t * frogfs_open (const frogfs_fs_t * fs, const frogfs_entry_t *, entrée non signé)
• 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, décalage long, mode int)
• size_t frogfs_tell (Frogfs_fh_t * fh)
• size_t frogfs_access (Frogfs_fh_t * fh, void ** buf)

Fonctions du répertoire:

• frogfs_dh_t * frogfs_opendir (frogfs_fs_t * fs, const frogfs_entry_t * entrée)
• 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)

Comment ça marche

Sous le capot, il y a une table de hachage composée de hachages de chemin DJB2 sur les décalages d'entrée, qui permettent des recherches rapides à l'aide d'un algorithme de recherche binaire. Toutes les entrées à l'exception de l'entrée racine ont un décalage de localisateur parent. Les entrées de répertoire ont une liste triée de compensations aux entrées enfants.

Les binaires FROGFS peuvent être intégrés dans votre application, soit accessibles à l'aide d'E / S mappées de mémoire. Il n'est pas possible (pour le moment) d'utiliser FrogFS sans le système de fichiers binaire existant dans l'espace d'adresse de données.

La création d'un système de fichiers Frogfs est gérée par un seul outil, tools/mkfrogfs.py . Il utilise des transformations dans le répertoire tools , ou vous pouvez ajouter vos propres transformations en créant un répertoire tools dans votre répertoire racine de projets, avec un nom de fichier commençant par transform- et se terminant par .js ou .py . Les outils de transformation prennent des données sur STDIN et produisent la sortie sur STDOUT.

Transform et Compresors peuvent accepter les arguments. Voir frogfs_example.yaml pour un exemple.

Histoire et remerciements

Frogfs a été divisé de Chris Morgan (Chmorgan) LibesPhTTPD Project (MPL 2.0), qui est une fourche de Jeroen Domurg (Sprite_TM) Libesphttpd (Beer-Ware). Ce projet n'aurait jamais existé sans eux.

Merci à tous les contributeurs de ce projet!