Module layout 

Constants

GUEST_VA_BASE_DEFAULT

Base VA at which the guest’s entire memory range is mapped. Both the host (via mmap of snapshot/scratch regions) and the guest (via its page table) use this as the anchor. Configurable via JAR_GUEST_VA_BASE env var (hex string, with or without 0x prefix); default chosen to sit in the practically-never-touched mid-range band of x86_64 user VA space.

GUEST_VA_SIZE

Total VA range reserved for the guest. Layout inside: [0, 4 GiB) javm program; [4, 5 GiB) JIT scratch; [5 GiB, 7 GiB) kernel (KERNEL_OFFSET); [7 GiB, end) scratch.

KERNEL_OFFSET

Offset within the reservation where the kernel binary loads.

MAX_GPA

We assume 36-bit IPAs for now, since every amd64 processor supports at least 36 bits. Almost all of them support at least 40 bits, so we could consider bumping this in the future if we were ever memory-constrained.

MAX_GVA

We have this the top of the page below the top of memory in order to make working with start/end ptrs in a few places more convenient (not needing to worry about overflow)

SCRATCH_TOP_ALLOCATOR_OFFSET

SCRATCH_TOP_EXN_STACK_OFFSET

SCRATCH_TOP_SIZE_OFFSET

SCRATCH_TOP_SNAPSHOT_GENERATION_OFFSET

SCRATCH_TOP_SNAPSHOT_PT_GPA_BASE_OFFSET

VCPU_DISPATCH_STACK_LANES

Fixed number of dispatch-stack lanes mapped by the guest at boot. The public Nub default caps at 8 vCPUs, but this leaves headroom for explicit test/bench overrides without needing a guest ABI field during phase 1.

VCPU_DISPATCH_STACK_STRIDE

Bytes reserved for each vCPU’s host-dispatch stack. These stacks are used while executing guest function dispatchers and long-lived invoke workers, not for ring-3 PVM execution.

VCPU_EXCEPTION_STACK_STRIDE

Bytes reserved for each vCPU’s ring-0 exception/interrupt stack. The stack top for lane n is below the legacy Hyperlight exception-stack top by n * VCPU_EXCEPTION_STACK_STRIDE.

Functions

guest_va_base

The guest VA base: the JAR_GUEST_VA_BASE env override (hex) if set, otherwise GUEST_VA_BASE_DEFAULT.

min_scratch_size

Compute the minimum scratch region size needed for a sandbox. On amd64, this is:

reserve_guest_va_range

One-time process-wide reservation of the [guest_va_base(), guest_va_base() + GUEST_VA_SIZE) range. Done on host startup so later mmaps of guest-visible regions (snapshot, scratch, kernel shadow) can land at known fixed VAs via MAP_FIXED inside this reservation.

scratch_base_gpa

scratch_base_gva