ZettaBridge

https://github.com/zailoxtt/zettabridge
Admin
ZettaBridge is an open-source ARM32 to ARM64 native code translator and app launcher that enables...
Tokens:216,119
Snippets:1,215
Trust Score:5.8
Update:1 week ago
Show doc for...
Tokens:
Raw
### start: launch service thread and process

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Starts the runtime by setting up the process, host call handler, and a runner thread. Returns an error if already started. The runner thread runs the process and handles pending commands on exit.

```cpp
bool LibraryRuntime::start(const LibraryRuntimeOptions& options, std::string& error) {
    {
        std::lock_guard<std::mutex> lock(impl_->mutex);
        if (impl_->started) {
            error = "guest library runtime was already started";
            return false;
        }
        impl_->started = true;
    }
    Impl* impl = impl_.get();
    impl->process.set_sysroot(options.sysroot);
    impl->process.set_host_call_handler(
        [impl](std::uint32_t index, GuestThread& thread) { return impl->handle_host_call(index, thread); });
    std::vector<std::string> argv = {options.zbhost, std::to_string(options.target_sdk)};
    if (!options.preload.empty()) argv.push_back(options.preload);
    impl->runner = std::thread([impl, argv, options] {
        const int status = impl->process.run(options.zbhost, argv, options.envp);
        std::deque<std::shared_ptr<Command>> pending;
        {
            std::lock_guard<std::mutex> lock(impl->mutex);
            impl->finished = true;
            if (!impl->ready && impl->startup_error.empty()) impl->startup_error = exit_message(status);
            pending.swap(impl->commands);
        }
        impl->cv.notify_all();
        for (const auto& command : pending) command->done.set_value({false, std::nullopt, exit_message(status)});
    });
}
```

--------------------------------

### LibraryRuntime::start - start guest runtime with options

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Starts the guest library runtime with the provided options. Sets sysroot and host call handler, launches a runner thread, and waits for readiness or timeout. Returns false with an error message if already started or if zbhost fails to report ready.

```cpp
bool LibraryRuntime::start(const LibraryRuntimeOptions& options, std::string& error) {
    {
        std::lock_guard<std::mutex> lock(impl_->mutex);
        if (impl_->started) {
            error = "guest library runtime was already started";
            return false;
        }
        impl_->started = true;
    }
    Impl* impl = impl_.get();
    impl->process.set_sysroot(options.sysroot);
    impl->process.set_host_call_handler(
        [impl](std::uint32_t index, GuestThread& thread) { return impl->handle_host_call(index, thread); });
    std::vector<std::string> argv = {options.zbhost, std::to_string(options.target_sdk)};
    if (!options.preload.empty()) argv.push_back(options.preload);
    impl->runner = std::thread([impl, argv, options] {
        const int status = impl->process.run(options.zbhost, argv, options.envp);
        std::deque<std::shared_ptr<Command>> pending;
        {
            std::lock_guard<std::mutex> lock(impl->mutex);
            impl->finished = true;
            if (!impl->ready && impl->startup_error.empty()) impl->startup_error = exit_message(status);
            pending.swap(impl->commands);
        }
        impl->cv.notify_all();
        impl->carrier_cv.notify_all();
        for (const auto& command : pending) command->done.set_value({false, std::nullopt, exit_message(status)});
    });

    std::unique_lock<std::mutex> lock(impl->mutex);
    const bool settled = impl->cv.wait_for(lock, options.ready_timeout, [impl] {
        return impl->ready || impl->finished || !impl->startup_error.empty();
    });
    if (impl->ready) return true;
    error = settled ? impl->startup_error
                    : "zbhost did not report ready within " + std::to_string(options.ready_timeout.count()) + " ms";
    return false;
}
```

--------------------------------

### Runtime start and service API checks

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Starts the runtime with options, verifies the guest thread count and service protocol version, and checks that calling malloc on the service thread fails.

```cpp
    std::string error;
    CHECK(runtime.start(runtime_options(argv), error));
    CHECK(runtime.guest_thread_count() == 1);
    CHECK(runtime.service_api().version == ZB_SERVICE_PROTOCOL_VERSION);
    CHECK(!runtime.call_on_current(runtime.service_api().malloc_fn, zb::GuestCall{}));
```

--------------------------------

