FS

Common API

group FS

The file-system driver provides support for accessing files on a flash. The following file-systems are available:

  • Read-only file system. This file-system is very basic but quite-convenient to have access to input data. The open operation does not scale well when having lots of file so this file-system should only be used with few files.

Unnamed Group

enum pi_fs_type_e

File-system type.

This can be used to select the type of file-system to mount.

Values:

enumerator PI_FS_READ_ONLY = 0

Read-only file system.

enumerator PI_FS_HOST = 1

Host file system.

enumerator PI_FS_LFS = 2

LittleFS Filesystem.

enum pi_fs_flags_e

File-system open flags.

This can be used to select the type of file-system to mount.

Values:

enumerator PI_FS_FLAGS_READ = 0

File is opened for reading.

enumerator PI_FS_FLAGS_WRITE = 1

File is opened for writing.

enumerator PI_FS_FLAGS_APPEND = 2

File is opened for appending (writing at end of file).

enumerator PI_FS_FLAGS_CREATE = 4
enumerator PI_FS_FLAGS_MAX = 255
enum pi_fs_file_type_e

Values:

enumerator PI_FS_TYPE_REG = 1
enumerator PI_FS_TYPE_DIR = 2
enum pi_fs_error_e

Values:

enumerator PI_FS_ERR_OK = 0
enumerator PI_FS_ERR_IO = -5
enumerator PI_FS_ERR_CORRUPT = -84
enumerator PI_FS_ERR_NOENT = -2
enumerator PI_FS_ERR_EXIST = -17
enumerator PI_FS_ERR_NOTDIR = -20
enumerator PI_FS_ERR_ISDIR = -21
enumerator PI_FS_ERR_NOTEMPTY = -39
enumerator PI_FS_ERR_BADF = -9
enumerator PI_FS_ERR_FBIG = -27
enumerator PI_FS_ERR_INVAL = -22
enumerator PI_FS_ERR_NOSPC = -28
enumerator PI_FS_ERR_NOMEM = -12
enumerator PI_FS_ERR_NOATTR = -61
enumerator PI_FS_ERR_NAMETOOLONG = -36
enumerator PI_FS_ERR_UNSUPPORTED = -37
enumerator PI_FS_MOUNT_FLASH_ERROR = 1
enumerator PI_FS_MOUNT_MEM_ERROR = 2
typedef struct pi_fs_info_s pi_fs_info_t
typedef struct pi_fs_file_s pi_fs_file_t

FS file structure.

This structure is used by the runtime to store information about a file.

typedef struct pi_fs_dir_s pi_fs_dir_t

FS dir structure.

This structure is used by the runtime to store information about a diractory.

typedef struct pi_cl_fs_req_s pi_cl_fs_req_t

FS cluster file request structure.

This structure is used by the runtime to manage a cluster remote operation with the FS. It must be instantiated once for each operation and must be kept alive until the operation is finished. It can be instantiated as a normal variable, for example as a global variable, a local one on the stack, or through a memory allocator.

void pi_fs_conf_init(struct pi_fs_conf *conf)

Initialize a file-system configuration with default values.

The structure containing the configuration must be kept allocated until the file-system is mounted.

Parameters:

  • conf – A pointer to the file-system configuration.

int32_t pi_fs_mount(struct pi_device *device)

Mount a file-system.

This function must be called before the file-system device can be used. It will do all the needed configuration to make it usable and initialize the handle used to refer to this opened device when calling other functions.

Parameters:

  • device – A pointer to the device structure of the device to open. This structure is allocated by the called and must be kept alive until the device is closed.

Returns:

0 if the operation is successfull, -1 if there was an error.

void pi_fs_unmount(struct pi_device *device)

Unmount a mounted file-system.

This function can be called to close a mounted file-system once it is not needed anymore, in order to free all allocated resources. Once this function is called, the file-system is not accessible anymore and must be mounted again before being used.

Parameters:

  • device – The device structure of the FS to unmount.

int32_t pi_fs_mkdir(struct pi_device *device, const char *path)

Create a Directory (only for read/write fs i.e. little FS)

This function can be called to create a directory

Parameters:

  • device – The device structure of the FS where to open the file.

  • path – The path of the directory to be created

Returns:

0 if successfull, other if error

int32_t pi_fs_remove(struct pi_device *device, const char *path)

