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

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

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.