### Runtime setup and host call handler

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Initializes a zb::LibraryRuntime with atomic counters and a host call handler that intercepts index 0xFD00, increments call counts, checks for misuse, loads a library on the service thread, and performs a nested call.

```cpp
    zb::LibraryRuntime runtime;
    std::atomic<std::uint32_t> chained_function{0};
    std::atomic<int> chained_calls{0};
    std::atomic<bool> chained_on_service{true};
    runtime.set_host_call_handler([&](std::uint32_t index, zb::GuestThread& thread) {
        if (index != 0xFD00) return false;
        ++chained_calls;
        std::string misuse;
        CHECK(!runtime.borrow(misuse));
        CHECK(misuse.find("call_on_current") != std::string::npos);
        if (chained_on_service) {
            misuse.clear();
            CHECK(runtime.load_library(argv[3], ZB_GUEST_RTLD_NOW, misuse) == 0);
            CHECK(misuse.find("service thread") != std::string::npos);
        }
        const auto nested = runtime.call_on_current(chained_function, zb::GuestCall{});
        CHECK(nested && nested->r0 == 42);
        thread.regs()[0] += nested->r0;
        return true;
    });
```

--------------------------------

### handle_ready: validate API and start service thread

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Handles the service-ready host call. Validates the API version, sets the service thread and ID, marks ready, and then enters the serve loop.

```cpp
    bool handle_ready(GuestThread& thread) {
        {
            std::unique_lock<std::mutex> lock(mutex);
            if (!ready) {
                std::string error;
                if (!validate_api(thread.regs()[0], error)) {
                    startup_error = std::move(error);
                    lock.unlock();
                    cv.notify_all();
                    thread.regs()[0] = 1;
                    return true;
                }
                service = &thread;
                service_id = std::this_thread::get_id();
                ready = true;
                lock.unlock();
                cv.notify_all();
            }
        }
        serve(thread);
        return true;
    }
```

--------------------------------

### set_host_call_handler: set chained handler before start

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Sets the chained host call handler. Aborts if called after start.

```cpp
void LibraryRuntime::set_host_call_handler(Process::HostCallHandler handler) {
    std::lock_guard<std::mutex> lock(impl_->mutex);
    if (impl_->started) {
        log("LibraryRuntime::set_host_call_handler called after start");
        std::abort();
    }
    impl_->chained = std::move(handler);
}
```

--------------------------------

### Build the guest tree

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-17-phase7a-native-surface.md

Builds the guest libraries and checks that libEGL.so and libandroid.so exist. tools/build_guest.sh must learn libEGL the same way it builds libGLESv2; add it there if the build fails with "no rule".

```bash
tools/build_guest.sh; ls -la build/guest/lib/libEGL.so build/guest/lib/libandroid.so
```

--------------------------------

### zb_probe_install_usr1: install SIGUSR1 handler

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Installs a handler for SIGUSR1 that records the thread ID and thread-local storage pointer. Returns 0 on success, -1 on failure.

```c
DATA volatile int32_t zb_usr1_count;
DATA volatile int32_t zb_usr1_tid;
DATA volatile uint32_t zb_usr1_tls;

static void on_usr1(int sig) {
    (void)sig;
    zb_usr1_tid = (int32_t)syscall(__NR_gettid);
    zb_usr1_tls = (uint32_t)(uintptr_t)__builtin_thread_pointer();
    ++zb_usr1_count;
}

API int32_t zb_probe_install_usr1(void) {
    struct sigaction sa;
    memset(&sa, 0, sizeof sa);
    sa.sa_handler = on_usr1;
    return sigaction(SIGUSR1, &sa, NULL);
}
```

--------------------------------

### Build guest and run host and guest tests

Source: https://github.com/zailoxtt/zettabridge/blob/main/CLAUDE.md

Builds the guest with tools/build_guest.sh, runs host tests with ctest, and runs guest tests with tools/run_guest_tests.sh. Requires the host build to be configured first.

```bash
tools/build_guest.sh; ctest --test-dir build/host --output-on-failure; tools/run_guest_tests.sh
```

--------------------------------

### main: Entry point with argument checks and RTLD flag validation

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Main function that checks argc == 4, runs preload failure check, and validates ZB_GUEST_RTLD flag values. Uses CHECK macros for assertions.

