Data Structures | Files | Defines | Typedefs | Enumerations | Functions

DragonFS

DragonFS filesystem implementation and newlib hooks. More...

Data Structures

struct  directory_entry
 Representation of a directory entry. More...
struct  file_entry
 Representation of a file sector. More...
struct  open_file
 Open file handle structure. More...

Files

file  dragonfs.c
 

DragonFS.


file  dfsinternal.h
 

Internal DFS Definitions.


file  dragonfs.h
 

DragonFS.


Defines

#define FLAGS_ID   0xFFFFFFFF
 The special ID value in directory_entry::flags defining the master sector.
#define NEXTENTRY_ID   0xDEADBEEF
 The special ID value in directory_entry::next_entry defining the master sector.
#define SECTOR_SIZE   256
 The size of a sector.
#define SECTOR_PAYLOAD   252
 The size of a sector payload.
#define DFS_DEFAULT_LOCATION   0xB0101000
 Default filesystem location.
#define MAX_OPEN_FILES   4
 Maximum open files in DragonFS.
#define MAX_FILENAME_LEN   243
 Maximum filename length.
#define MAX_DIRECTORY_DEPTH   100
 Maximum depth of directories supported.
#define FILETYPE(x)   ((x) & 3)
 Macro to extract the file type from a DragonFS file flag.

Typedefs

typedef struct directory_entry directory_entry_t
 Type definition.
typedef struct file_entry file_entry_t
 Type definition.
typedef struct open_file open_file_t
 Open file handle structure.

Enumerations

enum  { WALK_CHDIR, WALK_OPEN }
 

Directory walking flags.

More...
enum  { TYPE_ANY, TYPE_FILE, TYPE_DIR }
 

Directory walking return flags.

More...

Functions

int dfs_chdir (const char *const path)
 Change directories to the specified path.
int dfs_dir_findfirst (const char *const path, char *buf)
 Find the first file or directory in a directory listing.
int dfs_dir_findnext (char *buf)
 Find the next file or directory in a directory listing.
int dfs_open (const char *const path)
 Open a file given a path.
int dfs_close (uint32_t handle)
 Close an already open file handle.
int dfs_seek (uint32_t handle, int offset, int origin)
 Seek to an offset in the file.
int dfs_tell (uint32_t handle)
 Return the current offset into a file.
int dfs_read (void *const buf, int size, int count, uint32_t handle)
 Read data from a file.
int dfs_size (uint32_t handle)
 Return the file size of an open file.
int dfs_eof (uint32_t handle)
 Return whether the end of file has been reached.
int dfs_init (uint32_t base_fs_loc)
 Initialize the filesystem.

DragonFS Return values



#define DFS_ESUCCESS   0
 Success.
#define DFS_EBADINPUT   -1
 Input parameters invalid.
#define DFS_ENOFILE   -2
 File does not exist.
#define DFS_EBADFS   -3
 Bad filesystem.
#define DFS_ENOMEM   -4
 No memory for operation.
#define DFS_EBADHANDLE   -5
 Invalid file handle.

DragonFS file type flags



#define FLAGS_FILE   0x0
 This is a file entry.
#define FLAGS_DIR   0x1
 This is a directory entry.
#define FLAGS_EOF   0x2
 This is the end of a directory list.

Detailed Description

DragonFS filesystem implementation and newlib hooks.

DragonFS is a read only ROM filesystem for the N64. It provides an interface that homebrew developers can use to load resources from cartridge space that were not available at compile time. This can mean sprites or other game assets, or the filesystem can be appended at a later time if the homebrew developer wishes end users to be able to insert custom levels, music or other assets. It is loosely based off of FAT with consideration into application and limitations of the N64.

The filesystem can be generated using 'mkdfs' which is included in the 'tools' directory of libdragon. Due to the read-only nature, DFS does not support empty files or empty directories. Attempting to create a filesystem with either of these using 'mkdfs' will result in an error. If a filesystem contains either empty files or empty directories, the result of manipulating the filesystem is undefined.

DragonFS does not support writing, renaming or symlinking of files. It supports only file and directory types.

DFS files have a maximum size of 16,777,216 bytes. Directories can have an unlimited number of files in them. Each token (separated by a / in the path) can be 243 characters maximum. Directories can be 100 levels deep at maximum. There can be 4 files open simultaneously.

When DFS is initialized, it will register itself with newlib using 'rom:/' as a prefix. Files can be accessed either with standard POSIX functions and the 'rom:/' prefix or with DFS API calls and no prefix. Files can be opened using both sets of API calls simultaneously as long as no more than four files are open at any one time.


