libdragon
|
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 | fs_mapping_t |
Filesystem mapping structure. More... | |
struct | fs_handle_t |
Filesystem open handle structure. More... | |
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 | STACK_SIZE 0x10000 |
Stack size. More... | |
#define | DEBUG_OUT(x) ((uint32_t *)0xA4400044)[0] = ((uint32_t)(x)) |
Write to the MESS debug register. More... | |
#define | MAX_FILESYSTEMS 10 |
Number of filesystems that can be attached to the system. | |
#define | MAX_OPEN_HANDLES 100 |
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". More... | |
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. | |
void | enable_interrupts () |
Enable interrupts systemwide. More... | |
void | disable_interrupts () |
Disable interrupts systemwide. More... | |
int | close (int fildes) |
Close a file. More... | |
int | attach_filesystem (const char *const prefix, filesystem_t *filesystem) |
Register a filesystem with newlib. More... | |
int | detach_filesystem (const char *const prefix) |
Unregister a filesystem from newlib. More... | |
int | chown (const char *path, uid_t owner, gid_t group) |
Change ownership on a file or directory. More... | |
int | execve (char *name, char **argv, char **env) |
Load and execute an executable given a path. More... | |
void | _exit (int rc) |
End execution on current thread. More... | |
int | fork (void) |
Fork execution into two threads. More... | |
int | fstat (int fildes, struct stat *st) |
Return stats on an open file handle. More... | |
int | getpid (void) |
Return the PID of the current thread. More... | |
int | gettimeofday (struct timeval *ptimeval, void *ptimezone) |
Return the current time. More... | |
int | isatty (int file) |
Return whether a file is a TTY or a regular file. More... | |
int | kill (int pid, int sig) |
Send a signal to a PID. More... | |
int | link (char *existing, char *new) |
Link a new file to an existing file. More... | |
int | lseek (int file, int ptr, int dir) |
Seek to a location in a file. More... | |
int | open (const char *file, int flags,...) |
Open a file given a path. More... | |
int | read (int file, char *ptr, int len) |
Read data from a file. More... | |
int | readlink (const char *path, char *buf, size_t bufsize) |
Read a link. More... | |
void * | sbrk (int incr) |
Return a new chunk of memory to be used as heap. More... | |
int | stat (const char *file, struct stat *st) |
Return file stats based on a file name. More... | |
int | symlink (const char *path1, const char *path2) |
Create a symbolic link to a file. More... | |
clock_t | times (struct tms *buf) |
Return time information on the current process. More... | |
int | unlink (char *name) |
Remove a file based on filename. More... | |
int | wait (int *status) |
Wait for a child process. More... | |
int | write (int file, char *ptr, int len) |
Write data to a file. More... | |
int | dir_findfirst (const char *const path, dir_t *dir) |
Find the first file in a directory. More... | |
int | dir_findnext (const char *const path, dir_t *dir) |
Find the next file in a directory. More... | |
int | hook_stdio_calls (stdio_t *stdio_calls) |
Hook into stdio for STDIN, STDOUT and STDERR callbacks. More... | |
int | unhook_stdio_calls (stdio_t *stdio_calls) |
Unhook from stdio. More... | |
int | hook_time_call (time_t(*time_fn)(void)) |
Hook into gettimeofday with a current time callback. More... | |
int | unhook_time_call (time_t(*time_fn)(void)) |
Unhook from gettimeofday current time callback. More... | |
void | _flush_cache (uint8_t *addr, unsigned long bytes) |
Implement _flush_cache as required by GCC for nested functions. More... | |
void | __assert_func (const char *file, int line, const char *func, const char *failedexpr) |
Implement underlying function for assert() More... | |
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. | |
char * | __env [1] = { 0 } |
Environment variables. | |
void(* | __assert_func_ptr )(const char *file, int line, const char *func, const char *failedexpr)=0 |
Assert function pointer (initialized at startup) | |
int | __bootcic |
Boot CIC. More... | |
time_t(* | time_hook )(void) = NULL |
Function to provide the current time. | |
Directory entry type definitions | |
#define | DT_REG 1 |
Regular file. | |
#define | DT_DIR 2 |
Directory. | |
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. This is made somewhat complicated on the N64 by the fact that precompiled code doesn't know in advance if expanded memory is available. libdragon attempts to determine if this additional memory is available and return accordingly but can only do so if it knows what type of CIC/bootcode was used. If you are using a 6102, this has been set for you already. If you are using a 6105 for some reason, you will need to use sys_set_boot_cic to notify libdragon or malloc will not work properly!
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.
struct fs_mapping_t |
Filesystem mapping structure.
This is used to look up what filesystem to use when passed a generic path.
Data Fields | ||
---|---|---|
char * | prefix |
Filesystem prefix. This controls what filesystem prefix should link to this filesystem (eg. 'rom:/' or 'cf:/') |
filesystem_t * | fs | Filesystem callback pointers. |
struct fs_handle_t |
Filesystem open handle structure.
This is used to look up the correct filesystem function to call when working with an open file handle
struct dir_t |
#define STACK_SIZE 0x10000 |
Stack size.
This is the maximum stack size for the purpose of malloc. Any malloc call that tries to allocate data will not allocate within this range. However, there is no guarantee that user code won't blow the stack and cause heap corruption. Use this as loose protection at best.
#define DEBUG_OUT | ( | x | ) | ((uint32_t *)0xA4400044)[0] = ((uint32_t)(x)) |
Write to the MESS debug register.
[in] | x | 32-bit value to write to the MESS debug register |
void __do_global_ctors | ( | ) |
Execute global constructors "Constructors are called in reverse order of the list".
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.
void enable_interrupts | ( | ) |
Enable interrupts systemwide.
void disable_interrupts | ( | ) |
Disable interrupts systemwide.
int close | ( | int | fildes | ) |
Close a file.
[in] | fildes | File handle of the file to close |
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.
[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. |
-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 |
int detach_filesystem | ( | const char *const | prefix | ) |
Unregister a filesystem from newlib.
[in] | prefix | The prefix that was used to register the filesystem |
-1 | if the parameters were invalid |
-2 | if the filesystem couldn't be found |
0 | if the filesystem was successfully unregistered |
int chown | ( | const char * | path, |
uid_t | owner, | ||
gid_t | group | ||
) |
Change ownership on a file or directory.
[in] | path | Path of the file or directory to operate on |
[in] | owner | New owner of the file |
[in] | group | New group of the file |
int execve | ( | char * | name, |
char ** | argv, | ||
char ** | env | ||
) |
Load and execute an executable given a path.
[in] | name | Filename of the executable |
[in] | argv | Array of pointers to arguments |
[in] | env | Array of pointers to environment variables |
void _exit | ( | int | rc | ) |
End execution on current thread.
[in] | rc | Return value of the exiting program |
int fork | ( | void | ) |
Fork execution into two threads.
int fstat | ( | int | fildes, |
struct stat * | st | ||
) |
Return stats on an open file handle.
[in] | fildes | File handle |
[out] | st | Pointer to stat struct to be filled |
int getpid | ( | void | ) |
Return the PID of the current thread.
int gettimeofday | ( | struct timeval * | ptimeval, |
void * | ptimezone | ||
) |
Return the current time.
[out] | ptimeval | Time structure to be filled with current time. |
[out] | ptimezone | Timezone information to be filled. (Not supported) |
int isatty | ( | int | file | ) |
Return whether a file is a TTY or a regular file.
[in] | file | File handle |
int kill | ( | int | pid, |
int | sig | ||
) |
Send a signal to a PID.
[in] | pid | The PID of the process |
[in] | sig | The signal to send |
int link | ( | char * | existing, |
char * | new | ||
) |
Link a new file to an existing file.
[in] | existing | The path of the existing file |
[in] | new | The path of the new file |
int lseek | ( | int | file, |
int | ptr, | ||
int | dir | ||
) |
Seek to a location in a file.
[in] | file | The file handle of the file to seek |
[in] | ptr | The offset in bytes to seek to, given the direction in dir |
[in] | dir | The direction to seek. Use SEEK_SET to start from the beginning. Use SEEK_CUR to seek based on the current offset. Use SEEK_END to seek starting at the end of the file. |
int open | ( | const char * | file, |
int | flags, | ||
... | |||
) |
Open a file given a path.
[in] | file | File name of the file to open |
[in] | flags | Flags specifying open flags, such as binary, append. |
[in] | ... | mode Mode of the file (currently ignored). |
int read | ( | int | file, |
char * | ptr, | ||
int | len | ||
) |
Read data from a file.
[in] | file | File handle |
[out] | ptr | Data pointer to read data to |
[in] | len | Length in bytes of data to read |
int readlink | ( | const char * | path, |
char * | buf, | ||
size_t | bufsize | ||
) |
Read a link.
[in] | path | Path of the link |
[in] | buf | Buffer to read the link into |
[in] | bufsize | Size of the buffer |
void * sbrk | ( | int | incr | ) |
Return a new chunk of memory to be used as heap.
[in] | incr | The amount of memory needed in bytes |
int stat | ( | const char * | file, |
struct stat * | st | ||
) |
Return file stats based on a file name.
[in] | file | File name of the file in question |
[out] | st | Stat struct to populate with information from the file |
int symlink | ( | const char * | path1, |
const char * | path2 | ||
) |
Create a symbolic link to a file.
[in] | path1 | Path to symlink to |
[in] | path2 | Path to symlink from |
clock_t times | ( | struct tms * | buf | ) |
Return time information on the current process.
[out] | buf | Buffer to place timing information |
int unlink | ( | char * | name | ) |
Remove a file based on filename.
[in] | name | Name of the file to remove |
int wait | ( | int * | status | ) |
Wait for a child process.
[out] | status | Status of the wait operation |
int write | ( | int | file, |
char * | ptr, | ||
int | len | ||
) |
Write data to a file.
[in] | file | File handle |
[in] | ptr | Pointer to buffer to write to file |
[in] | len | Length of data in bytes to be written |
int dir_findfirst | ( | const char *const | path, |
dir_t * | dir | ||
) |
Find the first file in a directory.
This function should be called to start enumerating a directory or whenever a directory enumeration should be restarted.
[in] | path | Path to the directory structure |
[out] | dir | Directory entry structure to populate with first entry |
int dir_findnext | ( | const char *const | path, |
dir_t * | dir | ||
) |
Find the next file in a directory.
After finding the first file in a directory using dir_findfirst, call this to retrieve the rest of the directory entries. Call this repeatedly until a negative error is returned signifying that there are no more directory entries in the directory.
[in] | path | Path to the directory structure |
[out] | dir | Directory entry structure to populate with next entry |
int hook_stdio_calls | ( | stdio_t * | stdio_calls | ) |
Hook into stdio for STDIN, STDOUT and STDERR callbacks.
[in] | stdio_calls | Pointer to structure containing callbacks for stdio functions |
int unhook_stdio_calls | ( | stdio_t * | stdio_calls | ) |
Unhook from stdio.
[in] | stdio_calls | Pointer to structure containing callbacks for stdio functions |
int hook_time_call | ( | time_t(*)(void) | time_fn | ) |
Hook into gettimeofday with a current time callback.
[in] | time_fn | Pointer to callback for the current time function |
int unhook_time_call | ( | time_t(*)(void) | time_fn | ) |
Unhook from gettimeofday current time callback.
[in] | time_fn | Pointer to callback for the current time function |
void _flush_cache | ( | uint8_t * | addr, |
unsigned long | bytes | ||
) |
Implement _flush_cache as required by GCC for nested functions.
When using the nested function extensions of GCC, a call to _flush_cache is generated which must be supplied by the operating system or runtime to allow flushing the instruction cache for the generated trampoline.
void __assert_func | ( | const char * | file, |
int | line, | ||
const char * | func, | ||
const char * | failedexpr | ||
) |
Implement underlying function for assert()
Implementation of the function called when an assert fails. By default, we just abort execution, but this will be overriden at startup with a function that prints the assertion on the screen and via the debug channel (if initialized).
|
extern |
Boot CIC.
Defaults to 6102.