System hooks to provide low level threading and filesystem functionality to newlib. More...

Files
file	do_ctors.c
	C++ constructor handling.

file	system.c
	newlib Interface Hooks

file	dir.h
	Directory handling.

file	system.h
	newlib Interface Hooks

Data Structures
struct	dir_t
	Directory entry structure. More...

struct	filesystem_t
	Filesystem hook structure. More...

struct	stdio_t
	Standard I/O hook structure. More...

Macros
#define	MAX_FILESYSTEMS 10
	Number of filesystems that can be attached to the system.

#define	MAX_OPEN_HANDLES 4096
	Number of open handles that can be maintained at one time.

Typedefs
typedef void(*	func_ptr) (void)
	Function pointer.

Functions
void	__register_frame_info (void begin, uint32_t ob)
	Register exception frames This is used as a placeholder if the user does not link in libgcc.

void	__do_global_ctors ()
	Execute global constructors "Constructors are called in reverse order of the list".

void	__wrap___do_global_ctors ()
	Execute global constructors This version is used by the new build system (n64.mk) via the –wrap linker flag. When that is provided, this version will be utilized instead. New build system always links with g++ which is not directly compatible with ld when it comes to constructors and enables that flag by default.

int	attach_filesystem (const char const prefix, filesystem_t filesystem)
	Register a filesystem with newlib.

int	detach_filesystem (const char *const prefix)
	Unregister a filesystem from newlib.

int	hook_stdio_calls (stdio_t *stdio_calls)
	Hook into stdio for STDIN, STDOUT and STDERR callbacks.

int	unhook_stdio_calls (stdio_t *stdio_calls)
	Unhook from stdio.

int	hook_time_call (time_t(*time_fn)(void))
	Hook into gettimeofday with a current time callback.

int	unhook_time_call (time_t(*time_fn)(void))
	Unhook from gettimeofday current time callback.

Variables
func_ptr	__CTOR_LIST__ []
	Pointer to the beginning of the constructor list.

func_ptr	__CTOR_END__ []
	Pointer to the end of the constructor list.

char	__EH_FRAME_BEGIN__ []
	Pointer to the beginning of exception frames.

Directory entry type definitions
#define	DT_REG 1
	Regular file.

#define	DT_DIR 2
	Directory.

Detailed Description

System hooks to provide low level threading and filesystem functionality to newlib.

newlib provides all of the standard C libraries for homebrew development. In addition to standard C libraries, newlib provides some additional bridging functionality to allow POSIX function calls to be tied into libdragon. Currently this is used only for filesystems. The newlib interface hooks here are mostly stubs that allow homebrew applications to compile.

The sbrk function is responsible for allowing newlib to find the next chunk of free space for use with malloc calls. The size of the available heap is computed using the memory size computed by the boot code (IPL3), and available via get_memory_size(), which is normally either 4 MiB or 8 MiB if the expansion pak is available.

libdragon has defined a custom callback structure for filesystems to use. Providing relevant hooks for calls that your filesystem supports and passing the resulting structure to attach_filesystem will hook your filesystem into newlib. Calls to POSIX file operations will be passed on to your filesystem code if the file prefix matches, allowing code to make use of your filesystyem without being rewritten.

For example, your filesystem provides libdragon an interface to access a homebrew SD card interface. You register a filesystem with "sd:/" as the prefix and then attempt to open "sd://directory/file.txt". The open callback for your filesystem will be passed the file "/directory/file.txt". The file handle returned will be passed into all subsequent calls to your filesystem until the file is closed.

Data Structure Documentation

◆ dir_t

struct dir_t

Directory entry structure.

Data Fields
char	d_name[256]	The name of the directory entry (relative to the directory path)
int	d_type	The type of the directory entry. See DT_REG and DT_DIR.
int64_t	d_size	Size of the file. This value is well defined for files. For directories, the value is filesystem-dependent. If negative, the filesystem does not report the size during directory walking.
uint32_t	d_cookie	Opaque cookie used to continue walking.

Function Documentation

◆ __do_global_ctors()

void __do_global_ctors ( )

Execute global constructors "Constructors are called in reverse order of the list".

See also: https://gcc.gnu.org/onlinedocs/gccint/Initialization.html

This version of the function is kept for compatibility for projects not using the build system but linking directly with ld in a legacy setup. For the modern version see __wrap___do_global_ctors which is activated by the new build system (n64.mk) via –wrap linker flag. Do not use that flag if you are using ld so that this function is used instead.

◆ attach_filesystem()

int attach_filesystem	(	const char *const	prefix,
		filesystem_t *	filesystem
	)

Register a filesystem with newlib.

This function will take a prefix in the form of 'prefix:/' and a pointer to a filesystem structure of relevant callbacks and register it with newlib. Any standard open/fopen calls with the registered prefix will be passed to this filesystem. Userspace code does not need to know the underlying filesystem, only the prefix that it has been registered under.

The filesystem pointer passed in to this function should not go out of scope for the lifetime of the filesystem.

Parameters

[in]	prefix	Prefix of the filesystem
[in]	filesystem	Structure of callbacks for various functions in the filesystem. If the registered filesystem doesn't support an operation, it should leave the callback null.

Return values

-1	if the parameters are invalid
-2	if the prefix is already in use
-3	if there are no more slots for filesystems
0	if the filesystem was registered successfully

◆ detach_filesystem()

int detach_filesystem ( const char *const prefix )

Unregister a filesystem from newlib.

Note: This function will make sure all files are closed before unregistering the filesystem.

Parameters

[in] prefix The prefix that was used to register the filesystem

Return values

-1	if the parameters were invalid
-2	if the filesystem couldn't be found
0	if the filesystem was successfully unregistered

◆ hook_stdio_calls()

int hook_stdio_calls ( stdio_t * stdio_calls )

Hook into stdio for STDIN, STDOUT and STDERR callbacks.

Parameters

[in] stdio_calls Pointer to structure containing callbacks for stdio functions

Returns: 0 on successful hook or a negative value on failure.

◆ unhook_stdio_calls()

int unhook_stdio_calls ( stdio_t * stdio_calls )

Unhook from stdio.

Parameters

[in] stdio_calls Pointer to structure containing callbacks for stdio functions

Returns: 0 on successful hook or a negative value on failure.

◆ hook_time_call()

int hook_time_call ( time_t(*)(void) time_fn )

Hook into gettimeofday with a current time callback.

Parameters

[in] time_fn Pointer to callback for the current time function

Returns: 0 if successful or a negative value on failure.

◆ unhook_time_call()

int unhook_time_call ( time_t(*)(void) time_fn )

Unhook from gettimeofday current time callback.

Parameters

[in] time_fn Pointer to callback for the current time function

Returns: 0 if successful or a negative value on failure.

Files

Data Structures

Macros

Typedefs

Functions

Variables

Directory entry type definitions

Detailed Description

Data Structure Documentation

◆ dir_t

Function Documentation

◆ __do_global_ctors()

◆ attach_filesystem()

◆ detach_filesystem()

◆ hook_stdio_calls()

◆ unhook_stdio_calls()

◆ hook_time_call()

◆ unhook_time_call()