corevm_host/

package.rs

use crate::{fs, Arg, AudioMode, OutputStream, PageAddr, RangeSet, VideoMode};
use alloc::vec::Vec;
use codec::{ConstEncodedLen, Decode, Encode, MaxEncodedLen};
use jam_types::{Hash, SegmentTreeRoot, ServiceId, SignedGas, VecMap, MEMO_LEN, SEGMENT_LEN};

/// CoreVM-specific [work payload](jam_types::WorkPayload).
///
/// This is the input of the work package.
#[derive(Encode, Decode, Debug, Clone)]
pub struct CoreVmPayload {
	/// Inner VM gas.
	pub gas: SignedGas,
	/// The prior (known) VM state from which the program run should continue.
	///
	/// Equals [`VmState::initial`] on the first program run.
	pub vm_state: VmState,
	/// Execution environment location in the virtual file system.
	pub exec_ref: fs::BlockRef,
}

/// CoreVM-specific [work output](jam_types::WorkOutput).
///
/// This is the output of the work package.
#[derive(Encode, Decode, Debug)]
pub struct CoreVmOutput {
	/// The specification of the VM's output data.
	pub vm_output: VmOutput,
	/// The posterior VM state on which the program run was suspended.
	///
	/// Use this state in [`CoreVmPayload`] to continue the execution in another work package.
	pub vm_state: VmState,
	pub old_hash: Hash,
	pub new_hash: Hash,
	/// Memory pages that were imported and read from/written to while refining the package.
	pub touched_imported_pages: VecMap<u64, Hash>,
	/// Memory pages that were read from/written to while refining this work package.
	///
	/// Include deallocated pages indicated by zero hashes.
	pub updated_pages: VecMap<u64, Hash>,
	/// Execution environment location in the virtual file system.
	pub exec_ref: fs::BlockRef,
}

/// The specification of the VM's output data.
///
/// Includes the information that is needed to decode work package exports and also the final state
/// after the VM invocation (remaining gas and the outcome).
///
/// Exports have the following structure:
///
/// `[ memory pages | output stream 0 | ... | output stream N | null segments ]`
#[derive(Encode, Decode, Debug)]
pub struct VmOutput {
	/// Remainig inner VM gas.
	pub remaining_gas: SignedGas,
	/// The outcome of the inner VM invocation.
	pub outcome: Outcome,
	/// The no. of exported memory pages.
	pub num_memory_pages: u32,
	/// Per-stream output size.
	pub stream_len: [u32; OutputStream::COUNT],
}

impl VmOutput {
	/// Get the size of the stream `i`.
	pub fn stream_len(&self, i: OutputStream) -> u32 {
		self.stream_len[i as usize - 1]
	}

	/// Total length of all streams.
	pub fn all_streams_len(&self) -> u32 {
		self.stream_len.iter().sum()
	}

	/// Returns `true` if all streams are empty.
	pub fn is_empty(&self) -> bool {
		self.stream_len.iter().all(|len| *len == 0)
	}

	/// Get the number of output segments.
	pub fn num_output_segments(&self) -> u32 {
		self.stream_len.iter().sum::<u32>().div_ceil(SEGMENT_LEN as u32)
	}

	/// Get the start and end offset of the specified stream.
	///
	/// The offsets are measured from the first exported segment.
	pub fn get_stream_range(&self, stream: OutputStream) -> (u32, u32) {
		let mut start = 0;
		let mut end = 0;
		for i in OutputStream::ALL {
			let len = self.stream_len[i as usize - 1];
			if i == stream {
				end = start + len;
				break;
			}
			start += len;
		}
		let offset = self.num_memory_pages * SEGMENT_LEN as u32;
		(offset + start, offset + end)
	}
}

/// The result code returned by CoreVM service.
///
/// It is similar to `jam_pvm_common::InvokeOutcome` but does not include host-call
/// faults because they are automatically handled by CoreVM.
#[derive(Encode, Decode, MaxEncodedLen, PartialEq, Eq, Clone, Copy)]
pub enum Outcome {
	/// Completed normally.
	Halt,
	/// Completed with a panic.
	Panic,
	/// Completed with a page fault that couldn't be handled by CoreVM.
	///
	/// Undhandled page fault might occur because _either_ the max. no. of exports is reached _or_
	/// the corresponding page was not imported by the work package. In the former case the
	/// program needs to be resumed in the next work package without any further action from the
	/// builder. In the latter case the page with the specified address has to be imported on the
	/// next program run to continue.
	PageFault { page: u64, num_pages: u64 },
	/// Completed by running out of gas.
	OutOfGas,
	/// The inner VM has reached the max. no. of exports while appending new data to the output
	/// stream.
	OutputLimitReached,
	/// The program produced one time-slot worth of video frames or audio samples.
	///
	/// If both streams are active, then both streams need to have one time-slot worth of data to
	/// trigger this outcome.
	TimeLimitReached,
}

impl core::fmt::Debug for Outcome {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
		match self {
			Self::Halt => f.write_str("Halt"),
			Self::Panic => f.write_str("Panic"),
			Self::PageFault { page, num_pages } =>
				f.debug_tuple("PageFault").field(&format_args!("{page}+{num_pages}")).finish(),
			Self::OutOfGas => f.write_str("OutOfGas"),
			Self::OutputLimitReached => f.write_str("OutputLimitReached"),
			Self::TimeLimitReached => f.write_str("TimeLimitReached"),
		}
	}
}

