newlib Interface Hooks More...

Data Structures
struct	fs_mapping_t
	Filesystem mapping structure. More...

Macros
#define	STACK_SIZE 0x10000
	Stack size.

#define	DEBUG_OUT(x) ((uint32_t *)0xA4400044)[0] = ((uint32_t)(x))
	Write to the MESS debug register.

#define	BITS(v, b, e) ((unsigned int)(v) << (31-(e)) >> (31-(e)+(b)))
	Extract bits from word.

#define	HANDLE_MAX_BUCKETS 32
	Number of buckets file handles are divided into.

#define	HANDLE_BUCKET_SIZE 32
	Size of each bucket of file handles.

#define	FILENO_MAKE(bkt_idx, bkt_pos, fs_index) ( (bkt_pos) \| ((bkt_idx) << 5) \| (((fs_index)+1) << 11) )
	Create a fileno.

#define	FILENO_GET_FS_INDEX(fileno) ((int)BITS( (fileno), 11, 14 ) - 1)
	Extract the filesystem index from a fileno.

#define	FILENO_GET_BUCKET_IDX(fileno) BITS( (fileno), 5, 10 )
	Extract the bucket index from a fileno.

#define	FILENO_GET_BUCKET_POS(fileno) BITS( (fileno), 0, 4 )
	Extract the bucket position from a fileno.

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.

Functions
int	close (int fileno)
	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 fileno, 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 (const char *file, int flags,...)
	Open a file given a path.

int	read (int fileno, 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 (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.

void	_flush_cache (uint8_t *addr, unsigned long bytes)
	Implement _flush_cache as required by GCC for nested functions.

void	__assert_func (const char file, int line, const char func, const char *failedexpr)
	Implement underlying function for assert()

Variables
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)

time_t(*	time_hook )(void) = NULL
	Function to provide the current time.

Detailed Description

newlib Interface Hooks

Data Structure Documentation

◆ fs_mapping_t

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.

Macro Definition Documentation

◆ STACK_SIZE

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

◆ DEBUG_OUT

#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

◆ FILENO_MAKE

#define FILENO_MAKE	(	bkt_idx,
		bkt_pos,
		fs_index
	)	( (bkt_pos) \| ((bkt_idx) << 5) \| (((fs_index)+1) << 11) )

Create a fileno.

Filenos are created as bitfields containing a few fields.

They contain the indices required to access the handle in handle_map: the bucket index and the position within the bucket where the handle is.

They also contain the filesystem index, so that we always know which filesystem use to operate on the handle. Notice that the index is stored 1-based instead of 0-based, so that the special filenos 1,2,3 (used for stdin, stdout and stderr by C standard libraries) will never conflict with a fileno made by FILENO_MAKE.

Note: POSIX does not specify any specific limit for filenos returned by open(), besides that they need to be non-negative integers. Newlib stores them into a 16-bit signed integer though, so we are actually limited to 15 bits for them.

Function Documentation

◆ close()

int close ( int fileno )

Close a file.

Parameters

[in] fileno File handle of the file to close

Returns: 0 on success or a negative value on error.

◆ chown()

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.

◆ execve()

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.

◆ _exit()

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

◆ fork()

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.

◆ fstat()

int fstat	(	int	fileno,
		struct stat *	st
	)

Return stats on an open file handle.

Parameters

[in]	fileno	File handle
[out]	st	Pointer to stat struct to be filled

Returns: 0 on success or a negative value on error.

◆ getpid()

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.

◆ gettimeofday()

int gettimeofday	(	struct timeval *	ptimeval,
		void *	ptimezone
	)

Return the current time.

Parameters

[out]	ptimeval	Time structure to be filled with current time.
[out]	ptimezone	Timezone information to be filled. (Not supported)

Returns: 0 on success or a negative value on error.

◆ isatty()

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.

◆ kill()

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.

◆ link()

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.

◆ lseek()

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.

◆ open()

int open	(	const char *	file,
		int	flags,
			...
	)

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 (currently ignored).

Returns: File handle to refer to this file on success, or a negative value on error.

◆ read()

int read	(	int	fileno,
		char *	ptr,
		int	len
	)

Read data from a file.

Parameters

[in]	fileno	Fileno for this file
[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.

◆ readlink()

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.

◆ sbrk()

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 ((void*)-1) on error allocating.

◆ stat()

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.

◆ symlink()

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.

◆ times()

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.

◆ unlink()

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.

◆ wait()

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.

◆ write()

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.

◆ dir_findfirst()

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.

◆ dir_findnext()

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.

◆ _flush_cache()

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.

◆ __assert_func()

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

Data Structures

Macros

Functions

Variables

Detailed Description

Data Structure Documentation

◆ fs_mapping_t

Macro Definition Documentation

◆ STACK_SIZE

◆ DEBUG_OUT

◆ FILENO_MAKE

Function Documentation

◆ close()

◆ chown()

◆ execve()

◆ _exit()

◆ fork()

◆ fstat()

◆ getpid()

◆ gettimeofday()

◆ isatty()

◆ kill()

◆ link()

◆ lseek()

◆ open()

◆ read()

◆ readlink()

◆ sbrk()

◆ stat()

◆ symlink()

◆ times()

◆ unlink()

◆ wait()

◆ write()

◆ dir_findfirst()

◆ dir_findnext()

◆ _flush_cache()

◆ __assert_func()