From bafc22e016f8fa03e004fdc118cf5b4727f3a2c3 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Wed, 12 Feb 2025 11:58:37 -0700 Subject: [PATCH] feat(fs): clarify rest of docs on driver-identifier letters. (#7710) --- lv_conf_template.h | 28 +++++++++++++++------------- src/libs/fsdrv/lv_fs_uefi.c | 4 ++-- src/lv_conf_internal.h | 28 +++++++++++++++------------- src/misc/lv_fs.c | 2 +- src/misc/lv_fs.h | 4 ++-- 5 files changed, 35 insertions(+), 31 deletions(-) diff --git a/lv_conf_template.h b/lv_conf_template.h index bacbfd8e0..a52e2e187 100644 --- a/lv_conf_template.h +++ b/lv_conf_template.h @@ -794,13 +794,15 @@ /* File system interfaces for common APIs */ -/** Setting a default driver letter allows skipping the driver prefix in filepaths. */ +/** Setting a default driver letter allows skipping the driver prefix in filepaths. + * Documentation about how to use the below driver-identifier letters can be found at + * https://docs.lvgl.io/master/details/main-components/fs.html#lv-fs-identifier-letters . */ #define LV_FS_DEFAULT_DRIVER_LETTER '\0' /** API for fopen, fread, etc. */ #define LV_USE_FS_STDIO 0 #if LV_USE_FS_STDIO - #define LV_FS_STDIO_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_STDIO_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #define LV_FS_STDIO_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #define LV_FS_STDIO_CACHE_SIZE 0 /**< >0 to cache this number of bytes in lv_fs_read() */ #endif @@ -808,7 +810,7 @@ /** API for open, read, etc. */ #define LV_USE_FS_POSIX 0 #if LV_USE_FS_POSIX - #define LV_FS_POSIX_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_POSIX_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #define LV_FS_POSIX_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #define LV_FS_POSIX_CACHE_SIZE 0 /**< >0 to cache this number of bytes in lv_fs_read() */ #endif @@ -816,7 +818,7 @@ /** API for CreateFile, ReadFile, etc. */ #define LV_USE_FS_WIN32 0 #if LV_USE_FS_WIN32 - #define LV_FS_WIN32_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_WIN32_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #define LV_FS_WIN32_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #define LV_FS_WIN32_CACHE_SIZE 0 /**< >0 to cache this number of bytes in lv_fs_read() */ #endif @@ -824,7 +826,7 @@ /** API for FATFS (needs to be added separately). Uses f_open, f_read, etc. */ #define LV_USE_FS_FATFS 0 #if LV_USE_FS_FATFS - #define LV_FS_FATFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_FATFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #define LV_FS_FATFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #define LV_FS_FATFS_CACHE_SIZE 0 /**< >0 to cache this number of bytes in lv_fs_read() */ #endif @@ -832,34 +834,34 @@ /** API for memory-mapped file access. */ #define LV_USE_FS_MEMFS 0 #if LV_USE_FS_MEMFS - #define LV_FS_MEMFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_MEMFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif /** API for LittleFs. */ #define LV_USE_FS_LITTLEFS 0 #if LV_USE_FS_LITTLEFS - #define LV_FS_LITTLEFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ - #define LV_FS_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ + #define LV_FS_LITTLEFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ + #define LV_FS_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #endif /** API for Arduino LittleFs. */ #define LV_USE_FS_ARDUINO_ESP_LITTLEFS 0 #if LV_USE_FS_ARDUINO_ESP_LITTLEFS - #define LV_FS_ARDUINO_ESP_LITTLEFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ - #define LV_FS_ARDUINO_ESP_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ + #define LV_FS_ARDUINO_ESP_LITTLEFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ + #define LV_FS_ARDUINO_ESP_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #endif /** API for Arduino Sd. */ #define LV_USE_FS_ARDUINO_SD 0 #if LV_USE_FS_ARDUINO_SD - #define LV_FS_ARDUINO_SD_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ - #define LV_FS_ARDUINO_SD_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ + #define LV_FS_ARDUINO_SD_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ + #define LV_FS_ARDUINO_SD_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #endif /** API for UEFI */ #define LV_USE_FS_UEFI 0 #if LV_USE_FS_UEFI - #define LV_FS_UEFI_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_UEFI_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif /** LODEPNG decoder library */ diff --git a/src/libs/fsdrv/lv_fs_uefi.c b/src/libs/fsdrv/lv_fs_uefi.c index a91c3d5a2..8a60747c2 100644 --- a/src/libs/fsdrv/lv_fs_uefi.c +++ b/src/libs/fsdrv/lv_fs_uefi.c @@ -21,11 +21,11 @@ #error "LV_FS_UEFI_LETTER must be set to a valid value" #else #if (LV_FS_UEFI_LETTER < 'A') || (LV_FS_UEFI_LETTER > 'Z') - #if LV_FS_DEFAULT_DRIVE_LETTER != '\0' /*When using default drive letter, strict format (X:) is mandatory*/ + #if LV_FS_DEFAULT_DRIVE_LETTER != '\0' /* When using default driver-identifier letter, strict format (X:) is mandatory. */ #error "LV_FS_UEFI_LETTER must be an upper case ASCII letter" #else /*Lean rules for backward compatibility*/ #warning LV_FS_UEFI_LETTER should be an upper case ASCII letter. \ - Using a slash symbol as drive letter should be replaced with LV_FS_DEFAULT_DRIVE_LETTER mechanism + Using a slash symbol as driver-identifier letter should be replaced with LV_FS_DEFAULT_DRIVE_LETTER mechanism. #endif #endif #endif diff --git a/src/lv_conf_internal.h b/src/lv_conf_internal.h index f0071467b..dec5c4a07 100644 --- a/src/lv_conf_internal.h +++ b/src/lv_conf_internal.h @@ -2529,7 +2529,9 @@ /* File system interfaces for common APIs */ -/** Setting a default driver letter allows skipping the driver prefix in filepaths. */ +/** Setting a default driver letter allows skipping the driver prefix in filepaths. + * Documentation about how to use the below driver-identifier letters can be found at + * https://docs.lvgl.io/master/details/main-components/fs.html#lv-fs-identifier-letters . */ #ifndef LV_FS_DEFAULT_DRIVER_LETTER #ifdef CONFIG_LV_FS_DEFAULT_DRIVER_LETTER #define LV_FS_DEFAULT_DRIVER_LETTER CONFIG_LV_FS_DEFAULT_DRIVER_LETTER @@ -2551,7 +2553,7 @@ #ifdef CONFIG_LV_FS_STDIO_LETTER #define LV_FS_STDIO_LETTER CONFIG_LV_FS_STDIO_LETTER #else - #define LV_FS_STDIO_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_STDIO_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #ifndef LV_FS_STDIO_PATH @@ -2583,7 +2585,7 @@ #ifdef CONFIG_LV_FS_POSIX_LETTER #define LV_FS_POSIX_LETTER CONFIG_LV_FS_POSIX_LETTER #else - #define LV_FS_POSIX_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_POSIX_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #ifndef LV_FS_POSIX_PATH @@ -2615,7 +2617,7 @@ #ifdef CONFIG_LV_FS_WIN32_LETTER #define LV_FS_WIN32_LETTER CONFIG_LV_FS_WIN32_LETTER #else - #define LV_FS_WIN32_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_WIN32_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #ifndef LV_FS_WIN32_PATH @@ -2647,7 +2649,7 @@ #ifdef CONFIG_LV_FS_FATFS_LETTER #define LV_FS_FATFS_LETTER CONFIG_LV_FS_FATFS_LETTER #else - #define LV_FS_FATFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_FATFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #ifndef LV_FS_FATFS_PATH @@ -2679,7 +2681,7 @@ #ifdef CONFIG_LV_FS_MEMFS_LETTER #define LV_FS_MEMFS_LETTER CONFIG_LV_FS_MEMFS_LETTER #else - #define LV_FS_MEMFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_MEMFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #endif @@ -2697,14 +2699,14 @@ #ifdef CONFIG_LV_FS_LITTLEFS_LETTER #define LV_FS_LITTLEFS_LETTER CONFIG_LV_FS_LITTLEFS_LETTER #else - #define LV_FS_LITTLEFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_LITTLEFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #ifndef LV_FS_LITTLEFS_PATH #ifdef CONFIG_LV_FS_LITTLEFS_PATH #define LV_FS_LITTLEFS_PATH CONFIG_LV_FS_LITTLEFS_PATH #else - #define LV_FS_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ + #define LV_FS_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #endif #endif #endif @@ -2722,14 +2724,14 @@ #ifdef CONFIG_LV_FS_ARDUINO_ESP_LITTLEFS_LETTER #define LV_FS_ARDUINO_ESP_LITTLEFS_LETTER CONFIG_LV_FS_ARDUINO_ESP_LITTLEFS_LETTER #else - #define LV_FS_ARDUINO_ESP_LITTLEFS_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_ARDUINO_ESP_LITTLEFS_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #ifndef LV_FS_ARDUINO_ESP_LITTLEFS_PATH #ifdef CONFIG_LV_FS_ARDUINO_ESP_LITTLEFS_PATH #define LV_FS_ARDUINO_ESP_LITTLEFS_PATH CONFIG_LV_FS_ARDUINO_ESP_LITTLEFS_PATH #else - #define LV_FS_ARDUINO_ESP_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ + #define LV_FS_ARDUINO_ESP_LITTLEFS_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #endif #endif #endif @@ -2747,14 +2749,14 @@ #ifdef CONFIG_LV_FS_ARDUINO_SD_LETTER #define LV_FS_ARDUINO_SD_LETTER CONFIG_LV_FS_ARDUINO_SD_LETTER #else - #define LV_FS_ARDUINO_SD_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_ARDUINO_SD_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #ifndef LV_FS_ARDUINO_SD_PATH #ifdef CONFIG_LV_FS_ARDUINO_SD_PATH #define LV_FS_ARDUINO_SD_PATH CONFIG_LV_FS_ARDUINO_SD_PATH #else - #define LV_FS_ARDUINO_SD_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ + #define LV_FS_ARDUINO_SD_PATH "" /**< Set the working directory. File/directory paths will be appended to it. */ #endif #endif #endif @@ -2772,7 +2774,7 @@ #ifdef CONFIG_LV_FS_UEFI_LETTER #define LV_FS_UEFI_LETTER CONFIG_LV_FS_UEFI_LETTER #else - #define LV_FS_UEFI_LETTER '\0' /**< Set an upper cased letter on which the drive will accessible (e.g. 'A') */ + #define LV_FS_UEFI_LETTER '\0' /**< Set an upper-case driver-identifier letter for this driver (e.g. 'A'). */ #endif #endif #endif diff --git a/src/misc/lv_fs.c b/src/misc/lv_fs.c index 4cc42933d..e90d00c7f 100644 --- a/src/misc/lv_fs.c +++ b/src/misc/lv_fs.c @@ -509,7 +509,7 @@ static resolved_path_t lv_fs_resolve_path(const char * path) { resolved_path_t resolved; -#if LV_FS_DEFAULT_DRIVER_LETTER != '\0' /*When using default drive letter, strict format (X:) is mandatory*/ +#if LV_FS_DEFAULT_DRIVER_LETTER != '\0' /* When using default driver-identifier letter, strict format (X:) is mandatory */ bool has_drive_prefix = ('A' <= path[0]) && (path[0] <= 'Z') && (path[1] == ':'); if(has_drive_prefix) { diff --git a/src/misc/lv_fs.h b/src/misc/lv_fs.h index 075171b42..cefbf9633 100644 --- a/src/misc/lv_fs.h +++ b/src/misc/lv_fs.h @@ -119,7 +119,7 @@ void lv_fs_drv_register(lv_fs_drv_t * drv); /** * Give a pointer to a driver from its letter - * @param letter the driver letter + * @param letter the driver-identifier letter * @return pointer to a driver or NULL if not found */ lv_fs_drv_t * lv_fs_get_drv(char letter); @@ -144,7 +144,7 @@ lv_fs_res_t lv_fs_open(lv_fs_file_t * file_p, const char * path, lv_fs_mode_t mo /** * Make a path object for the memory-mapped file compatible with the file system interface * @param path path to a lv_fs_path_ex object - * @param letter the letter of the driver. E.g. `LV_FS_MEMFS_LETTER` + * @param letter the identifier letter of the driver. E.g. `LV_FS_MEMFS_LETTER` * @param buf address of the memory buffer * @param size size of the memory buffer in bytes */