IC:

Introduction

This section describes the types, usage scenarios, and operational methods of the Virtual File System (VFS).

The VFS implements two underlying file systems: FatFS and LittleFS.

FatFS offers advantages in compatibility, cross-platform support, and development convenience.
LittleFS excels in power-loss recovery, flash lifespan optimization, and low resource consumption.

Users can utilize VFS to abstract away differences between file systems and focus on development requirements.

VFS provides universal file operation interfaces such as fopen, fclose, fwrite, and fread (refer to Common File Operation), and the Key-Value (KV) Interface is implemented based on these universal file operations.

The VFS architecture is illustrated below:

../../_images/vfs_architecture_lite_dplus.svg

VFS Initialization

The VFS on Flash contains two independent regions:

VFS1 is initialized with LittleFS.
VFS2 is initialized with FatFS.

VFS2 does not allocate flash space by default. Users may modify configurations as needed.

When enabling the VFS within APP Image feature, VFS2 initialization will search for and identify the FatFS binary file starting from the end of the application firmware.

Note

If VFS mount operation on flash fails, the system checks whether the flash is blank (all 0xFF). If true, flash programming will be executed to initialize VFS.
To ensure proper use of FatFS, navigate to CONFIG VFS via Configuring SDK (menuconfig) and select Enable VFS FATFS while enabling required functional modules.

Usage of VFS

VFS on Flash

If you need to appropriately adjust the VFS location, refer to Flash Layout Modification Guide to modify the VFS1 or VFS2 areas.

Note

The VFS1 region must exist, and its size should always be equal to or greater than 128KB.
There are two VFS regions at most.

VFS within APP Image

If the content in the file system requires upgrades, such as replacing prompt tones and voice packages in voice solutions, VFS provides more convenient configuration capabilities. Detailed steps are as follows:

Prepare the read-only files and convert them into a FAT-formatted bin file. Refer to section FatFS Bin File Generation for the method.
Name the bin file fatfs.bin and place it in {SDK}\amebadplus_gcc_project.
Refer to Configuring SDK (menuconfig) to navigate to the CONFIG VFS configuration, then select both Enable VFS FATFS and FATFS within APP Image.
Rebuild the application firmware.

The application firmware (km0_km4_app.bin) will include a read-only VFS area in FAT format, which will be mounted during the startup process.

Prepare the read-only files and convert them into a FAT-formatted bin file. Refer to section FatFS Bin File Generation for the method.
Name the bin file fatfs.bin and place it in {SDK}\amebalite_gcc_project.
Refer to Configuring SDK (menuconfig) to navigate to the CONFIG VFS configuration, then select both Enable VFS FATFS and FATFS within APP Image.
Rebuild the application firmware.

The application firmware (kr4_km4_app.bin) will include a read-only VFS area in FAT format, which will be mounted during the startup process.

Prepare the read-only files and convert them into a FAT-formatted bin file. Refer to section FatFS Bin File Generation for the method.
Name the bin file fatfs.bin and place it in {SDK}\amebalite_gcc_project.
Refer to Configuring SDK (menuconfig) to navigate to the CONFIG VFS configuration, then select both Enable VFS FATFS and FATFS within APP Image.
Rebuild the application firmware.

The application firmware (kr4_km4_app.bin) will include a read-only VFS area in FAT format, which will be mounted during the startup process.

Prepare the read-only files and convert them into a FAT-formatted bin file. Refer to section FatFS Bin File Generation for the method.
Name the bin file fatfs.bin and place it in {SDK}\amebasmart_gcc_project.
Refer to Configuring SDK (menuconfig) to navigate to the CONFIG VFS configuration, then select both Enable VFS FATFS and FATFS within APP Image.
Rebuild the application firmware.

The application firmware (km0_km4_ca32_app.bin) will include a read-only VFS area in FAT format, which will be mounted during the startup process.

After startup, the log VFS-FAT Init Success indicates that the FAT file system has been successfully mounted.

When subsequent updates to the FAT file system content are required, they can be updated alongside image via OTA.

For the file usage method, refer to Section Common File Operation or Key-Value Operation.

Note

To optimize the effective space utilization of the file system, only FAT format is currently supported.

Common File Operation

The common file operation interfaces used in VFS are listed below:

API	Parameter	Description
fopen	const char * filename const char * mode	Open the filename pointed to, by filename using the given mode
fclose	FILE * stream	Close the stream
fread	void * ptr size_t size size_t count FILE * stream	Read data from the given stream by ptr into the array pointed to
fwrite	const void * ptr size_t size size_t count FILE * stream	Write data from the array pointed to by ptr to the given stream
fseek	FILE * stream long int offset int origin	Set the file position of the stream to the given offset
rewind	FILE * stream	Set the file position to the beginning of the file of the given stream
fgetpos	FILE * stream fpos_t * p	Get the current file position of the stream and writes it to pos
fsetpos	FILE * stream fpos_t * p	Set the file position of the given stream to the given position
fflush	FILE * stream	Flush the output buffer of a stream
remove	const char * filename	Delete the given filename so that it is no longer accessible
rename	const char * oldname const char * newname	Cause the filename referred to from old_filename to new_filename
feof	FILE * stream	Test the end-of-file indicator for the given stream
ferror	FILE * stream	Test the error indicator for the given stream
ftell	FILE * stream	Return the current file position of the given stream
ftruncate	FILE * stream off_t length	Truncate a file to a specified length
opendir	const char * name	Open a directory
readdir	DIR * pdir	Read a directory
closedir	DIR * dirp	Close a directory
rmdir	const char * path	Remove a directory
mkdir	const char * pathname mode_t mode	Make a directory
access	const char * pathname int mode	Determine accessibility of a file
stat	const char * path struct stat * buf	Get file status

