API Reference

This section provides detailed API documentation for all public functions and types in the ZBC Semihosting library.

Overview

The library is organized into five main components:

High-Level API (zbc_api.h): Type-safe wrapper functions for guest code that wants a POSIX-like interface. Bundles client state and buffer management into a single zbc_api_t context.
Client API (zbc_client.h): Lower-level functions for guest/embedded code. Use this when implementing libc integration (sys_semihost()), or when you need direct control over the RIFF protocol.
Host API (zbc_host.h): Functions for processing semihosting requests from guest code. Use this when implementing a semihosting device in an emulator.
Backend API (zbc_backend.h): Backend vtable and factory functions. Backends provide the actual file I/O, console, and time implementations.
Protocol API (zbc_protocol.h): Low-level RIFF chunk parsing, constants, and helper functions. Most users won’t need these directly.

Design Principles

The library follows these design principles:

C90 compliant – works with any C compiler
Zero allocation – caller provides all buffers
Explicit error handling – all errors via return values
Architecture agnostic – works from 8-bit to 64-bit systems
Output parameters first – consistent parameter ordering

Error Codes

All functions return ZBC_OK (0) on success or a negative error code:

#define ZBC_OK                     0
#define ZBC_ERR_NULL_ARG          (-1)
#define ZBC_ERR_HEADER_OVERFLOW   (-2)
#define ZBC_ERR_DATA_OVERFLOW     (-3)
#define ZBC_ERR_BAD_RIFF_MAGIC    (-4)
#define ZBC_ERR_BAD_FORM_TYPE     (-5)
#define ZBC_ERR_RIFF_OVERFLOW     (-6)
#define ZBC_ERR_NOT_FOUND         (-7)
#define ZBC_ERR_BUFFER_FULL       (-8)
#define ZBC_ERR_UNKNOWN_OPCODE    (-9)
#define ZBC_ERR_NOT_INITIALIZED   (-10)
#define ZBC_ERR_DEVICE_ERROR      (-11)
#define ZBC_ERR_TIMEOUT           (-12)
#define ZBC_ERR_INVALID_ARG       (-13)
#define ZBC_ERR_PARSE_ERROR       (-14)

Check for errors with if (rc < 0).