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

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

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.