EFS Library

EFS Library
General
Author	Noda
Type	Development
Version	2.0
License	Mixed
Last Updated	2008/06/25
Links
Download
Website

EFS Lib (Embedded File System) is a new set of library/tools to manage files embedded within a NDS binary, like graphic/music/sound/config data, for example.

Basically, it’s an appended file system like the old GBFS, but it has many more features and less limitations. It’s also more standard, as it makes use of the NitroFS, using ndstool.

Features

• Works on all slot-1 & 2 cards via DLDI patching, but also on GBA carts.
• Works on emulators without any changes in the code.
• The NDS file path in the card is autodetected and stored within NDS, using unique ID generated by the EFS patcher. The file path is searched only on the first launch, and if the file has moved.
• Support reading & writing file support [writing only works using DLDI. For writing, space must be already allocated.
• It has a complete devoptab integration, so it works the same way as libfat using standard C I/O functions.
• It’s very fast, and opening a file is way faster than with libfat.

User guide

The following functions are available:

Store all the data (e.g. gfx, sfx, music, texts, scripts) used by your project inside one tidy .nds.

Use way more than 4Mo of data in your program because the data stored inside the EFS is not loaded in RAM when your homebrew is loaded.

Use it to retrieve the current path of you NDS to avoid the root bloating problem, and write external data in a relative path.

Use it to test on emulators your existing programs that use libfat without changing anything and using complicated FCSR method, just init EFS as the default device, put your data in the efsroot folder and you’re done.

FAQ

Q. Can you tell me more about the retrieval of current path?

On compile time, space is allocated in your homebrew to store its current path, its unique ID and file size. File size and unique ID is filled by the EFS patcher, usually just after compilation in the makefile. On the first launch, the file is quickly searched on whole card, for a match of the stored file size and ID. Once the file is found, its current path is written inside the file itself.

The next time the homebrew is launched, this path is checked to verify if the file match ID & file size: if it’s the case, to need to search for the file again, we’re good, otherwise it means that the file has moved then we go through the search again.

Q. But as argv is already supported by DKA to provide the current path, isn’t your search method obsolote?

Yes, but for now, no existing homebrew loader makes use of that feature. But fortunately, when this will be supported, you’ll just have to provide this path as an argument on EFS init, and instead of searching the card, EFS will check the path provided. So you don’t have to worry of future problems with using EFS lib, it’s already future-proof.

Compatibility

It works on emulator by using the fcsr method by GPF and including the .nds (or the .ds.gba, it depends of the emu) itself in the FAT image.

Known issues

After a series of writes, make sure you call EFS_Flush(), to ensure data is written (automatically done by default now).

This is due to a libfat limitation (caused by its the cache system, and the way EFS lib use libfat).

Changelog

v2.0 2008/06/25

• Complete rewrite of the lib (breaks compatibility with old versions!).
• Added full devoptab integration, so it now use standard iolib functions.
• Added automatic GBA rom detection (so it works in GBA flash kits & emu without any modifications), based on Eris’ NitroFS driver idea.
• Full chdir and unix standard paths (relative/absolute) support.
• Great speed improve.

v1.2 2007/09/28

• Fixed real fat mode (hopefully).
• Corrected a major bug with EFS_fread and EFS_fwrite.
• Moved some functions tweaks to fix real fat mode.
• Added autoflush on file close by default.
• Added extension checking when searching the NDS file (improve speed).
• Added some options.

v1.1a 2007/05/14

• Corrected bug with EFS_fopen() when filename does not begin with “/”.
• Added defines for c++ compatibility.

v1.1 2007/05/13

• Cleaned up code a bit.
• Corrected problems with nds files with loader.
• Corrected problems with nds files made with standard libnds makefile.
• Removed header struct.
• Optimised variables, now use 505 bytes less in RAM.
• Added EFS_Flush() function, to ensure data is written.
• Included ASM code for reserved space in efs_lib.c.

v1.0 2007/05/12

• Original release.

External links

• Author's website - http://nodadev.wordpress.com/nds-projects/efs-library