4.2. fs — Debug and virtual file system

The debug file system is not really a file system, but rather a file system like tree of commands, counters, parameters, and “real” file systems.

  • A command is a file path mapped to a function callback. The callback is invoked when its path is passed to the fs_call() function. Commands are registered into the debug file system by a call to fs_command_register().
  • A counter is a file path mapped to a 64 bit value. The value can be incremented and read by the application. Counters are registered into the debug file system by a call to fs_counter_register().
  • A parameter is file path mapped to a value stored in ram that can be easily read and modified by the user from a shell. Parameters are registered into the debug file system by a call to fs_parameter_register().
  • A “real” file system is a file path, or mount point, mapped to a file system instance. The virtual file system has a file access interface. The purpose of this interface is to have a common file access interface, independent of the underlying file systems interface. File systems are registered into the debug file system by a call to fs_filesystem_register().

4.2.1. Debug file system commands

The debug file system module itself registers seven commands, all located in the directory filesystems/fs/.

Command Description
filesystems/list Print a list of all registered file systems.
list [<folder>] Print a list of all files and folders in given folder.
read <file> Read from given file.
write <file> <data> Create and write to a file. Overwrites existing files.
append <file> <data> Append data to an existing file.
counters/list Print a list of all registered counters.
counters/reset Rest all counters to zero.
parameters/list Print a list of all registered parameters.

Example output from the shell:

$ filesystems/fs/filesystems/list
MOUNT-POINT                    MEDIUM   TYPE     AVAILABLE  SIZE  USAGE
/tmp                           ram      fat16          54K   64K    14%
/home/erik                     sd       fat16         1.9G    2G     5%
/etc                           flash    spiffs        124K  128K     3%
OK
$ filesystems/fs/write tmp/foo.txt "Hello "
OK
$ filesystems/fs/append tmp/foo.txt world!
OK
$ filesystems/fs/read tmp/foo.txt
Hello world!
OK
$ filesystems/fs/list tmp
xxxx-xx-xx xx-xx       12 foo.txt
OK
$ filesystems/fs/counters/list
NAME                                                 VALUE
/your/counter                                        0000000000000034
/my/counter                                          0000000000000002
OK
$ filesystems/fs/counters/reset
OK
$ filesystems/fs/counters/list
NAME                                                 VALUE
/your/counter                                        0000000000000000
/my/counter                                          0000000000000000
OK
$ filesystems/fs/parameters/list
NAME                                                 VALUE
/foo/bar                                             -2
OK

Source code: src/filesystems/fs.h, src/filesystems/fs.c

Test code: tst/filesystems/fs/main.c

Test coverage: src/filesystems/fs.c


Defines

FS_SEEK_SET
FS_SEEK_CUR

The offset is relative to the current position indicator.

FS_SEEK_END

The offset is relative to the end of the file.

FS_READ

Open for reading.

FS_WRITE

Open for write.

FS_RDWR

Open for reading and writing.

FS_APPEND

The file position indicator shall be set to the end of the file prior to each write.

FS_SYNC

Synchronous writes.

FS_CREAT

Create the file if non-existent.

FS_EXCL

If FS_CREAT and FS_EXCL are set, file open shall fail if the file exists.

FS_TRUNC

Truncate the file to zero length.

FS_TYPE_FILE
FS_TYPE_DIR

Typedefs

typedef int (*fs_callback_t)(int argc, const char *argv[], void *out_p, void *in_p, void *arg_p, void *call_arg_p)

Command callback prototype.

Return
zero(0) or negative error code.
Parameters
  • argc: Number of arguements in argv.
  • argv: An array of agruments.
  • out_p: Output channel.
  • in_p: Input channel.
  • arg_p: Argument passed to the init function of given command.
  • call_arg_p: Argument passed to the fs_call function.

typedef int (*fs_parameter_set_callback_t)(void *value_p, const char *src_p)

Parameter setter callback prototype.

Return
zero(0) or negative error code.
Parameters
  • value_p: Buffer the new value should be written to.
  • src_p: Value to set as a string.

