DragonFS

DragonFS filesystem implementation and newlib hooks. More...

Files
file	dragonfs.c
	DragonFS.
file	dfsinternal.h
	Internal DFS Definitions.
file	dragonfs.h
	DragonFS.

Data Structures
struct	directory_entry_t
	Representation of a directory entry. More...
struct	dfs_open_file_t
	Open file handle structure. More...
struct	dfs_lookup_file_t
	Data for a single file in dfs_lookup_t. More...
struct	dfs_lookup_t
	Data for DFS file lookup used to speed up file open performance. More...

Macros
#define	ROOT_FLAGS   0xFFFFFFFF
	The special ID value in directory_entry::flags defining the root sector.
#define	ROOT_NEXT_ENTRY   0xDEADBEEF
	The special ID value in directory_entry::next_entry defining the root sector.
#define	ROOT_PATH   "DragonFS 2.0"
	Special path value in directory_entry::path defining the root sector.
#define	SECTOR_SIZE   256
	The size of a sector.
#define	SECTOR_PAYLOAD   252
	The size of a sector payload.
#define	DFS_LOOKUP_PRIME   31
	Prime number used for hash lookups.
#define	DFS_DEFAULT_LOCATION   0
	Default filesystem location.
#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.

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_ENFILE   -4
	Too many open files.
#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 256 MiB. 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 (open, fopen) using the 'rom:/' prefix or the lower-level DFS API calls without prefix. In most cases, it is not necessary to use the DFS API directly, given that the standard C functions are more comprehensive. 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.

DragonFS does not support file compression; if you want to compress your assets, use the asset API (asset_load / asset_fopen).

---

Data Structure Documentation

directory_entry

struct directory_entry

Representation of a directory entry.

Type definition.

Data Fields
uint32_t	next_entry	Offset to next directory entry.
uint32_t	flags	File size and flags. See FLAGS_FILE, FLAGS_DIR and FLAGS_EOF.
char	path[MAX_FILENAME_LEN+1]	The file or directory name.
uint32_t	file_pointer	Offset to start sector of the file.

dfs_open_file_t

struct dfs_open_file_t

Open file handle structure.

Data Fields
uint32_t	size	The size in bytes of this file.
uint32_t	loc	The offset of the current location in the file.
uint32_t	cart_start_loc	The offset within the filesystem where the file is stored.

dfs_lookup_file_t

struct dfs_lookup_file_t

Data for a single file in dfs_lookup_t.

Data Fields
uint32_t	path_hash	Hash of the path string.
uint32_t	path_ofs	Top 12 bits: length of the path string; lowest 20 bits: offset of the path string.
uint32_t	data_ofs	Data offset for file.
uint32_t	data_len	Data length for file.

dfs_lookup_t

struct dfs_lookup_t

Data for DFS file lookup used to speed up file open performance.

Data Fields
uint32_t	num_files	Number of files.
uint32_t	path_ofs	Base offset for path data.
dfs_lookup_file_t	files[]	Array of file entries.

Macro Definition Documentation

DFS_DEFAULT_LOCATION

#define DFS_DEFAULT_LOCATION   0

Default filesystem location.

The default value 0 instruct dfs_init to search for the DFS image within the rompak.

MAX_FILENAME_LEN

#define MAX_FILENAME_LEN   243

Maximum filename length.

This value is due to the direcory structure

FILETYPE

#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