Struct ImageCap 

pub struct ImageCap {
    pub code: Vec<u8>,
    pub endpoints: Vec<(Key, EndpointDef)>,
    pub mappings: Vec<MemoryMapping>,
    pub pinned: Vec<ImageSlotEntry>,
    pub initial: Vec<ImageSlotEntry>,
    pub yield_receiver_slot: Option<Key>,
    pub gas_slots: Vec<Key>,
    pub quota_slots: Vec<Key>,
}

Validation model: structure is eager, semantics are lazy

An ImageCap is admitted from untrusted input under a two-layer discipline:

• Structure — validated eagerly (here / in image_cap, the “deblob”). The metadata that frames execution: code length (≤ MAX_CODE_SIZE), memory-mapping bounds, slot indices, source-path depth, endpoint indices. A malformed structural field has no clean execution point to fault on — it would diverge between engines or panic the host — so it is rejected at construction. This is cheap (O(#endpoints + #mappings + #slots), it never scans the code) and therefore compatible with lazy compilation.

• Semantics — validated lazily (at execution, by both engines identically). The instruction stream itself: illegal/forbidden encodings, and jal/branch/jalr/entry_pc targets. These are not rejected at admission — any code bytes are accepted. A forbidden encoding decodes as illegal and an off-bb_start target is refused only when reached, as ε = panic. Lazy (not eager deblob) because, without an instruction bitmask, a linear validator can’t tell code from data — eager rejection would reject legitimate code-as-data; lazy also keeps admission version-independent (a future ISA extension forks only at execution, never the cap set at admission) and preserves lazy compilation. The consensus requirement is that the two engines agree on what panics, not that the bytes are pre-screened. The producer toolchain still rejects forbidden encodings at build time as a diagnostic — that is UX, not a consensus rule.

Fields

code: Vec<u8>

The (single) code region: raw RV+C+custom-0 bytes, page-aligned so the kernel can direct-map it RO at the fixed protocol constant crate::layout::CODE_BASE. Empty for codeless images. See ImageCap::code_mapping.

endpoints: Vec<(Key, EndpointDef)>

Endpoint definitions, keyed by a Key selector. A sparse, sorted association list (Dict-style — kept sorted by key, no fixed capacity); an absent key is an undefined endpoint. There is no dense array and no entry_pc == 0 sentinel, so an endpoint may legitimately start at code offset 0. (Vec<(Key, _)> rather than BTreeMap because the rkyv wire form has no Ord on the archived key.)

mappings: Vec<MemoryMapping>

Memory mappings.

pinned: Vec<ImageSlotEntry>

Pinned read-only slots (Cap::Data / Cap::Image). Images only ever reference content-addressed caps, so the target is a plain CapHash.

initial: Vec<ImageSlotEntry>

Initial mutable slot state for non-pinned slots.

yield_receiver_slot: Option<Key>

Slot holding Cap::Instance[YieldReceiver] (the catch-set), if any.

gas_slots: Vec<Key>

Cnode slots holding the Cap::Instance[Gas{meter_key}] unit handles, consulted in order. See crate::image::Image::gas_slots.

quota_slots: Vec<Key>

Cnode slots holding the Cap::Instance[Quota{quota_key}] unit handles.

Implementations

impl ImageCap

pub fn code_mapping(&self) -> Option<(u32, &[u8])>

The executable code region as (code_base, bytes). code_base is the fixed protocol constant crate::layout::CODE_BASE, so a PVM PC is code_base + byte_offset. None if the image declares no code (empty region) — such an image cannot execute.

pub fn mapping_is_pinned(&self, start: u32) -> bool

True iff the memory mapping starting at guest VA start draws from a pinned (read-only) slot, so it must be laid read-only — a guest store to it faults. Mirrors the recompiler’s pinned-vs- initial slot classification (nub-arch-x86 build_runtime). Derived from Self::pinned at lay time, so a mapping carries no per-mapping permission field; the interpreter drivers (javm build_entry, nub-arch-local) call this so they classify identically to the recompiler.

Trait Implementations

impl Archive for ImageCap

where Vec<u8>: Archive, Vec<(Key, EndpointDef)>: Archive, Vec<MemoryMapping>: Archive, Vec<ImageSlotEntry>: Archive, Option<Key>: Archive, Vec<Key>: Archive,

const COPY_OPTIMIZATION: CopyOptimization<Self>

An optimization flag that allows the bytes of this type to be copied directly to a writer instead of calling serialize.

type Archived = ArchivedImageCap

The archived representation of this type.

type Resolver = ImageCapResolver

The resolver for this type. It must contain all the additional information from serializing needed to make the archived type from the normal type.

fn resolve(&self, resolver: Self::Resolver, out: Place<Self::Archived>)

Creates the archived version of this value at the given position and writes it to the given output.

impl Clone for ImageCap

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ImageCap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<__D: Fallible + ?Sized> Deserialize<ImageCap, __D> for Archived<ImageCap>

where Vec<u8>: Archive, <Vec<u8> as Archive>::Archived: Deserialize<Vec<u8>, __D>, Vec<(Key, EndpointDef)>: Archive, <Vec<(Key, EndpointDef)> as Archive>::Archived: Deserialize<Vec<(Key, EndpointDef)>, __D>, Vec<MemoryMapping>: Archive, <Vec<MemoryMapping> as Archive>::Archived: Deserialize<Vec<MemoryMapping>, __D>, Vec<ImageSlotEntry>: Archive, <Vec<ImageSlotEntry> as Archive>::Archived: Deserialize<Vec<ImageSlotEntry>, __D>, Option<Key>: Archive, <Option<Key> as Archive>::Archived: Deserialize<Option<Key>, __D>, Vec<Key>: Archive, <Vec<Key> as Archive>::Archived: Deserialize<Vec<Key>, __D>,

fn deserialize( &self, deserializer: &mut __D, ) -> Result<ImageCap, <__D as Fallible>::Error>

Deserializes using the given deserializer

impl HashTreeRoot for ImageCap

fn hash_tree_root<__D: Digest<OutputSize = U32>>(&self) -> [u8; 32]

Compute the hash tree root using D as the underlying hash.

impl<__S: Fallible + ?Sized> Serialize<__S> for ImageCap

where Vec<u8>: Serialize<__S>, Vec<(Key, EndpointDef)>: Serialize<__S>, Vec<MemoryMapping>: Serialize<__S>, Vec<ImageSlotEntry>: Serialize<__S>, Option<Key>: Serialize<__S>, Vec<Key>: Serialize<__S>,

fn serialize( &self, serializer: &mut __S, ) -> Result<<Self as Archive>::Resolver, <__S as Fallible>::Error>

Writes the dependencies for the object and returns a resolver that can create the archived type.