Data Structures
struct	pi_fs_conf
	File-system configuration structure. More...

Typedefs
typedef struct pi_fs_file_s	pi_fs_file_t
	FS file structure. More...

typedef struct pi_cl_fs_req_s	pi_cl_fs_req_t
	FS cluster file request structure. More...

Enumerations
enum	pi_fs_type_e
	File-system type. More...

enum	pi_fs_flags_e
	File-system open flags. More...

Functions
void	pi_fs_conf_init (struct pi_fs_conf *conf)
	Initialize a file-system configuration with default values. More...

int32_t	pi_fs_mount (struct pi_device *device)
	Mount a file-system. More...

void	pi_fs_unmount (struct pi_device *device)
	Unmount a mounted file-system. More...

pi_fs_file_t *	pi_fs_open (struct pi_device device, const char file, int flags)
	Open a file. More...

void	pi_fs_close (pi_fs_file_t *file)
	Close a file. More...

int32_t	pi_fs_read (pi_fs_file_t file, void buffer, uint32_t size)
	Read data from a file. More...

int32_t	pi_fs_write (pi_fs_file_t file, void buffer, uint32_t size)
	Write data to a file. More...

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. More...

int32_t	pi_fs_seek (pi_fs_file_t *file, unsigned int offset)
	Reposition the current file position. More...

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. More...

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. More...

int32_t	pi_fs_read_async (pi_fs_file_t file, void buffer, uint32_t size, pi_task_t *task)
	Read data from a file asynchronously. More...

int32_t	pi_fs_write_async (pi_fs_file_t file, void buffer, uint32_t size, pi_task_t *task)
	Write data to a file asynchronously. More...

int32_t	pi_fs_direct_read_async (pi_fs_file_t file, void buffer, uint32_t size, pi_task_t *task)
	Read data from a file with no intermediate cache asynchronously. More...

int32_t	pi_fs_copy_async (pi_fs_file_t file, uint32_t index, void buffer, uint32_t size, int32_t ext2loc, pi_task_t *task)
	Copy data between a FS file and a chip memory asynchronously. More...

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_task_t *task)
	Enqueue a 2D copy (rectangle area) between a FS file and a chip memory asynchronously. More...

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. More...

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. More...

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. More...

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. More...

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. More...

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. More...

static int32_t	pi_cl_fs_wait (pi_cl_fs_req_t *req)
	Wait until the specified fs request has finished. More...

Description

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.

Typedef Documentation

typedef struct pi_cl_fs_req_s pi_cl_fs_req_t

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.

typedef struct pi_fs_file_s pi_fs_file_t

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

Enumeration Type Documentation

enum pi_fs_flags_e

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

Enumerator

PI_FS_FLAGS_READ

File is opened for reading.

PI_FS_FLAGS_WRITE

File is opened for writing.

PI_FS_FLAGS_APPEND

 File is opened for appending (writing at

end of file).

enum pi_fs_type_e

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

Enumerator
PI_FS_READ_ONLY	Read-only file system.
PI_FS_HOST	Host file system.
PI_FS_LFS	LittleFS Filesystem.

Function Documentation

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
	)

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
	)

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.

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

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_read	(	pi_fs_file_t *	file,
		void *	buffer,
		uint32_t	size,
		pi_cl_fs_req_t *	req
	)

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_seek	(	pi_fs_file_t *	file,
		uint32_t	offset,
		pi_cl_fs_req_t *	req
	)

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.

static int32_t pi_cl_fs_wait ( pi_cl_fs_req_t * req )

inlinestatic

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.

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

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_fs_close ( pi_fs_file_t * 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.

void pi_fs_conf_init ( struct pi_fs_conf * conf )

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_copy	(	pi_fs_file_t *	file,
		uint32_t	index,
		void *	buffer,
		uint32_t	size,
		int32_t	ext2loc
	)

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
	)

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_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_task_t *	task
	)

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. A task 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.
task	The task used to notify the end of transfer.

Returns: 0 if the operation was successful, -1 otherwise.

int32_t pi_fs_copy_async	(	pi_fs_file_t *	file,
		uint32_t	index,
		void *	buffer,
		uint32_t	size,
		int32_t	ext2loc,
		pi_task_t *	task
	)

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. A task 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.
task	The task used to notify the end of transfer.

Returns: 0 if the operation was successful, -1 otherwise.

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

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_direct_read_async	(	pi_fs_file_t *	file,
		void *	buffer,
		uint32_t	size,
		pi_task_t *	task
	)

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. A task 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.
task	The task 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_mount ( struct pi_device * device )

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.

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

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.

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

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_read_async	(	pi_fs_file_t *	file,
		void *	buffer,
		uint32_t	size,
		pi_task_t *	task
	)

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. A task 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.
task	The task used to notify the end of transfer. See the documentation of pi_task_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	(	pi_fs_file_t *	file,
		unsigned int	offset
	)

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.

void pi_fs_unmount ( struct pi_device * device )

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_write	(	pi_fs_file_t *	file,
		void *	buffer,
		uint32_t	size
	)

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_write_async	(	pi_fs_file_t *	file,
		void *	buffer,
		uint32_t	size,
		pi_task_t *	task
	)

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. A task 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.
task	The task used to notify the end of transfer. See the documentation of pi_task_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.

Data Structures

Typedefs

Enumerations

Functions

Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation