Thursday, June 17, 2010

The NitroFS filesystem and the HomebrewMenu

In the post I wrote more than a week ago, concretely the located at, I mentioned the libnds developers' own homebrew loader with a simple flashcard navigation menu, that is only capable of execute non-commercial applications; even I embedded a snapshot of my own DSi with the hbmenu running.

I also mentioned why this homebrew menu was so important ---because of the relatively-new filesystem NitroFS developed by Wintermute, the nowadays main libnds programmer, instead of the obsolete EFS library ---, but I didn't explained what kind of relation was yielding between both two things: now this post is trying to make things clearer.

But first of all, what is a filesystem in terms of NintendoDS homebrew programming? Well, a filesystem is considered any way to access external data, properly stored in individual archives, from the code in an easy and fast mood. The desired external data that can be loaded are graphical and audio resources, like bitmaps, sound effects, sprite tiles... and structured in a folder tree, like in the following figure:

An honorific and preliminar mention of the different filesystems to be used within DS applications written using libnds can be useful to understand what is NitroFS, before entering its own description, because it's an improvement of the previous technologies:
  • the embedded data system; the most basic way ---indeed, it's the preferred way for small applications--- to include external data like bitmaps or audio files is to include them as data arrays within the application code itself. The most important disadvantage is that all data will be uncompressedly stored in the DS RAM memory, and it's limited to 4MB, so for large applications it's unviable.
  • the direct FAT access; it allows the code to navigate across the flashcard filesystem and read/write files in a standard way as in a computer ---the hbmenu uses FAT to show the flashcard file list indeed---. However, this requires a predefined location of the files because there's no disk pointer to the executed archive ---that means, the '.' pointer---.
  • the GBFS embedding filesystem; the perfect appended filesystem ---indeed, NitroFS uses the same philosophy---, because there's no file list in the flashcard but the files are appended within the .nds file, at the end. However, it's not available for slot1 flashcards ---the DS-cartridge-like ones--- because the appended datafile system is stored in the GBA cartridge ROM area ---that is, in the slot2, even disappeared in the new DSi handheld models---.
  • the EFS; a great idea to implement the GBFS in a slot1 card: abstractically, (a) the current path for the .nds file will be written within it, in a predetermined location by the library. (b) In case of no coincidence with the stored path, or it's empty, a full search across the flashcard will begin for the file ---EFS provides a unique ID for the application---. Then, the files are appended in a datafile similar to the GBFS. The disadvantages are the long time before the search process ends, and the most important factor: EFS is obsolete and not maintained anymore.
Luckily, NitroFS is a step beyond the EFS: it's capable of implementing a GBFS appended to a .nds file, and require no full flashcard search by a special homebrew loading ---included in hbmenu--- that sets the path as an input argument, in the same way that in any ANSI C application with argc and argv input parameters, in the main. This is called 'the ARGV protocol', as can be seen in

This enhancement is available to all DS homebrew applications compiled from devKitPro v27+ that use libnds v1.4.0+. In the following lines a testing code for this special argument is shown:

#include < nds.h>
int main( int argc, char** argv )
    iprintf( "number of parameters = %d \n", argc );
    for( u8 k=0; k < argc; k++ )
        if( argv[k] )
            iprintf("[%d] %s\n", k, argv[k]);
    while( 1 )

Finally, the figures below are the results of executing the test code from my own EZFlashVi flashcard kernel (left) and from the hbmenu (right).

Although, if NitroFS will not be used in the homebrew application, this feature doesn't matter, so the hbmenu won't be necessary. If it's used, a nitroFSInit() calling is needed, which will take use of the special hbmenu argv[0] argument. After that, the access to embedded files is like the used in normal FAT but instead of "fat:/" root, it's "nitro:/".


  1. sorry if this sounds stupid but how do I do the thing the nitrofs on the DSi? I've observed or tuhn I do? It would be very nice if you could send me an e-mail to where everything is exactly as I describe to do it. Thank you

  2. So NitroFS is either doing GBA ROM access (on slot 2 linkers) or DLDI/FAT accesses. Not a chance they would also use the 'native' SLOT-1 ROM access ?