impl ConstEncodedLen for Outcome {}

/// Inner VM state.
#[derive(Encode, Decode, Debug, Clone)]
pub struct VmState {
	/// Registers.
	pub regs: [u64; 13],
	/// Program counter.
	pub program_counter: u64,
	/// Mapped heap memory pages' indices.
	///
	/// These pages were allocated by the guest but not necessarily read from/written to.
	///
	/// Note that it's possible to include only a subset of the pages if you're sure that they will
	/// not be touched again during the program run. Howeve,r if such a page is touched the engine
	/// will panic.
	pub mapped_heap_pages: RangeSet,
	/// All memory pages that were read from/written to by the guest but haven't been unmapped
	/// yet.
	///
	/// Note that it's possible to include only a subset of the pages if you're sure that they will
	/// not be touched again during the program run. However, if such a page is touched the
	/// engine will silently initialize it from the default: from zeroes for stack/heap and from
	/// the program's RW data section for RW data. The program might continue without an error
	/// after that, but the output will most likely be incorrect.
	pub resident_pages: RangeSet,
	/// The state of the Linux kernel syscall layer.
	pub kernel: KernelState,
	/// The index of the host-call that needs to be restarted on resuming the program execution.
	#[doc(hidden)]
	pub restart_host_call: Option<u64>,
	/// Video output mode.
	pub video: Option<VideoMode>,
	/// Audio output mode.
	pub audio: Option<AudioMode>,
}

impl VmState {
	/// Create initial state.
	pub const fn initial() -> Self {
		Self {
			regs: [0; 13],
			program_counter: 0,
			mapped_heap_pages: RangeSet::new(),
			resident_pages: RangeSet::new(),
			kernel: KernelState { fds: VecMap::new() },
			restart_host_call: None,
			video: None,
			audio: None,
		}
	}
}

/// Storage keys used by CoreVM.
#[derive(Encode, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[non_exhaustive]
pub enum StorageKey {
	/// Inner VM gas.
	Gas,
	/// The hash of this CoreVM instance.
	///
	/// Computed with `corevm_engine::compute_state_hash`.
	StateHash,
	/// The last known metadata of a memory page with the specified address.
	///
	/// An instance of [`PageInfo`](crate::PageInfo).
	PageInfo(PageAddr),
	/// The output data specification of the VM.
	///
	/// An instance of [`VmSpec`](crate::VmSpec).
	VmSpec,
	/// The current video mode.
	///
	/// An instance of [`VideoMode`](crate::VideoMode).
	VideoMode,
	/// The current audio mode.
	///
	/// An instance of [`AudioMode`](crate::AudioMode).
	AudioMode,
	/// Execution environment location in the virtual file system.
	///
	/// The environment ([`ExecEnv`]) itself is stored as a file.
	ExecEnvRef,
	/// The owner of this CoreVM instance; they can reset the code.
	Owner,
	/// The pages currently in active use by the program.
	ResidentPages,
}

/// Memory page metadata.
#[derive(Encode, Decode, Debug)]
pub struct PageInfo {
	/// The hash of the page segment.
	pub hash: Hash,
	/// Segment-root of the package exports where the page contents are stored.
	pub exports_root: SegmentTreeRoot,
	/// The index of the exported segment where the page contents are stored.
	pub export_index: u16,
}

/// Same as [`CoreVmOutput`] but only includes the data necessary to continue program execution.
#[derive(Encode, Decode, Debug)]
pub struct VmSpec {
	/// Segment-root of the package exports where the actual output is stored.
	pub exports_root: SegmentTreeRoot,
	/// The specification of the VM's output data.
	pub output: VmOutput,
	pub state: VmState,
}

/// Guest execution environment.
#[derive(Encode, Decode, Clone, Debug)]
pub struct ExecEnv {
	/// Program location in the virtual file system.
	pub program: fs::BlockRef,
	/// Root directory location in the virtual file system.
	pub root_dir: fs::BlockRef,
	// TODO @ivan add current working directory
	/// Command-line arguments.
	pub args: Vec<Arg>,
	/// Environment variables.
	pub env: Vec<Arg>,
}

/// Instruction to send to the CoreVM service.
#[derive(Encode, Decode, Debug)]
pub enum CoreVmInstruction {
	/// Reset the VM.
	Reset {
		/// Inner VM gas.
		gas: SignedGas,
		/// Reference to a file where the environment ([`ExecEnv`]) is stored.
		exec_ref: fs::BlockRef,
	},
	/// Set the owner of this CoreVM instance.
	SetOwner(ServiceId),
}

impl MaxEncodedLen for CoreVmInstruction {
	fn max_encoded_len() -> usize {
		MEMO_LEN
	}
}

/// The state of the Linux kernel syscall layer.
#[derive(Encode, Decode, Clone, Debug, Default)]
pub struct KernelState {
	/// Opened file descriptors.
	pub fds: VecMap<u32, KernelFd>,
}

/// In-kernel file descriptor state.
#[derive(Encode, Decode, MaxEncodedLen, Clone, Debug)]
pub struct KernelFd {
	/// File reference in the virtual FS.
	pub block_ref: fs::BlockRef,
	/// File read/write offset.
	pub position: u64,
}

impl ConstEncodedLen for KernelFd {}