javm_cap/abi.rs
1//! Well-known cnode slot keys the v3 chain ABI exposes at genesis.
2//! Shared between jar-kernel (which populates the slots at chain init)
3//! and consumers like the JAVM transpiler (which emit chain Images
4//! referencing them).
5//!
6//! Under the V1 single-byte ABI a slot is named by a one-byte
7//! [`crate::Key`]; these constants are the byte values. Wrap with
8//! `Key::from(BARE_*_SLOT)` at the call site — the same `u8 → Key`
9//! boundary the ecall handlers use (`Key::from((gpr & 0xFF) as u8)`).
10
11/// The **scratchpad slot**: the single cap-shaped data-flow channel between a
12/// caller and callee. Its *contents* may be freely mutated and reset to empty,
13/// but the slot itself is "mutably pinned" — `MGMT_MOVE`/`MGMT_SWAP` of this
14/// slot trap. On CALL the caller's scratchpad moves to the callee; on HALT/reply
15/// the callee's moves back to the caller; so the **running** Instance always
16/// holds the scratchpad here, and every other frame's `slot[0]` is empty (one
17/// owner — see the data-flow principle). The fuzz / kernel return path hands the
18/// top-level Instance's `slot[0]` `Cap::Data` back as the invocation result.
19pub const SCRATCHPAD_SLOT: u8 = 0;
20
21// ---- BareFrame slot keys (kernel-issued caps at chain init) ----
22
23/// Root `Cap::Instance[Gas{0}]` handle. The chain reads this slot
24/// to learn its active gas meter.
25pub const BARE_GAS_SLOT: u8 = 7;
26
27/// Root `Cap::Instance[Quota{0}]` handle (symmetric to
28/// `BARE_GAS_SLOT`).
29pub const BARE_QUOTA_SLOT: u8 = 8;
30
31/// Slot the chain Image's `yield_receiver_slot` points at, holding the chain's
32/// `Cap::Instance[YieldReceiver]` (its catch-set; per-block reset). The kernel
33/// reads it when routing a yield.
34///
35/// The per-syscall factory/marker slots (set_gas_meter, mint_gas,
36/// create_yield_catcher, …) that used to follow are gone: a syscall is a
37/// `host_yield` of a named `kernel:*` YieldSender from the top-level scratchpad
38/// CNode, caught by the kernel as the root YieldReceiver — not a CALL into a
39/// factory Instance pinned at a well-known slot.
40pub const BARE_YIELD_RECEIVER_SLOT: u8 = 9;
41
42/// `Cap::Instance[HostOpen]` — read-only entry handle for `host_open`.
43pub const BARE_HOST_OPEN_SLOT: u8 = 15;
44
45/// `Cap::Instance[HostSave]` — entry handle for `host_save`.
46pub const BARE_HOST_SAVE_SLOT: u8 = 16;