Configuring EVFS

There are two sets of configuration options for the EVFS library. One is handled by the CMake build system using command line configuration settings. The other uses definitions from ‘evfs_config.h’ for settings that don’t affect the build script.

CMake configuration

Thread support

EVFS uses shared data structures that need to be protected with locks in multi-threaded envronments. You will need to select the threading API that EVFS will work with.

Threading support is provided for the C11 and pthreads APIs. If you are targeting another platform like an RTOS, it is necessary to write wrapper functions that expose the required locking functionality to EVFS. See ‘evfs_c11_thread.c’ for an example of the required wrappers. You will also have to add a section to ‘evfs_custom_threading.h’ that provides a typedef for EvfsLock and defines any LOCK_INITIALIZER macro.

USE_C11_THREADS

Use the C11 threading API.

USE_PTHREADS

Use the pthreads API.

These are Boolean CMake options that are configured from the command line:

> cmake -DUSE_C11_THREADS=on .

> cmake -DUSE_PTHREADS=on .

C11 threads will take priority if both are enabled.

evfs_config.h

The configuration header has defaults that are set up to work in a typical PC environment. For embedded targets you will need modify features like the thread support settings.

Debug settings

EVFS_DEBUG

Define this to enable debugging of EVFS. Set it to 1 to enable and 0 to disable debugging. If it is undefined, EVFS debugging will be active unless NDEBUG is defined.

EVFS_ASSERT_LEVEL

This sets the debug levels for the library’s internal ASSERT() macro. It should be set to one of the following values:

  • 0 - Ignore assertion

  • 1 - Silent assertion check with no stderr output

  • 2 - Check assertion with stderr output

  • 3 - Check assertion with stderr output and call abort() when EVFS_DEBUG == 1, otherwise silent check

Path handling

EVFS_PATH_SEPS

This is a string of all characters recognized as a path separator. Default is “\\/”.

EVFS_DIR_SEP

This is the character used as separator in normalized paths. Default is ‘/’.

EVFS_MAX_PATH

Set the maximum allowed length for path strings. This affects the sizing of internal buffers. Default is 256. On memory constrained targets it may be necessary to reduce this.

ALLOW_LONG_PATHS

Allow paths that exceed EVFS_MAX_PATH as output from evfs_path_join_ex() and evfs_path_absolute_ex().

Library behavior

EVFS_FILE_OFFSET_BITS

Set the number of bits in evfs_off_t used to handle file sizes and offsets. It defaults to 32-bits. Set this to 64 to enable 64-bit support. This will be necessary if you need to work with files larger than 2GiB.

EVFS_USE_ATEXIT

Install an atexit() handler to shutdown the EVFS library when the process exits. Disable this if you are on an embedded platform where atexit() will not be called. If this is disabled you should always terminate by calling evfs_unregister_all() so that VFSs have the opportunity to flush data and release resources.

EVFS_USE_ANSI_COLOR

Use ANSI color for diagnostic debug output. This is useful for dealing with the output from the trace shim. Disable this if your debug console can’t support color.

VFS options

These are options spcific to various filesystems and shims

EVFS_USE_STDIO_POSIX

Enable POSIX API calls for the Stdio filesystem driver. The Stdio driver will have reduced functionality without this defined.

EVFS_USE_LITTLEFS_SHARED_BUFFER

Save memory by using a common shared buffer in the littlefs driver.

EVFS_USE_ROTATE_SHARED_BUFFER

Save memory by using a common shared buffer in the rotate shim driver.

EVFS_USE_TARFS_SHARED_BUFFER

Save memory by using a common shared buffer in the tar fs drivers.

EVFS_USE_ROMFS_SHARED_BUFFER

Save memory by using a common shared buffer in the Romfs driver.

EVFS_USE_ROMFS_FAST_INDEX

Generate a hash table index for direct lookup of file paths. When disabled, the filesystem will walk the directory tree sequentially for file lookups.

EVFS_ROMFS_MAX_NAME_LEN

Maximum length of a Romfs file or directory name. Must be a multiple of 16. Defaults to 32. Every open file and directory object has a buffer of this size. Keep it small if memory is limited.