FS Development Guide_Rev1.2

中文

Revision History

Version	Date	Author	Revision Content
Rev1.0	23-09-06	SXX	Initial document creation
Rev1.1	24-03-25	SXX	Changed document name
Rev1.2	24-12-19	YMX	Removed function links to resolve DingTalk to Feishu link issues Removed the last chapter complete example, code is subject to SDK
Rev1.3	25-02-11	LJZ	Modified liot_fopen file open mode

1 Introduction

This document introduces the LTE-EC71X fs interface APIs. The API interfaces are declared in the file components/kernel/lierda_api/liot_fs/liot_fs_api.h.

1. FS API provides file system operation interfaces, including file open, close, delete, read, write, move, truncate, get file size, get file information, get file system remaining space, get file system information, get file system directory list, change file name, and synchronize file data.

2. FS is managed by blocks. For file system size, please refer to the specific partition table, such as: components/basePkg/F6D_A/partition_info.txt. The file system block size is 4K. Different base packages have different sizes.

2 API Function Overview

Function	Description
liot_fopen()	Open a file based on file path or file name.
liot_fclose()	Close an opened file.
liot_remove()	Delete a file.
liot_fread()	Read file content.
liot_fwrite()	Write content to a file.
liot_fseek()	Set file pointer position.
liot_frewind()	Set the file position pointer to the beginning of the file.
liot_ftell()	Get current file pointer position.
liot_fstat()	Get file status based on file descriptor.
liot_stat()	Get file information based on file name.
liot_ftruncate()	Truncate file from specified length.
liot_fsize()	Get file size.
liot_file_exist()	Determine whether a file exists based on file name.
liot_mkdir()	Create a directory.
liot_opendir()	Open a directory.
liot_closedir()	Close an opened directory.
liot_readdir()	Get directory information.
liot_rename()	Change directory/file name.
liot_fsync()	Synchronize file data.
liot_internal_fs_free_size_get()	Get remaining file system size.

3 Type Descriptions

3.1 liot_file_errcode_e

FS API execution result error codes.

1. Definition

   typedef enum
   {
   LIOT_FS_OK                      = 0,
   LIOT_FS_INVALID_INPUT_VALUE     = -1,  /* invalid input value */
   LIOT_FS_LARGER_THAN_FILESIZE    = -2,  /* large than file size */
   LIOT_FS_READ_ZERO               = -3,  /* read zero byte */
   LIOT_FS_DRIVE_FULL              = -4,  /* drive full */
   LIOT_FS_MOV_ERROR               = -5,  /* move error */
   LIOT_FS_FILE_NOT_FOUND          = -6,  /* file not found */
   LIOT_FS_INVALID_FILE_NAME       = -7,  /* invalidate file name*/
   LIOT_FS_FILE_ALREADY_EXISTED    = -8,  /* file already exist */
   LIOT_FS_FAILED_TO_CREATE_FILE   = -9,  /* failed to create file */
   LIOT_FS_FAILED_TO_WRITE_FILE    = -10, /* failed to write file */
   LIOT_FS_FAILED_TO_OPEN_FILE     = -11, /* failed to open file */
   LIOT_FS_FAILED_TO_READ_FILE     = -12, /* failed to read file */
   LIOT_FS_EXCEED_MAX_LENGTH       = -13, /* exceed max length */
   LIOT_FS_REACH_MAX_OPENFILE_NUM  = -14, /* reach max opened file num */
   LIOT_FS_IS_READONLY             = -15, /* file is the read-only */
   LIOT_FS_GET_SIZE_FAIL           = -16, /* get file size failed */
   LIOT_FS_INVALID_FILE_DESCRIPTOR = -17, /* description invalidate */
   LIOT_FS_LIST_FILE_FAIL          = -18, /* failed to list file */
   LIOT_FS_DELETE_FILE_FAIL        = -19, /* failed to delete file */
   LIOT_FS_GET_DISK_INFO_FAIL      = -20, /* failed to get disk info */
   LIOT_FS_NO_SPACE                = -21, /* disk no space */
   LIOT_FS_TIME_OUT                = -22, /*time out */
   LIOT_FS_FILE_NOT_FOUND_2        = -23, /* file not found */
   LIOT_FS_FILE_TOO_LARGE          = -24, /* file too large */
   LIOT_FS_FILE_ALREADY_EXIST      = -25, /* file already exist */
   LIOT_FS_INVALID_PARAMETER       = -26, /* invalidate parameter */
   LIOT_FS_ALREADY_OPERATION       = -27, /* file already open */
   LIOT_FS_ERROR_GENERAL           = -28,
   LIOT_FS_RENAME_ERROR            = -29,
   LIOT_FS_QUIT_DATE_MODE          = -30,
   LIOT_FS_CLOSE_FAIL              = -31,
   LIOT_FS_SEEK_FAIL               = -32,
   LIOT_FS_TELL_FAIL               = -33,
   LIOT_FS_FAILED_TO_GET_STAT      = -34,
   LIOT_FS_NOT_EXIST               = -35,
   LIOT_FS_RENAME_FAIL             = -36,
   LIOT_FS_TRUNCATE_FAIL           = -37,
   LIOT_FS_DIR_MAKE_FAIL           = -38,
   LIOT_FS_DIR_OPEN_FAIL           = -39,
   LIOT_FS_DIR_CLOSE_FAIL          = -40,
   LIOT_FS_DIR_READ_FAIL           = -41,
   LIOT_FS_DIR_TELL_FAIL           = -42,
   LIOT_FS_DIR_SEEK_FAIL           = -43,
   LIOT_FS_DIR_REMOVE_FAIL         = -44,
   LIOT_FS_DIR_DIR_ALREADY_EXIST   = -45,
   LIOT_FS_ERROR_MAX,
   } liot_file_errcode_e;
   

