docs(filesystem) update to v8

lvgl · Jun 14, 2021 · 7971ade · 7971ade
1 parent 5cf6303
commit 7971ade
Showing 3 changed files with 89 additions and 187 deletions.
diff --git a/docs/overview/file-system.md b/docs/overview/file-system.md
@@ -8,34 +8,31 @@ 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 */
 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,14 +114,15 @@ 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
 - seek
 - tell
 
 
+
 ## API
 
 ```eval_rst