diff --git a/components/vfs/include/esp_vfs_minified.h b/components/vfs/include/esp_vfs_minified.h index bcd9871217..55cdbd65e0 100644 --- a/components/vfs/include/esp_vfs_minified.h +++ b/components/vfs/include/esp_vfs_minified.h @@ -52,6 +52,10 @@ typedef struct #ifdef CONFIG_VFS_SUPPORT_DIR +/** + * @brief Struct containing function pointers to directory related functionality. + * + */ typedef struct { union { int (*stat_p)(void* ctx, const char * path, struct stat * st); /*!< stat with context pointer */ @@ -123,6 +127,10 @@ typedef struct { #ifdef CONFIG_VFS_SUPPORT_TERMIOS +/** + * @brief Struct containing function pointers to termios related functionality. + * + */ typedef struct { union { int (*tcsetattr_p)(void *ctx, int fd, int optional_actions, const struct termios *p); /*!< tcsetattr with context pointer */ @@ -158,6 +166,10 @@ typedef struct { #ifdef CONFIG_VFS_SUPPORT_SELECT +/** + * @brief Struct containing function pointers to select related functionality. + * + */ typedef struct { /** start_select is called for setting up synchronous I/O multiplexing of the desired file descriptors in the given VFS */ esp_err_t (*start_select)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, esp_vfs_select_sem_t sem, void **end_select_args); @@ -180,6 +192,10 @@ typedef struct { #endif // CONFIG_VFS_SUPPORT_SELECT +/** + * @brief Main struct of the minified vfs API, containing basic function pointers as well as pointers to the other subcomponents. + * + */ typedef struct { union { ssize_t (*write_p)(void* p, int fd, const void * data, size_t size); /*!< Write with context pointer */ @@ -227,15 +243,15 @@ typedef struct { }; #ifdef CONFIG_VFS_SUPPORT_DIR - esp_vfs_dir_t *dir; + esp_vfs_dir_t *dir; /*!< pointer to the dir subcomponent */ #endif #ifdef CONFIG_VFS_SUPPORT_TERMIOS - esp_vfs_termios_t *termios; + esp_vfs_termios_t *termios; /*!< pointer to the termios subcomponent */ #endif #if CONFIG_VFS_SUPPORT_SELECT || defined __DOXYGEN__ - esp_vfs_select_t *select; + esp_vfs_select_t *select; /*!< pointer to the select subcomponent */ #endif } esp_vfs_minified_t; @@ -256,7 +272,7 @@ 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 flag Set of binary flags controlling how the registered FS should be treated + * @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 diff --git a/docs/doxygen/Doxyfile b/docs/doxygen/Doxyfile index 8a131eddec..5bdefdc834 100644 --- a/docs/doxygen/Doxyfile +++ b/docs/doxygen/Doxyfile @@ -314,6 +314,7 @@ INPUT = \ $(PROJECT_PATH)/components/vfs/include/esp_vfs_eventfd.h \ $(PROJECT_PATH)/components/vfs/include/esp_vfs_semihost.h \ $(PROJECT_PATH)/components/vfs/include/esp_vfs_null.h \ + $(PROJECT_PATH)/components/vfs/include/esp_vfs_minified.h \ $(PROJECT_PATH)/components/vfs/include/esp_vfs.h \ $(PROJECT_PATH)/components/wear_levelling/include/wear_levelling.h \ $(PROJECT_PATH)/components/wifi_provisioning/include/wifi_provisioning/manager.h \ diff --git a/docs/en/api-reference/storage/vfs.rst b/docs/en/api-reference/storage/vfs.rst index 44b1307546..6b0d09aace 100644 --- a/docs/en/api-reference/storage/vfs.rst +++ b/docs/en/api-reference/storage/vfs.rst @@ -192,6 +192,18 @@ 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`. +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. + Well Known VFS Devices ---------------------- @@ -213,6 +225,8 @@ API Reference .. include-build-file:: inc/esp_vfs.inc +.. include-build-file:: inc/esp_vfs_minified.inc + .. include-build-file:: inc/esp_vfs_dev.inc .. include-build-file:: inc/uart_vfs.inc