2. Parameters

• LIOT_FS_OK: API executed successfully.

• LIOT_FS_INVALID_INPUT_VALUE: Input parameter error.

• LIOT_FS_LARGER_THAN_FILESIZE: Length greater than file size.

• LIOT_FS_READ_ZERO: Read 0 bytes.

• LIOT_FS_DRIVE_FULL: File system memory is full.

• LIOT_FS_MOV_ERROR: Failed to delete file.

• LIOT_FS_FILE_NOT_FOUND: File not found.

• LIOT_FS_INVALID_FILE_NAME: Input file name does not exist.

• LIOT_FS_FILE_ALREADY_EXISTED: File already exists.

• LIOT_FS_FAILED_TO_CREATE_FILE: Failed to create file.

• LIOT_FS_FAILED_TO_WRITE_FILE: Failed to write data to file.

• LIOT_FS_FAILED_TO_OPEN_FILE: Failed to open file.

• LIOT_FS_FAILED_TO_READ_FILE: Failed to read file content.

• LIOT_FS_EXCEED_MAX_LENGTH: File exceeds maximum length.

• LIOT_FS_REACH_MAX_OPENFILE_NUM: Reached maximum number of open files.

• LIOT_FS_IS_READONLY: File is read-only.

• LIOT_FS_GET_SIZE_FAIL: Failed to get file size.

• LIOT_FS_INVALID_FILE_DESCRIPTOR: Invalid file descriptor.

• LIOT_FS_LIST_FILE_FAIL: Failed to get file list.

• LIOT_FS_DELETE_FILE_FAIL: Failed to delete file.

• LIOT_FS_GET_DISK_INFO_FAIL: Failed to get file system information.

• LIOT_FS_NO_SPACE: Insufficient space.

• LIOT_FS_TIME_OUT: Timeout.

• LIOT_FS_FILE_NOT_FOUND_2: File not found.

• LIOT_FS_FILE_TOO_LARGE: File too large.

• LIOT_FS_FILE_ALREADY_EXIST: File already exists.

• LIOT_FS_INVALID_PARAMETER: Parsing failed.

• LIOT_FS_ALREADY_OPERATION: File already open.

• LIOT_FS_ERROR_GENERAL: General error.

• LIOT_FS_RENAME_ERROR: File rename failed.

• LIOT_FS_QUIT_DATE_MODE: Failed to exit file data mode.

• LIOT_FS_CLOSE_FAIL: Failed to close file.

• LIOT_FS_SEEK_FAIL: Failed to set file pointer position.

• LIOT_FS_TELL_FAIL: Failed to get file pointer position.

• LIOT_FS_FAILED_TO_GET_STAT: Failed to get file information.

