Crate corevm_guest

Expand description

CoreVM’s guest API.

Functions exposed to the guest programs running in an inner VM.

§How to write a program for CoreVM

⚠️ CoreVM API is subject to change. ⚠️

§Rust

CoreVM programs have single entry-point called main with index = 0 (the default). The simplest program looks like the following.

#![no_std]
#![no_main]

#[polkavm_derive::polkavm_export]
extern "C" fn main() -> u64 {
    0
}

CoreVM programs produce output into one of the output streams. Currently console and video streams are available. The simplest program that outputs “Hello world” to the console output stream is shown below.

#![no_std]
#![no_main]

use corevm_guest::println;

#[polkavm_derive::polkavm_export]
extern "C" fn main() -> u64 {
    println!("Hello world");
    0
}

Copying out the data is an atomic operation: the array passed to e.g. yield_console_data is either fully copied or not copied at all. If the array can’t be copied, the program execution is suspended, and the continuation is possible via creating another work package.

§C

Here is the example program written in C.

#include <stdint.h>

#include "corevm_guest.h"

POLKAVM_EXPORT(uint64_t, ext_main);

uint64_t ext_main() {
    corevm_printf("Hello world\n");
    return 0;
}

Modules§

c: C API.

Macros§

eprint: Print a message to the standard error stream.
eprintln: Print a message to the standard error stream, with a newline.
min_stack_size
print: Print a message to the standard output stream.
println: Print a message to the standard output stream, with a newline.

Structs§

AudioMode: Audio monitor output mode.
VideoMode: Video monitor output mode.

Enums§

AudioSampleFormat: The format of the samples emitted via [yield_audio_samples].
ConsoleStream: Console stream type.
VideoFrameFormat: The format of the frames emitted via [yield_video_frame].

Traits§

AudioSample: Marker trait for types that can be used as audio samples.

Functions§

alloc^⚠: Allocate memory block of the specified size.
audio_mode: Set audio output mode to mode.
free^⚠: Deallocate the memory block of the specified size starting at address.
gas: Get the current amount of gas.
panic: Default panic handler.
stderr: Get standard error stream.
stdout: Get standard output stream.
video_mode: Set video monitor output mode to mode.
yield_audio_samples: Append audio samples to the audio output stream.
yield_console_data: Append data to the specified console output stream.
yield_video_frame: Append video frame to the video output stream.