github-code/lvgl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(filesystem) update to v8

Browse Source
This commit is contained in:
Gabor Kiss-Vamosi
2021-06-14 11:07:15 +02:00
parent 5cf6303e74
commit 7971ade47b
3 changed files with 89 additions and 187 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/overview/file-system.md
View File

@@ -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. 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"`. 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 ## 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 ```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*/ lv_fs_drv_init(&drv); /*Basic initialization*/
drv.letter = 'S'; /*An uppercase letter to identify the drive */ 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.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.open_cb = my_open_cb; /*Callback to open a file */
drv.close_cb = my_close_cb; /*Callback to close 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.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.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.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_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_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.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*/ drv.user_data = my_user_data; /*Any custom data if required*/
lv_fs_drv_register(&drv); /*Finally register the drive*/ 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. 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'`. ### Implementing the callbacks
2. Checks if it's `open_cb` is implemented (not `NULL`).
3. Calls the set `open_cb` with `"folder/file.txt"` path. #### 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 ## 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). [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 - open
- close - close
- read - read
@@ -106,6 +122,7 @@ To initialize the image, the following callbacks are required:
- tell - tell
## API ## API
```eval_rst ```eval_rst

218
examples/porting/lv_port_fs_template.c
View File

@@ -19,23 +19,6 @@
* TYPEDEFS * 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 * 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_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_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_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_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_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_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_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); 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); lv_fs_drv_init(&fs_drv);
/*Set up fields...*/ /*Set up fields...*/
fs_drv.file_size = sizeof(file_t);
fs_drv.letter = 'P'; fs_drv.letter = 'P';
fs_drv.open_cb = fs_open; fs_drv.open_cb = fs_open;
fs_drv.close_cb = fs_close; fs_drv.close_cb = fs_close;
@@ -96,13 +75,7 @@ void lv_port_fs_init(void)
fs_drv.write_cb = fs_write; fs_drv.write_cb = fs_write;
fs_drv.seek_cb = fs_seek; fs_drv.seek_cb = fs_seek;
fs_drv.tell_cb = fs_tell; 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_close_cb = fs_dir_close;
fs_drv.dir_open_cb = fs_dir_open; fs_drv.dir_open_cb = fs_dir_open;
fs_drv.dir_read_cb = fs_dir_read; fs_drv.dir_read_cb = fs_dir_read;
@@ -124,44 +97,41 @@ static void fs_init(void)
/** /**
* Open a file * Open a file
* @param drv pointer to a driver where this function belongs * @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 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
* @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
* @return LV_FS_RES_OK or any error from lv_fs_res_t enum
*/ */
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; lv_fs_res_t res = LV_FS_RES_NOT_IMP;
void * f = NULL;
if(mode == LV_FS_MODE_WR) if(mode == LV_FS_MODE_WR)
{ {
/*Open a file for write*/ /*Open a file for write*/
f = ... /*Add your code here*/
/*Add your code here*/
} }
else if(mode == LV_FS_MODE_RD) else if(mode == LV_FS_MODE_RD)
{ {
/*Open a file for read*/ /*Open a file for read*/
f = ... /*Add your code here*/
/*Add your code here*/
} }
else if(mode == (LV_FS_MODE_WR | LV_FS_MODE_RD)) else if(mode == (LV_FS_MODE_WR | LV_FS_MODE_RD))
{ {
/*Open a file for read and write*/ /*Open a file for read and write*/
f = ... /*Add your code here*/
/*Add your code here*/
} }
return res; return file;
} }
/** /**
* Close an opened file * Close an opened file
* @param drv pointer to a driver where this function belongs * @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 file_p pointer to a file_t variable. (opened with lv_ufs_open)
* @return LV_FS_RES_OK: no error, the file is read * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum
* any error from lv_fs_res_t enum
*/ */
static lv_fs_res_t fs_close (lv_fs_drv_t * drv, void * file_p) 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 * Read data from an opened file
* @param drv pointer to a driver where this function belongs * @param drv pointer to a driver where this function belongs
* @param file_p pointer to a file_t variable. * @param file_p pointer to a file_t variable.
* @param buf pointer to a memory block where to store the read data * @param buf pointer to a memory block where to store the read data
* @param btr number of Bytes To Read * @param btr number of Bytes To Read
* @param br the real number of read bytes (Byte Read) * @param br the real number of read bytes (Byte Read)
* @return LV_FS_RES_OK: no error, the file is read * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum
* 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) 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 * Write into a file
* @param drv pointer to a driver where this function belongs * @param drv pointer to a driver where this function belongs
* @param file_p pointer to a file_t variable * @param file_p pointer to a file_t variable
* @param buf pointer to a buffer with the bytes to write * @param buf pointer to a buffer with the bytes to write
* @param btr Bytes To Write * @param btr Bytes To Write
* @param br the number of real written bytes (Bytes Written). NULL if unused. * @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 * @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) 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. * Set the read write pointer. Also expand the file size if necessary.
* @param drv pointer to a driver where this function belongs * @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 file_p pointer to a file_t variable. (opened with lv_ufs_open )
* @param pos the new position of read write pointer * @param pos the new position of read write pointer
* @return LV_FS_RES_OK: no error, the file is read * @param whence tells from where to interpret the `pos`. See @lv_fs_whence_t
* any error from lv_fs_res_t enum * @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) 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;
/*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)
{ {
lv_fs_res_t res = LV_FS_RES_NOT_IMP; 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 * Give the position of the read write pointer
* @param drv pointer to a driver where this function belongs * @param drv pointer to a driver where this function belongs
* @param file_p pointer to a file_t variable. * @param file_p pointer to a file_t variable.
* @param pos_p pointer to to store the result * @param pos_p pointer to to store the result
* @return LV_FS_RES_OK: no error, the file is read * @return LV_FS_RES_OK: no error or any error from @lv_fs_res_t enum
* 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) 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; 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 * Initialize a 'lv_fs_dir_t' variable for directory reading
* @param drv pointer to a driver where this function belongs * @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
* @param path path to a directory * @return pointer to the directory read descriptor or NULL on error
* @return LV_FS_RES_OK or any error from lv_fs_res_t enum
*/ */
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*/ /*Add your code here*/
dir = ... /*Add your code here*/
return res; return dir;
} }
/** /**
* Read the next filename form a directory. * Read the next filename form a directory.
* The name of the directories will begin with '/' * The name of the directories will begin with '/'
* @param drv pointer to a driver where this function belongs * @param drv pointer to a driver where this function belongs
* @param rddir_p pointer to an initialized 'lv_fs_dir_t' variable * @param rddir_p pointer to an initialized 'lv_fs_dir_t' variable
* @param fn pointer to a buffer to store the filename * @param fn pointer to a buffer to store the filename
* @return LV_FS_RES_OK or any error from lv_fs_res_t enum * @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) 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 * Close the directory reading
* @param drv pointer to a driver where this function belongs * @param drv pointer to a driver where this function belongs
* @param rddir_p pointer to an initialized 'lv_fs_dir_t' variable * @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 * @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) static lv_fs_res_t fs_dir_close (lv_fs_drv_t * drv, void * rddir_p)
{ {

11
src/misc/lv_fs.h
View File

@@ -61,12 +61,11 @@ typedef uint8_t lv_fs_mode_t;
/** /**
* Seek modes. * Seek modes.
*/ */
enum { typedef enum {
LV_FS_SEEK_SET = 0x00, LV_FS_SEEK_SET = 0x00, /**< Set the position from absolutely (from the start of file)*/
LV_FS_SEEK_CUR = 0x01, LV_FS_SEEK_CUR = 0x01, /**< Set the position from the current position*/
LV_FS_SEEK_END = 0x02, LV_FS_SEEK_END = 0x02, /**< Set the position from the end of the file*/
}; }lv_fs_whence_t;
typedef uint8_t lv_fs_whence_t;
typedef struct _lv_fs_drv_t { typedef struct _lv_fs_drv_t {
char letter; char letter;