libdragon
Macros | Enumerations | Functions
dragonfs.c File Reference

DragonFS. More...

Macros

#define OPENFILE_TO_HANDLE(file)   ((int)PhysicalAddr(file))
 Convert an open file pointer to a handle.
 
#define HANDLE_TO_OPENFILE(handle)   ((dfs_open_file_t*)((uint32_t)(handle) | 0x80000000))
 Convert a handle to an open file pointer.
 

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.
More...
 
int dfs_dir_findfirst (const char *const path, char *buf)
 Find the first file or directory in a directory listing. More...
 
int dfs_dir_findnext (char *buf)
 Find the next file or directory in a directory listing. More...
 
int dfs_open (const char *const path)
 Open a file given a path. More...
 
int dfs_close (uint32_t handle)
 Close an already open file handle. More...
 
int dfs_seek (uint32_t handle, int offset, int origin)
 Seek to an offset in the file. More...
 
int dfs_tell (uint32_t handle)
 Return the current offset into a file. More...
 
int dfs_read (void *const buf, int size, int count, uint32_t handle)
 Read data from a file. More...
 
int dfs_size (uint32_t handle)
 Return the file size of an open file. More...
 
uint32_t dfs_rom_addr (const char *path)
 Return the physical address of a file (in ROM space) More...
 
int dfs_eof (uint32_t handle)
 Return whether the end of file has been reached. More...
 
int dfs_init (uint32_t base_fs_loc)
 Initialize the filesystem. More...
 
const char * dfs_strerror (int error)
 Convert DFS error code into an error string.
 

Detailed Description

DragonFS.

Enumeration Type Documentation

◆ anonymous enum

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

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

◆ dfs_chdir()

int dfs_chdir ( const char *const  path)

Change directories to the specified path.

Supports absolute and relative

Parameters
[in]pathRelative or absolute path to change directories to
Returns
DFS_ESUCCESS on success or a negative value on error.

◆ dfs_dir_findfirst()

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]pathThe path to look for files in
[out]bufBuffer 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.

◆ dfs_dir_findnext()

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]bufBuffer 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.

◆ dfs_open()

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]pathPath of the file to open
Returns
A valid file handle to reference the file by or a negative error on failure.

◆ dfs_close()

int dfs_close ( uint32_t  handle)

Close an already open file handle.

Parameters
[in]handleA valid file handle as returned from dfs_open.
Returns
DFS_ESUCCESS on success or a negative value on error.

◆ dfs_seek()

int dfs_seek ( uint32_t  handle,
int  offset,
int  origin 
)

Seek to an offset in the file.

Parameters
[in]handleA valid file handle as returned from dfs_open.
[in]offsetA byte offset from the origin to seek from.
[in]originAn offset to seek from. Either SEEK_SET, SEEK_CUR or SEEK_END.
Returns
DFS_ESUCCESS on success or a negative value on error.

◆ dfs_tell()

int dfs_tell ( uint32_t  handle)

Return the current offset into a file.

Parameters
[in]handleA valid file handle as returned from dfs_open.
Returns
The current byte offset into a file or a negative error on failure.

◆ dfs_read()

int dfs_read ( void *const  buf,
int  size,
int  count,
uint32_t  handle 
)

Read data from a file.

Note that no caching is performed: if you need to read small amounts (eg: one byte at a time), consider using standard C API instead (fopen()) which performs internal buffering to avoid too much overhead.

Parameters
[out]bufBuffer to read into
[in]sizeSize of each element to read
[in]countNumber of elements to read
[in]handleA valid file handle as returned from dfs_open.
Returns
The actual number of bytes read or a negative value on failure.

◆ dfs_size()

int dfs_size ( uint32_t  handle)

Return the file size of an open file.

Parameters
[in]handleA valid file handle as returned from dfs_open.
Returns
The file size in bytes or a negative value on failure.

◆ dfs_rom_addr()

uint32_t dfs_rom_addr ( const char *  path)

Return the physical address of a file (in ROM space)

This function should be used for highly-specialized, high-performance use cases. Using dfs_open / dfs_read is generally acceptable performance-wise, and is easier to use rather than managing direct access to PI space.

Direct access to ROM data must go through io_read or dma_read. Do not dereference directly as the console might hang if the PI is busy.

Parameters
[in]pathName of the file
Returns
A pointer to the physical address of the file body, or 0 if the file was not found.

◆ dfs_eof()

int dfs_eof ( uint32_t  handle)

Return whether the end of file has been reached.

Parameters
[in]handleA 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.

◆ dfs_init()

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/C file operations work with DragonFS, using the "rom:/" prefix".

The function needs to know where the DFS image is located within the cartridge space. To simplify this, you can pass DFS_DEFAULT_LOCATION which tells dfs_init to search for the DFS image by itself, using the rompak TOC (see rompak_internal.h). Most users should use this option.

Otherwise, if the ROM cannot be built with a rompak TOC for some reason, a virtual address should be passed. This is normally 0xB0000000 + the offset used when building your ROM + the size of the header file used (typically 0x1000).

Parameters
[in]base_fs_locVirtual address in cartridge space at which to find the filesystem, or DFS_DEFAULT_LOCATION to automatically search for the filesystem in the cartridge (using the rompak).
Returns
DFS_ESUCCESS on success or a negative error otherwise.