polkavm/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![forbid(unused_must_use)]
3#![forbid(clippy::missing_safety_doc)]
4#![deny(clippy::undocumented_unsafe_blocks)]
5#![deny(clippy::exhaustive_structs)]
6// TODO: Uncomment this once we get rid of all of the `as` casts:
7// #![deny(clippy::as_conversions)]
8
9#[cfg(all(
10    not(miri),
11    target_arch = "x86_64",
12    any(
13        target_os = "linux",
14        all(feature = "generic-sandbox", any(target_os = "macos", target_os = "freebsd"))
15    ),
16    feature = "std",
17))]
18macro_rules! if_compiler_is_supported {
19    ({
20        $($if_true:tt)*
21    } else {
22        $($if_false:tt)*
23    }) => {
24        $($if_true)*
25    };
26
27    ($($if_true:tt)*) => {
28        $($if_true)*
29    }
30}
31
32#[cfg(not(all(
33    not(miri),
34    target_arch = "x86_64",
35    any(
36        target_os = "linux",
37        all(feature = "generic-sandbox", any(target_os = "macos", target_os = "freebsd"))
38    ),
39    feature = "std",
40)))]
41macro_rules! if_compiler_is_supported {
42    ({
43        $($if_true:tt)*
44    } else {
45        $($if_false:tt)*
46    }) => {
47        $($if_false)*
48    };
49
50    ($($if_true:tt)*) => {}
51}
52
53extern crate alloc;
54
55mod error;
56
57mod api;
58mod config;
59mod gas;
60mod interpreter;
61mod linker;
62#[cfg(feature = "std")]
63mod source_cache;
64mod utils;
65
66#[cfg(feature = "std")]
67mod mutex_std;
68
69#[cfg(feature = "std")]
70pub(crate) use mutex_std as mutex;
71
72#[cfg(not(feature = "std"))]
73mod mutex_no_std;
74
75#[cfg(not(feature = "std"))]
76pub(crate) use mutex_no_std as mutex;
77
78impl<T> Default for crate::mutex::Mutex<T>
79where
80    T: Default,
81{
82    fn default() -> Self {
83        Self::new(Default::default())
84    }
85}
86
87#[cfg(feature = "module-cache")]
88mod module_cache;
89
90if_compiler_is_supported! {
91    mod compiler;
92    mod page_set;
93    mod sandbox;
94
95    #[cfg(all(target_os = "linux", not(feature = "export-internals-for-testing")))]
96    mod generic_allocator;
97
98    #[cfg(all(target_os = "linux", not(feature = "export-internals-for-testing")))]
99    mod bit_mask;
100
101    #[cfg(target_os = "linux")]
102    mod shm_allocator;
103}
104
105// These are needed due to: https://github.com/rust-lang/rustfmt/issues/3253
106#[cfg(rustfmt)]
107mod bit_mask;
108#[cfg(rustfmt)]
109mod compiler;
110#[cfg(rustfmt)]
111mod generic_allocator;
112#[cfg(rustfmt)]
113mod page_set;
114#[cfg(rustfmt)]
115mod sandbox;
116#[cfg(rustfmt)]
117mod shm_allocator;
118
119pub use polkavm_common::{
120    abi::{MemoryMap, MemoryMapBuilder},
121    program::{ProgramBlob, ProgramCounter, ProgramParts, Reg},
122    utils::{ArcBytes, AsUninitSliceMut},
123};
124
125/// Miscellaneous types related to debug info.
126pub mod debug_info {
127    pub use polkavm_common::program::{FrameInfo, FrameKind, LineProgram, RegionInfo, SourceLocation};
128
129    #[cfg(feature = "std")]
130    pub use crate::source_cache::SourceCache;
131}
132
133/// Miscellaneous types related to program blobs.
134pub mod program {
135    pub use polkavm_common::program::{
136        EstimateInterpreterMemoryUsageArgs, ISA_JamV1, ISA_Latest32, ISA_Latest64, ISA_ReviveV1, Imports, ImportsIter, Instruction,
137        InstructionSet, InstructionSetKind, Instructions, JumpTable, JumpTableIter, Opcode, ParsedInstruction, ProgramExport,
138        ProgramMemoryInfo, ProgramParseError, ProgramSymbol, RawReg,
139    };
140
141    // This is meant to be public *eventually*, but since it's still a work-in-progress
142    // let's hide it for now so that only those who know what they're doing use it.
143    #[doc(hidden)]
144    pub use polkavm_common::assembler::assemble;
145}
146
147pub type Gas = i64;
148
149pub use crate::api::{Engine, MemoryAccessError, MemoryProtection, Module, RawInstance, RegValue, SetCacheSizeLimitArgs};
150pub use crate::config::{BackendKind, Config, CustomCodegen, GasMeteringKind, ModuleConfig, SandboxKind};
151pub use crate::error::Error;
152pub use crate::gas::{Cost, CostModel, CostModelKind, CostModelRef};
153pub use crate::linker::{CallError, Caller, Instance, InstancePre, Linker};
154pub use crate::utils::{InterruptKind, Segfault};
155pub use polkavm_common::simulator::CacheModel;
156
157pub const RETURN_TO_HOST: u64 = polkavm_common::abi::VM_ADDR_RETURN_TO_HOST as u64;
158
159#[cfg(test)]
160mod tests;
161
162// These need to be toplevel for the macros to work.
163#[cfg(feature = "export-internals-for-testing")]
164pub mod generic_allocator;
165
166#[cfg(feature = "export-internals-for-testing")]
167pub mod bit_mask;
168
169#[cfg(feature = "export-internals-for-testing")]
170#[doc(hidden)]
171pub mod _for_testing {
172    #[cfg(target_os = "linux")]
173    if_compiler_is_supported! {
174        pub use crate::shm_allocator::{ShmAllocation, ShmAllocator};
175        pub fn create_shm_allocator() -> Result<crate::shm_allocator::ShmAllocator, polkavm_linux_raw::Error> {
176            crate::sandbox::init_native_page_size();
177            crate::shm_allocator::ShmAllocator::new()
178        }
179
180        pub use crate::page_set::PageSet;
181    }
182}
polkavm/lib.rs

polkavm/
lib.rs