Remove a Directory or a file (only for read/write fs i.e. little FS)

This function can be called to remove a directory or a regular file.

Parameters:

  • device – The device structure of the FS where to open the file.

  • path – The path of the directory or file to be remove

Returns:

0 if successfull, other if error

int32_t pi_fs_ls(struct pi_device *device, const char *path)

List the content of a directory.

This function can be called to list the content of directory which is printed to STDOUT. This is a debug function.

Parameters:

  • device – The device structure of the FS where to open the file.

  • path – The path of the directory to be listed

pi_fs_file_t *pi_fs_dir_open(struct pi_device *device, const char *path)

Open a diractory.

This function can be called to open a file on a file-system in order to read or write data to it.

Parameters:

  • device – The device structure of the FS where to open the file.

  • path – The path to the directory to be opened.

Returns:

NULL if the directory is not found, or a handle identifying the directory which can be used with other functions.

void pi_fs_dir_close(pi_fs_file_t *file)

Close a directory.

This function can be called to close an opened directory once it is not needed anymore in order to free the allocated resources.

Parameters:

  • file – The handle of the file to be closed.

int32_t pi_fs_dir_read(pi_fs_file_t *file, pi_fs_info_t *info)

Read directory content.

This function can be called to read the content of a directory. The infos are read from the current position which is the beginning of the directory when the it is opened. The current position is incremented by the number of bytes read by the call to this function. The caller is blocked until the transfer is finished.

Parameters:

  • file – The handle of the file where to read directory information.

  • info – A structure with file information.

Returns:

0 if end of directory, < 0 if error, > 0 otherwise be smaller than the requested size if the end of file is reached.

pi_fs_file_t *pi_fs_open(struct pi_device *device, const char *file, int flags)

Open a file.

This function can be called to open a file on a file-system in order to read or write data to it.

Parameters:

  • device – The device structure of the FS where to open the file.

  • file – The path to the file to be opened.

  • flags – Optional flags to configure how the file is opened.

Returns:

NULL if the file is not found, or a handle identifying the file which can be used with other functions.

void pi_fs_close(pi_fs_file_t *file)

Close a file.

This function can be called to close an opened file once it is not needed anymore in order to free the allocated resources.

Parameters:

  • file – The handle of the file to be closed.

int32_t pi_fs_read(pi_fs_file_t *file, void *buffer, uint32_t size)

Read data from a file.

This function can be called to read data from an opened file. The data is read from the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes read by the call to this function. The caller is blocked until the transfer is finished. Compared to pi_fs_direct_read, this functions can use a cache to optimize small transfers. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • buffer – The memory location where the read data must be copied.

  • size – The size in bytes to read from the file.

Returns:

The number of bytes actually read from the file. This can be smaller than the requested size if the end of file is reached.

int32_t pi_fs_write(pi_fs_file_t *file, void *buffer, uint32_t size)

Write data to a file.

This function can be called to write data to an opened file. The data is written to the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes written by the call to this function. This functionmay not be supported by each file-system. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to write data.

  • buffer – The memory location where the data to be written must be read.

  • size – The size in bytes to write to the file.

Returns:

The number of bytes actually written to the file. This can be smaller than the requested size if the end of file is reached.

int32_t pi_fs_direct_read(pi_fs_file_t *file, void *buffer, uint32_t size)

Read data from a file with no intermediate cache.

This function can be called to read data from an opened file. The data is read from the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes read by the call to this function. The caller is blocked until the transfer is finished. Compared to pi_fs_read, this function does direct read transfers from the flash without any cache. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • buffer – The memory location where the read data must be copied.

  • size – The size in bytes to read from the file.

Returns:

The number of bytes actually read from the file. This can be smaller than the requested size if the end of file is reached.

int32_t pi_fs_seek(pi_fs_file_t *file, unsigned int offset)

Reposition the current file position.

This function can be called to change the current position of a file. Note that this does not affect pending copies, but only the ones which will be enqueued after this call.

Parameters:

  • file – The handle of the file for which the current position is changed.

  • offset – The offset where to set the current position. The offset can be between 0 for the beginning of the file and the file size.

Returns:

0 if the operation was successful, -1 otherwise.

int32_t pi_fs_seek_read(pi_fs_file_t *file, uint32_t offset, void *buffer, uint32_t size)

Reposition the current file position and do a read from there.