• LIOT_FS_NOT_EXIST: File does not exist.

• LIOT_FS_RENAME_FAIL: File rename failed.

• LIOT_FS_TRUNCATE_FAIL: Failed to truncate file length.

• LIOT_FS_DIR_MAKE_FAIL: Failed to create directory.

• LIOT_FS_DIR_OPEN_FAIL: Failed to open directory.

• LIOT_FS_DIR_CLOSE_FAIL: Failed to close directory.

• LIOT_FS_DIR_READ_FAIL: Failed to read directory.

• LIOT_FS_DIR_TELL_FAIL

• LIOT_FS_DIR_SEEK_FAIL

• LIOT_FS_DIR_REMOVE_FAIL

• LIOT_FS_DIR_DIR_ALREADY_EXIST: Directory already exists.

• LIOT_FS_ERROR_MAX,

3.2 liot_stat_s

File information type.

1. Definition

typedef struct
{
    UINT8 type;
    UINT32 size;
    CHAR name[LIOT_FS_NAME_MAX + 1];
} liot_stat_s;

2. Parameters

• type: File type, 0x001: file type, 0x002: directory type.

Reference macros:

#define LIOT_FS_TYPE_FILE 0x001
#define LIOT_FS_TYPE_DIR  0x002

• size: File size.

• name: File name.

3.3 LDIR

Directory descriptor type.

1. Definition

typedef struct
{
    INT32 fs_index;  ///< internal fs index
    INT32 _reserved; ///< reserved
} LDIR;

2. Parameters

• fs_index: Internal file sorting number, i.e., ID number of internal directory list.

• _reserved: Context parameter passed by user when registering callback.

3.4 ldirent

Directory information type.

1. Definition

 typedef struct
{
    INT32 d_info;     ///< inode number, file system implementation can use it for any purpose
    UINT8 d_type;     ///< type of file
    CHAR d_name[256]; ///< file name
} ldirent;

2. Parameters

• d_info: Internal file sorting number, i.e., ID number of internal directory list.

• d_type: File type.

• d_name: Directory name.

4 API Function Details

4.1 liot_fopen

Open a file based on file path or file name.

1. Declaration

LFILE liot_fopen(const char *file_name, const char *mode);

2. Parameters

file_name: [in] File path or file name.

mode: [in] File open mode.

r or rb: Open as read-only file, fails if file does not exist.

r+ or rb+: Open as read-write file, fails if file does not exist.

w or wb: Open as write-only file, clears if file exists, creates if not exists.

w+ or wb+: Open as read-write file, clears if file exists, creates if not exists.

a or ab: Open as write-append file, appends at end if file exists, creates if not exists.

a+/ab+: Open as read-write-append file, appends at end if file exists, creates if not exists.

3. Return Value

LFILE: File descriptor.

4.2 liot_fclose

Close an opened file.

1. Declaration

int liot_fclose(LFILE fd);

2. Parameters

fd: [in] File descriptor.

3. Return Value

liot_file_errcode_e: File execution error code, see 3.1 for reference.

4.3 liot_remove

Delete a file based on name or file path.

1. Declaration

int liot_remove(const char *file_name);

2. Parameters

file_name: [in] File path or file name.

3. Return Value

liot_file_errcode_e: File execution error code, see 3.1 for reference.

4.4 liot_fread

Read file content.

1. Declaration

int liot_fread(void *buffer, size_t size, size_t num, LFILE fd);

2. Parameters

buffer: [out] File data read.

size: [in] Size of data to read from file each time.

num: [in] Number of times to read size-sized data.

fd: [in] Opened file descriptor.

3. Return Value

Length of data read. On error, returns file execution error code, see 3.1 for reference.

4.5 liot_fwrite

Write content to a file.

1. Declaration

int liot_fwrite(void *buffer, size_t size, size_t num, LFILE fd);

2. Parameters

buffer: [in] Data to write to file.

size: [in] Size of data to write from buffer to file each time.

num: [in] Number of times to write size-sized data.

fd: [in] Opened file descriptor.

3. Return Value

Length of data successfully written to file. On error, returns file execution error code, see 3.1 for reference.

4.6 liot_fseek

Set file pointer position.

1. Declaration

