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): 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_t os_write(int fd, const void *buf, size_t count): 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_t os_lseek(int fd, off_t offset, int whence): 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_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): 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 -errno 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

int os_isatty(int fd): check if file descriptor refers to a terminal

Parameters

int fd: File descriptor to check

Return

1 if fd is a terminal, 0 if not, -1 on error

int os_unlink(const char *pathname): 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_mkdir(const char *pathname, int mode): Create a directory

Parameters

const char *pathname: Path of directory to create
int mode: Permissions (e.g. 0755)

Return

0 for success, -errno on error

int os_rmdir(const char *pathname): Remove an empty directory

Parameters

const char *pathname: Path of directory to remove

Return

0 for success, -errno on error

int os_readlink(const char *pathname, char *buf, int size): Read the target of a symbolic link

Parameters

const char *pathname: Path of the symbolic link
char *buf: Buffer to receive the target path
int size: Size of buffer

Return

length of target on success, -errno on error

int os_symlink(const char *target, const char *linkpath): Create a symbolic link

Parameters

const char *target: Target path
const char *linkpath: Path of the symbolic link to create

Return

0 for success, -errno on error

int os_rename(const char *old_path, const char *new_path): Rename or move a file or directory

Parameters

const char *old_path: Current path
const char *new_path: New path

Return

0 for success, -errno on error

char *os_fgets(char *str, int size, int fd): read a string from a file stream

Parameters

char *str: Buffer to store the string
int size: Maximum number of characters to read (including null terminator)
int fd: File descriptor to read from

Description

Reads at most size - 1 characters from the stream and stores them in str. Reading stops after an EOF or a newline. If a newline is read, it is stored in str. A terminating nul byte is appended.

Return

str on success, NULL on error, or EOF with no characters read

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

int os_tty_set_params(int fd): configure terminal parameters

Parameters

int fd: file descriptor of terminal device

Description

Configure the terminal device for serial communication with specific baud rate, data bits, parity, and flow control suitable for embedded device protocols like TKey.

Return

0 on success, -errno on error

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): get monotonically increasing number of nano seconds from OS

Parameters

void: no arguments

Return

a monotoniccally increasing time scaled in nano seconds

int os_parse_args(struct sandbox_state *state, int argc, 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

struct os_dirent_node: directory node

Definition

struct os_dirent_node {
  struct os_dirent_node *next;
  unsigned long 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

int os_get_filetype(const char *fname): get the type of a file

Parameters

const char *fname: Filename to check

Return

-ve error code if the file does not exist, OS_FILET_REG for a regular file, OS_FILET_DIR for a directory, OS_FILET_LNK for a link, or OS_FILET_UNKNOWN for some other type of file

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_putsn(const char *str, int len): write a string with length to controlling OS terminal

Parameters

const char *str: String to write (need not be nul-terminated)
int len: Number of characters to write

Description

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

Outputs exactly len characters from str, regardless of any nul characters.

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

int malloc_dump_to_file(const char *fname): Write heap dump to a host file

Parameters

const char *fname: Path to the output file on the host filesystem

Description

This is only available in sandbox builds. It writes the same information as malloc_dump() but to a file instead of the console.

Return

0 on success, negative error code on failure

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

uint os_backtrace(void **buffer, uint size, uint skip): get backtrace addresses

Parameters

void **buffer: array to fill with return addresses
uint size: maximum number of entries in buffer
uint skip: number of stack frames to skip (0 to include os_backtrace itself)

Description

Collect backtrace addresses into a caller-supplied buffer.

Return

number of addresses collected

void os_backtrace_symbols(struct backtrace_ctx *ctx): convert addresses to symbol strings

Parameters

struct backtrace_ctx *ctx: backtrace context with addrs and count already filled in

Description

Convert backtrace addresses to human-readable symbol strings. The symbol strings are written into ctx->sym_buf and ctx->syms pointers are set up.

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.