typedef int (*fs_parameter_print_callback_t)(void *chout_p, void *value_p)

Parameter printer callback prototype.

Return
zero(0) or negative error code.
Parameters
  • chout_p: Channel to write the formatted value to.
  • value_p: Value to format and print to the output channel.

Enums

enum fs_type_t

Values:

fs_type_fat16_t = 0
fs_type_spiffs_t
fs_type_generic_t

Functions

int fs_module_init(void)

Initialize the file system module. This function must be called before calling any other function in this module.

The module will only be initialized once even if this function is called multiple times.

Return
zero(0) or negative error code.

int fs_call(char *command_p, void *chin_p, void *chout_p, void *arg_p)

Call given file system command with given input and output channels. Quote an argument if it contains spaces, otherwise it is parsed as multiple arguments. Any quotation mark in an argument string must be escaped with a backslash (\), otherwise it is interpreted as a string quotation mask.

Return
zero(0) or negative error code.
Parameters
  • command_p: Command string to call. The command string will be modified by this function, so don’t use it after this function returns.
  • chin_p: Input channel.
  • chout_p: Output channel.
  • arg_p: User argument passed to the command callback function as call_arg_p.

int fs_open(struct fs_file_t *self_p, const char *path_p, int flags)

Open a file by file path and mode flags. File operations are permitted after the file has been opened.

The path can be either absolute or relative. It’s an absolute path if it starts with a forward slash /, and relative otherwise. Relative paths are are relative to the current working directory, given by the thread environment variable CWD.

Return
zero(0) or negative error code.
Parameters
  • self_p: File object to be initialized.
  • path_p: Path of the file to open. The path can be absolute or relative.
  • flags: Mode of file open. A combination of FS_READ, FS_RDONLY, FS_WRITE, FS_WRONLY, FS_RDWR, FS_APPEND, FS_SYNC, FS_CREAT, FS_EXCL and FS_TRUNC.

int fs_close(struct fs_file_t *self_p)

Close given file. No file operations are permitted on a closed file.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized file object.

ssize_t fs_read(struct fs_file_t *self_p, void *dst_p, size_t size)

Read from given file into given buffer.

Return
Number of bytes read or negative error code.
Parameters
  • self_p: Initialized file object.
  • dst_p: Buffer to read data into.
  • size: Number of bytes to read.

ssize_t fs_read_line(struct fs_file_t *self_p, void *dst_p, size_t size)

Read one line from given file into given buffer. The function reads one character at a time from given file until the destination buffer is full, a newline \n is found or end of file is reached.

Return
If a line was found the number of bytes read not including the null-termination is returned. If the destination buffer becomes full before a newline character, the destination buffer size is returned. Otherwise a negative error code is returned.
Parameters
  • self_p: Initialized file object.
  • dst_p: Buffer to read data into. Should fit the whole line and null-termination.
  • size: Size of the destination buffer.

ssize_t fs_write(struct fs_file_t *self_p, const void *src_p, size_t size)

Write from given buffer into given file.

Return
Number of bytes written or negative error code.
Parameters
  • self_p: Initialized file object.
  • src_p: Buffer to write.
  • size: Number of bytes to write.

int fs_seek(struct fs_file_t *self_p, int offset, int whence)

Sets the file’s read/write position relative to whence.

Return
zero(0) or negative error code.
Parameters
  • self_p: Initialized file object.
  • offset: New position in bytes from given whence.
  • whence: Absolute (FS_SEEK_SET), relative (FS_SEEK_CUR) or from end (FS_SEEK_END).

ssize_t fs_tell(struct fs_file_t *self_p)

Return current position in the file.

Return
Current position or negative error code.
Parameters
  • self_p: Initialized file object.

int fs_dir_open(struct fs_dir_t *dir_p, const char *path_p, int oflag)

Open a directory by directory path and mode flags.

Return
zero(0) or negative error code.
Parameters
  • dir_p: Directory object to be initialized.
  • path_p: A valid path name for a directory path.
  • oflag: mode of the directory to open (create, read, etc).

int fs_dir_close(struct fs_dir_t *dir_p)

