From 3cab84f03394f4d355fed18d3cc9497df56df826 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tom=C3=A1=C5=A1=20Rohl=C3=ADnek?= Date: Thu, 26 Sep 2024 08:29:03 +0200 Subject: [PATCH] fix(storage/vfs): clarify minified related documentation --- components/vfs/include/esp_vfs.h | 15 +++++++++++++++ components/vfs/include/esp_vfs_minified.h | 18 +++++++++++------- docs/en/api-reference/storage/vfs.rst | 7 +++++-- 3 files changed, 31 insertions(+), 9 deletions(-) diff --git a/components/vfs/include/esp_vfs.h b/components/vfs/include/esp_vfs.h index 5a664475aa..0f4a879465 100644 --- a/components/vfs/include/esp_vfs.h +++ b/components/vfs/include/esp_vfs.h @@ -486,6 +486,21 @@ ssize_t esp_vfs_pwrite(int fd, const void *src, size_t size, off_t offset); */ void esp_vfs_dump_fds(FILE *fp); +/** + * @brief Dump all registered FSs to the provided FILE* + * + * Dump the FSs in the format: + @verbatim + : -> + + where: + index : internal index in the table of registered FSs (the same as returned when registering fd with id) + VFS Path Prefix : file prefix used in the esp_vfs_register call or "NULL" + VFS entry ptr : pointer to the esp_vfs_minified_t struct used internally when resolving the calls + @endverbatim + * + * @param fp File descriptor where data will be dumped + */ void esp_vfs_dump_registered_paths(FILE *fp); #ifdef __cplusplus diff --git a/components/vfs/include/esp_vfs_minified.h b/components/vfs/include/esp_vfs_minified.h index 55cdbd65e0..3a522cc5f7 100644 --- a/components/vfs/include/esp_vfs_minified.h +++ b/components/vfs/include/esp_vfs_minified.h @@ -272,13 +272,17 @@ typedef struct { * matched by any other registered VFS. * @param vfs Pointer to esp_vfs_minified_t, a structure which maps syscalls to * the filesystem driver functions. VFS component does not assume ownership of this struct, but see flags for more info - * @param flags Set of binary flags controlling how the registered FS should be treated - * - ESP_FLAG_VFS_STATIC - if this flag is specified VFS assumes the provided esp_vfs_minified_t is statically allocated, - * if it is not enabled a copy of the provided struct will be created, which will be managed by the VFS component - * @param ctx If vfs->flags has ESP_VFS_FLAG_CONTEXT_PTR set, a pointer - * which should be passed to VFS functions. Otherwise, NULL. * - * @return ESP_OK if successful, ESP_ERR_NO_MEM if too many VFSes are + * @param flags Set of binary flags controlling how the registered FS should be treated + * - ESP_VFS_FLAG_STATIC - if this flag is specified VFS assumes the provided esp_vfs_minified_t and all its subcomponents are statically allocated, + * if it is not enabled a deep copy of the provided struct will be created, which will be managed by the VFS component + * - ESP_VFS_FLAG_CONTEXT_PTR - If set, the VFS will use the context-aware versions of the filesystem operation functions (suffixed with `_p`) in `esp_vfs_fs_ops_t` and its subcomponents. + * The `ctx` parameter will be passed as the context argument when these functions are invoked. + * + * @param ctx Context pointer for fs operation functions, see the ESP_VFS_FLAG_CONTEXT_PTR. + * Should be `NULL` if not used. + * + * @return ESP_OK if successful, ESP_ERR_NO_MEM if too many FSes are * registered. */ esp_err_t esp_vfs_register_minified(const char* base_path, const esp_vfs_minified_t* vfs, int flags, void* ctx); @@ -287,7 +291,7 @@ esp_err_t esp_vfs_register_minified(const char* base_path, const esp_vfs_minifie * Analog of esp_vfs_register_with_id which accepts esp_vfs_minified_t instead. * */ -esp_err_t esp_vfs_register_minified_with_id(const esp_vfs_minified_t* vfs, int flags, void* ctx, int* id); +esp_err_t esp_vfs_register_fs_with_id(const esp_vfs_minified_t* vfs, int flags, void* ctx, esp_vfs_id_t* id); /** * Alias for esp_vfs_unregister for naming consistency diff --git a/docs/en/api-reference/storage/vfs.rst b/docs/en/api-reference/storage/vfs.rst index 6b0d09aace..84c1afd99d 100644 --- a/docs/en/api-reference/storage/vfs.rst +++ b/docs/en/api-reference/storage/vfs.rst @@ -192,17 +192,19 @@ Standard I/O streams (``stdin``, ``stdout``, ``stderr``) are mapped to file desc Note that creating an eventfd with ``EFD_SUPPORT_ISR`` will cause interrupts to be temporarily disabled when reading, writing the file and during the beginning and the ending of the ``select()`` when this file is set. + Minified VFS ------------ -To minimize RAM usage, most provided filesystems use alternative version of :cpp:func:`esp_vfs_register` function, :cpp:func:`esp_vfs_register_minified`. +To minimize RAM usage, an alternative version of :cpp:func:`esp_vfs_register` function, :cpp:func:`esp_vfs_register_minified` is provided. This version accepts :cpp:class:`esp_vfs_minified_t` instead of :cpp:class:`esp_vfs_t` alongside separate argument for OR-ed flags, unlike :cpp:func:`esp_vfs_register` it can handle statically allocated struct, as long as the ``ESP_VFS_FLAG_STATIC`` is provided. The :cpp:class:`esp_vfs_minified_t` is split into separate structs based on features (directory operations, select support, termios support, ...). The main struct contains the basic functions (``read``, ``write``, ...), alongside pointers to the feature-specific structs, these pointers can be ``NULL`` indicating lack of support for all the functions provided by that struct, this decreases the required memory. -This API is also available for users to use. +Internally the vfs component uses this version of API, with additional steps to convert the :cpp:class:`esp_vfs_t` to :cpp:class:`esp_vfs_minified_t` upon registration. + Well Known VFS Devices ---------------------- @@ -220,6 +222,7 @@ Application Examples - :example:`system/select` demonstrates how to use synchronous I/O multiplexing with the ``select()`` function, using UART and socket file descriptors, and configuring both to act as loopbacks to receive messages sent from other tasks. + API Reference -------------