Users can refer to VFS example to test how common file operations work. Test logs should be like below:

[example_vfs_thread] fwrite succeeded !!!
[example_vfs_thread] fread succeeded !!!
[example_vfs_thread] remove file succeeded !!!

Note

The return value of fseek differs from standard implementations: it returns the current file pointer offset relative to the file start upon success.

Key-Value Operation

Simple KV interfaces are also provided for users. All KV APIs are placed in kv.c.

Users can refer to KV example to test how KV APIs work. Test logs should be like below:

rt_kv_set success, write 28 letters.
rt_kv_get success, read 28 letters.
rt_kv_delett success.

Note

KV operations occur in the KV directory under the VFS1 partition, where keys correspond to filenames and values to file contents.

Code Conversion

The conversion between Unicode and other codes is not supported on FatFS by default.

Modify the macro FF_CODE_PAGE in ffconf.h to enable the code conversion function, where FF_CODE_PAGE should be chosen as code page number which is desired.

#define FF_CODE_PAGE  999
/* This option specifies the OEM code page to be used on the target system.
/  Incorrect code page setting can cause a file open failure.
/   437 - U.S.
/   720 - Arabic
/   737 - Greek
/   771 - KBL
/   775 - Baltic
/   850 - Latin 1
/   852 - Latin 2
/   855 - Cyrillic
/   857 - Turkish
/   860 - Portuguese
/   861 - Icelandic
/   862 - Hebrew
/   863 - Canadian French
/   864 - Arabic
/   865 - Nordic
/   866 - Russian
/   869 - Greek 2
/   932 - Japanese (DBCS)
/   936 - Simplified Chinese (DBCS)
/   949 - Korean (DBCS)
/   950 - Traditional Chinese (DBCS)
/   999 - Realtek defined for code size
/     0 - Include all code pages above and configured by f_setcp()
*/

VFS Encryption

For special storage security needs, users can configure encryption and decryption interfaces of VFS.

This functionality requires users to prepare encryption/decryption functions and keys in advance by referring to the VFS encryption/decryption example.

After successfully running the example program, the test logs should include the following key information:

[example_vfs_encrypt_thread] fwrite succeeded !!!
[example_vfs_encrypt_thread] fread succeeded !!!
[example_vfs_encrypt_thread] remove file succeeded !!!

Note

Plaintext will be padded according to the length of grouped data. It will take more cost of memory space if using vfs encryption.

VFS Bin File Generation

If data needs to be placed in the Flash in advance, VFS bin file can be generated on PC. After generating the bin file, it should be downloaded to VFS region according to the Flash layout.

LittleFS Bin File Generation

Prepare a needed object folder including files before generating LittleFS bin files. For example:
```
root:~$ ls -R test
test:
AUDIO KV

test/AUDIO
audio_test.mp3

test/KV
kv_test.txt
```
AUDIO and KV directories will be LittleFS directory in the Flash. The test directory is equivalent to the root directory.
Use the command $vfs.py -t LITTLEFS -s 4096 -c 32 -dir TEST -out image_littlefs.bin with the vfs.py to generate the LittleFS binary file,

Where:

s:

block size

c:

block count

dir:

source directory

out:

output LittleFS bin file name
```
root:~$ vfs.py -t LITTLEFS -s 4096 -c 32 -dir test -out image_littlefs.bin
args:
├─ type: LITTLEFS
├─ block_size: 4096
├─ block_count: 32
├─ image_size: 131072
├─ source_directory: test
└─ output_image: image_littlefs.bin
```
Note
- -s 4096 is the default configuration of LittleFS. Users must align this value with the block_size defined in the lfs_config struct within littlefs_adapter.c.
- -c 32 should be configured based on the VFS partition size described in VFS on Flash, where the partition size equals block size × block count.
Download the image to the Flash.

Refer to Image Download to download the binary file into Flash. The start address of Image Tool should be StartAddr of VFS Flash region mentioned in Section VFS on Flash. The end address of Image Tool should be it’s EndAddr + 1.

FatFS Bin File Generation

Prepare a needed object folder including files before generating FatFS bin files. For example:
```
root:~$ ls -R test
test:
AUDIO KV

test/AUDIO
audio_test.mp3

test/KV
kv_test.txt
```
AUDIO and KV directories will be FatFS directory in the Flash. The test directory is equivalent to the root directory.
Use the command $vfs.py -t FatFS -s 512 -c 256 -dir test -out image_fatfs.bin with the vfs.py to generate the FatFS binary file,

Where:

s:

sector size

c:

sector count

dir:

source directory

out:

output FatFS bin file name
```
root:~$ vfs.py -t FATFS -s 512 -c 256 -dir test -out image_fatfs.bin
image_fatfs.bin has been successfully generated.
args:
├─ type: FATFS
├─ sector_size: 512
├─ sector_count: 256
├─ image_size: 131072
├─ source_directory: test
└─ output_image: image_fatfs.bin
```
Note
- -s 512 is the default configuration of FatFS which can be omitted.
- -c 256 should be configured based on the VFS partition size described in VFS on Flash, where the partition size equals sector size × sector count.
Download the image to the Flash.

Refer to Image Download to download the binary file into Flash. The start address of Image Tool should be StartAddr of VFS Flash region mentioned in Section VFS on Flash. The end address of Image Tool should be it’s EndAddr + 1.