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.