Bob Herlien, rah, MBARI, 4/18/2016

You'll notice that the FatFs file system has an API that is incompatible
with stdio.h.  E.g.
f_open() rather than fopen()
f_read() rathe than fread()
etc

This primarily has to do with memory management.  Take e.g. fopen():

STDIO:  FILE *fopen(char *path, char *mode)

FatFs:  FRESULT f_open(FIL *fp, char *path, BYTE mode)

The primary difference is that in FatFs, YOU pass in the FIL (not FILE) struct,
rather than receive one on return.  Also, this allows the FatFs file system
to always pass back a result code, rather than rely on things like NULL pointers
and errno.

Why?  In the case of a full-featured operating sytem supporting fopen(),
the OS will allocate the internal structures necessary for the open file.
This may mean either malloc()'ing the memory, or using a static array
of memory structures.

FatFs is intended for memory-limited systems, and allows the system programmer
the flexibility to decide how to handle the allocation of memory.  You may
choose to:
1. allocate FIL structures statically
2. allocate them on the stack
3. allocate them dynamically, e.g. using malloc()

Let's explore those options

1 is good for small, single-threaded embedded systems.  For a multi-thread
system such as Oasis5, it's a bad choice, unless you KNOW that you'll have
just one of those objects in the system.  E.g., you'll have just one instance
of a driver, using a statically allocated FIL structure.  Or all drivers
will share that open file (but note that only one can open for write, so
that doesn't work well).

2 is also bad for Oasis5, for a couple of reasons.  One, you'd have to open,
read/write, and close the file within the context of a single function
(to keep the struct in context).  But there's another reason.  Due to
limited memory, we need to keep the size of each thread's stack small.
A FIL struct contains, among other things, a 512 byte sector buffer.
It's too big to automatically allocate it on the stack.

That leaves 3 as the best way to handle this.  But you have to MAKE SURE that
you have a free() in every error leg of your file handling code.  Otherwise
you'll have a memory leak.