Difference between revisions of "GFILE"

From uGFX Wiki
Jump to: navigation, search
(Multiple file systems)
(File systems)
 
(16 intermediate revisions by 2 users not shown)
Line 2: Line 2:
  
 
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).
 
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 [http://api.ugfx.org/group___g_f_i_l_e.html here].
  
 
== File handling ==
 
== File handling ==
 
The following set of functions is available as soon as the GFILE module has been enabled:
 
The following set of functions is available as soon as the GFILE module has been enabled:
 
<syntaxhighlight lang=c>
 
<syntaxhighlight lang=c>
bool_t gfileExists(const char *fname);
+
bool_t         gfileExists(const char* fname);
bool_t gfileDelete(const char *fname);
+
bool_t         gfileDelete(const char* fname);
long int gfileGetFilesize(const char *fname);
+
long int       gfileGetFilesize(const char* fname);
bool_t gfileRename(const char *oldname, const char *newname);
+
bool_t         gfileRename(const char* oldname, const char* newname);
GFILE* gfileOpen(const char *fname, const char *mode);
+
GFILE*         gfileOpen(const char* fname, const char* mode);
void gfileClose(GFILE *f);
+
void           gfileClose(GFILE* f);
size_t gfileRead(GFILE *f, void *buf, size_t len);
+
size_t         gfileRead(GFILE* f, void* buf, size_t len);
size_t gfileWrite(GFILE *f, const void *buf, size_t len);
+
size_t         gfileWrite(GFILE* f, const void* buf, size_t len);
long int gfileGetPos(GFILE *f);
+
long int       gfileGetPos(GFILE* f);
bool_t gfileSetPos(GFILE *f, long int pos);
+
bool_t         gfileSetPos(GFILE* f, long int pos);
long int gfileGetSize(GFILE *f);
+
long int       gfileGetSize(GFILE* f);
bool_t gfileEOF(GFILE *f);
+
bool_t         gfileEOF(GFILE* f);
bool_t          gfileMount(char fs, const char *drive);
+
bool_t          gfileMount(char fs, const char* drive);
bool_t          gfileUnmount(char fs, const char *drive);
+
bool_t          gfileUnmount(char fs, const char* drive);
bool_t          gfileSync(GFILE *f);
+
bool_t          gfileSync(GFILE* f);
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
== File systems ==
 
== File systems ==
 
Many different file systems can be used with GFILE:
 
Many different file systems can be used with GFILE:
* FATFS - uses the FatFS file system library
+
* [[FATFS]] - uses the [http://elm-chan.org/fsw/ff/00index_e.html FatFS] file system library for FAT file systems
* NATIVEFS - The native operating system file system
+
* [[PETITFS]] - uses the [http://elm-chan.org/fsw/ff/00index_p.html PetitFS] file system library for FAT file systems
* ROMFS - A file system that stores files in the code itself (usually in ROM/FLASH)
+
* [[NATIVEFS]] - The native operating system file system
* MEMFS - A virtual file for accessing memory pointers as if they were files
+
* [[ROMFS]] - A file system that stores files in the code itself (usually in ROM/FLASH)
* CHIBIOSFS - A virtual file for accessing ChibiOS BaseFileStream files (Not fully tested)
+
* [[MEMFS]] - A virtual file for accessing memory pointers as if they were files
* RAMFS - A temporary file system using <code>gfxAlloc()</code>  (Not implemented yet)
+
* [[CHIBIOSFS]] - A virtual file for accessing ChibiOS BaseFileStream files (Not fully tested)
 +
* [[RAMFS]] - A temporary file system using <code>gfxAlloc()</code>  (Not implemented yet)
 +
* [[USERFS]] - Allows the user to implement his own file system
  
 
== Multiple file systems ==
 
== Multiple file systems ==
Line 40: Line 45:
 
Each file system has it's own descriptor:
 
Each file system has it's own descriptor:
  
File system Descriptor
+
{| class="wikitable"
ROMFS S
+
! scope="col"|File system
RAMFS R
+
! scope="col"|Descriptor
FATFS F
+
|-
NATIVEFS N
+
|ROMFS
 +
|S
 +
|-
 +
|RAMFS
 +
|R
 +
|-
 +
|FATFS/PETITFS
 +
|F
 +
|-
 +
|NATIVEFS
 +
|N
 +
|-
 +
|USERFS
 +
|U
 +
|}
 
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).
 
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).
  
Line 81: Line 100:
  
 
== STDIO emulation ==
 
== STDIO emulation ==
The optional [http://en.wikipedia.org/wiki/C_file_input/output stdio] emulation can be activated by setting <code>GFILE_NEED_STDIO</code> to ''TRUE'' in your [[gfxconf.h]]. A large set of stdio functions are then available.  
+
The optional [http://en.wikipedia.org/wiki/C_file_input/output stdio] emulation can be activated by setting <code>GFILE_NEED_STDIO</code> to <code>TRUE</code> 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.
 
'''''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.
 +
 +
 +
 +
[[Category:Module]]

Latest revision as of 10:15, 9 January 2017

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)
  • 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:

File system Descriptor
ROMFS S
RAMFS R
FATFS/PETITFS F
NATIVEFS N
USERFS U

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.