wasmtime_environ/compile/
mod.rs

1//! A `Compilation` contains the compiled function bodies for a WebAssembly
2//! module.
3
4use crate::prelude::*;
5use crate::{obj, Tunables};
6use crate::{
7    BuiltinFunctionIndex, DefinedFuncIndex, FlagValue, FuncIndex, FunctionLoc, ObjectKind,
8    PrimaryMap, StaticModuleIndex, TripleExt, WasmError, WasmFuncType,
9};
10use anyhow::Result;
11use object::write::{Object, SymbolId};
12use object::{Architecture, BinaryFormat, FileFlags};
13use std::any::Any;
14use std::borrow::Cow;
15use std::fmt;
16use std::path;
17use std::sync::Arc;
18
19mod address_map;
20mod module_artifacts;
21mod module_environ;
22mod module_types;
23mod stack_maps;
24mod trap_encoding;
25
26pub use self::address_map::*;
27pub use self::module_artifacts::*;
28pub use self::module_environ::*;
29pub use self::module_types::*;
30pub use self::stack_maps::*;
31pub use self::trap_encoding::*;
32
33/// An error while compiling WebAssembly to machine code.
34#[derive(Debug)]
35pub enum CompileError {
36    /// A wasm translation error occurred.
37    Wasm(WasmError),
38
39    /// A compilation error occurred.
40    Codegen(String),
41
42    /// A compilation error occurred.
43    DebugInfoNotSupported,
44}
45
46impl fmt::Display for CompileError {
47    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
48        match self {
49            CompileError::Wasm(_) => write!(f, "WebAssembly translation error"),
50            CompileError::Codegen(s) => write!(f, "Compilation error: {s}"),
51            CompileError::DebugInfoNotSupported => {
52                write!(f, "Debug info is not supported with this configuration")
53            }
54        }
55    }
56}
57
58impl From<WasmError> for CompileError {
59    fn from(err: WasmError) -> CompileError {
60        CompileError::Wasm(err)
61    }
62}
63
64impl core::error::Error for CompileError {
65    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
66        match self {
67            CompileError::Wasm(e) => Some(e),
68            _ => None,
69        }
70    }
71}
72
73/// What relocations can be applied against.
74///
75/// Each wasm function may refer to various other `RelocationTarget` entries.
76#[derive(Copy, Clone, Debug, PartialEq, Eq)]
77pub enum RelocationTarget {
78    /// This is a reference to another defined wasm function in the same module.
79    Wasm(FuncIndex),
80    /// This is a reference to a trampoline for a builtin function.
81    Builtin(BuiltinFunctionIndex),
82    /// A compiler-generated libcall.
83    HostLibcall(obj::LibCall),
84    /// A pulley->host call from the interpreter.
85    PulleyHostcall(u32),
86}
87
88/// Implementation of an incremental compilation's key/value cache store.
89///
90/// In theory, this could just be Cranelift's `CacheKvStore` trait, but it is not as we want to
91/// make sure that wasmtime isn't too tied to Cranelift internals (and as a matter of fact, we
92/// can't depend on the Cranelift trait here).
93pub trait CacheStore: Send + Sync + std::fmt::Debug {
94    /// Try to retrieve an arbitrary cache key entry, and returns a reference to bytes that were
95    /// inserted via `Self::insert` before.
96    fn get(&self, key: &[u8]) -> Option<Cow<[u8]>>;
97
98    /// Given an arbitrary key and bytes, stores them in the cache.
99    ///
100    /// Returns false when insertion in the cache failed.
101    fn insert(&self, key: &[u8], value: Vec<u8>) -> bool;
102}
103
104/// Abstract trait representing the ability to create a `Compiler` below.
105///
106/// This is used in Wasmtime to separate compiler implementations, currently
107/// mostly used to separate Cranelift from Wasmtime itself.
108pub trait CompilerBuilder: Send + Sync + fmt::Debug {
109    /// Sets the target of compilation to the target specified.
110    fn target(&mut self, target: target_lexicon::Triple) -> Result<()>;
111
112    /// Enables clif output in the directory specified.
113    fn clif_dir(&mut self, _path: &path::Path) -> Result<()> {
114        anyhow::bail!("clif output not supported");
115    }
116
117    /// Returns the currently configured target triple that compilation will
118    /// produce artifacts for.
119    fn triple(&self) -> &target_lexicon::Triple;
120
121    /// Compiler-specific method to configure various settings in the compiler
122    /// itself.
123    ///
124    /// This is expected to be defined per-compiler. Compilers should return
125    /// errors for unknown names/values.
126    fn set(&mut self, name: &str, val: &str) -> Result<()>;
127
128    /// Compiler-specific method for configuring settings.
129    ///
130    /// Same as [`CompilerBuilder::set`] except for enabling boolean flags.
131    /// Currently cranelift uses this to sometimes enable a family of settings.
132    fn enable(&mut self, name: &str) -> Result<()>;
133
134    /// Returns a list of all possible settings that can be configured with
135    /// [`CompilerBuilder::set`] and [`CompilerBuilder::enable`].
136    fn settings(&self) -> Vec<Setting>;
137
138    /// Enables Cranelift's incremental compilation cache, using the given `CacheStore`
139    /// implementation.
140    ///
141    /// This will return an error if the compiler does not support incremental compilation.
142    fn enable_incremental_compilation(&mut self, cache_store: Arc<dyn CacheStore>) -> Result<()>;
143
144    /// Set the tunables for this compiler.
145    fn set_tunables(&mut self, tunables: Tunables) -> Result<()>;
146
147    /// Builds a new [`Compiler`] object from this configuration.
148    fn build(&self) -> Result<Box<dyn Compiler>>;
149
150    /// Enables or disables wmemcheck during runtime according to the wmemcheck CLI flag.
151    fn wmemcheck(&mut self, _enable: bool) {}
152}
153
154/// Description of compiler settings returned by [`CompilerBuilder::settings`].
155#[derive(Clone, Copy, Debug)]
156pub struct Setting {
157    /// The name of the setting.
158    pub name: &'static str,
159    /// The description of the setting.
160    pub description: &'static str,
161    /// The kind of the setting.
162    pub kind: SettingKind,
163    /// The supported values of the setting (for enum values).
164    pub values: Option<&'static [&'static str]>,
165}
166
167/// Different kinds of [`Setting`] values that can be configured in a
168/// [`CompilerBuilder`]
169#[derive(Clone, Copy, Debug)]
170pub enum SettingKind {
171    /// The setting is an enumeration, meaning it's one of a set of values.
172    Enum,
173    /// The setting is a number.
174    Num,
175    /// The setting is a boolean.
176    Bool,
177    /// The setting is a preset.
178    Preset,
179}
180
181/// The result of compiling a single function body.
182pub struct CompiledFunctionBody {
183    /// The code. This is whatever type the `Compiler` implementation wants it
184    /// to be, we just shepherd it around.
185    pub code: Box<dyn Any + Send>,
186    /// Whether the compiled function needs a GC heap to run; that is, whether
187    /// it reads a struct field, allocates, an array, or etc...
188    pub needs_gc_heap: bool,
189}
190
191/// An implementation of a compiler which can compile WebAssembly functions to
192/// machine code and perform other miscellaneous tasks needed by the JIT runtime.
193pub trait Compiler: Send + Sync {
194    /// Compiles the function `index` within `translation`.
195    ///
196    /// The body of the function is available in `data` and configuration
197    /// values are also passed in via `tunables`. Type information in
198    /// `translation` is all relative to `types`.
199    fn compile_function(
200        &self,
201        translation: &ModuleTranslation<'_>,
202        index: DefinedFuncIndex,
203        data: FunctionBodyData<'_>,
204        types: &ModuleTypesBuilder,
205    ) -> Result<CompiledFunctionBody, CompileError>;
206
207    /// Compile a trampoline for an array-call host function caller calling the
208    /// `index`th Wasm function.
209    ///
210    /// The trampoline should save the necessary state to record the
211    /// host-to-Wasm transition (e.g. registers used for fast stack walking).
212    fn compile_array_to_wasm_trampoline(
213        &self,
214        translation: &ModuleTranslation<'_>,
215        types: &ModuleTypesBuilder,
216        index: DefinedFuncIndex,
217    ) -> Result<CompiledFunctionBody, CompileError>;
218
219    /// Compile a trampoline for a Wasm caller calling a array callee with the
220    /// given signature.
221    ///
222    /// The trampoline should save the necessary state to record the
223    /// Wasm-to-host transition (e.g. registers used for fast stack walking).
224    fn compile_wasm_to_array_trampoline(
225        &self,
226        wasm_func_ty: &WasmFuncType,
227    ) -> Result<CompiledFunctionBody, CompileError>;
228
229    /// Creates a trampoline that can be used to call Wasmtime's implementation
230    /// of the builtin function specified by `index`.
231    ///
232    /// The trampoline created can technically have any ABI but currently has
233    /// the native ABI. This will then perform all the necessary duties of an
234    /// exit trampoline from wasm and then perform the actual dispatch to the
235    /// builtin function. Builtin functions in Wasmtime are stored in an array
236    /// in all `VMContext` pointers, so the call to the host is an indirect
237    /// call.
238    fn compile_wasm_to_builtin(
239        &self,
240        index: BuiltinFunctionIndex,
241    ) -> Result<CompiledFunctionBody, CompileError>;
242
243    /// Returns the list of relocations required for a function from one of the
244    /// previous `compile_*` functions above.
245    fn compiled_function_relocation_targets<'a>(
246        &'a self,
247        func: &'a dyn Any,
248    ) -> Box<dyn Iterator<Item = RelocationTarget> + 'a>;
249
250    /// Appends a list of compiled functions to an in-memory object.
251    ///
252    /// This function will receive the same `Box<dyn Any>` produced as part of
253    /// compilation from functions like `compile_function`,
254    /// `compile_host_to_wasm_trampoline`, and other component-related shims.
255    /// Internally this will take all of these functions and add information to
256    /// the object such as:
257    ///
258    /// * Compiled code in a `.text` section
259    /// * Unwind information in Wasmtime-specific sections
260    /// * Relocations, if necessary, for the text section
261    ///
262    /// Each function is accompanied with its desired symbol name and the return
263    /// value of this function is the symbol for each function as well as where
264    /// each function was placed within the object.
265    ///
266    /// The `resolve_reloc` argument is intended to resolving relocations
267    /// between function, chiefly resolving intra-module calls within one core
268    /// wasm module. The closure here takes two arguments:
269    ///
270    /// 1. First, the index within `funcs` that is being resolved,
271    ///
272    /// 2. and next the `RelocationTarget` which is the relocation target to
273    ///    resolve.
274    ///
275    /// The return value is an index within `funcs` that the relocation points
276    /// to.
277    fn append_code(
278        &self,
279        obj: &mut Object<'static>,
280        funcs: &[(String, Box<dyn Any + Send>)],
281        resolve_reloc: &dyn Fn(usize, RelocationTarget) -> usize,
282    ) -> Result<Vec<(SymbolId, FunctionLoc)>>;
283
284    /// Creates a new `Object` file which is used to build the results of a
285    /// compilation into.
286    ///
287    /// The returned object file will have an appropriate
288    /// architecture/endianness for `self.triple()`, but at this time it is
289    /// always an ELF file, regardless of target platform.
290    fn object(&self, kind: ObjectKind) -> Result<Object<'static>> {
291        use target_lexicon::Architecture::*;
292
293        let triple = self.triple();
294        let (arch, flags) = match triple.architecture {
295            X86_32(_) => (Architecture::I386, 0),
296            X86_64 => (Architecture::X86_64, 0),
297            Arm(_) => (Architecture::Arm, 0),
298            Aarch64(_) => (Architecture::Aarch64, 0),
299            S390x => (Architecture::S390x, 0),
300            Riscv64(_) => (Architecture::Riscv64, 0),
301            // XXX: the `object` crate won't successfully build an object
302            // with relocations and such if it doesn't know the
303            // architecture, so just pretend we are riscv64. Yolo!
304            //
305            // Also note that we add some flags to `e_flags` in the object file
306            // to indicate that it's pulley, not actually riscv64. This is used
307            // by `wasmtime objdump` for example.
308            Pulley32 | Pulley32be => (Architecture::Riscv64, obj::EF_WASMTIME_PULLEY32),
309            Pulley64 | Pulley64be => (Architecture::Riscv64, obj::EF_WASMTIME_PULLEY64),
310            architecture => {
311                anyhow::bail!("target architecture {:?} is unsupported", architecture,);
312            }
313        };
314        let mut obj = Object::new(
315            BinaryFormat::Elf,
316            arch,
317            match triple.endianness().unwrap() {
318                target_lexicon::Endianness::Little => object::Endianness::Little,
319                target_lexicon::Endianness::Big => object::Endianness::Big,
320            },
321        );
322        obj.flags = FileFlags::Elf {
323            os_abi: obj::ELFOSABI_WASMTIME,
324            e_flags: flags
325                | match kind {
326                    ObjectKind::Module => obj::EF_WASMTIME_MODULE,
327                    ObjectKind::Component => obj::EF_WASMTIME_COMPONENT,
328                },
329            abi_version: 0,
330        };
331        Ok(obj)
332    }
333
334    /// Returns the target triple that this compiler is compiling for.
335    fn triple(&self) -> &target_lexicon::Triple;
336
337    /// Returns the alignment necessary to align values to the page size of the
338    /// compilation target. Note that this may be an upper-bound where the
339    /// alignment is larger than necessary for some platforms since it may
340    /// depend on the platform's runtime configuration.
341    fn page_size_align(&self) -> u64 {
342        // Conservatively assume the max-of-all-supported-hosts for pulley
343        // and round up to 64k.
344        if self.triple().is_pulley() {
345            return 0x10000;
346        }
347
348        use target_lexicon::*;
349        match (self.triple().operating_system, self.triple().architecture) {
350            (
351                OperatingSystem::MacOSX { .. }
352                | OperatingSystem::Darwin(_)
353                | OperatingSystem::IOS(_)
354                | OperatingSystem::TvOS(_),
355                Architecture::Aarch64(..),
356            ) => 0x4000,
357            // 64 KB is the maximal page size (i.e. memory translation granule size)
358            // supported by the architecture and is used on some platforms.
359            (_, Architecture::Aarch64(..)) => 0x10000,
360            _ => 0x1000,
361        }
362    }
363
364    /// Returns a list of configured settings for this compiler.
365    fn flags(&self) -> Vec<(&'static str, FlagValue<'static>)>;
366
367    /// Same as [`Compiler::flags`], but ISA-specific (a cranelift-ism)
368    fn isa_flags(&self) -> Vec<(&'static str, FlagValue<'static>)>;
369
370    /// Get a flag indicating whether branch protection is enabled.
371    fn is_branch_protection_enabled(&self) -> bool;
372
373    /// Returns a suitable compiler usable for component-related compilations.
374    ///
375    /// Note that the `ComponentCompiler` trait can also be implemented for
376    /// `Self` in which case this function would simply return `self`.
377    #[cfg(feature = "component-model")]
378    fn component_compiler(&self) -> &dyn crate::component::ComponentCompiler;
379
380    /// Appends generated DWARF sections to the `obj` specified.
381    ///
382    /// The `translations` track all compiled functions and `get_func` can be
383    /// used to acquire the metadata for a particular function within a module.
384    fn append_dwarf<'a>(
385        &self,
386        obj: &mut Object<'_>,
387        translations: &'a PrimaryMap<StaticModuleIndex, ModuleTranslation<'a>>,
388        get_func: &'a dyn Fn(
389            StaticModuleIndex,
390            DefinedFuncIndex,
391        ) -> (SymbolId, &'a (dyn Any + Send)),
392        dwarf_package_bytes: Option<&'a [u8]>,
393        tunables: &'a Tunables,
394    ) -> Result<()>;
395
396    /// Creates a new System V Common Information Entry for the ISA.
397    ///
398    /// Returns `None` if the ISA does not support System V unwind information.
399    fn create_systemv_cie(&self) -> Option<gimli::write::CommonInformationEntry> {
400        // By default, an ISA cannot create a System V CIE.
401        None
402    }
403}
wasmtime_environ/compile/mod.rs

wasmtime_environ/compile/
mod.rs