```cpp
int main(int argc, char** argv) {
    CHECK(argc == 4);
    const std::string probe = argv[3];
    const std::string libdir = std::filesystem::path(probe).parent_path();
    check_preload_failure(argv);

    CHECK(ZB_GUEST_RTLD_NOW == 0u && ZB_GUEST_RTLD_LAZY == 1u && ZB_GUEST_RTLD_GLOBAL == 2u);
    CHECK(ZB_GUEST_RTLD_NOLOAD == 4u && ZB_GUEST_RTLD_NODELETE == 0x1000u && ZB_GUEST_RTLD_DEFAULT == 0xFFFFFFFFu);
}
```

--------------------------------

### Regenerate stubs and check index rule

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-17-phase7a-native-surface.md

Runs the generator and greps for key symbols in hostcalls.inc. Expected: AAssetManager_fromJava still 145, AAsset_read still 157, ANativeWindow_* starts at 160, egl* starts after window names. If asset indices moved, fix the generator, not asset_hostcalls.h.

```bash
python3 tools/gen_stubs.py; grep -n "AAssetManager_fromJava\|AAsset_read\|ANativeWindow_acquire\|eglCreateContext" core/src/gen/hostcalls.inc
```

--------------------------------

### RuntimeReport GL section example output

Source: https://github.com/zailoxtt/zettabridge/blob/main/AGENTS.md

Example output from the gl_chain_test showing the four new text() lines: gl-calls, gl-first-call, gl-egl-context-current, and gl-first-error. The gl-first-error line shows '(none)' when no error is seen, and would show 'glGetError 0x0502' when the first non-zero result is seen.

```text
gl-calls: 1
gl-first-call: glClear tid=4242
gl-egl-context-current: yes
gl-first-error: (none)
```

--------------------------------

### Run GREEN: build and run host_looper_test, platform_compat_test, proxy_runtime_test

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-17-phase7a-native-surface.md

Commands to build and run the host_looper_test, platform_compat_test, and proxy_runtime_test after implementation. Expected all pass, with platform_compat_test now expecting eight remaining non-looper fallbacks.

```bash
ninja -C build/host host_looper_test platform_compat_test proxy_runtime_test
build/host/tests/host/host_looper_test
build/host/tests/host/platform_compat_test
build/host/tests/host/proxy_runtime_test
```

--------------------------------

### LibraryRuntime header declaration (library_runtime.h)

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Declares the LibraryRuntime class and LibraryRuntimeOptions for a guest process in library mode. The runtime is process-lifetime; guest threads cannot be torn down, so after a successful start() the destructor logs and aborts, and tests end with std::_Exit. Host calls outside the runtime range 0xFE00-0xFEFF are received via set_host_call_handler before start().

```cpp
#pragma once

#include <chrono>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <vector>

#include "zb/guest_memory.h"
#include "zb/guest_thread.h"
#include "zb/library_protocol.h"
#include "zb/native_call.h"
#include "zb/process.h"

namespace zb {

struct LibraryRuntimeOptions {
    std::string zbhost;   // host path of the arm32 zbhost executable
    std::string sysroot;  // host directory with the arm32 system files
    std::uint32_t target_sdk = 0;
    std::vector<std::string> envp;  // guest environment, e.g. LD_LIBRARY_PATH=...
    std::string preload;            // guest path dlopen'ed RTLD_GLOBAL before READY; empty: none
    std::chrono::milliseconds ready_timeout{10000};
};

// A guest process in library mode: zbhost runs on a service guest thread that owns the boot
// JIT and serves requests from inside its READY host call.
//
// The runtime is process-lifetime. Guest threads cannot be torn down, so after a successful
// start() the destructor logs and aborts; tests end with std::_Exit.
class LibraryRuntime {
public:
    LibraryRuntime();
    ~LibraryRuntime();
    LibraryRuntime(const LibraryRuntime&) = delete;
    LibraryRuntime& operator=(const LibraryRuntime&) = delete;

    // Receives every host call outside the runtime range 0xFE00-0xFEFF. Call before start().
    void set_host_call_handler(Process::HostCallHandler handler);
    bool start(const LibraryRuntimeOptions& options, std::string& error);

    // Guest dlopen/dlsym/dlerror on the service thread. Flags are ZB_GUEST_RTLD_* values.
    // Return 0 and set error (guest dlerror text) on failure.
    std::uint32_t load_library(const std::string& path, std::uint32_t guest_flags, std::string& error);
    std::uint32_t find_symbol(std::uint32_t handle, const std::string& name, std::string& error);
    std::optional<GuestResult> call_on_service(std::uint32_t function, const GuestCall& args);
    // Nested call on the guest thread the calling host thread already runs (for host-call
    // handlers). nullopt if the calling host thread runs no guest code.
    std::optional<GuestResult> call_on_current(std::uint32_t function, const GuestCall& args);

    GuestMemory& memory();
    // Valid after a successful start().
    const zb_service_api& service_api() const;
    // Real guest pthreads (service, carriers, guest-created threads); borrowers are not counted.
    std::size_t guest_thread_count() const;

private:
    struct Impl;
    std::unique_ptr<Impl> impl_;
};

}  // namespace zb

```

