PVM2 spec — differential against PVM (jar1)

Companion to rv64e-xjar-eei.md. That doc specifies PVM2 from the RV side; this one specifies it from the PVM side. Every PVM jar1 opcode is listed with what happens to it in PVM2.

The architecture is mostly unchanged: the same 13 hot registers used by jar-produced programs (within RV64E’s full 15-GPR file), the same 4 GiB guest memory period now specified as a 2^32-fold alias, the gas metering shape, and the host-call mechanism. PVM2 uses plain RISC-V control flow: function calls are jal/auipc+jalr, returns are jalr (c.jr ra), and PC is a real low-4 GiB virtual address (code mapped read-only at CODE_BASE). PVM’s single-global-jump- table jump_ind dispatch becomes a native jalr; the only runtime divergence is that a jalr target must be a basic-block start (validated when it executes — see rv64e-xjar-eei.md §8). An earlier draft routed all calls/returns through a custom br_table backed by Image.jump_table; that static-dispatch model has been removed. The wire encoding adopts RV+C for the ~97 ops with strict 1:1 mappings, keeps the jar-specific operations in the RV custom-0 slot, and drops everything else.

Status legend

• KEEP (R) — same architectural semantics, new encoding is the corresponding standard RV instruction.
• KEEP (R, CF) — control-flow op, encoded as the standard RV instruction; PC is a real virtual address (code mapped at CODE_BASE), same as RV.
• KEEP (custom-0) — kept, but moved to RV custom-0 space.
• DROP (static) — removed from PVM2 because the corresponding PVM dynamic-dispatch opcode has no direct analogue; the linker lowers the source pattern to native RV control flow (jal / auipc+jalr, with jalr targets validated against the basic-block-start set at runtime).
• DROP — removed from the PVM2 spec. If the operation is ever needed, software lowers it to a sequence of standard RV ops.
• DROP (fallback: …) — removed; expected RV lowering shown.

Per-opcode mapping (all 141 jar1 opcodes)

No-arg (0–3)

One-immediate (10)

One reg + 8-byte imm (20)

Two immediates / store-imm-direct (30–33)

One offset / unconditional jump (40)

One reg + one imm (50–62)

One reg + two imm / store-imm-ind (70–73)

One reg + imm + offset (80–90)

Two registers (100–111, jar1)

Two reg + one imm (120–161)

Loads / stores indirect (120–130)

ALU 32-bit + imm (131–146) + cmov-imm (147–148)

ALU 64-bit + imm (149–161)

Two reg + offset / branches (170–175)

Two reg + two imm (180)

Three registers — 32-bit ALU (190–199)

Note: dropping these is encoding-level only. The fallback RV-W opcodes (addw, mulw, etc.) are still valid RV instructions in PVM2 (since we include the M extension and base 64-bit ALU); they just aren’t called out as “kept PVM ops” here because no bench guest emits them.

Three registers — 64-bit ALU (200–209)

Three registers — bitwise + upper-mul + slt + cmov (210–219)

Three registers — rotations + inverted-bitwise + min/max (220–230)

Tally

So PVM2 has 59 of PVM’s 141 opcodes in its primary encoding (55 RV + 4 custom-0). The other 82 are either unused (per bench stats) or have a trivial 1-to-N RV-instruction lowering.

The 4 custom-0 opcodes (trap, fallthrough, ecall.jar, ecalli) carry the entire “PVM is not RV” semantic content. Everything else — including all control flow — is standard RV (with PVM2-Base’s divergences applied uniformly).

Architecture preserved

For clarity, all of these stay the same between PVM and PVM2:

• RV64E’s 15 GPRs, with jar-produced programs using the same 13 hot registers and x3/x4 valid but host-spilled
• 4 GiB guest memory period, specified as a 2^32-fold alias across the RV64E 64-bit address space
• Gas metering model (cost-per-instruction, basic-block accounting)
• Host-call interface (ecalli selector → host function dispatch)
• Memory mapping format (pinned slots, initial slots, RW regions), plus the code region mapped read-only at CODE_BASE

Architecture changed: dispatch model

PVM has a single global runtime-validated indirect jump (jump_ind / load_imm_jump_ind); targets are checked against a deblob-time valid_pc bitmap.

PVM2 uses plain RISC-V control flow:

• jal / auipc+jalr for calls, jalr (c.jr ra) for returns, branches unchanged. ra holds a real return VA (code_base + next_pc), not an opaque handle.
• auipc, jalr, c.jr, c.jalr are all standard — they are not rejected at deblob.
• A jalr target is validated against the basic-block-start set at runtime (the recompiler runs untrusted code and never trusts a target table). jal/branch targets are immediates, validated at recompile time against the same set.
• Indirect dispatch (Rust fn pointers, vtables, switch tables) works natively through jalr — no link-time target enumeration.

The Image format changes: code is re-encoded as RV+C+custom-0 in one or more CodeRegions, referenced by a MappingSource::Code mapping that maps the region read-only at CODE_BASE; the bitmask and the jump table / jump-table-offsets are gone (RV+C is self-describing in length, and bb_starts is derived from code by both engines rather than carried on the wire).