diff --git a/docs/overview/file-system.md b/docs/overview/file-system.md index dfebd5b4d..a87743173 100644 --- a/docs/overview/file-system.md +++ b/docs/overview/file-system.md @@ -8,16 +8,19 @@ LVGL has a 'File system' abstraction module that enables you to attach any type The file system is identified by a drive letter. For example, if the SD card is associated with the letter `'S'`, a file can be reached like `"S:path/to/file.txt"`. +## Ready to use drivers +The [lv_fs_if](https://github.com/lvgl/lv_fs_if) repository contains ready to use drivers using POSIX, standard C and [FATFS](http://elm-chan.org/fsw/ff/00index_e.html) API. +See it's [README](https://github.com/lvgl/lv_fs_if#readme) for the details. + ## Add a driver -To add a driver, `lv_fs_drv_t` needs to be initialized like this: +### Registering a driver +To add a driver, `lv_fs_drv_t` needs to be initialized like below. `lv_fs_drv_t` needs to be static, global or dynamically allocated and not a local varaible. ```c -lv_fs_drv_t drv; +static lv_fs_drv_t drv; /*Needs to be static or global*/ lv_fs_drv_init(&drv); /*Basic initialization*/ drv.letter = 'S'; /*An uppercase letter to identify the drive */ -drv.file_size = sizeof(my_file_object); /*Size required to store a file object*/ -drv.rddir_size = sizeof(my_dir_object); /*Size required to store a directory object (used by dir_open/close/read)*/ drv.ready_cb = my_ready_cb; /*Callback to tell if the drive is ready to use */ drv.open_cb = my_open_cb; /*Callback to open a file */ drv.close_cb = my_close_cb; /*Callback to close a file */ @@ -25,17 +28,11 @@ drv.read_cb = my_read_cb; /*Callback to read a file */ drv.write_cb = my_write_cb; /*Callback to write a file */ drv.seek_cb = my_seek_cb; /*Callback to seek in a file (Move cursor) */ drv.tell_cb = my_tell_cb; /*Callback to tell the cursor position */ -drv.trunc_cb = my_trunc_cb; /*Callback to delete a file */ -drv.size_cb = my_size_cb; /*Callback to tell a file's size */ -drv.rename_cb = my_rename_cb; /*Callback to rename a file */ - drv.dir_open_cb = my_dir_open_cb; /*Callback to open directory to read its content */ drv.dir_read_cb = my_dir_read_cb; /*Callback to read a directory's content */ drv.dir_close_cb = my_dir_close_cb; /*Callback to close a directory */ -drv.free_space_cb = my_free_space_cb; /*Callback to tell free space on the drive */ - drv.user_data = my_user_data; /*Any custom data if required*/ lv_fs_drv_register(&drv); /*Finally register the drive*/ @@ -44,11 +41,30 @@ lv_fs_drv_register(&drv); /*Finally register the drive*/ Any of the callbacks can be `NULL` to indicate that operation is not supported. -As an example of how the callbacks are used, if you use `lv_fs_open(&file, "S:/folder/file.txt", LV_FS_MODE_WR)`, LVGL: -1. Verifies that a registered drive exists with the letter `'S'`. -2. Checks if it's `open_cb` is implemented (not `NULL`). -3. Calls the set `open_cb` with `"folder/file.txt"` path. +### Implementing the callbacks + +#### Open callback +The prototype of `open_cb` looks like this: +```c +void * (*open_cb)(lv_fs_drv_t * drv, const char * path, lv_fs_mode_t mode); +``` + +`path` is path after the driver letter (e.g. "S:path/to/file.txt" -> "path/to/file.txt"). `mode` can be `LV_FS_MODE_WR` or `LV_FS_MODE_RD` to open for write or read. + +The return value is a pointer the *file object* the describes the opened file or `NULL` if there were any issues (e.g. the file wasn't found). +The returned file object will be passed to to other file system related callbacks. (see below) + +### Other callbacks +The other callbacks are quite similar. For example `write_cb` looks like this: +```c +lv_fs_res_t (*write_cb)(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw); +``` + +As `file_p` LVGL passes the return value of `open_cb`, `buf` is the data to write, `btw` is the Bytes To Write, `bw` is the actually written bytes. + +For a template to the callbacks see [lv_fs_template.c](https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_fs_template.c). + ## Usage example @@ -98,7 +114,7 @@ lv_fs_dir_close(&dir); [Image](/widgets/core/img) objects can be opened from files too (besides variables stored in the flash). -To initialize the image, the following callbacks are required: +To use files in image widgets the following callbacks are required: - open - close - read @@ -106,6 +122,7 @@ To initialize the image, the following callbacks are required: - tell + ## API ```eval_rst diff --git a/examples/porting/lv_port_fs_template.c b/examples/porting/lv_port_fs_template.c index 864980149..51b18a874 100644 --- a/examples/porting/lv_port_fs_template.c +++ b/examples/porting/lv_port_fs_template.c @@ -19,23 +19,6 @@ * TYPEDEFS **********************/ -/*Create a type to store the required data about your file. - *If you are using a File System library - *it already should have a File type. - *For example FatFS has `FIL`. In this case use `typedef FIL file_t`*/ -typedef struct { - /*Add the data you need to store about a file*/ - uint32_t dummy1; - uint32_t dummy2; -}file_t; - -/*Similarly to `file_t` create a type for directory reading too*/ -typedef struct { - /*Add the data you need to store about directory reading*/ - uint32_t dummy1; - uint32_t dummy2; -}dir_t; - /********************** * STATIC PROTOTYPES **********************/ @@ -45,13 +28,10 @@ static lv_fs_res_t fs_open (lv_fs_drv_t * drv, void * file_p, const char * path, static lv_fs_res_t fs_close (lv_fs_drv_t * drv, void * file_p); static lv_fs_res_t fs_read (lv_fs_drv_t * drv, void * file_p, void * buf, uint32_t btr, uint32_t * br); static lv_fs_res_t fs_write(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw); -static lv_fs_res_t fs_seek (lv_fs_drv_t * drv, void * file_p, uint32_t pos); +static lv_fs_res_t fs_seek (lv_fs_drv_t * drv, void * file_p, uint32_t pos, lv_fs_whence_t whence);); static lv_fs_res_t fs_size (lv_fs_drv_t * drv, void * file_p, uint32_t * size_p); static lv_fs_res_t fs_tell (lv_fs_drv_t * drv, void * file_p, uint32_t * pos_p); -static lv_fs_res_t fs_remove (lv_fs_drv_t * drv, const char *path); -static lv_fs_res_t fs_trunc (lv_fs_drv_t * drv, void * file_p); -static lv_fs_res_t fs_rename (lv_fs_drv_t * drv, const char * oldname, const char * newname); -static lv_fs_res_t fs_free (lv_fs_drv_t * drv, uint32_t * total_p, uint32_t * free_p); + static lv_fs_res_t fs_dir_open (lv_fs_drv_t * drv, void * rddir_p, const char *path); static lv_fs_res_t fs_dir_read (lv_fs_drv_t * drv, void * rddir_p, char *fn); static lv_fs_res_t fs_dir_close (lv_fs_drv_t * drv, void * rddir_p); @@ -88,7 +68,6 @@ void lv_port_fs_init(void) lv_fs_drv_init(&fs_drv); /*Set up fields...*/ - fs_drv.file_size = sizeof(file_t); fs_drv.letter = 'P'; fs_drv.open_cb = fs_open; fs_drv.close_cb = fs_close; @@ -96,13 +75,7 @@ void lv_port_fs_init(void) fs_drv.write_cb = fs_write; fs_drv.seek_cb = fs_seek; fs_drv.tell_cb = fs_tell; - fs_drv.free_space_cb = fs_free; - fs_drv.size_cb = fs_size; - fs_drv.remove_cb = fs_remove; - fs_drv.rename_cb = fs_rename; - fs_drv.trunc_cb = fs_trunc; - fs_drv.rddir_size = sizeof(dir_t); fs_drv.dir_close_cb = fs_dir_close; fs_drv.dir_open_cb = fs_dir_open; fs_drv.dir_read_cb = fs_dir_read; @@ -124,44 +97,41 @@ static void fs_init(void) /** * Open a file - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to a file_t variable - * @param path path to the file beginning with the driver letter (e.g. S:/folder/file.txt) - * @param mode read: FS_MODE_RD, write: FS_MODE_WR, both: FS_MODE_RD | FS_MODE_WR - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param path path to the file beginning with the driver letter (e.g. S:/folder/file.txt) + * @param mode read: FS_MODE_RD, write: FS_MODE_WR, both: FS_MODE_RD | FS_MODE_WR + * @return a file descriptor or NULL on error */ -static lv_fs_res_t fs_open (lv_fs_drv_t * drv, void * file_p, const char * path, lv_fs_mode_t mode) +static void * fs_open (lv_fs_drv_t * drv, const char * path, lv_fs_mode_t mode) { lv_fs_res_t res = LV_FS_RES_NOT_IMP; + void * f = NULL; + if(mode == LV_FS_MODE_WR) { /*Open a file for write*/ - - /*Add your code here*/ + f = ... /*Add your code here*/ } else if(mode == LV_FS_MODE_RD) { /*Open a file for read*/ - - /*Add your code here*/ + f = ... /*Add your code here*/ } else if(mode == (LV_FS_MODE_WR | LV_FS_MODE_RD)) { /*Open a file for read and write*/ - - /*Add your code here*/ + f = ... /*Add your code here*/ } - return res; + return file; } /** * Close an opened file - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to a file_t variable. (opened with lv_ufs_open) - * @return LV_FS_RES_OK: no error, the file is read - * any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param file_p pointer to a file_t variable. (opened with lv_ufs_open) + * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum */ static lv_fs_res_t fs_close (lv_fs_drv_t * drv, void * file_p) { @@ -174,13 +144,12 @@ static lv_fs_res_t fs_close (lv_fs_drv_t * drv, void * file_p) /** * Read data from an opened file - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to a file_t variable. - * @param buf pointer to a memory block where to store the read data - * @param btr number of Bytes To Read - * @param br the real number of read bytes (Byte Read) - * @return LV_FS_RES_OK: no error, the file is read - * any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param file_p pointer to a file_t variable. + * @param buf pointer to a memory block where to store the read data + * @param btr number of Bytes To Read + * @param br the real number of read bytes (Byte Read) + * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum */ static lv_fs_res_t fs_read (lv_fs_drv_t * drv, void * file_p, void * buf, uint32_t btr, uint32_t * br) { @@ -193,12 +162,12 @@ static lv_fs_res_t fs_read (lv_fs_drv_t * drv, void * file_p, void * buf, uint32 /** * Write into a file - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to a file_t variable - * @param buf pointer to a buffer with the bytes to write - * @param btr Bytes To Write - * @param br the number of real written bytes (Bytes Written). NULL if unused. - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param file_p pointer to a file_t variable + * @param buf pointer to a buffer with the bytes to write + * @param btr Bytes To Write + * @param br the number of real written bytes (Bytes Written). NULL if unused. + * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum */ static lv_fs_res_t fs_write(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw) { @@ -211,29 +180,13 @@ static lv_fs_res_t fs_write(lv_fs_drv_t * drv, void * file_p, const void * buf, /** * Set the read write pointer. Also expand the file size if necessary. - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to a file_t variable. (opened with lv_ufs_open ) - * @param pos the new position of read write pointer - * @return LV_FS_RES_OK: no error, the file is read - * any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param file_p pointer to a file_t variable. (opened with lv_ufs_open ) + * @param pos the new position of read write pointer + * @param whence tells from where to interpret the `pos`. See @lv_fs_whence_t + * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum */ -static lv_fs_res_t fs_seek (lv_fs_drv_t * drv, void * file_p, uint32_t pos) -{ - lv_fs_res_t res = LV_FS_RES_NOT_IMP; - - /*Add your code here*/ - - return res; -} - -/** - * Give the size of a file bytes - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to a file_t variable - * @param size pointer to a variable to store the size - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum - */ -static lv_fs_res_t fs_size (lv_fs_drv_t * drv, void * file_p, uint32_t * size_p) +static lv_fs_res_t fs_seek (lv_fs_drv_t * drv, void * file_p, uint32_t pos, lv_fs_whence_t whence) { lv_fs_res_t res = LV_FS_RES_NOT_IMP; @@ -243,11 +196,10 @@ static lv_fs_res_t fs_size (lv_fs_drv_t * drv, void * file_p, uint32_t * size_p) } /** * Give the position of the read write pointer - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to a file_t variable. - * @param pos_p pointer to to store the result - * @return LV_FS_RES_OK: no error, the file is read - * any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param file_p pointer to a file_t variable. + * @param pos_p pointer to to store the result + * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum */ static lv_fs_res_t fs_tell (lv_fs_drv_t * drv, void * file_p, uint32_t * pos_p) { @@ -258,93 +210,27 @@ static lv_fs_res_t fs_tell (lv_fs_drv_t * drv, void * file_p, uint32_t * pos_p) return res; } -/** - * Delete a file - * @param drv pointer to a driver where this function belongs - * @param path path of the file to delete - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum - */ -static lv_fs_res_t fs_remove (lv_fs_drv_t * drv, const char *path) -{ - lv_fs_res_t res = LV_FS_RES_NOT_IMP; - - /*Add your code here*/ - - return res; -} - -/** - * Truncate the file size to the current position of the read write pointer - * @param drv pointer to a driver where this function belongs - * @param file_p pointer to an 'ufs_file_t' variable. (opened with lv_fs_open ) - * @return LV_FS_RES_OK: no error, the file is read - * any error from lv_fs_res_t enum - */ -static lv_fs_res_t fs_trunc (lv_fs_drv_t * drv, void * file_p) -{ - lv_fs_res_t res = LV_FS_RES_NOT_IMP; - - /*Add your code here*/ - - return res; -} - -/** - * Rename a file - * @param drv pointer to a driver where this function belongs - * @param oldname path to the file - * @param newname path with the new name - * @return LV_FS_RES_OK or any error from 'fs_res_t' - */ -static lv_fs_res_t fs_rename (lv_fs_drv_t * drv, const char * oldname, const char * newname) -{ - lv_fs_res_t res = LV_FS_RES_NOT_IMP; - - /*Add your code here*/ - - return res; -} - -/** - * Get the free and total size of a driver in kB - * @param drv pointer to a driver where this function belongs - * @param letter the driver letter - * @param total_p pointer to store the total size [kB] - * @param free_p pointer to store the free size [kB] - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum - */ -static lv_fs_res_t fs_free (lv_fs_drv_t * drv, uint32_t * total_p, uint32_t * free_p) -{ - lv_fs_res_t res = LV_FS_RES_NOT_IMP; - - /*Add your code here*/ - - return res; -} - /** * Initialize a 'lv_fs_dir_t' variable for directory reading - * @param drv pointer to a driver where this function belongs - * @param rddir_p pointer to a 'lv_fs_dir_t' variable - * @param path path to a directory - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param path path to a directory + * @return pointer to the directory read descriptor or NULL on error */ -static lv_fs_res_t fs_dir_open (lv_fs_drv_t * drv, void * rddir_p, const char *path) +static void * fs_dir_open (lv_fs_drv_t * drv, void * rddir_p, const char *path) { - lv_fs_res_t res = LV_FS_RES_NOT_IMP; - + void * dir = NULL; /*Add your code here*/ - - return res; + dir = ... /*Add your code here*/ + return dir; } /** * Read the next filename form a directory. * The name of the directories will begin with '/' - * @param drv pointer to a driver where this function belongs - * @param rddir_p pointer to an initialized 'lv_fs_dir_t' variable - * @param fn pointer to a buffer to store the filename - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param rddir_p pointer to an initialized 'lv_fs_dir_t' variable + * @param fn pointer to a buffer to store the filename + * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum */ static lv_fs_res_t fs_dir_read (lv_fs_drv_t * drv, void * rddir_p, char *fn) { @@ -357,9 +243,9 @@ static lv_fs_res_t fs_dir_read (lv_fs_drv_t * drv, void * rddir_p, char *fn) /** * Close the directory reading - * @param drv pointer to a driver where this function belongs - * @param rddir_p pointer to an initialized 'lv_fs_dir_t' variable - * @return LV_FS_RES_OK or any error from lv_fs_res_t enum + * @param drv pointer to a driver where this function belongs + * @param rddir_p pointer to an initialized 'lv_fs_dir_t' variable + * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum */ static lv_fs_res_t fs_dir_close (lv_fs_drv_t * drv, void * rddir_p) { diff --git a/src/misc/lv_fs.h b/src/misc/lv_fs.h index 44aeb9157..85c1e33f3 100644 --- a/src/misc/lv_fs.h +++ b/src/misc/lv_fs.h @@ -61,12 +61,11 @@ typedef uint8_t lv_fs_mode_t; /** * Seek modes. */ -enum { - LV_FS_SEEK_SET = 0x00, - LV_FS_SEEK_CUR = 0x01, - LV_FS_SEEK_END = 0x02, -}; -typedef uint8_t lv_fs_whence_t; +typedef enum { + LV_FS_SEEK_SET = 0x00, /**< Set the position from absolutely (from the start of file)*/ + LV_FS_SEEK_CUR = 0x01, /**< Set the position from the current position*/ + LV_FS_SEEK_END = 0x02, /**< Set the position from the end of the file*/ +}lv_fs_whence_t; typedef struct _lv_fs_drv_t { char letter;