Sandbox

The following API routines are used to implement the U-Boot sandbox.

ssize_t os_read(int fd, void * buf, size_t count)

Parameters

int fd
File descriptor as returned by os_open()
void * buf
Buffer to place data
size_t count
Number of bytes to read

Return

number of bytes read, or -1 on error

ssize_t os_write(int fd, const void * buf, size_t count)

Parameters

int fd
File descriptor as returned by os_open()
const void * buf
Buffer containing data to write
size_t count
Number of bytes to write

Return

number of bytes written, or -1 on error

off_t os_lseek(int fd, off_t offset, int whence)

Parameters

int fd
File descriptor as returned by os_open()
off_t offset
File offset (based on whence)
int whence
Position offset is relative to (see below)

Return

new file offset

int os_open(const char * pathname, int flags)

Parameters

const char * pathname
Pathname of file to open
int flags
Flags, like OS_O_RDONLY, OS_O_RDWR

Return

file descriptor, or -1 on error

int os_close(int fd)

access to the OS close() system call

Parameters

int fd
File descriptor to close

Return

0 on success, -1 on error

access to the OS unlink() system call

Parameters

const char * pathname
Path of file to delete

Return

0 for success, other for error

void os_exit(int exit_code)

access to the OS exit() system call

Parameters

int exit_code
exit code for U-Boot

Description

This exits with the supplied return code, which should be 0 to indicate success.

void os_tty_raw(int fd, bool allow_sigs)

put tty into raw mode to mimic serial console better

Parameters

int fd
File descriptor of stdin (normally 0)
bool allow_sigs
Allow Ctrl-C, Ctrl-Z to generate signals rather than be handled by U-Boot
void os_fd_restore(void)

restore the tty to its original mode

Parameters

void
no arguments

Description

Call this to restore the original terminal mode, after it has been changed by os_tty_raw(). This is an internal function.

void * os_malloc(size_t length)

aquires some memory from the underlying os.

Parameters

size_t length
Number of bytes to be allocated

Return

Pointer to length bytes or NULL on error

void os_free(void * ptr)

free memory previous allocated with os_malloc()

Parameters

void * ptr
Pointer to memory block to free

Description

This returns the memory to the OS.

void os_usleep(unsigned long usec)

access to the usleep function of the os

Parameters

unsigned long usec
time to sleep in micro seconds
uint64_t os_get_nsec(void)

Parameters

void
no arguments

Return

a monotonic increasing time scaled in nano seconds

int os_parse_args(struct sandbox_state * state, int argc, char * argv)

Parameters

struct sandbox_state * state
sandbox state to update
int argc
argument count
char * argv
argument vector

Return

  • 0 if ok, and program should continue
  • 1 if ok, but program should stop
  • -1 on error: program should terminate
struct os_dirent_node

directory node

Definition

struct os_dirent_node {
  struct os_dirent_node *next;
  ulong size;
  enum os_dirent_t type;
  char name[0];
};

Members

next
pointer to next node, or NULL
size
size of file in bytes
type
type of entry
name
name of entry

Description

A directory entry node, containing information about a single dirent

int os_dirent_ls(const char * dirname, struct os_dirent_node ** headp)

get a directory listing

Parameters

const char * dirname
directory to examine
struct os_dirent_node ** headp
on return pointer to head of linked list, or NULL if none

Description

This allocates and returns a linked list containing the directory listing.

Return

0 if ok, -ve on error

void os_dirent_free(struct os_dirent_node * node)

free directory list

Parameters

struct os_dirent_node * node
pointer to head of linked list

Description

This frees a linked list containing a directory listing.

const char * os_dirent_get_typename(enum os_dirent_t type)

get the name of a directory entry type

Parameters

enum os_dirent_t type
type to check

Return

string containing the name of that type, or “???” if none/invalid

int os_get_filesize(const char * fname, loff_t * size)

get the size of a file

Parameters

const char * fname
filename to check
loff_t * size
size of file is returned if no error

Return

0 on success or -1 if an error ocurred

void os_putc(int ch)

