corevm-guest 0.1.16

//! Rust wrappers around C API.

#![allow(clippy::missing_safety_doc)]

use crate::c;
use core::mem::size_of_val;

/// Get the current amount of gas.
pub fn gas() -> u64 {
	unsafe { c::gas() }
}

/// Allocate memory block of the specified size.
///
/// - The size is rounded up to the next multiple of page size.
/// - The returned address is aligned at a page boundary.
///
/// Returns the pointer to the allocated memory region or [`null_mut()`](core::ptr::null_mut) if the
/// allocation was unsuccessful.
pub unsafe fn alloc(size: u64) -> *mut u8 {
	c::alloc(size) as *mut u8
}

/// Deallocate the memory block of the specified size starting at `address`.
///
/// Deallocates *all* the pages that overlap the memory block.
pub unsafe fn free(address: *mut u8, size: u64) {
	c::free(address as u64, size)
}

/// Console stream type.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConsoleStream {
	/// Standard output stream.
	Stdout = 1,
	/// Standard error stream.
	Stderr = 2,
}

/// Append `text` to the specified _console_ output stream.
pub fn yield_console_data(stream: ConsoleStream, text: &str) {
	let bytes = text.as_bytes();
	let len = bytes.len() as u64;
	unsafe { c::yield_console_data(stream as u64, bytes.as_ptr() as u64, len) };
}

/// Append video frame to the _video_ output stream.
///
/// Frame format is defined by [`video_mode`](crate::video_mode).
pub fn yield_video_frame<S: AsRef<[T]>, T: Sized>(frame_number: u64, frame: S) {
	let frame = frame.as_ref();
	let address = frame.as_ptr() as u64;
	let len = size_of_val(frame) as u64;
	unsafe { c::yield_video_frame(frame_number, address, len) };
}

/// Set video monitor output mode to `mode`.
pub fn video_mode(mode: &VideoMode) {
	unsafe {
		c::video_mode(
			mode.width as u64,
			mode.height as u64,
			mode.refresh_rate as u64,
			mode.format as u64,
		)
	}
}

/// Video monitor output mode.
pub struct VideoMode {
	/// Frame width.
	pub width: u32,
	/// Frame height.
	pub height: u32,
	/// Monitor refresh rate (frames per second).
	pub refresh_rate: u16,
	/// Frame encoding.
	pub format: VideoFrameFormat,
}

/// The format of the frames emitted via [`yield_video_frame`].
#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)]
pub enum VideoFrameFormat {
	/// Indexed RGB colors.
	///
	/// Format: `[ has_palette(1) | palette(256*3) | frame(width*height) ]`.
	///
	/// Each frame starts with `has_palette` flag that defines whether the pallete is present or
	/// not. `0` means the palette is not present and one should use the palette from the previous
	/// frames. It is an error to transmit the first frame without a palette. `1` means the palette
	/// is present.
	///
	/// The pallete has 256 colors and each colors has 3 components. Each color in the
	/// palette is encoded as a sequence of red, green, blue components, each component occupies 8
	/// bits.
	///
	/// The frame itself goes after the pallete. It is encoded as a sequence of 8-bit indices into
	/// the palette in row-major order, there are `width * height` indices in total.
	Rgb888Indexed8 = 1,
}