Crate corevm_guest

CoreVM’s guest API.

Functions exposed to the guest programs running in an inner VM. ⚠️ CoreVM API is subject to change.

How to write a program for CoreVM

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.

print

Print a message to the standard output stream.

println

Print a message to the standard output stream, with a newline.

Structs

VideoMode

Video monitor output mode.

Enums

ConsoleStream

Console stream type.

VideoFrameFormat

The format of the frames emitted via yield_video_frame.

Functions

alloc^⚠

Allocate memory block of the specified size.

free^⚠

Deallocate the memory block of the specified size starting at address.

gas

Get the current amount of gas.

stderr

Get standard error stream.

stdout

Get standard output stream.

video_mode

Set video monitor output mode to mode.

yield_console_data

Append text to the specified console output stream.

yield_video_frame

Append video frame to the video output stream.