Sandbox

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

intos_printf(constchar*format, ...)

print directly to OS console

Parameters

const char *format

format string

...

variable arguments

ssize_tos_read(intfd, void*buf, size_tcount)

access the OS read() system call

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 -errno on error

ssize_tos_write(intfd, constvoid*buf, size_tcount)

access the OS write() system call

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 -errno on error

off_tos_lseek(intfd, off_toffset, intwhence)

access the OS lseek() system call

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, or -errno on error

off_tos_filesize(intfd)

Calculate the size of a file

Parameters

int fd

File descriptor as returned by os_open()

Return

file size or negative error code

intos_open(constchar*pathname, intflags)

access the OS open() system call

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

intos_close(intfd)

access to the OS close() system call

Parameters

int fd

File descriptor to close

Return

0 on success, -1 on error

intos_unlink(constchar*pathname)

access to the OS unlink() system call

Parameters

const char *pathname

Path of file to delete

Return

0 for success, other for error

intos_mktemp(char*fname, off_tsize)

Create a temporary file

Parameters

char *fname

The template to use for the file name. This must end with 6 Xs. It will be modified to the opened filename on success.

off_t size

The size of the file

Description

Create a temporary file using fname as a template, unlink it, and truncate it to size.

Return

A file descriptor, or negative errno on error

voidos_exit(intexit_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.

unsignedintos_alarm(unsignedintseconds)

access to the OS alarm() system call

Parameters

unsigned int seconds

number of seconds before the signal is sent

Return

number of seconds remaining until any previously scheduled alarm was due to be delivered; 0 if there was no previously scheduled alarm

voidos_set_alarm_handler(void(*handler)(int))

set handler for SIGALRM

Parameters

void (*handler)(int)

The handler function. Pass NULL for SIG_DFL.

voidos_raise_sigalrm(void)

do raise(SIGALRM)

Parameters

void

no arguments

voidos_tty_raw(intfd, boolallow_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

voidos_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_tlength)

aquires some memory from the underlying os.

Parameters

size_t length

Number of bytes to be allocated

Return

Pointer to length bytes or NULL if length is 0 or on error

voidos_free(void*ptr)

free memory previous allocated with os_malloc()

Parameters

void *ptr

Pointer to memory block to free. If this is NULL then this function does nothing

Description

This returns the memory to the OS.

void*os_realloc(void*ptr, size_tlength)

reallocate memory

Parameters

void *ptr

pointer to previously allocated memory of NULL

size_t length

number of bytes to allocate

Description

This follows the semantics of realloc(), so can perform an os_malloc() or os_free() depending on ptr and length.

Return

pointer to reallocated memory or NULL if length is 0

voidos_usleep(unsignedlongusec)

access to the usleep function of the os

Parameters

unsigned long usec

time to sleep in micro seconds

uint64_tos_get_nsec(void)

get monotonically increasing number of nano seconds from OS

Parameters

void

no arguments

Return

a monotoniccally increasing time scaled in nano seconds

intos_parse_args(structsandbox_state*state, intargc, char*argv[])

parse arguments and update sandbox state.

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

structos_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

intos_dirent_ls(constchar*dirname, structos_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

voidos_dirent_free(structos_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.

constchar*os_dirent_get_typename(enumos_dirent_ttype)

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

intos_get_filesize(constchar*fname, longlong*size)

get the size of a file

Parameters

const char *fname

filename to check

long long *size

size of file is returned if no error

Return

0 on success or -1 if an error ocurred

voidos_putc(intch)

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.

voidos_puts(constchar*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.

voidos_flush(void)

flush controlling OS terminal

Parameters

void

no arguments

Description

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

intos_write_ram_buf(constchar*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

intos_read_ram_buf(constchar*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

intos_jump_to_image(constvoid*dest, intsize)

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

intos_find_u_boot(char*fname, intmaxlen, booluse_img, constchar*cur_prefix, constchar*next_prefix)

determine the path to U-Boot proper

Parameters

char *fname

place to put full path to U-Boot

int maxlen

maximum size of fname

bool use_img

select the ‘u-boot.img’ file instead of the ‘u-boot’ ELF file

const char *cur_prefix

prefix of current executable, e.g. "spl" or "tpl"

const char *next_prefix

prefix of executable to find, e.g. "spl" or ""

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

intos_spl_to_uboot(constchar*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

voidos_localtime(structrtc_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.

voidos_abort(void)

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

Parameters

void

no arguments

intos_mprotect_allow(void*start, size_tlen)

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

intos_write_file(constchar*name, constvoid*buf, intsize)

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

intos_read_file(constchar*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

intos_map_file(constchar*pathname, intos_flags, void**bufp, int*sizep)

Map a file from the host filesystem into memory

Parameters

const char *pathname

File pathname to map

int os_flags

Flags, like OS_O_RDONLY, OS_O_RDWR

void **bufp

Returns buffer containing the file

int *sizep

Returns size of data

Description

This can be useful when to provide a backing store for an emulated device

Return

0 if OK, -ve on error

intos_unmap(void*buf, intsize)

Unmap a file previously mapped

Parameters

void *buf

Mapped address

int size

Size in bytes

Return

0 if OK, -ve on error

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

intos_setup_signal_handlers(void)

setup signal handlers

Parameters

void

no arguments

Description

Install signal handlers for SIGBUS and SIGSEGV.

Return

0 for success

voidos_signal_action(intsig, unsignedlongpc)

handle a signal

Parameters

int sig

signal

unsigned long pc

program counter

longos_get_time_offset(void)

get time offset

Parameters

void

no arguments

Description

Get the time offset from environment variable UBOOT_SB_TIME_OFFSET.

Return

offset in seconds

voidos_set_time_offset(longoffset)

set time offset

Parameters

long offset

offset in seconds

Description

Save the time offset in environment variable UBOOT_SB_TIME_OFFSET.