Data Structures | Files | Defines | Typedefs | Functions | Variables

newlib Interface Hooks

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

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

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


Defines

#define STACK_SIZE   0x10000
 Stack size.
#define DEBUG_OUT(x)   ((uint32_t *)0xA4400044)[0] = ((uint32_t)(x))
 Write to the MESS debug register.
#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 __do_global_ctors ()
 Execute global constructors.
void enable_interrupts ()
 Enable interrupts systemwide.
void disable_interrupts ()
 Disable interrupts systemwide.
int close (int fildes)
 Close a file.
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 chown (const char *path, uid_t owner, gid_t group)
 Change ownership on a file or directory.
int execve (char *name, char **argv, char **env)
 Load and execute an executable given a path.
void exit (int rc)
 End execution on current thread.
int fork (void)
 Fork execution into two threads.
int fstat (int fildes, struct stat *st)
 Return stats on an open file handle.
int getpid (void)
 Return the PID of the current thread.
int gettimeofday (struct timeval *ptimeval, void *ptimezone)
 Return the current time.
int isatty (int file)
 Return whether a file is a TTY or a regular file.
int kill (int pid, int sig)
 Send a signal to a PID.
int link (char *existing, char *new)
 Link a new file to an existing file.
int lseek (int file, int ptr, int dir)
 Seek to a location in a file.
int open (char *file, int flags, int mode)
 Open a file given a path.
int read (int file, char *ptr, int len)
 Read data from a file.
int readlink (const char *path, char *buf, size_t bufsize)
 Read a link.
void * sbrk (int incr)
 Return a new chunk of memory to be used as heap.
int stat (const char *file, struct stat *st)
 Return file stats based on a file name.
int symlink (const char *path1, const char *path2)
 Create a symbolic link to a file.
clock_t times (struct tms *buf)
 Return time information on the current process.
int unlink (char *name)
 Remove a file based on filename.
int wait (int *status)
 Wait for a child process.
int write (int file, char *ptr, int len)
 Write data to a file.
int dir_findfirst (const char *const path, dir_t *dir)
 Find the first file in a directory.
int dir_findnext (const char *const path, dir_t *dir)
 Find the next file in a directory.
int hook_stdio_calls (stdio_t *stdio_calls)
 Hook into stdio for STDIN, STDOUT and STDERR callbacks.
int unhook_stdio_calls ()
 Unhook from stdio.

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 * __env [1] = { 0 }
 Environment variables.
char ** environ = __env
 Environment variables.
int errno
 Master definition of errno.
int __bootcic
 Boot CIC.

STDIN/STDOUT/STDERR definitions from unistd.h

We can't just include unistd.h as it redefines several of the functions here that we are attempting to replace.



#define STDIN_FILENO   0
 Standard input file descriptor.
#define STDOUT_FILENO   1
 Standard output file descriptor.
#define STDERR_FILENO   2
 Standard error file descriptor.

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


Define Documentation

#define DEBUG_OUT (   x  )     ((uint32_t *)0xA4400044)[0] = ((uint32_t)(x))

Write to the MESS debug register.

Parameters:
[in] x 32-bit value to write to the MESS debug register
#define STACK_SIZE   0x10000

Stack size.

Todo:
Dirty hack, should investigate this further

Function Documentation

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
int chown ( const char *  path,
uid_t  owner,
gid_t  group 
)

Change ownership on a file or directory.

