gba_nds_fat
By chishm (Michael Chisholm)

Routines for reading a compact flash card using the GBA Movie Player or M3 devices.
FAT16 and FAT32 are supported, but not FAT12.

This software is completely free. No warranty is provided. If you use it, please give due credit and/or email me about your project at chishm@hotmail.com

________________________________________________________________
License:
Copyright (c) 2005 Michael Chisholm ("Chishm")

This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software.

Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute it freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.

2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.

3. This notice may not be removed or altered from any source distribution.

________________________________________________________________
How to use:

Insert #include "gba_nds_cf/gba_nds_cf.h" into your project where you need compact flash access. Make sure you compile the included code by adding the gba_nds_cf directory to your sources.

To use on a Nintendo DS, make sure you define NDS. Don't define it on GBA. This driver requires libgba on GBA or libnds on an NDS.

You MUST call FAT_InitFiles() before using any other FAT function. If you do not, bad things will happen.

Paths are separated with forward slashes ( / ). / is the root of the card. Filenames can be in short or long format. Only ASCII is supported for long filenames. Extended characters are case sensitive, eg ä and Ä are treated as two different characters, whereas a and A are both treated as A.

Call FAT_CWD to change directory, specifying either relative or absolute paths. Paths do not have to be terminated with a slash. Any terminating slashes are ignored.

Call FAT_FindFirstFile(char* filename) to get the name of the first file or directory in the current directory. A return value of 1 indicates a file was found, 2 indicates a directory was found and 0 indicates nothing was found.

Call FAT_FindNextFile(char* filename) to get the name of the next file or directory.

Call FAT_GetLongFilename to get the long filename as a C-string.

Call FAT_GetFileSize to get the size of the last file found or openned.

Call FAT_GetFileCluster to get the start cluster of the last file found or openned.

FAT_fopen, FAT_fclose, FAT_fseek, FAT_ftell, FAT_fread and FAT_fwrite work the same as normal fopen, fclose etc. However, files can only be openned in binary mode. Text mode is unsupported. 
From this version onwards, files are refered to using FAT_FILE* handle, where handle is the handle of the file. If you have used previous versions, change the int handle to FAT_FILE* handle when refering to files.
When specifying a mode to FAT_fopen, only the strings "r", "r+", "w", "w+", "a" and "a+" will work. Anything else is rejected. 
Make sure you call FAT_fclose when you are finished with a file, especially after writing. Otherwise the file length will not be updated.

________________________________________________________________
Acknowledgements:
FAT_NextCluster is based on routines in fat.c, which is part of avrlib by Pascal Stang.
Darkfader helped with low level CF reading and writing.
MightyMax added support for the M3.

Thanks Tepples for answers to my questions.
The author of maverick-os for the documentation about the FAT16 file system (available http://www.maverick-os.dk/FileSystemFormats/FAT16_FileSystem.html)
CF routines were modified with help from Darkfader.
Dwedit was very helpful in discovering bugs.
SaTa was the first to add automatic memory access control settings.
MoonShine came up with the idea of getting the size of files.
MightyMax has helped with fseek.
Joat provided system time and date functions.

________________________________________________________________
History:

2005-06-12
 * Successfully reverse engineered the reading of compact flash cards

2005-06-13
 * Started work on file system driver

2005-06-15
 * First release of file system driver
 * File reading implemented

2005-06-24
 * Second proper release
 * All known bugs fixed
 * File writing implemented
 * File functions behave as expected
 * Long filenames now work

2005-06-27
 * Third release
 * Bug fix for small cards
 * FAT32 implemented
 * Structure packing changed to be more compatible with non GCC compilers

2005-07-12
 * Some bug fixes: 
  * Reading & writing files on FAT16 cards in the root directory is now fixed
  * Accessing files near the end of FAT32 cards is now fixed

2005-07-13
 * Added option not to use DMA

2005-07-14
 * Fixed FAT_fseek() buffer bug

2005-07-24
 * Modified for use on the NDS
  * When using it on the ARM9 you don't need to modify anything. On the ARM7 you will have to manually define NDS.

2005-08-05
 * Fixed FAT_fopen bug in append mode
 * Fixed FAT_AddDirEntry bug that created orphen clusters if a directory entry was created that filled the end of a cluster

2005-08-07
 * Fixed FAT_CWD bug when changing to ".." from a 1st level subdirectory

2005-08-21
 * Added FAT_GetFileSize - Returns the size of the last file accessed
 * Included automatic memory access control setting for the NDS
 * Removed typedef of bool (not needed with libnds)

2005-09-05
 * Added FAT_GetFileCluster - Returns the start cluster of the last file accessed

2005-09-10
 * Fixed problem with FAT_GetDirEntry not initialising the attrib of the returned DIR_ENT

2005-09-15
 * Added ability to read multiple sectors at once
 * Improved FAT_fread and FAT_fwrite functions
 * Fixed bug when trying to create a file in a non-existant directory

2005-09-18
 * Fixed fseek bug with u32 offset instead of s32. Thanks goes to MightyMax for pointing that out

2005-09-21
 * Improved FAT_fseek speed

2005-10-12
 * Fixed long file name bug in FAT_GetDirEntry. Thanks goes to MoonLight for pointing it out

2005-10-15
 * Changed file functions to use FAT_FILE* handles instead of int handles. Please change your code to reflect this change
 * Split source into hardware and disk level files and renamed the files. Include gba_nds_cf.h into your project instead of gbamp_cf.h
 * Added M3 adapter support

2005-10-16
 * Added file time and date modification for writing, thanks to Joat


