virtual_machine/lib.rs
1//! # Virtual Machine Module
2//!
3//! This crate provides a WebAssembly (WASM) virtual machine implementation for the Xila operating system.
4//! It is built on top of the WAMR (WebAssembly Micro Runtime) and provides a high-level interface
5//! for executing WASM modules in a no_std environment.
6//!
7//! ## Features
8//!
9//! - **Module Management**: Load, instantiate, and execute WASM modules
10//! - **Runtime Environment**: Provides isolated execution environments for WASM instances
11//! - **Host Function Registration**: Register native functions that can be called from WASM
12//! - **Memory Management**: Safe pointer conversion between WASM and native address spaces
13//! - **Error Handling**: Comprehensive error types for debugging and error recovery
14//! - **XIP Support**: Execute-in-place for AOT compiled modules
15//! - **WASI Integration**: WebAssembly System Interface support with custom I/O redirection
16//!
17//! ## Architecture
18//!
19//! The crate is organized into several key components:
20//!
21//! - [`Manager`]: Global singleton that manages the WASM runtime and loaded modules
22//! - [`Runtime`]: Represents a WASM runtime instance with registered host functions
23//! - [`Module`]: Represents a loaded WASM module ready for instantiation
24//! - [`Instance`]: An instantiated WASM module that can execute functions
25//! - [`Environment`]: Execution environment providing context for function calls
26//!
27//! ## Usage Example
28//!
29//! ```rust,ignore
30//! use virtual_machine::*;
31//!
32//! // Define host functions that WASM can call
33//! struct MyRegistrable;
34//! impl Registrable_trait for MyRegistrable {
35//! fn get_functions(&self) -> &[Function_descriptor_type] {
36//! &[Function_descriptor!(my_host_function)]
37//! }
38//! fn get_name(&self) -> &'static str { "my_module" }
39//! }
40//!
41//! // Initialize the virtual machine manager
42//! let manager = Initialize(&[&MyRegistrable]);
43//!
44//! // Execute a WASM module
45//! let result = manager.Execute(
46//! wasm_bytes,
47//! stack_size,
48//! stdin_fd,
49//! stdout_fd,
50//! stderr_fd
51//! ).await;
52//! ```
53
54#![no_std]
55#![allow(unused_imports)]
56extern crate alloc;
57
58mod custom_data;
59mod environment;
60mod error;
61mod instance;
62mod manager;
63mod module;
64mod registrable;
65mod runtime;
66
67// Re-export key types from WAMR
68pub use wamr_rust_sdk::value::WasmValue;
69
70// Re-export all public types from modules
71pub use custom_data::*;
72pub use environment::*;
73pub use error::*;
74pub use instance::*;
75pub use manager::*;
76pub use module::*;
77pub use registrable::*;
78pub use runtime::*;
79
80/// Type alias for WASM pointer addresses in the 32-bit WASM address space
81pub type WasmPointer = u32;
82
83/// Type alias for WASM size values (32-bit)
84pub type WasmUsize = u32;