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

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.