Note:
Not supported in libdragon
Parameters:
[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
Returns:
0 on success or a negative value on error.
int close ( int  fildes  ) 

Close a file.

Parameters:
[in] fildes File handle of the file to close
Returns:
0 on success or a negative value on error.
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
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.

Parameters:
[in] path Path to the directory structure
[out] dir Directory entry structure to populate with first entry
Returns:
0 on successful lookup or a negative value on error.
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.

Parameters:
[in] path Path to the directory structure
[out] dir Directory entry structure to populate with next entry
Returns:
0 on successful lookup or a negative value on error.
void disable_interrupts (  ) 

Disable interrupts systemwide.

Note:
If interrupts are already disabled on the system or interrupts have not been initialized, this function will not modify the system state.
void enable_interrupts (  ) 

Enable interrupts systemwide.

Note:
If this is called inside a nested disable call, it will have no effect on the system. Therefore it is safe to nest disable/enable calls. After the last nested interrupt is enabled, systemwide interrupts will be reenabled.
int execve ( char *  name,
char **  argv,
char **  env 
)

Load and execute an executable given a path.

Note:
Not supported in libdragon
Parameters:
[in] name Filename of the executable
[in] argv Array of pointers to arguments
[in] env Array of pointers to environment variables
Returns:
0 on success or a negative value on error.
void exit ( int  rc  ) 

End execution on current thread.

Note:
This function does not exit. If this is the last thread, the system will hang.
Parameters:
[in] rc Return value of the exiting program
int fork ( void   ) 

Fork execution into two threads.

Note:
Not supported in libdragon.
Returns:
PID of child process if parent, 0 if child, negative value on failure.
int fstat ( int  fildes,
struct stat *  st 
)

Return stats on an open file handle.

Parameters:
[in] fildes File handle
[out] st Pointer to stat struct to be filled
Returns:
0 on success or a negative value on error.
int getpid ( void   ) 

Return the PID of the current thread.

Note:
Not supported in libdragon.
Returns:
The PID on success or a negative value on error.
int gettimeofday ( struct timeval *  ptimeval,
void *  ptimezone 
)

Return the current time.

Note:
Not supported in libdragon.
Parameters:
[out] ptimeval Time structure to be filled with current time.
[out] ptimezone Timezone information to be filled.
Returns:
0 on success or a negative value on error.
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.
int isatty ( int  file  ) 

Return whether a file is a TTY or a regular file.

Parameters:
[in] file File handle
Returns:
1 if the file is a TTY, or 0 if not.
int kill ( int  pid,
int  sig 
)

Send a signal to a PID.

Note:
Not supported in libdragon.
Parameters:
[in] pid The PID of the process
[in] sig The signal to send
Returns:
0 on success or a negative value on error.
int link ( char *  existing,
char *  new 
)

Link a new file to an existing file.

Note:
Not supported in libdragon.
Parameters:
[in] existing The path of the existing file
[in] new The path of the new file
Returns:
0 on success or a negative value on error.
int lseek ( int  file,
int  ptr,
int  dir 
)

Seek to a location in a file.

Parameters:
[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.
Returns:
The new location of the file in bytes or -1 on error.
int open ( char *  file,
int  flags,
int  mode 
)

Open a file given a path.

Parameters:
[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.
Returns:
File handle to refer to this file on success, or a negative value on error.
int read ( int  file,
char *  ptr,
int  len 
)

Read data from a file.

Parameters:
[in] file File handle
[out] ptr Data pointer to read data to
[in] len Length in bytes of data to read
Returns:
Actual number of bytes read or a negative value on error.
int readlink ( const char *  path,
char *  buf,
size_t  bufsize 
)

Read a link.

Note:
Not supported in libdragon.
Parameters:
[in] path Path of the link
[in] buf Buffer to read the link into
[in] bufsize Size of the buffer
Returns:
0 on success or a negative value on error.
void* sbrk ( int  incr  ) 

Return a new chunk of memory to be used as heap.

Parameters:
[in] incr The amount of memory needed in bytes
Returns:
A pointer to the memory or null on error allocating.
int stat ( const char *  file,
struct stat *  st 
)

Return file stats based on a file name.

Parameters:
[in] file File name of the file in question
[out] st Stat struct to populate with information from the file
Returns:
0 on success or a negative value on error.
int symlink ( const char *  path1,
const char *  path2 
)

Create a symbolic link to a file.

Note:
Not supported in libdragon.
Parameters:
[in] path1 Path to symlink to
[in] path2 Path to symlink from
Returns:
0 on success or a negative value on error.
clock_t times ( struct tms *  buf  ) 

Return time information on the current process.

Note:
Not supported in libdragon.
Parameters:
[out] buf Buffer to place timing information
Returns:
Timing information or a negative value on error.
int unhook_stdio_calls (  ) 

Unhook from stdio.

Returns:
0 on successful hook or a negative value on failure.
int unlink ( char *  name  ) 

Remove a file based on filename.

Parameters:
[in] name Name of the file to remove
Returns:
0 on success or a negative value on error.
int wait ( int *  status  ) 

Wait for a child process.

Note:
Not supported in libdragon.
Parameters:
[out] status Status of the wait operation
Returns:
0 on success or a negative value on error.
int write ( int  file,
char *  ptr,
int  len 
)

Write data to a file.

Parameters:
[in] file File handle
[in] ptr Pointer to buffer to write to file
[in] len Length of data in bytes to be written
Returns:
The actual number of bytes written, or a negative value on error.

Variable Documentation

int __bootcic

Boot CIC.

Defaults to 6102.

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines