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.
-
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.