Close given directory.

Return
zero(0) or negative error code.
Parameters
  • dir_p: Directory object.

int fs_dir_read(struct fs_dir_t *dir_p, struct fs_dir_entry_t *entry_p)

Read the next file or directory within the opened directory.

Return
true(1) if an entry was read or false(0) if no entry could be read, otherwise negative error code.
Parameters
  • dir_p: Directory object.
  • entry_p: Read entry.

int fs_remove(const char *path_p)

Remove file by given path.

Return
zero(0) or negative error code.
Parameters
  • path_p: The path of the file to remove.

int fs_stat(const char *path_p, struct fs_stat_t *stat_p)

Gets file status by path.

Return
zero(0) or negative error code.
Parameters
  • path_p: The path of the file to stat.
  • stat_p: The stat struct to populate.

int fs_mkdir(const char *path_p)

Craete a directory with given path.

Return
zero(0) or negative error code.
Parameters
  • path_p: The path of the directoy to create.

int fs_format(const char *path_p)

Format file system at given path.

Return
zero(0) or negative error code.
Parameters
  • path_p: The path to the root of the file system to format. All data in the file system will be deleted.

int fs_ls(const char *path_p, const char *filter_p, void *chout_p)

List files and folders in given path. Optionally with given filter. The list is written to the output channel.

Return
zero(0) or negative error code.
Parameters
  • path_p: Directory to list.
  • filter_p: Filter out files and folders.
  • chout_p: Output chan.

int fs_list(const char *path_p, const char *filter_p, void *chout_p)

List files (callbacks) and directories in given path. Optionally with given filter. The list is written to the output channel.

Return
zero(0) or negative error code.
Parameters
  • path_p: Directory to list.
  • filter_p: Filter out files and folders.
  • chout_p: Output chan.

int fs_auto_complete(char *path_p)

Auto-complete given path.

Return
>=1 if completion happened. Number of autocompleted characters added to the path. 0 if no completion happend, or negative error code.
Parameters
  • path_p: Absolute or relative path to auto-complete.

void fs_split(char *buf_p, char **path_pp, char **cmd_pp)

Split buffer into path and command inplace.

Return
zero(0) or negative error code.
Parameters
  • buf_p: Buffer to split.
  • path_pp: Path or NULL if no path was found.
  • cmd_pp: Command or empty string.

void fs_merge(char *path_p, char *cmd_p)

Merge path and command previously split using fs_split().

Return
zero(0) or negative error code.
Parameters
  • path_p: Path from spilt.
  • cmd_p: Command from split.

int fs_filesystem_init_generic(struct fs_filesystem_t *self_p, const char *name_p, struct fs_filesystem_operations_t *ops_p)

Initialize given generic file system.

Return
zero(0) or negative error code.
Parameters
  • self_p: File system to initialize.
  • name_p: Path to register.
  • ops_p: File system function callbacks.

int fs_filesystem_register(struct fs_filesystem_t *self_p)

Register given file system. Use the functions fs_open(), fs_read(), fs_write(), fs_close(), fs_seek(), fs_tell() and fs_read_line() to access files in a registerd file system.

Return
zero(0) or negative error code.
Parameters
  • self_p: File system to register.

int fs_filesystem_deregister(struct fs_filesystem_t *self_p)

Deregister given file system.

Return
zero(0) or negative error code.
Parameters
  • self_p: File system to deregister.

int fs_command_init(struct fs_command_t *self_p, far_string_t path_p, fs_callback_t callback, void *arg_p)

Initialize given command.

Return
zero(0) or negative error code.
Parameters
  • self_p: Command to initialize.
  • path_p: Path to register.
  • callback: Command callback function.
  • arg_p: Callback argument.

int fs_command_register(struct fs_command_t *command_p)

Register given command. Registered commands are called by the function fs_call().

Return
zero(0) or negative error code.
Parameters
  • command_p: Command to register.

int fs_command_deregister(struct fs_command_t *command_p)

Deregister given command.

Return
zero(0) or negative error code.
Parameters
  • command_p: Command to deregister.

