Update LVGL to v9.1.0

lib/lvgl/docs/overview/fs.rst

@@ -0,0 +1,161 @@
+.. _overview_file_system:
+
+===========
+File system
+===========
+
+LVGL has a 'File system' abstraction module that enables you to attach
+any type of file system. A file system is identified by an assigned
+drive letter. For example, if an SD card is associated with the letter
+``'S'``, a file can be reached using ``"S:path/to/file.txt"``.
+
+Ready to use drivers
+********************
+
+LVGL contains prepared drivers for the API of POSIX, standard C,
+Windows, and `FATFS <http://elm-chan.org/fsw/ff/00index_e.html>`__.
+Learn more :ref:`here <libs_filesystem>`.
+
+Adding a driver
+***************
+
+Registering a driver
+--------------------
+
+To add a driver, a :cpp:type:`lv_fs_drv_t` needs to be initialized like below.
+The :cpp:type:`lv_fs_drv_t` needs to be static, global or dynamically allocated
+and not a local variable.
+
+.. code:: c
+
+   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.cache_size = my_cache_size;           /*Cache size for reading in bytes. 0 to not cache.*/
+
+   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.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.user_data = my_user_data;             /*Any custom data if required*/
+
+   lv_fs_drv_register(&drv);                 /*Finally register the drive*/
+
+Any of the callbacks can be ``NULL`` to indicate that operation is not
+supported.
+
+Implementing the callbacks
+--------------------------
+
+Open callback
+^^^^^^^^^^^^^
+
+The prototype of ``open_cb`` looks like this:
+
+.. code:: c
+
+   void * (*open_cb)(lv_fs_drv_t * drv, const char * path, lv_fs_mode_t mode);
+
+``path`` is the path after the drive letter (e.g. "S:path/to/file.txt" -> "path/to/file.txt").
+``mode`` can be :cpp:enumerator:`LV_FS_MODE_WR` or :cpp:enumerator:`LV_FS_MODE_RD` to open for writes or reads.
+
+The return value is a pointer to a *file object* that 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 other file system
+related callbacks. (see below)
+
+Other callbacks
+---------------
+
+The other callbacks are quite similar. For example ``write_cb`` looks
+like this:
+
+.. code:: c
+
+   lv_fs_res_t (*write_cb)(lv_fs_drv_t * drv, void * file_p, const void * buf, uint32_t btw, uint32_t * bw);
+
+For ``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 of these callbacks see
+`lv_fs_template.c <https://github.com/lvgl/lvgl/blob/master/examples/porting/lv_port_fs_template.c>`__.
+
+Usage example
+*************
+
+The example below shows how to read from a file:
+
+.. code:: c
+
+   lv_fs_file_t f;
+   lv_fs_res_t res;
+   res = lv_fs_open(&f, "S:folder/file.txt", LV_FS_MODE_RD);
+   if(res != LV_FS_RES_OK) my_error_handling();
+
+   uint32_t read_num;
+   uint8_t buf[8];
+   res = lv_fs_read(&f, buf, 8, &read_num);
+   if(res != LV_FS_RES_OK || read_num != 8) my_error_handling();
+
+   lv_fs_close(&f);
+
+The mode in :cpp:func:`lv_fs_open` can be :cpp:enumerator:`LV_FS_MODE_WR` to open for writes
+only or :cpp:enumerator:`LV_FS_MODE_RD` ``|`` :cpp:enumerator:`LV_FS_MODE_WR` for both
+
+This example shows how to read a directory's content. It's up to the
+driver how to mark directories in the result but it can be a good
+practice to insert a ``'/'`` in front of each directory name.
+
+.. code:: c
+
+   lv_fs_dir_t dir;
+   lv_fs_res_t res;
+   res = lv_fs_dir_open(&dir, "S:/folder");
+   if(res != LV_FS_RES_OK) my_error_handling();
+
+   char fn[256];
+   while(1) {
+       res = lv_fs_dir_read(&dir, fn, sizeof(fn));
+       if(res != LV_FS_RES_OK) {
+           my_error_handling();
+           break;
+       }
+
+       /*fn is empty, if not more files to read*/
+       if(strlen(fn) == 0) {
+           break;
+       }
+
+       printf("%s\n", fn);
+   }
+
+   lv_fs_dir_close(&dir);
+
+Use drives for images
+*********************
+
+:ref:`Image <lv_image>` objects can be opened from files too (besides
+variables stored in the compiled program).
+
+To use files in image widgets the following callbacks are required:
+
+- open
+- close
+- read
+- seek
+- tell
+
+.. _overview_file_system_api:
+
+API
+***