Crate nub_arch_x86_abi 

Wire format for the host ↔ guest “run this PVM program” RPC.

The host pre-publishes each Cap it wants the guest to see via the FN_ID_NUB_PUT_CAP RPC (rkyv-archived javm_cap::Cap payload; see the state_cache module in nub-arch-x86 for the guest-side heap-resident directory it lands in), then ships a fixed-size InvokePacket referencing the published Cap::Instance by hash on every call. The invoke packet is #[repr(C)] bytes (no codec); the response is rkyv-archived (InvocationResult).

Structs

ArchivedInvocationResult

An archived InvocationResult

BootInfo

Boot-time info published by the guest at a known location (linker section .boot_info). The host reads it after the sandbox boots to learn the VA of the guest’s cap directory, then dereferences the directory directly from host code (the kernel half is mapped at the same VA via the shallow-PML4-copy mechanism, so a directory-VA pointer is valid both in guest kernel mode and via the host’s mmap shadow of the kernel image).

InvocationResult

Invocation result. Both backends produce this shape on completion; rkyv-archived on the wire from the cached path’s response.

InvocationResultResolver

The resolver for an archived InvocationResult

InvokePacket

Fixed-layout invocation packet. Sent as raw #[repr(C)] bytes via the existing rkyv Request envelope (its payload field). The guest reads the bytes directly with core::ptr::read_unaligned.

ParallelInvokeSlot

One host<->guest invoke slot. Slots are addressed by lane index at parallel_slot_base + lane * PARALLEL_INVOKE_SLOT_BYTES.

Constants

FN_ID_NUB_EVICT_JIT_ALL

fn_id for the bench-only “evict the entire JIT compile cache” RPC. Empty payload; empty response. Used by javm-bench to force each criterion iteration to pay the recompile cost (otherwise the JIT cache turns the loop into pure warm-cache execute, which isn’t what we want to measure for PolkaVM-shaped workloads).

FN_ID_NUB_GET_BOOT_INFO

fn_id for the boot-info-read diagnostic RPC. Empty payload; the guest replies with the raw bytes of its BootInfo struct. The host can also obtain the same data by reading the kernel’s .boot_info ELF section directly — this RPC exists as a belt-and-braces fallback in case the ELF symbol lookup misses.

FN_ID_NUB_HEAP_STATS

fn_id for the nub_heap_stats diagnostic. Payload is empty; response is 32 bytes packing four LE u64s (allocated_bytes, allocation_count, fragment_count, available_bytes).

FN_ID_NUB_INVOKE_CACHED

fn_id for the cache-based RPC. Payload is a InvokePacket (host-side #[repr(C)] bytes, no rkyv); the guest dereferences cache VAs by instance_hash lookup, runs the JIT, and replies with rkyv-archived InvocationResult.

FN_ID_NUB_INVOKE_WORKER

fn_id for a long-lived per-vCPU invoke worker. Payload is a little-endian u32 lane index. The function does not use the legacy rkyv response ring; it polls that lane’s ParallelInvokeSlot in scratch memory, runs invokes with run_top_on_lane, and writes results back into the same slot.

FN_ID_NUB_PUT_CAP

fn_id for the heap-resident cap directory put_cap RPC.

MAX_EXECUTION_LANES

Maximum fixed execution lanes the guest runtime can address. The production default vCPU pool is capped lower, but host configuration must not exceed this ABI-visible lane table size.

PARALLEL_INVOKE_SLOT_BYTES

PARALLEL_INVOKE_STATUS_DONE

PARALLEL_INVOKE_STATUS_EMPTY

PARALLEL_INVOKE_STATUS_EVICT_JIT_READY

PARALLEL_INVOKE_STATUS_READY

PARALLEL_INVOKE_STATUS_RUNNING

PARALLEL_INVOKE_STATUS_STARTING

PARALLEL_INVOKE_STATUS_STOP

SCRATCHPAD_HEAD_LEN

Bytes of the running Instance’s scratchpad (slot[0]) region surfaced at the top-level HALT — a fixed-size head of the returned DataCap’s effective content. The guest writes its result into the scratchpad-mapped memory region during the run (CoW into the cap); at top HALT the engine reads the region’s effective bytes back out here, so the host observes the full, uncompressed result without a separate data-flow event.

Type Aliases

CapHash

32-byte Cap::Instance identity hash. Matches javm_cap::CapHash byte-wise (kept as a local alias here so nub-arch-x86-abi stays free of the javm-cap dependency, which pulls in alloc::collections etc.).