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.