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

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 on error

void os_free(void * ptr)¶: free memory previous allocated with os_malloc()

Parameters

void * ptr: Pointer to memory block to free

Description

This returns the memory to the OS.

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)¶: determine the path to U-Boot proper

Parameters

char * fname: place to put full path to U-Boot
int maxlen: maximum size of fname

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.