This function can be called to change the current position of a file. Note that this does not affect pending copies, but only the ones which will be enqueued after this call. It will then directly execute a read. Final position will be offset + size

Parameters:

  • file – The handle of the file for which the current position is changed.

  • offset – The offset where to set the current position. The offset can be between 0 for the beginning of the file and the file size.

  • buffer – Buffer into which data readen from file will be written

  • size – Size to be readen from file

Returns:

0 if the operation was successful, -1 otherwise.

int32_t pi_fs_copy(pi_fs_file_t *file, uint32_t index, void *buffer, uint32_t size, int32_t ext2loc)

Copy data between a FS file and a chip memory.

This function can be called to transfer data between an opened file and a chip memory using a specified offset instead of a current position. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • index – The offset in the file where to start accessing data.

  • buffer – The memory location in the chip memory where the data is accessed.

  • size – The size in bytes to transfer.

  • ext2loc – 1 if the copy is from file to the chip or 0 for the contrary.

Returns:

0 if the operation was successful, -1 otherwise.

int32_t pi_fs_copy_2d(pi_fs_file_t *file, uint32_t index, void *buffer, uint32_t size, uint32_t stride, uint32_t length, int32_t ext2loc)

Enqueue a 2D copy (rectangle area) between a FS file and a chip memory.

This function can be called to transfer data between an opened file and a chip memory using a specified offset instead of a current position. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • index – The offset in the file where to start accessing data.

  • buffer – The memory location in the chip memory where the data is accessed.

  • size – The size in bytes to transfer.

  • stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.

  • length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.

  • ext2loc – 1 if the copy is from file to the chip or 0 for the contrary.

Returns:

0 if the operation was successful, -1 otherwise.

int32_t pi_fs_read_async(pi_fs_file_t *file, void *buffer, uint32_t size, pi_evt_t *event)

Read data from a file asynchronously.

This function can be called to read data from an opened file. The data is read from the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes read by the call to this function. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Compared to pi_fs_direct_read, this function can use a cache to optimize small transfers. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • buffer – The memory location where the read data must be copied.

  • size – The size in bytes to read from the file.

  • event – The event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

Returns:

The number of bytes actually read from the file. This can be smaller than the requested size if the end of file is reached.

int32_t pi_fs_seek_read_async(pi_fs_file_t *file, uint32_t offset, void *buffer, uint32_t size, pi_evt_t *event)

Asynchronously Reposition the current file position and do a read from there.

This function can be called to change the current position of a file. Note that this does not affect pending copies, but only the ones which will be enqueued after this call. It will then directly execute a read. Final position will be offset + size

Parameters:

  • file – The handle of the file for which the current position is changed.

  • offset – The offset where to set the current position. The offset can be between 0 for the beginning of the file and the file size.

  • buffer – Buffer into which data readen from file will be written

  • size – Size to be readen from file

  • event – pi_evt_t to be pushed at the end of operation

Returns:

0 if the operation was successful, -1 otherwise.

int32_t pi_fs_write_async(pi_fs_file_t *file, void *buffer, uint32_t size, pi_evt_t *event)

Write data to a file asynchronously.

This function can be called to write data to an opened file. The data is written to the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes written by the call to this function. This functionmay not be supported by each file-system. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to write data.

  • buffer – The memory location where the data to be written must be written.

  • size – The size in bytes to write to the file.

  • event – The event used to notify the end of transfer. See the documentation of pi_evt_t for more details.

Returns:

The number of bytes actually written to the file. This can be smaller than the requested size if the end of file is reached.

int32_t pi_fs_direct_read_async(pi_fs_file_t *file, void *buffer, uint32_t size, pi_evt_t *event)

Read data from a file with no intermediate cache asynchronously.

This function can be called to read data from an opened file. The data is read from the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes read by the call to this function. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Compared to pi_fs_read, this function does direct read transfers from the flash without any cache. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • buffer – The memory location where the read data must be copied.

  • size – The size in bytes to read from the file.

  • event – The event used to notify the end of transfer.

Returns:

The number of bytes actually read from the file. This can be smaller than the requested size if the end of file is reached.

int32_t pi_fs_copy_async(pi_fs_file_t *file, uint32_t index, void *buffer, uint32_t size, int32_t ext2loc, pi_evt_t *event)

Copy data between a FS file and a chip memory asynchronously.