write a character to the controlling OS terminal

Parameters

int ch
haracter to write

Description

This bypasses the U-Boot console support and writes directly to the OS stdout file descriptor.

void os_puts(const char * str)

write a string to the controlling OS terminal

Parameters

const char * str
string to write (note that n is not appended)

Description

This bypasses the U-Boot console support and writes directly to the OS stdout file descriptor.

int os_write_ram_buf(const char * fname)

write the sandbox RAM buffer to a existing file

Parameters

const char * fname
filename to write memory to (simple binary format)

Return

0 if OK, -ve on error

int os_read_ram_buf(const char * fname)

read the sandbox RAM buffer from an existing file

Parameters

const char * fname
filename containing memory (simple binary format)

Return

0 if OK, -ve on error

int os_jump_to_image(const void * dest, int size)

jump to a new executable image

Parameters

const void * dest
buffer containing executable image
int size
size of buffer

Description

This uses exec() to run a new executable image, after putting it in a temporary file. The same arguments and environment are passed to this new image, with the addition of:

-j <filename> Specifies the filename the image was written to. The calling image may want to delete this at some point.
-m <filename> Specifies the file containing the sandbox memory (ram_buf) from this image, so that the new image can have access to this. It also means that the original memory filename passed to U-Boot will be left intact.

Return

0 if OK, -ve on error

int os_find_u_boot(char * fname, int maxlen)

determine the path to U-Boot proper

Parameters

char * fname
place to put full path to U-Boot
int maxlen
maximum size of fname

Description

This function is intended to be called from within sandbox SPL. It uses a few heuristics to find U-Boot proper. Normally it is either in the same directory, or the directory above (since u-boot-spl is normally in an spl/ subdirectory when built).

Return

0 if OK, -NOSPC if the filename is too large, -ENOENT if not found

int os_spl_to_uboot(const char * fname)

Run U-Boot proper

Parameters

const char * fname
full pathname to U-Boot executable

Description

When called from SPL, this runs U-Boot proper. The filename is obtained by calling os_find_u_boot().

Return

0 if OK, -ve on error

void os_localtime(struct rtc_time * rt)

read the current system time

Parameters

struct rtc_time * rt
place to put system time

Description

This reads the current Local Time and places it into the provided structure.

void os_abort(void)

raise SIGABRT to exit sandbox (e.g. to debugger)

Parameters

void
no arguments
int os_mprotect_allow(void * start, size_t len)

Remove write-protection on a region of memory

Parameters

void * start
Region start
size_t len
Region length in bytes

Description

The start and length will be page-aligned before use.

Return

0 if OK, -1 on error from mprotect()

int os_write_file(const char * name, const void * buf, int size)

write a file to the host filesystem

Parameters

const char * name
File path to write to
const void * buf
Data to write
int size
Size of data to write

Description

This can be useful when debugging for writing data out of sandbox for inspection by external tools.

Return

0 if OK, -ve on error

int os_read_file(const char * name, void ** bufp, int * sizep)

Read a file from the host filesystem

Parameters

const char * name
File path to read from
void ** bufp
Returns buffer containing data read
int * sizep
Returns size of data

Description

This can be useful when reading test data into sandbox for use by test routines. The data is allocated using os_malloc() and should be freed by the caller.

Return

0 if OK, -ve on error

void os_relaunch(char * argv)

restart the sandbox

Parameters

char * argv
NULL terminated list of command line parameters

Description

This functions is used to implement the cold reboot of the sand box. argv[0] specifies the binary that is started while the calling process stops immediately. If the new binary cannot be started, the process is terminated and 1 is set as shell return code.

The PID of the process stays the same. All file descriptors that have not been opened with O_CLOEXEC stay open including stdin, stdout, stderr.

int os_setup_signal_handlers(void)

setup signal handlers

Parameters

void
no arguments

Description

Install signal handlers for SIGBUS and SIGSEGV.

Return

0 for success

void os_signal_action(int sig, unsigned long pc)

handle a signal

Parameters

int sig
signal
unsigned long pc
program counter