int fs_counter_init(struct fs_counter_t *self_p, far_string_t path_p, uint64_t value)

Initialize given counter.

Return
zero(0) or negative error code.
Parameters
  • self_p: Counter to initialize.
  • path_p: Path to register.
  • value: Initial value of the counter.

int fs_counter_increment(struct fs_counter_t *self_p, uint64_t value)

Increment given counter.

Return
zero(0) or negative error code.
Parameters
  • self_p: Command to initialize.
  • value: Increment value.

int fs_counter_register(struct fs_counter_t *counter_p)

Register given counter.

Return
zero(0) or negative error code.
Parameters
  • counter_p: Counter to register.

int fs_counter_deregister(struct fs_counter_t *counter_p)

Deregister given counter.

Return
zero(0) or negative error code.
Parameters
  • counter_p: Counter to deregister.

int fs_parameter_init(struct fs_parameter_t *self_p, far_string_t path_p, fs_parameter_set_callback_t set_cb, fs_parameter_print_callback_t print_cb, void *value_p)

Initialize given parameter.

Return
zero(0) or negative error code.
Parameters
  • self_p: Parameter to initialize.
  • path_p: Path to register.
  • set_cb: Callback function set set the parameter value.
  • print_cb: Callback function set print the parameter value.
  • value_p: Value storage area.

int fs_parameter_register(struct fs_parameter_t *parameter_p)

Register given parameter.

Return
zero(0) or negative error code.
Parameters
  • parameter_p: Parameter to register.

int fs_parameter_deregister(struct fs_parameter_t *parameter_p)

Deregister given parameter.

Return
zero(0) or negative error code.
Parameters
  • parameter_p: Parameter to deregister.

int fs_parameter_int_set(void *value_p, const char *src_p)

Integer parameter setter function callback

Return
zero(0) or negative error code.
Parameters
  • value_p: Buffer the new value should be written to.
  • src_p: Value to set as a string.

int fs_parameter_int_print(void *chout_p, void *value_p)

Integer parameter printer function callback

Return
zero(0) or negative error code.
Parameters
  • chout_p: Channel to write the formatted value to.
  • value_p: Value to format and print to the output channel.

struct fs_filesystem_t

Public Members

const char *name_p
fs_type_t type
struct fs_filesystem_operations_t *ops_p
struct fs_filesystem_t::@49::@51 fs_filesystem_t::generic
union fs_filesystem_t::@49 fs_filesystem_t::fs
union fs_filesystem_t::@50 fs_filesystem_t::config
struct fs_filesystem_t *next_p
struct fs_file_t

Public Members

struct fs_filesystem_t *filesystem_p
union fs_file_t::@52 fs_file_t::u
struct fs_stat_t
#include <fs.h>

Path stats.

Public Members

uint32_t size
uint8_t type
struct fs_command_t

Public Members

far_string_t path_p
fs_callback_t callback
void *arg_p
struct fs_command_t *next_p
struct fs_counter_t

Public Members

struct fs_command_t command
long long unsigned int fs_counter_t::value
struct fs_counter_t *next_p
struct fs_parameter_t

Public Members

struct fs_command_t command
fs_parameter_set_callback_t set_cb
fs_parameter_print_callback_t print_cb
void *value_p
struct fs_parameter_t *next_p
struct fs_dir_t

Public Members

struct fs_filesystem_t *filesystem_p
union fs_dir_t::@53 fs_dir_t::u
struct fs_dir_entry_t

Public Members

char name[256]
int type
size_t size
struct date_t latest_mod_date
struct fs_filesystem_operations_t

Public Members

int (*file_open)(struct fs_filesystem_t *filesystem_p, struct fs_file_t *self_p, const char *path_p, int flags)
int (*file_close)(struct fs_file_t *self_p)
ssize_t (*file_read)(struct fs_file_t *self_p, void *dst_p, size_t size)
ssize_t (*file_write)(struct fs_file_t *self_p, const void *src_p, size_t size)
int (*file_seek)(struct fs_file_t *self_p, int offset, int whence)
ssize_t (*file_tell)(struct fs_file_t *self_p)