Sandbox

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

int os_printf(const char *format, ...)

print directly to OS console

Parameters

const char *format

format string

...

variable arguments

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

off_t os_filesize(int fd)

Calculate the size of a file

Parameters

int fd

File descriptor as returned by os_open()

Return

file size or negative error code

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

int os_mktemp(char *fname, off_t size)

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

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.

unsigned int os_alarm(unsigned int seconds)

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

void os_set_alarm_handler(void (*handler)(int))

set handler for SIGALRM

Parameters

void (*handler)(int)

The handler function. Pass NULL for SIG_DFL.

void os_raise_sigalrm(void)

do raise(SIGALRM)

Parameters

void

no arguments

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 if length is 0 or on error

void os_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_t length)

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

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, long long *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

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.

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

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, bool use_img, const char *cur_prefix, const char *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

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

int os_map_file(const char *pathname, int os_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

int os_unmap(void *buf, int size)

Unmap a file previously mapped

Parameters

void *buf

Mapped address

int size

Size in bytes

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

long os_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

void os_set_time_offset(long offset)

set time offset

Parameters

long offset

offset in seconds

Description

Save the time offset in environment variable UBOOT_SB_TIME_OFFSET.