Difference between revisions of "GFILE"

Revision as of 10:22, 5 February 2016

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

API reference

The API reference of the GFILE module can be found here.

File handling

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);

File systems

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)

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 printf(), scanf(), sprintf() etc.

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

STDIO emulation

The optional stdio emulation can be activated by setting GFILE_NEED_STDIO to TRUE in your gfxconf.h. A large set of stdio functions are then available.

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.