What is the EFS Lib?
EFS (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.
What are the most important features of EFS Lib?
- It works on all slot-1 & 2 cards via DLDI patching, but also on GBA carts
- It also 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
How can the EFS Lib be useful for me?
- You can store all the data (gfx, sfx, music, texts, scripts..) used by your project inside one tidy .nds
- You can 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.
- You can use it to retrieve the current path of you NDS to avoid the root bloating problem, and write external data in a relative path.
- You can 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
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?
A: 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
25/06/2008 – v2.0
+ 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
EFS (Embedded File System) is a new set of library / tools to manage files embedded within a NDS binary.
Basically, it’s an appended file system like GBFS, but it has many more features and less limitations:
- use NitroFS via ndstool
- works on slot-1 & 2, via DLDI patch
- autodetection of the NDS file in the card, using unique ID generated by the EFS patcher
- autosaving of the NDS file path in the card inside the NDS file. If the file has moved, then it’s searched again
- read/write file support (for writing, space must be already allocated)
- multiple files can be opened at the same time
- directory listing
- can use real FAT instead of EFS with a simple define (useful for debugging, when you need to change files without changing the code)
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.
12/05/2007 – v1.0
= Original release
13/05/2007 – v1.1
= 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
14/05/2007 – v1.1a
= corrected bug with EFS_fopen() when filename does not begin with “/”
+ added defines for c++ compatibility
28/09/2007 – v1.2
= 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
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).