Runtime ABI

#include <playbit/sys/abi.h>

This describes the boundary between guest code and host runtime.

Boundary functions

Function	Direction	Purpose
PBSysThreadEnterMain	guest → host	Initialize runtime state for main thread.
PBSysNativeMain	guest → host	Start native runtime process execution.
pb_syscall	guest → host	Execute synchronous syscall operation.
pb_syscall_async	guest → host	Execute potentially long-running syscall operation.
pb_thread	host ← guest	Enter guest code on a runtime thread.

Signatures

void pb_thread(
    PBSysThreadEntry entry,
    void* stack, uint32_t stackSize,
    u64 arg1, u64 arg2);

i64 pb_syscall(
    PBSysHandle subject,
    PBSysCallOp action,
    u64 arg1, u64 arg2, u64 arg3,
    u64 arg4, u64 arg5, u64 arg6);
;

i64 pb_syscall_async(
    PBSysHandle subject,
    PBSysCallOp action,
    u64 arg1, u64 arg2, u64 arg3,
    u64 arg4, u64 arg5, u64 arg6);

Notes:

• On non-wasm builds, pb_syscall_async aliases to pb_syscall.
• PBSysNativeMain is native-only (playbit/sys/native.h).
• pb_thread is exported by guest and called by host runtime.

Syscall contract

pb_syscall and pb_syscall_async takes:

• subject: handle associated with operation target (or 0 for none).
• action: PBSysCallOp_* opcode.
• a..f: operation-specific arguments.

Return value meaning is operation-specific:

• negative values are PBSysErr errors,
• otherwise return type depends on syscall wrapper (PBSysHandle, counts, timestamps, etc).

See System calls and Types.

Native startup timeline

1. Guest calls PBSysThreadEnterMain(flags).
2. Guest calls PBSysNativeMain(entry, arg1, arg2, configurator).
3. Host runtime creates/attaches the runtime main thread.
4. Host runtime calls guest pb_thread(entry, stack, stackSize, arg1, arg2).
5. Guest executes and uses syscalls/events.

typedef uint64_t (*PBSysNativeAppConfigurator)(PBSysThreadFlags mainThreadFlags);
void PBSysNativeMain(PBSysThreadEntry entry, u64 arg1, u64 arg2,
                     PBSysNativeAppConfigurator nullable configurator);