4.2. fs — Debug 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 debug 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%
$ filesystems/fs/write tmp/foo.txt "Hello "
$ filesystems/fs/append tmp/foo.txt world!
$ filesystems/fs/read tmp/foo.txt
Hello world!
$ filesystems/fs/list tmp
xxxx-xx-xx xx-xx       12 foo.txt
$ filesystems/fs/counters/list
NAME                                                 VALUE
/your/counter                                        0000000000000034
/my/counter                                          0000000000000002
$ filesystems/fs/counters/reset
$ filesystems/fs/counters/list
NAME                                                 VALUE
/your/counter                                        0000000000000000
/my/counter                                          0000000000000000
$ filesystems/fs/parameters/list
NAME                                                 VALUE
/foo/bar                                             -2

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

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

Test coverage: src/filesystems/fs.c


Version
7.0.0

Defines

FS_SEEK_SET

The offset is relative to the start of the file.

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.

Typedefs

typedef int(* fs_callback_t)(int argc, const char *argv[], chan_t *out_p, chan_t *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)(chan_t *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

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, chan_t *chin_p, chan_t *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.

  • dst_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_ls(const char *path_p, const char *filter_p, chan_t *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, chan_t *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(struct fs_filesystem_t * self_p, const char * name_p, enum fs_type_t type, void * fs_p)

Initialize given file system.

Return
zero(0) or negative error code.
Parameters
  • self_p -

    File system to initialize.

  • name_p -

    Path to register.

  • type -

    File system type.

  • fs_p -

    File system pointer.

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, const FAR char * 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, const FAR char * 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, const FAR char * 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(chan_t *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
void *fs_p
struct fs_filesystem_t *next_p
struct fs_file_t

Public Members

struct fs_filesystem_t *filesystem_p
struct fat16_file_t fat16
spiffs_file_t spiffs
union fs_file_t::@26 fs_file_t::u
struct fs_command_t

Public Members

const FAR char* fs_command_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