--------------------------------

### LibraryRuntime::guest_thread_count - Get guest thread count

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Returns the number of guest threads in the process.

```cpp
std::size_t LibraryRuntime::guest_thread_count() const {
    return impl_->process.thread_count();
}
```

--------------------------------

### Implementation file core/src/library_runtime.cpp (partial content)

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

The exact content for core/src/library_runtime.cpp as specified in the task. Includes includes, namespace, constants, and internal Response and Command structs. The file is to be written with exactly this content.

```cpp
#include "zb/library_runtime.h"

#include <condition_variable>
#include <cstdlib>
#include <cstring>
#include <deque>
#include <functional>
#include <future>
#include <mutex>
#include <thread>
#include <unordered_map>
#include <utility>

#include "zb/log.h"

namespace zb {

namespace {

constexpr std::chrono::milliseconds kCarrierParkTimeout{10000};

struct Response {
    bool ok = false;
    std::optional<GuestResult> result;
    std::string error;
};

struct Command {
    enum class Kind { Load, Symbol, Call, SpawnCarrier };
    Kind kind = Kind::Call;
    std::uint32_t value = 0;
    std::uint32_t flags = 0;
    std::string text;
    GuestCall args;
    std::promise<Response> done;
};

```

--------------------------------

### Build and run all tests

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Builds the guest, host, runs all tests, and checks git status.

```sh
tools/build_guest.sh; ninja -C build/host; ctest --test-dir build/host --output-on-failure; tools/run_guest_tests.sh; git status --short
```

--------------------------------

### Get guest tid and tls from carrier

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Returns the guest thread ID and thread-local storage pointer from the borrower thread.

```cpp
std::int32_t LibraryRuntime::Carrier::guest_tid() const {
    return state_->borrower->tid;
}

std::uint32_t LibraryRuntime::Carrier::guest_tls() const {
    return state_->borrower->tls();
}
```

--------------------------------

### LibraryRuntime constructor and destructor

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Constructor initializes the implementation. Destructor aborts if the runtime was started and not finished, otherwise joins the runner thread.

```cpp
LibraryRuntime::LibraryRuntime() : impl_(std::make_unique<Impl>()) {}

LibraryRuntime::~LibraryRuntime() {
    if (!impl_->runner.joinable()) return;
    {
        std::lock_guard<std::mutex> lock(impl_->mutex);
        if (impl_->ready || !impl_->finished) {
            log("LibraryRuntime destroyed after start; the runtime is process-lifetime");
            std::abort();
        }
    }
    impl_->runner.join();
}
```

--------------------------------

### Build and run guest probe (RED)

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-17-phase7a-native-surface.md

Commands to build the guest probe and run the host_looper_guest test, expecting failure because callback dispatch is not yet implemented.

```bash
tools/build_guest.sh
ctest --test-dir build/host -R host_looper_guest --output-on-failure
```

--------------------------------

### Expected test output for carrier latency

Source: https://github.com/zailoxtt/zettabridge/blob/main/docs/superpowers/plans/2026-09-14-phase4b-library-runtime.md

Example output from the library_runtime_test showing carrier latency timings and test PASS. Timings vary by machine.

```text
carrier latency: borrow 30.92 ms, first call 0.43 ms, warm call 0.001 ms
library_runtime_test PASS
```
Tokens:
Raw