Crate virtual_machine

Virtual Machine Module

This crate provides a WebAssembly (WASM) virtual machine implementation for the Xila operating system. It is built on top of the WAMR (WebAssembly Micro Runtime) and provides a high-level interface for executing WASM modules in a no_std environment.

Features

• Module Management: Load, instantiate, and execute WASM modules
• Runtime Environment: Provides isolated execution environments for WASM instances
• Host Function Registration: Register native functions that can be called from WASM
• Memory Management: Safe pointer conversion between WASM and native address spaces
• Error Handling: Comprehensive error types for debugging and error recovery
• XIP Support: Execute-in-place for AOT compiled modules
• WASI Integration: WebAssembly System Interface support with custom I/O redirection

Architecture

The crate is organized into several key components:

• Manager: Global singleton that manages the WASM runtime and loaded modules
• Runtime: Represents a WASM runtime instance with registered host functions
• Module: Represents a loaded WASM module ready for instantiation
• Instance: An instantiated WASM module that can execute functions
• Environment: Execution environment providing context for function calls

Usage Example

use virtual_machine::*;

// Define host functions that WASM can call
struct MyRegistrable;
impl Registrable_trait for MyRegistrable {
    fn get_functions(&self) -> &[Function_descriptor_type] {
        &[Function_descriptor!(my_host_function)]
    }
    fn get_name(&self) -> &'static str { "my_module" }
}

// Initialize the virtual machine manager
let manager = Initialize(&[&MyRegistrable]);

// Execute a WASM module
let result = manager.Execute(
    wasm_bytes,
    stack_size,
    stdin_fd,
    stdout_fd,
    stderr_fd
).await;

Macros

Function_descriptor

Function_descriptors

Structs

CustomData

Environment

FunctionDescriptor

Instance

Manager

The Virtual Machine Manager handles WASM runtime lifecycle and module execution.

Module

Runtime

RuntimeBuilder

Builder for configuring and creating WASM runtime instances.

Enums

Error

Comprehensive error types for Virtual Machine operations

WasmValue

Traits

Registrable

Functions

get_instance

Get a reference to the initialized Virtual Machine Manager instance.

initialize

Initialize the Virtual Machine Manager with a set of registrable host functions.

Type Aliases

EnvironmentPointer

FunctionPointer

Result

Result type alias for Virtual Machine operations

WasmPointer

Type alias for WASM pointer addresses in the 32-bit WASM address space

WasmUsize

Type alias for WASM size values (32-bit)