int liot_fseek(LFILE fd, long offset, int origin);

2. Parameters

fd: [in] Opened file descriptor.

offset: [in] Offset length, positive for forward offset, negative for backward offset.

origin: [in] Starting position for offset.

0: File starting position.

1: File current position.

2: File ending position.

3. Return Value

Current file position. On error, returns file execution error code, see 3.1 for reference.

4.7 liot_frewind

Set file pointer to the beginning of the file.

1. Declaration

int liot_frewind(LFILE fd);

2. Parameters

fd: [in] Opened file descriptor.

3. Return Value

File execution error code, see 3.1 for reference.

4.8 liot_ftell

Get current file pointer position.

1. Declaration

int liot_ftell(LFILE fd);

2. Parameters

fd: [in] Opened file descriptor.

3. Return Value

File execution error code, see 3.1 for reference.

4.9 liot_fstat

Get file status based on file descriptor.

1. Declaration

int liot_fstat(LFILE fd, liot_stat_s *st);

2. Parameters

fd: [in] Opened file descriptor.

st: [out] liot_stat_s type file status, see 3.2 for reference.

3. Return Value

File execution error code, see 3.1 for reference.

4.10 liot_stat

Get file status based on file name or file path.

1. Declaration

int liot_stat(const char *file_name, liot_stat_s *st);

2. Parameters

file_name: [in] File name or file path.

st: [out] liot_stat_s type file status, see 3.2 for reference.

3. Return Value

File execution error code, see 3.1 for reference.

4.11 liot_ftruncate

Truncate file from specified position.

1. Declaration

int liot_ftruncate(LFILE fd, UINT32 length);

2. Parameters

fd: [in] Opened file descriptor.

length: [in] Specified file length, calculated from file starting position.

3. Return Value

Returns 0 on success, non-zero on failure. File execution error code, see 3.1 for reference.

4.12 liot_fsize

Get file size.

1. Declaration

int liot_fsize(LFILE fd);

2. Parameters

fd: [in] Opened file descriptor.

3. Return Value

Returns file size normally, returns file execution error code on error, see 3.1 for reference.

4.13 liot_file_exist

Determine whether a file exists.

1. Declaration

int liot_file_exist(const char *file_path);

2. Parameters

file_path: [in] File path.

3. Return Value

File execution error code, see 3.1 for reference.

Returns LIOT_FS_OK if exists, returns LIOT_FS_NOT_EXIST if not exists.

4.14 liot_mkdir

Create a directory.

1. Declaration

int liot_mkdir(const char *path, UINT32 mode);

2. Parameters

path: [in] Directory path or directory name.

mode: [in] (Not currently used)

3. Return Value

File execution error code, see 3.1 for reference.

4.15 liot_opendir

Open a directory.

1. Declaration

LDIR *liot_opendir(const char *path);

2. Parameters

path: [in] Directory path or directory name.

3. Return Value

LDIR directory information type descriptor, see 3.3 for reference.

4.16 liot_closedir

Close an opened directory.

1. Declaration

int liot_closedir(LDIR *pdir);

2. Parameters

pdir: [in] Directory type descriptor.

3. Return Value

File execution error code, see 3.1 for reference.

4.17 liot_readdir

Get directory information.

1. Declaration

ldirent *liot_readdir(LDIR *pdir);

2. Parameters

pdir: [in] Directory type descriptor.

3. Return Value

ldirent type directory information, see 3.3 for reference.

4.18 liot_rename

Change file name.

1. Declaration

int liot_rename(const char *oldpath, const char *newpath);

2. Parameters

oldpath: [in] File path or file name.

newpath: [in] Changed file path or file name.

3. Return Value

File execution error code, see 3.1 for reference.

4.19 liot_fsync

Synchronize file data from cache to FLASH.

1. Declaration

int liot_fsync(LFILE fd);

2. Parameters

fd: [in] Opened file descriptor.

3. Return Value

File execution error code, see 3.1 for reference.

4.20 liot_internal_fs_free_size_get

Get remaining file system size.

1. Declaration

int liot_internal_fs_free_size_get(void);

2. Parameters

None.

3. Return Value

Current remaining available space size of the file system.

5 Code Example

Refer to the examples/demo/src/demo_fs.c file for sample code.

Execution Result: