The GFILE module provides an operating system independent way of reading and writing files no matter whether they are stored in RAM, FLASH, an SD-Card or the host operating systems native file system. Optionally, GFILE also provides an stdio emulation layer so that existing applications can be ported to an embedded target much more easily.
A ROM file system is also available enabling files to be compiled directly into the program code as a direct replacement (or as well as) the operating systems native file I/O sub-system. This is ideal for operating systems that don't have a native file system (i.e. most RTOSes).
The API reference of the GFILE module can be found here.
The following set of functions is available as soon as the GFILE module has been enabled:
bool_t gfileExists(const char* fname); bool_t gfileDelete(const char* fname); long int gfileGetFilesize(const char* fname); bool_t gfileRename(const char* oldname, const char* newname); GFILE* gfileOpen(const char* fname, const char* mode); void gfileClose(GFILE* f); size_t gfileRead(GFILE* f, void* buf, size_t len); size_t gfileWrite(GFILE* f, const void* buf, size_t len); long int gfileGetPos(GFILE* f); bool_t gfileSetPos(GFILE* f, long int pos); long int gfileGetSize(GFILE* f); bool_t gfileEOF(GFILE* f); bool_t gfileMount(char fs, const char* drive); bool_t gfileUnmount(char fs, const char* drive); bool_t gfileSync(GFILE* f);
Many different file systems can be used with GFILE:
- FATFS - uses the FatFS file system library for FAT file systems
- PETITFS - uses the PetitFS file system library for FAT file systems
- NATIVEFS - The native operating system file system
- ROMFS - A file system that stores files in the code itself (usually in ROM/FLASH)
- MEMFS - A virtual file for accessing memory pointers as if they were files
- CHIBIOSFS - A virtual file for accessing ChibiOS BaseFileStream files (Not fully tested)
- RAMFS - A temporary file system using
gfxAlloc()(Not implemented yet)
- USERFS - Allows the user to implement his own file system
Multiple file systems
GFILE supports using more than one file system at once. When searching for a file, the file systems are scanned one after another. This feature is very handy when creating demo programs or using a different target system when developing your application as the application code does not need to be modified even if the underlying file system changes.
It's also possible to specify from which file system you want the file to come from by using N| as a prefix for your file name where N is the file system descriptor if you set
GFILE_ALLOW_DEVICESPECIFIC to TRUE in your gfxconf.h.
File system descriptor
Each file system has it's own descriptor:
It is possible to have more than just one file system of the same type. For example, you can have more than just one SD card in your system. This capability is handled by the actual file system. In case of FatFS, one would be provided with different partition letters (just like in DOS).
String manipulation & printing
GFILE provides a rich set of functions to manipulate strings and print data equivalent to the standard C functions
#if GFILE_NEED_PRINTG int vfnprintg(GFILE *f, int maxlen, const char *fmt, va_list arg); int fnprintg(GFILE *f, int maxlen, const char *fmt, ...); #define vfprintg(f,m,a) vfnprintg(f,0,m,a) #define fprintg(f,m,...) fnprintg(f,0,m,...) #define vprintg(m,a) vfnprintg(gfileStdOut,0,m,a) #define printg(m,...) fnprintg(gfileStdOut,0,m,...) #if GFILE_NEED_STRINGS int vsnprintg(char *buf, int maxlen, const char *fmt, va_list arg); int snprintg(char *buf, int maxlen, const char *fmt, ...); #define vsprintg(s,m,a) vsnprintg(s,0,m,a) #define sprintg(s,m,...) snprintg(s,0,m,...) #endif #endif #if GFILE_NEED_SCANG int vfscang(GFILE *f, const char *fmt, va_list arg); int fscang(GFILE *f, const char *fmt, ...); #define vscang(f,a) vfscang(gfileStdIn,f,a) #define scang(f,...) fscang(gfileStdIn,f,...) #if GFILE_NEED_STRINGS int vsscang(const char *buf, const char *fmt, va_list arg); int sscang(const char *buf, const char *fmt, ...); #endif #endif
Float support is available when
GFILE_ALLOW_FLOATS is set to TRUE in your gfxconf.h.
Note: The standard C include file stdio.h should not be included when using STDIO emulation as gfx.h provides the necessary definitions which may be slightly different to the definitions in stdio.