This function can be called to transfer data between an opened file and a chip memory using a specified offset instead of a current position. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • index – The offset in the file where to start accessing data.

  • buffer – The memory location in the chip memory where the data is accessed.

  • size – The size in bytes to transfer.

  • ext2loc – 1 if the copy is from file to the chip or 0 for the contrary.

  • event – The event used to notify the end of transfer.

Returns:

0 if the operation was successful, -1 otherwise.

int32_t pi_fs_copy_2d_async(pi_fs_file_t *file, uint32_t index, void *buffer, uint32_t size, uint32_t stride, uint32_t length, int32_t ext2loc, pi_evt_t *event)

Enqueue a 2D copy (rectangle area) between a FS file and a chip memory asynchronously.

This function can be called to transfer data between an opened file and a chip memory using a specified offset instead of a current position. An event must be specified in order to specify how the caller should be notified when the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • index – The offset in the file where to start accessing data.

  • buffer – The memory location in the chip memory where the data is accessed.

  • size – The size in bytes to transfer.

  • stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.

  • length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.

  • ext2loc – 1 if the copy is from file to the chip or 0 for the contrary.

  • event – The event used to notify the end of transfer.

Returns:

0 if the operation was successful, -1 otherwise.

void pi_cl_fs_read(pi_fs_file_t *file, void *buffer, uint32_t size, pi_cl_fs_req_t *req)

Read data from a file from cluster side.

This function implements the same feature as pi_fs_read but can be called from cluster side in order to expose the feature on the cluster. This function can be called to read data from an opened file. The data is read from the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes read by the call to this function. This operation is asynchronous and its termination is managed through the request structure. Compared to pi_fs_direct_read, this function can use a cache to optimize small transfers. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details. The only difference compared to pi_cl_fs_read is that the file position is automatically set to 0 for the next transfer if the current transfer reaches the end of the file.

Parameters:

  • file – The handle of the file where to read data.

  • buffer – The memory location where the read data must be copied.

  • size – The size in bytes to read from the file.

  • req – The request structure used for termination.

void pi_cl_fs_write(pi_fs_file_t *file, void *buffer, uint32_t size, pi_cl_fs_req_t *req)

Write data to a file from cluster side.

This function implements the same feature as pi_fs_write but can be called from cluster side in order to expose the feature on the cluster. This function can be called to write data to an opened file. The data is written to the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes written by the call to this function. This functionmay not be supported by each file-system. The caller is blocked until the transfer is finished. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to write data.

  • buffer – The memory location where the data to be written must be read.

  • size – The size in bytes to write to the file.

  • req – The request structure used for termination.

Returns:

The number of bytes actually written to the file. This can be smaller than the requested size if the end of file is reached.

void pi_cl_fs_direct_read(pi_fs_file_t *file, void *buffer, uint32_t size, pi_cl_fs_req_t *req)

Read data from a file with no intermediate cache from cluster side.

This function implements the same feature as pi_fs_direct_read but can be called from cluster side in order to expose the feature on the cluster. This function can be called to read data from an opened file. The data is read from the current position which is the beginning of the file when the file is opened. The current position is incremented by the number of bytes read by the call to this function. This operation is asynchronous and its termination is managed through the request structure. Compared to pi_cl_fs_read, this function does direct read transfers from the flash without any cache. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • buffer – The memory location where the read data must be copied.

  • size – The size in bytes to read from the file.

  • req – The request structure used for termination.

void pi_cl_fs_seek(pi_fs_file_t *file, uint32_t offset, pi_cl_fs_req_t *req)

Reposition the current file position from cluster side.

This function can be called from cluster side to change the current position of a file. Note that this does not affect pending copies, but only the ones which will be enqueued after this call. This operation is asynchronous and its termination is managed through the request structure.

Parameters:

  • file – The handle of the file for which the current position is changed.

  • offset – The offset where to set the current position. The offset can be between 0 for the beginning of the file and the file size.

  • req – The request structure used for termination.

void pi_cl_fs_seek_read(pi_fs_file_t *file, uint32_t offset, void *buffer, uint32_t size, pi_cl_fs_req_t *req)

Reposition the current file position and read from cluster side.

This function can be called from cluster side to change the current position of a file and do a combined read. Note that this does not affect pending copies, but only the ones which will be enqueued after this call. This operation is asynchronous and its termination is managed through the request structure. At the end, the file position will in fact be at offset+size