Define Documentation

#define DFS_DEFAULT_LOCATION   0xB0101000

Default filesystem location.

The default is 1MB into the ROM space, plus the header offset

#define FILETYPE (   x  )     ((x) & 3)

Macro to extract the file type from a DragonFS file flag.

Parameters:
[in] x File flags from DFS entry
Returns:
The file type flag
#define MAX_FILENAME_LEN   243

Maximum filename length.

This value is due to the direcory structure


Enumeration Type Documentation

anonymous enum

Directory walking flags.

Enumerator:
WALK_CHDIR 

Walk the directory structure for the purpose of changing directories.

WALK_OPEN 

Walk the directory structure for the purpose of opening a file or directory.

anonymous enum

Directory walking return flags.

Enumerator:
TYPE_ANY 

Return any file or directory found.

TYPE_FILE 

Return a file from directory walk.

TYPE_DIR 

Return a directory from a directory walk.


Function Documentation

int dfs_chdir ( const char *const   path  ) 

Change directories to the specified path.

Supports absolute and relative

Parameters:
[in] path Relative or absolute path to change directories to
Returns:
DFS_ESUCCESS on success or a negative value on error.
int dfs_close ( uint32_t  handle  ) 

Close an already open file handle.

Parameters:
[in] handle A valid file handle as returned from dfs_open.
Returns:
DFS_ESUCCESS on success or a negative value on error.
int dfs_dir_findfirst ( const char *const   path,
char *  buf 
)

Find the first file or directory in a directory listing.

Supports absolute and relative. If the path is invalid, returns a negative DFS_errno. If a file or directory is found, returns the flags of the entry and copies the name into buf.

Parameters:
[in] path The path to look for files in
[out] buf Buffer to place the name of the file or directory found
Returns:
The flags (FLAGS_FILE, FLAGS_DIR, FLAGS_EOF) or a negative value on error.
int dfs_dir_findnext ( char *  buf  ) 

Find the next file or directory in a directory listing.

Note:
Should be called after doing a dfs_dir_findfirst.
Parameters:
[out] buf Buffer to place the name of the next file or directory found
Returns:
The flags (FLAGS_FILE, FLAGS_DIR, FLAGS_EOF) or a negative value on error.
int dfs_eof ( uint32_t  handle  ) 

Return whether the end of file has been reached.

Parameters:
[in] handle A valid file handle as returned from dfs_open.
Returns:
1 if the end of file is reached, 0 if not, and a negative value on error.
int dfs_init ( uint32_t  base_fs_loc  ) 

Initialize the filesystem.

Given a base offset where the filesystem should be found, this function will initialize the filesystem to read from cartridge space. This function will also register DragonFS with newlib so that standard POSIX file operations work with DragonFS.

Parameters:
[in] base_fs_loc Memory mapped location at which to find the filesystem. This is normally 0xB0000000 + the offset used when building your ROM + the size of the header file used.
Returns:
DFS_ESUCCESS on success or a negative error otherwise.
int dfs_open ( const char *const   path  ) 

Open a file given a path.

Check if we have any free file handles, and if we do, try to open the file specified. Supports absolute and relative paths

Parameters:
[in] path Path of the file to open
Returns:
A valid file handle to reference the file by or a negative error on failure.
int dfs_read ( void *const   buf,
int  size,
int  count,
uint32_t  handle 
)

Read data from a file.

Parameters:
[out] buf Buffer to read into
[in] size Size of each element to read
[in] count Number of elements to read
[in] handle A valid file handle as returned from dfs_open.
Returns:
The actual number of bytes read or a negative value on failure.
int dfs_seek ( uint32_t  handle,
int  offset,
int  origin 
)

Seek to an offset in the file.

Parameters:
[in] handle A valid file handle as returned from dfs_open.
[in] offset A byte offset from the origin to seek from.
[in] origin An offset to seek from. Either SEEK_SET, SEEK_CUR or SEEK_END.
Returns:
DFS_ESUCCESS on success or a negative value on error.
int dfs_size ( uint32_t  handle  ) 

Return the file size of an open file.

Parameters:
[in] handle A valid file handle as returned from dfs_open.
Returns:
The file size in bytes or a negative value on failure.
int dfs_tell ( uint32_t  handle  ) 

Return the current offset into a file.

Parameters:
[in] handle A valid file handle as returned from dfs_open.
Returns:
The current byte offset into a file or a negative error on failure.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines