High-Level API
Header: zbc_api.h
The high-level API provides POSIX-like wrapper functions for guest code.
It bundles client state, buffer, and errno tracking into a single
zbc_api_t context, so you can write code like zbc_api_open()
instead of manually packing argument arrays for zbc_call().
Example:
#include "zbc_api.h"
zbc_client_state_t client;
zbc_api_t api;
uint8_t buf[256];
zbc_client_init(&client, (void *)0xFFFF0000);
zbc_api_init(&api, &client, buf, sizeof(buf));
int fd = zbc_api_open(&api, "/tmp/test.txt", SH_OPEN_W);
zbc_api_write(&api, fd, "Hello\n", 6);
zbc_api_close(&api, fd);
Types
-
type zbc_api_t
High-level API state.
Bundles the client state and RIFF buffer for convenient function calls. Initialize with zbc_api_init() before use.
Initialization
-
void zbc_api_init(zbc_api_t *api, zbc_client_state_t *client, void *buf, size_t buf_size)
Initialize API state.
- Parameters:
api – API state to initialize
client – Pointer to initialized client state
buf – RIFF buffer (caller-provided)
buf_size – Size of RIFF buffer in bytes
File Operations
-
int zbc_api_open(zbc_api_t *api, const char *path, int mode)
Open a file.
- Parameters:
api – API state
path – File path (null-terminated)
mode – Open mode (SH_OPEN_R, SH_OPEN_W, etc.)
- Returns:
File descriptor on success, -1 on error
-
int zbc_api_close(zbc_api_t *api, int fd)
Close a file.
- Parameters:
api – API state
fd – File descriptor
- Returns:
0 on success, -1 on error
-
int zbc_api_read(zbc_api_t *api, int fd, void *dest, size_t count)
Read from a file.
- Parameters:
api – API state
fd – File descriptor
dest – Destination buffer
count – Maximum bytes to read
- Returns:
Bytes NOT read (0 = full read), -1 on error
-
int zbc_api_write(zbc_api_t *api, int fd, const void *data, size_t count)
Write to a file.
- Parameters:
api – API state
fd – File descriptor
data – Data to write
count – Number of bytes to write
- Returns:
Bytes NOT written (0 = full write), -1 on error
-
int zbc_api_seek(zbc_api_t *api, int fd, int pos)
Seek to position in file.
- Parameters:
api – API state
fd – File descriptor
pos – Absolute position in bytes
- Returns:
0 on success, -1 on error
-
intmax_t zbc_api_flen(zbc_api_t *api, int fd)
Get file length.
- Parameters:
api – API state
fd – File descriptor
- Returns:
File length in bytes, -1 on error
-
int zbc_api_istty(zbc_api_t *api, int fd)
Check if file descriptor is a TTY.
- Parameters:
api – API state
fd – File descriptor
- Returns:
1 if TTY, 0 if not, -1 on error
-
int zbc_api_remove(zbc_api_t *api, const char *path)
Remove (delete) a file.
- Parameters:
api – API state
path – File path (null-terminated)
- Returns:
0 on success, -1 on error
Console Operations
-
void zbc_api_writec(zbc_api_t *api, char c)
Write a single character to console.
- Parameters:
api – API state
c – Character to write
Time Operations
-
int zbc_api_clock(zbc_api_t *api)
Get centiseconds since execution started.
- Parameters:
api – API state
- Returns:
Centiseconds, or -1 on error
-
int zbc_api_time(zbc_api_t *api)
Get seconds since Unix epoch.
- Parameters:
api – API state
- Returns:
Seconds since epoch, or -1 on error
-
int zbc_api_tickfreq(zbc_api_t *api)
Get tick frequency (ticks per second).
- Parameters:
api – API state
- Returns:
Ticks per second, or -1 on error
System Operations
-
int zbc_api_iserror(int status)
Check if a value represents an error.
This is pure logic (no semihosting call).
- Parameters:
status – Value to check
- Returns:
1 if error (negative), 0 otherwise
-
int zbc_api_get_errno(zbc_api_t *api)
Get errno value from host.
This fetches the current errno from the host, which may differ from zbc_api_errno() if other operations occurred.
- Parameters:
api – API state
- Returns:
Host errno value
-
int zbc_api_system(zbc_api_t *api, const char *cmd)
Execute a shell command on the host.
- Parameters:
api – API state
cmd – Command string (null-terminated)
- Returns:
Command exit code, or -1 on error
-
int zbc_api_get_cmdline(zbc_api_t *api, char *dest, size_t maxlen)
Get command line arguments.
- Parameters:
api – API state
dest – Destination buffer
maxlen – Maximum length
- Returns:
0 on success, -1 on error
-
int zbc_api_heapinfo(zbc_api_t *api, uintptr_t *heap_base, uintptr_t *heap_limit, uintptr_t *stack_base, uintptr_t *stack_limit)
Get heap and stack information.
- Parameters:
api – API state
heap_base – Receives heap base address
heap_limit – Receives heap limit address
stack_base – Receives stack base address
stack_limit – Receives stack limit address
- Returns:
0 on success, -1 on error