Parameters:

  • file – The handle of the file for which the current position is changed.

  • offset – The offset where to set the current position. The offset can be between 0 for the beginning of the file and the file size.

  • buffer – Buffer into which readen data will be written

  • size – Size in bytes which will be readen from the file

  • req – The request structure used for termination.

void pi_cl_fs_copy(pi_fs_file_t *file, uint32_t index, void *buffer, uint32_t size, int32_t ext2loc, pi_cl_fs_req_t *req)

Copy data between a FS file and a chip memory from cluster side.

This function is a remote call that the cluster can do to transfer data between an opened file and a chip memory using a specified offset instead of a current position. This operation is asynchronous and its termination is managed through the request structure. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • index – The offset in the file where to start accessing data.

  • buffer – The memory location in the chip memory where the data is accessed.

  • size – The size in bytes to transfer.

  • ext2loc – 1 if the copy is from file to the chip or 0 for the contrary.

  • req – The request structure used for termination.

void pi_cl_fs_copy_2d(pi_fs_file_t *file, uint32_t index, void *buffer, uint32_t size, uint32_t stride, uint32_t length, int32_t ext2loc, pi_cl_fs_req_t *req)

Enqueue a 2D copy (rectangle area) between a FS file and a chip memory from cluster side.

This function is a remote call that the cluster can do to transfer data between an opened file and a chip memory using a specified offset instead of a current position. This operation is asynchronous and its termination is managed through the request structure. Depending on the chip, there may be some restrictions on the memory which can be used. Check the chip-specific documentation for more details.

Parameters:

  • file – The handle of the file where to read data.

  • index – The offset in the file where to start accessing data.

  • buffer – The memory location in the chip memory where the data is accessed.

  • size – The size in bytes to transfer.

  • stride – 2D stride, which is the number of bytes which are added to the beginning of the current line to switch to the next one.

  • length – 2D length, which is the number of transferred bytes after which the driver will switch to the next line.

  • ext2loc – 1 if the copy is from file to the chip or 0 for the contrary.

  • req – The request structure used for termination.

static inline int32_t pi_cl_fs_wait(pi_cl_fs_req_t *req)

Wait until the specified fs request has finished.

This blocks the calling core until the specified cluster remote copy is finished. As the remote copy is asynchronous, this also gives the number of bytes which was read.

Parameters:

  • req – The request structure used for termination.

Returns:

The number of bytes actually read from the file. This can be smaller than the requested size if the end of file is reached.

struct pi_fs_info_s
struct pi_fs_conf
#include <fs.h>

File-system configuration structure.

This structure is used to pass the desired file-system configuration to the runtime when mounting the file-system.

Public Members

pi_fs_type_e type

File-system type.

struct pi_device *flash

Flash device. The flash device must be first opened and its device structure passed here.

char *volume_name

useful if to select the volume in which the partition is located. By default this field is set to null, which uses the active application volume

char *partition_name

useful if there are several partitions of this FS type. By default this field is set to null, which allows to find the first partition compatible with this type of FS.

bool auto_format

Defined the behavior of the mount operation in case the file system could not be found in the partition. if auto_format is set to false, An error is returned . In the opposite case, if auto_format is set to true, the partition will be formated and ready to use. Not available in ReadFS.

pi_fs_api_t *api

Pointer to specific FS methods. Reserved for internal runtime usage.

WriteFS Specific API

group WriteFS

WriteFS is a filesystem enabling streamed writes on flash.

Functions

void pi_writefs_conf_init(struct pi_writefs_conf *conf)

Initialize a WriteFS configuration with default values.

The structure containing the configuration must be kept alive until the FS device is opened.

Parameters:

  • conf – A pointer to the WriteFS configuration.

struct pi_writefs_conf
#include <writefs.h>

Configuration structure for writeable filesystem.

Public Members

struct pi_fs_conf fs

Generic filesystem configuration.

uint32_t align

Alignment value (in bytes).

uint32_t pre_erase

Indicates if flash has been pre-erased.

uint32_t force_init

Forces initialization at mount time.

struct pi_write_fs_create_arg_t
#include <writefs.h>

Structure containing arguments for creating a file in the filesystem.

Public Members

uint32_t size

Size of the file in bytes. Ignored if streamed is set to 1.

const char *name

Name of the file to be created.

uint32_t timestamp

Optional timestamp for the file.