wasmtime/runtime/
module.rs

1use crate::prelude::*;
2#[cfg(feature = "std")]
3use crate::runtime::vm::open_file_for_mmap;
4use crate::runtime::vm::{CompiledModuleId, MmapVec, ModuleMemoryImages, VMWasmCallFunction};
5use crate::sync::OnceLock;
6use crate::{
7    Engine,
8    code::CodeObject,
9    code_memory::CodeMemory,
10    instantiate::CompiledModule,
11    resources::ResourcesRequired,
12    types::{ExportType, ExternType, ImportType},
13};
14use alloc::sync::Arc;
15use core::fmt;
16use core::ops::Range;
17use core::ptr::NonNull;
18#[cfg(feature = "std")]
19use std::{fs::File, path::Path};
20use wasmparser::{Parser, ValidPayload, Validator};
21use wasmtime_environ::{
22    CompiledFunctionsTable, CompiledModuleInfo, EntityIndex, HostPtr, ModuleTypes, ObjectKind,
23    TypeTrace, VMOffsets, VMSharedTypeIndex,
24};
25#[cfg(feature = "gc")]
26use wasmtime_unwinder::ExceptionTable;
27mod registry;
28
29pub use registry::*;
30
31/// A compiled WebAssembly module, ready to be instantiated.
32///
33/// A `Module` is a compiled in-memory representation of an input WebAssembly
34/// binary. A `Module` is then used to create an [`Instance`](crate::Instance)
35/// through an instantiation process. You cannot call functions or fetch
36/// globals, for example, on a `Module` because it's purely a code
37/// representation. Instead you'll need to create an
38/// [`Instance`](crate::Instance) to interact with the wasm module.
39///
40/// A `Module` can be created by compiling WebAssembly code through APIs such as
41/// [`Module::new`]. This would be a JIT-style use case where code is compiled
42/// just before it's used. Alternatively a `Module` can be compiled in one
43/// process and [`Module::serialize`] can be used to save it to storage. A later
44/// call to [`Module::deserialize`] will quickly load the module to execute and
45/// does not need to compile any code, representing a more AOT-style use case.
46///
47/// Currently a `Module` does not implement any form of tiering or dynamic
48/// optimization of compiled code. Creation of a `Module` via [`Module::new`] or
49/// related APIs will perform the entire compilation step synchronously. When
50/// finished no further compilation will happen at runtime or later during
51/// execution of WebAssembly instances for example.
52///
53/// Compilation of WebAssembly by default goes through Cranelift and is
54/// recommended to be done once-per-module. The same WebAssembly binary need not
55/// be compiled multiple times and can instead used an embedder-cached result of
56/// the first call.
57///
58/// `Module` is thread-safe and safe to share across threads.
59///
60/// ## Modules and `Clone`
61///
62/// Using `clone` on a `Module` is a cheap operation. It will not create an
63/// entirely new module, but rather just a new reference to the existing module.
64/// In other words it's a shallow copy, not a deep copy.
65///
66/// ## Examples
67///
68/// There are a number of ways you can create a `Module`, for example pulling
69/// the bytes from a number of locations. One example is loading a module from
70/// the filesystem:
71///
72/// ```no_run
73/// # use wasmtime::*;
74/// # fn main() -> anyhow::Result<()> {
75/// let engine = Engine::default();
76/// let module = Module::from_file(&engine, "path/to/foo.wasm")?;
77/// # Ok(())
78/// # }
79/// ```
80///
81/// You can also load the wasm text format if more convenient too:
82///
83/// ```no_run
84/// # use wasmtime::*;
85/// # fn main() -> anyhow::Result<()> {
86/// let engine = Engine::default();
87/// // Now we're using the WebAssembly text extension: `.wat`!
88/// let module = Module::from_file(&engine, "path/to/foo.wat")?;
89/// # Ok(())
90/// # }
91/// ```
92///
93/// And if you've already got the bytes in-memory you can use the
94/// [`Module::new`] constructor:
95///
96/// ```no_run
97/// # use wasmtime::*;
98/// # fn main() -> anyhow::Result<()> {
99/// let engine = Engine::default();
100/// # let wasm_bytes: Vec<u8> = Vec::new();
101/// let module = Module::new(&engine, &wasm_bytes)?;
102///
103/// // It also works with the text format!
104/// let module = Module::new(&engine, "(module (func))")?;
105/// # Ok(())
106/// # }
107/// ```
108///
109/// Serializing and deserializing a module looks like:
110///
111/// ```no_run
112/// # use wasmtime::*;
113/// # fn main() -> anyhow::Result<()> {
114/// let engine = Engine::default();
115/// # let wasm_bytes: Vec<u8> = Vec::new();
116/// let module = Module::new(&engine, &wasm_bytes)?;
117/// let module_bytes = module.serialize()?;
118///
119/// // ... can save `module_bytes` to disk or other storage ...
120///
121/// // recreate the module from the serialized bytes. For the `unsafe` bits
122/// // see the documentation of `deserialize`.
123/// let module = unsafe { Module::deserialize(&engine, &module_bytes)? };
124/// # Ok(())
125/// # }
126/// ```
127///
128/// [`Config`]: crate::Config
129#[derive(Clone)]
130pub struct Module {
131    inner: Arc<ModuleInner>,
132}
133
134struct ModuleInner {
135    engine: Engine,
136    /// The compiled artifacts for this module that will be instantiated and
137    /// executed.
138    module: CompiledModule,
139
140    /// Runtime information such as the underlying mmap, type information, etc.
141    ///
142    /// Note that this `Arc` is used to share information between compiled
143    /// modules within a component. For bare core wasm modules created with
144    /// `Module::new`, for example, this is a uniquely owned `Arc`.
145    code: Arc<CodeObject>,
146
147    /// A set of initialization images for memories, if any.
148    ///
149    /// Note that this is behind a `OnceCell` to lazily create this image. On
150    /// Linux where `memfd_create` may be used to create the backing memory
151    /// image this is a pretty expensive operation, so by deferring it this
152    /// improves memory usage for modules that are created but may not ever be
153    /// instantiated.
154    memory_images: OnceLock<Option<ModuleMemoryImages>>,
155
156    /// Flag indicating whether this module can be serialized or not.
157    #[cfg(any(feature = "cranelift", feature = "winch"))]
158    serializable: bool,
159
160    /// Runtime offset information for `VMContext`.
161    offsets: VMOffsets<HostPtr>,
162}
163
164impl fmt::Debug for Module {
165    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
166        f.debug_struct("Module")
167            .field("name", &self.name())
168            .finish_non_exhaustive()
169    }
170}
171
172impl fmt::Debug for ModuleInner {
173    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
174        f.debug_struct("ModuleInner")
175            .field("name", &self.module.module().name.as_ref())
176            .finish_non_exhaustive()
177    }
178}
179
180impl Module {
181    /// Creates a new WebAssembly `Module` from the given in-memory `bytes`.
182    ///
183    /// The `bytes` provided must be in one of the following formats:
184    ///
185    /// * A [binary-encoded][binary] WebAssembly module. This is always supported.
186    /// * A [text-encoded][text] instance of the WebAssembly text format.
187    ///   This is only supported when the `wat` feature of this crate is enabled.
188    ///   If this is supplied then the text format will be parsed before validation.
189    ///   Note that the `wat` feature is enabled by default.
190    ///
191    /// The data for the wasm module must be loaded in-memory if it's present
192    /// elsewhere, for example on disk. This requires that the entire binary is
193    /// loaded into memory all at once, this API does not support streaming
194    /// compilation of a module.
195    ///
196    /// The WebAssembly binary will be decoded and validated. It will also be
197    /// compiled according to the configuration of the provided `engine`.
198    ///
199    /// # Errors
200    ///
201    /// This function may fail and return an error. Errors may include
202    /// situations such as:
203    ///
204    /// * The binary provided could not be decoded because it's not a valid
205    ///   WebAssembly binary
206    /// * The WebAssembly binary may not validate (e.g. contains type errors)
207    /// * Implementation-specific limits were exceeded with a valid binary (for
208    ///   example too many locals)
209    /// * The wasm binary may use features that are not enabled in the
210    ///   configuration of `engine`
211    /// * If the `wat` feature is enabled and the input is text, then it may be
212    ///   rejected if it fails to parse.
213    ///
214    /// The error returned should contain full information about why module
215    /// creation failed if one is returned.
216    ///
217    /// [binary]: https://webassembly.github.io/spec/core/binary/index.html
218    /// [text]: https://webassembly.github.io/spec/core/text/index.html
219    ///
220    /// # Examples
221    ///
222    /// The `new` function can be invoked with a in-memory array of bytes:
223    ///
224    /// ```no_run
225    /// # use wasmtime::*;
226    /// # fn main() -> anyhow::Result<()> {
227    /// # let engine = Engine::default();
228    /// # let wasm_bytes: Vec<u8> = Vec::new();
229    /// let module = Module::new(&engine, &wasm_bytes)?;
230    /// # Ok(())
231    /// # }
232    /// ```
233    ///
234    /// Or you can also pass in a string to be parsed as the wasm text
235    /// format:
236    ///
237    /// ```
238    /// # use wasmtime::*;
239    /// # fn main() -> anyhow::Result<()> {
240    /// # let engine = Engine::default();
241    /// let module = Module::new(&engine, "(module (func))")?;
242    /// # Ok(())
243    /// # }
244    /// ```
245    #[cfg(any(feature = "cranelift", feature = "winch"))]
246    pub fn new(engine: &Engine, bytes: impl AsRef<[u8]>) -> Result<Module> {
247        crate::CodeBuilder::new(engine)
248            .wasm_binary_or_text(bytes.as_ref(), None)?
249            .compile_module()
250    }
251
252    /// Creates a new WebAssembly `Module` from the contents of the given
253    /// `file` on disk.
254    ///
255    /// This is a convenience function that will read the `file` provided and
256    /// pass the bytes to the [`Module::new`] function. For more information
257    /// see [`Module::new`]
258    ///
259    /// # Examples
260    ///
261    /// ```no_run
262    /// # use wasmtime::*;
263    /// # fn main() -> anyhow::Result<()> {
264    /// let engine = Engine::default();
265    /// let module = Module::from_file(&engine, "./path/to/foo.wasm")?;
266    /// # Ok(())
267    /// # }
268    /// ```
269    ///
270    /// The `.wat` text format is also supported:
271    ///
272    /// ```no_run
273    /// # use wasmtime::*;
274    /// # fn main() -> anyhow::Result<()> {
275    /// # let engine = Engine::default();
276    /// let module = Module::from_file(&engine, "./path/to/foo.wat")?;
277    /// # Ok(())
278    /// # }
279    /// ```
280    #[cfg(all(feature = "std", any(feature = "cranelift", feature = "winch")))]
281    pub fn from_file(engine: &Engine, file: impl AsRef<Path>) -> Result<Module> {
282        crate::CodeBuilder::new(engine)
283            .wasm_binary_or_text_file(file.as_ref())?
284            .compile_module()
285    }
286
287    /// Creates a new WebAssembly `Module` from the given in-memory `binary`
288    /// data.
289    ///
290    /// This is similar to [`Module::new`] except that it requires that the
291    /// `binary` input is a WebAssembly binary, the text format is not supported
292    /// by this function. It's generally recommended to use [`Module::new`], but
293    /// if it's required to not support the text format this function can be
294    /// used instead.
295    ///
296    /// # Examples
297    ///
298    /// ```
299    /// # use wasmtime::*;
300    /// # fn main() -> anyhow::Result<()> {
301    /// # let engine = Engine::default();
302    /// let wasm = b"\0asm\x01\0\0\0";
303    /// let module = Module::from_binary(&engine, wasm)?;
304    /// # Ok(())
305    /// # }
306    /// ```
307    ///
308    /// Note that the text format is **not** accepted by this function:
309    ///
310    /// ```
311    /// # use wasmtime::*;
312    /// # fn main() -> anyhow::Result<()> {
313    /// # let engine = Engine::default();
314    /// assert!(Module::from_binary(&engine, b"(module)").is_err());
315    /// # Ok(())
316    /// # }
317    /// ```
318    #[cfg(any(feature = "cranelift", feature = "winch"))]
319    pub fn from_binary(engine: &Engine, binary: &[u8]) -> Result<Module> {
320        crate::CodeBuilder::new(engine)
321            .wasm_binary(binary, None)?
322            .compile_module()
323    }
324
325    /// Creates a new WebAssembly `Module` from the contents of the given `file`
326    /// on disk, but with assumptions that the file is from a trusted source.
327    /// The file should be a binary- or text-format WebAssembly module, or a
328    /// precompiled artifact generated by the same version of Wasmtime.
329    ///
330    /// # Unsafety
331    ///
332    /// All of the reasons that [`deserialize`] is `unsafe` apply to this
333    /// function as well. Arbitrary data loaded from a file may trick Wasmtime
334    /// into arbitrary code execution since the contents of the file are not
335    /// validated to be a valid precompiled module.
336    ///
337    /// [`deserialize`]: Module::deserialize
338    ///
339    /// Additionally though this function is also `unsafe` because the file
340    /// referenced must remain unchanged and a valid precompiled module for the
341    /// entire lifetime of the [`Module`] returned. Any changes to the file on
342    /// disk may change future instantiations of the module to be incorrect.
343    /// This is because the file is mapped into memory and lazily loaded pages
344    /// reflect the current state of the file, not necessarily the original
345    /// state of the file.
346    #[cfg(all(feature = "std", any(feature = "cranelift", feature = "winch")))]
347    pub unsafe fn from_trusted_file(engine: &Engine, file: impl AsRef<Path>) -> Result<Module> {
348        let open_file = open_file_for_mmap(file.as_ref())?;
349        let mmap = crate::runtime::vm::MmapVec::from_file(open_file)?;
350        if &mmap[0..4] == b"\x7fELF" {
351            let code = engine.load_code(mmap, ObjectKind::Module)?;
352            return Module::from_parts(engine, code, None);
353        }
354
355        crate::CodeBuilder::new(engine)
356            .wasm_binary_or_text(&mmap[..], Some(file.as_ref()))?
357            .compile_module()
358    }
359
360    /// Deserializes an in-memory compiled module previously created with
361    /// [`Module::serialize`] or [`Engine::precompile_module`].
362    ///
363    /// This function will deserialize the binary blobs emitted by
364    /// [`Module::serialize`] and [`Engine::precompile_module`] back into an
365    /// in-memory [`Module`] that's ready to be instantiated.
366    ///
367    /// Note that the [`Module::deserialize_file`] method is more optimized than
368    /// this function, so if the serialized module is already present in a file
369    /// it's recommended to use that method instead.
370    ///
371    /// # Unsafety
372    ///
373    /// This function is marked as `unsafe` because if fed invalid input or used
374    /// improperly this could lead to memory safety vulnerabilities. This method
375    /// should not, for example, be exposed to arbitrary user input.
376    ///
377    /// The structure of the binary blob read here is only lightly validated
378    /// internally in `wasmtime`. This is intended to be an efficient
379    /// "rehydration" for a [`Module`] which has very few runtime checks beyond
380    /// deserialization. Arbitrary input could, for example, replace valid
381    /// compiled code with any other valid compiled code, meaning that this can
382    /// trivially be used to execute arbitrary code otherwise.
383    ///
384    /// For these reasons this function is `unsafe`. This function is only
385    /// designed to receive the previous input from [`Module::serialize`] and
386    /// [`Engine::precompile_module`]. If the exact output of those functions
387    /// (unmodified) is passed to this function then calls to this function can
388    /// be considered safe. It is the caller's responsibility to provide the
389    /// guarantee that only previously-serialized bytes are being passed in
390    /// here.
391    ///
392    /// Note that this function is designed to be safe receiving output from
393    /// *any* compiled version of `wasmtime` itself. This means that it is safe
394    /// to feed output from older versions of Wasmtime into this function, in
395    /// addition to newer versions of wasmtime (from the future!). These inputs
396    /// will deterministically and safely produce an `Err`. This function only
397    /// successfully accepts inputs from the same version of `wasmtime`, but the
398    /// safety guarantee only applies to externally-defined blobs of bytes, not
399    /// those defined by any version of wasmtime. (this means that if you cache
400    /// blobs across versions of wasmtime you can be safely guaranteed that
401    /// future versions of wasmtime will reject old cache entries).
402    pub unsafe fn deserialize(engine: &Engine, bytes: impl AsRef<[u8]>) -> Result<Module> {
403        let code = engine.load_code_bytes(bytes.as_ref(), ObjectKind::Module)?;
404        Module::from_parts(engine, code, None)
405    }
406
407    /// In-place deserialization of an in-memory compiled module previously
408    /// created with [`Module::serialize`] or [`Engine::precompile_module`].
409    ///
410    /// See [`Self::deserialize`] for additional information; this method
411    /// works identically except that it will not create a copy of the provided
412    /// memory but will use it directly.
413    ///
414    /// # Unsafety
415    ///
416    /// All of the safety notes from [`Self::deserialize`] apply here as well
417    /// with the additional constraint that the code memory provide by `memory`
418    /// lives for as long as the module and is nevery externally modified for
419    /// the lifetime of the deserialized module.
420    pub unsafe fn deserialize_raw(engine: &Engine, memory: NonNull<[u8]>) -> Result<Module> {
421        // SAFETY: the contract required by `load_code_raw` is the same as this
422        // function.
423        let code = unsafe { engine.load_code_raw(memory, ObjectKind::Module)? };
424        Module::from_parts(engine, code, None)
425    }
426
427    /// Same as [`deserialize`], except that the contents of `path` are read to
428    /// deserialize into a [`Module`].
429    ///
430    /// This method is provided because it can be faster than [`deserialize`]
431    /// since the data doesn't need to be copied around, but rather the module
432    /// can be used directly from an mmap'd view of the file provided.
433    ///
434    /// [`deserialize`]: Module::deserialize
435    ///
436    /// # Unsafety
437    ///
438    /// All of the reasons that [`deserialize`] is `unsafe` applies to this
439    /// function as well. Arbitrary data loaded from a file may trick Wasmtime
440    /// into arbitrary code execution since the contents of the file are not
441    /// validated to be a valid precompiled module.
442    ///
443    /// Additionally though this function is also `unsafe` because the file
444    /// referenced must remain unchanged and a valid precompiled module for the
445    /// entire lifetime of the [`Module`] returned. Any changes to the file on
446    /// disk may change future instantiations of the module to be incorrect.
447    /// This is because the file is mapped into memory and lazily loaded pages
448    /// reflect the current state of the file, not necessarily the original
449    /// state of the file.
450    #[cfg(feature = "std")]
451    pub unsafe fn deserialize_file(engine: &Engine, path: impl AsRef<Path>) -> Result<Module> {
452        let file = open_file_for_mmap(path.as_ref())?;
453        // SAFETY: the contract of `deserialize_open_file` is the samea s this
454        // function.
455        unsafe {
456            Self::deserialize_open_file(engine, file)
457                .with_context(|| format!("failed deserialization for: {}", path.as_ref().display()))
458        }
459    }
460
461    /// Same as [`deserialize_file`], except that it takes an open `File`
462    /// instead of a path.
463    ///
464    /// This method is provided because it can be used instead of
465    /// [`deserialize_file`] in situations where `wasmtime` is running with
466    /// limited file system permissions. In that case a process
467    /// with file system access can pass already opened files to `wasmtime`.
468    ///
469    /// [`deserialize_file`]: Module::deserialize_file
470    ///
471    /// Note that the corresponding will be mapped as private writeable
472    /// (copy-on-write) and executable. For `windows` this means the file needs
473    /// to be opened with at least `FILE_GENERIC_READ | FILE_GENERIC_EXECUTE`
474    /// [`access_mode`].
475    ///
476    /// [`access_mode`]: https://doc.rust-lang.org/std/os/windows/fs/trait.OpenOptionsExt.html#tymethod.access_mode
477    ///
478    /// # Unsafety
479    ///
480    /// All of the reasons that [`deserialize_file`] is `unsafe` applies to this
481    /// function as well.
482    #[cfg(feature = "std")]
483    pub unsafe fn deserialize_open_file(engine: &Engine, file: File) -> Result<Module> {
484        let code = engine.load_code_file(file, ObjectKind::Module)?;
485        Module::from_parts(engine, code, None)
486    }
487
488    /// Entrypoint for creating a `Module` for all above functions, both
489    /// of the AOT and jit-compiled categories.
490    ///
491    /// In all cases the compilation artifact, `code_memory`, is provided here.
492    /// The `info_and_types` argument is `None` when a module is being
493    /// deserialized from a precompiled artifact or it's `Some` if it was just
494    /// compiled and the values are already available.
495    pub(crate) fn from_parts(
496        engine: &Engine,
497        code_memory: Arc<CodeMemory>,
498        info_and_types: Option<(CompiledModuleInfo, CompiledFunctionsTable, ModuleTypes)>,
499    ) -> Result<Self> {
500        // Acquire this module's metadata and type information, deserializing
501        // it from the provided artifact if it wasn't otherwise provided
502        // already.
503        let (mut info, index, mut types) = match info_and_types {
504            Some((info, index, types)) => (info, index, types),
505            None => postcard::from_bytes(code_memory.wasmtime_info())?,
506        };
507
508        // Register function type signatures into the engine for the lifetime
509        // of the `Module` that will be returned. This notably also builds up
510        // maps for trampolines to be used for this module when inserted into
511        // stores.
512        //
513        // Note that the unsafety here should be ok since the `trampolines`
514        // field should only point to valid trampoline function pointers
515        // within the text section.
516        let signatures =
517            engine.register_and_canonicalize_types(&mut types, core::iter::once(&mut info.module));
518
519        // Package up all our data into a `CodeObject` and delegate to the final
520        // step of module compilation.
521        let code = Arc::new(CodeObject::new(code_memory, signatures, types.into()));
522        let index = Arc::new(index);
523        Module::from_parts_raw(engine, code, info, index, true)
524    }
525
526    pub(crate) fn from_parts_raw(
527        engine: &Engine,
528        code: Arc<CodeObject>,
529        info: CompiledModuleInfo,
530        index: Arc<CompiledFunctionsTable>,
531        serializable: bool,
532    ) -> Result<Self> {
533        let module = CompiledModule::from_artifacts(
534            code.code_memory().clone(),
535            info,
536            index,
537            engine.profiler(),
538        )?;
539
540        // Validate the module can be used with the current instance allocator.
541        let offsets = VMOffsets::new(HostPtr, module.module());
542        engine
543            .allocator()
544            .validate_module(module.module(), &offsets)?;
545
546        let _ = serializable;
547
548        Ok(Self {
549            inner: Arc::new(ModuleInner {
550                engine: engine.clone(),
551                code,
552                memory_images: OnceLock::new(),
553                module,
554                #[cfg(any(feature = "cranelift", feature = "winch"))]
555                serializable,
556                offsets,
557            }),
558        })
559    }
560
561    /// Validates `binary` input data as a WebAssembly binary given the
562    /// configuration in `engine`.
563    ///
564    /// This function will perform a speedy validation of the `binary` input
565    /// WebAssembly module (which is in [binary form][binary], the text format
566    /// is not accepted by this function) and return either `Ok` or `Err`
567    /// depending on the results of validation. The `engine` argument indicates
568    /// configuration for WebAssembly features, for example, which are used to
569    /// indicate what should be valid and what shouldn't be.
570    ///
571    /// Validation automatically happens as part of [`Module::new`].
572    ///
573    /// # Errors
574    ///
575    /// If validation fails for any reason (type check error, usage of a feature
576    /// that wasn't enabled, etc) then an error with a description of the
577    /// validation issue will be returned.
578    ///
579    /// [binary]: https://webassembly.github.io/spec/core/binary/index.html
580    pub fn validate(engine: &Engine, binary: &[u8]) -> Result<()> {
581        let mut validator = Validator::new_with_features(engine.features());
582
583        let mut functions = Vec::new();
584        for payload in Parser::new(0).parse_all(binary) {
585            let payload = payload?;
586            if let ValidPayload::Func(a, b) = validator.payload(&payload)? {
587                functions.push((a, b));
588            }
589            if let wasmparser::Payload::Version { encoding, .. } = &payload {
590                if let wasmparser::Encoding::Component = encoding {
591                    bail!("component passed to module validation");
592                }
593            }
594        }
595
596        engine.run_maybe_parallel(functions, |(validator, body)| {
597            // FIXME: it would be best here to use a rayon-specific parallel
598            // iterator that maintains state-per-thread to share the function
599            // validator allocations (`Default::default` here) across multiple
600            // functions.
601            validator.into_validator(Default::default()).validate(&body)
602        })?;
603        Ok(())
604    }
605
606    /// Serializes this module to a vector of bytes.
607    ///
608    /// This function is similar to the [`Engine::precompile_module`] method
609    /// where it produces an artifact of Wasmtime which is suitable to later
610    /// pass into [`Module::deserialize`]. If a module is never instantiated
611    /// then it's recommended to use [`Engine::precompile_module`] instead of
612    /// this method, but if a module is both instantiated and serialized then
613    /// this method can be useful to get the serialized version without
614    /// compiling twice.
615    #[cfg(any(feature = "cranelift", feature = "winch"))]
616    pub fn serialize(&self) -> Result<Vec<u8>> {
617        // The current representation of compiled modules within a compiled
618        // component means that it cannot be serialized. The mmap returned here
619        // is the mmap for the entire component and while it contains all
620        // necessary data to deserialize this particular module it's all
621        // embedded within component-specific information.
622        //
623        // It's not the hardest thing in the world to support this but it's
624        // expected that there's not much of a use case at this time. In theory
625        // all that needs to be done is to edit the `.wasmtime.info` section
626        // to contains this module's metadata instead of the metadata for the
627        // whole component. The metadata itself is fairly trivially
628        // recreateable here it's more that there's no easy one-off API for
629        // editing the sections of an ELF object to use here.
630        //
631        // Overall for now this simply always returns an error in this
632        // situation. If you're reading this and feel that the situation should
633        // be different please feel free to open an issue.
634        if !self.inner.serializable {
635            bail!("cannot serialize a module exported from a component");
636        }
637        Ok(self.compiled_module().mmap().to_vec())
638    }
639
640    pub(crate) fn compiled_module(&self) -> &CompiledModule {
641        &self.inner.module
642    }
643
644    pub(crate) fn code_object(&self) -> &Arc<CodeObject> {
645        &self.inner.code
646    }
647
648    pub(crate) fn env_module(&self) -> &Arc<wasmtime_environ::Module> {
649        self.compiled_module().module()
650    }
651
652    pub(crate) fn types(&self) -> &ModuleTypes {
653        self.inner.code.module_types()
654    }
655
656    #[cfg(any(feature = "component-model", feature = "gc-drc"))]
657    pub(crate) fn signatures(&self) -> &crate::type_registry::TypeCollection {
658        self.inner.code.signatures()
659    }
660
661    /// Returns identifier/name that this [`Module`] has. This name
662    /// is used in traps/backtrace details.
663    ///
664    /// Note that most LLVM/clang/Rust-produced modules do not have a name
665    /// associated with them, but other wasm tooling can be used to inject or
666    /// add a name.
667    ///
668    /// # Examples
669    ///
670    /// ```
671    /// # use wasmtime::*;
672    /// # fn main() -> anyhow::Result<()> {
673    /// # let engine = Engine::default();
674    /// let module = Module::new(&engine, "(module $foo)")?;
675    /// assert_eq!(module.name(), Some("foo"));
676    ///
677    /// let module = Module::new(&engine, "(module)")?;
678    /// assert_eq!(module.name(), None);
679    ///
680    /// # Ok(())
681    /// # }
682    /// ```
683    pub fn name(&self) -> Option<&str> {
684        self.compiled_module().module().name.as_deref()
685    }
686
687    /// Returns the list of imports that this [`Module`] has and must be
688    /// satisfied.
689    ///
690    /// This function returns the list of imports that the wasm module has, but
691    /// only the types of each import. The type of each import is used to
692    /// typecheck the [`Instance::new`](crate::Instance::new) method's `imports`
693    /// argument. The arguments to that function must match up 1-to-1 with the
694    /// entries in the array returned here.
695    ///
696    /// The imports returned reflect the order of the imports in the wasm module
697    /// itself, and note that no form of deduplication happens.
698    ///
699    /// # Examples
700    ///
701    /// Modules with no imports return an empty list here:
702    ///
703    /// ```
704    /// # use wasmtime::*;
705    /// # fn main() -> anyhow::Result<()> {
706    /// # let engine = Engine::default();
707    /// let module = Module::new(&engine, "(module)")?;
708    /// assert_eq!(module.imports().len(), 0);
709    /// # Ok(())
710    /// # }
711    /// ```
712    ///
713    /// and modules with imports will have a non-empty list:
714    ///
715    /// ```
716    /// # use wasmtime::*;
717    /// # fn main() -> anyhow::Result<()> {
718    /// # let engine = Engine::default();
719    /// let wat = r#"
720    ///     (module
721    ///         (import "host" "foo" (func))
722    ///     )
723    /// "#;
724    /// let module = Module::new(&engine, wat)?;
725    /// assert_eq!(module.imports().len(), 1);
726    /// let import = module.imports().next().unwrap();
727    /// assert_eq!(import.module(), "host");
728    /// assert_eq!(import.name(), "foo");
729    /// match import.ty() {
730    ///     ExternType::Func(_) => { /* ... */ }
731    ///     _ => panic!("unexpected import type!"),
732    /// }
733    /// # Ok(())
734    /// # }
735    /// ```
736    pub fn imports<'module>(
737        &'module self,
738    ) -> impl ExactSizeIterator<Item = ImportType<'module>> + 'module {
739        let module = self.compiled_module().module();
740        let types = self.types();
741        let engine = self.engine();
742        module
743            .imports()
744            .map(move |(imp_mod, imp_field, ty)| {
745                debug_assert!(ty.is_canonicalized_for_runtime_usage());
746                ImportType::new(imp_mod, imp_field, ty, types, engine)
747            })
748            .collect::<Vec<_>>()
749            .into_iter()
750    }
751
752    /// Returns the list of exports that this [`Module`] has and will be
753    /// available after instantiation.
754    ///
755    /// This function will return the type of each item that will be returned
756    /// from [`Instance::exports`](crate::Instance::exports). Each entry in this
757    /// list corresponds 1-to-1 with that list, and the entries here will
758    /// indicate the name of the export along with the type of the export.
759    ///
760    /// # Examples
761    ///
762    /// Modules might not have any exports:
763    ///
764    /// ```
765    /// # use wasmtime::*;
766    /// # fn main() -> anyhow::Result<()> {
767    /// # let engine = Engine::default();
768    /// let module = Module::new(&engine, "(module)")?;
769    /// assert!(module.exports().next().is_none());
770    /// # Ok(())
771    /// # }
772    /// ```
773    ///
774    /// When the exports are not empty, you can inspect each export:
775    ///
776    /// ```
777    /// # use wasmtime::*;
778    /// # fn main() -> anyhow::Result<()> {
779    /// # let engine = Engine::default();
780    /// let wat = r#"
781    ///     (module
782    ///         (func (export "foo"))
783    ///         (memory (export "memory") 1)
784    ///     )
785    /// "#;
786    /// let module = Module::new(&engine, wat)?;
787    /// assert_eq!(module.exports().len(), 2);
788    ///
789    /// let mut exports = module.exports();
790    /// let foo = exports.next().unwrap();
791    /// assert_eq!(foo.name(), "foo");
792    /// match foo.ty() {
793    ///     ExternType::Func(_) => { /* ... */ }
794    ///     _ => panic!("unexpected export type!"),
795    /// }
796    ///
797    /// let memory = exports.next().unwrap();
798    /// assert_eq!(memory.name(), "memory");
799    /// match memory.ty() {
800    ///     ExternType::Memory(_) => { /* ... */ }
801    ///     _ => panic!("unexpected export type!"),
802    /// }
803    /// # Ok(())
804    /// # }
805    /// ```
806    pub fn exports<'module>(
807        &'module self,
808    ) -> impl ExactSizeIterator<Item = ExportType<'module>> + 'module {
809        let module = self.compiled_module().module();
810        let types = self.types();
811        let engine = self.engine();
812        module.exports.iter().map(move |(name, entity_index)| {
813            ExportType::new(name, module.type_of(*entity_index), types, engine)
814        })
815    }
816
817    /// Looks up an export in this [`Module`] by name.
818    ///
819    /// This function will return the type of an export with the given name.
820    ///
821    /// # Examples
822    ///
823    /// There may be no export with that name:
824    ///
825    /// ```
826    /// # use wasmtime::*;
827    /// # fn main() -> anyhow::Result<()> {
828    /// # let engine = Engine::default();
829    /// let module = Module::new(&engine, "(module)")?;
830    /// assert!(module.get_export("foo").is_none());
831    /// # Ok(())
832    /// # }
833    /// ```
834    ///
835    /// When there is an export with that name, it is returned:
836    ///
837    /// ```
838    /// # use wasmtime::*;
839    /// # fn main() -> anyhow::Result<()> {
840    /// # let engine = Engine::default();
841    /// let wat = r#"
842    ///     (module
843    ///         (func (export "foo"))
844    ///         (memory (export "memory") 1)
845    ///     )
846    /// "#;
847    /// let module = Module::new(&engine, wat)?;
848    /// let foo = module.get_export("foo");
849    /// assert!(foo.is_some());
850    ///
851    /// let foo = foo.unwrap();
852    /// match foo {
853    ///     ExternType::Func(_) => { /* ... */ }
854    ///     _ => panic!("unexpected export type!"),
855    /// }
856    ///
857    /// # Ok(())
858    /// # }
859    /// ```
860    pub fn get_export(&self, name: &str) -> Option<ExternType> {
861        let module = self.compiled_module().module();
862        let entity_index = module.exports.get(name)?;
863        Some(ExternType::from_wasmtime(
864            self.engine(),
865            self.types(),
866            &module.type_of(*entity_index),
867        ))
868    }
869
870    /// Looks up an export in this [`Module`] by name to get its index.
871    ///
872    /// This function will return the index of an export with the given name. This can be useful
873    /// to avoid the cost of looking up the export by name multiple times. Instead the
874    /// [`ModuleExport`] can be stored and used to look up the export on the
875    /// [`Instance`](crate::Instance) later.
876    pub fn get_export_index(&self, name: &str) -> Option<ModuleExport> {
877        let compiled_module = self.compiled_module();
878        let module = compiled_module.module();
879        let entity = *module.exports.get(name)?;
880        Some(ModuleExport {
881            module: self.id(),
882            entity,
883        })
884    }
885
886    /// Returns the [`Engine`] that this [`Module`] was compiled by.
887    pub fn engine(&self) -> &Engine {
888        &self.inner.engine
889    }
890
891    /// Returns a summary of the resources required to instantiate this
892    /// [`Module`].
893    ///
894    /// Potential uses of the returned information:
895    ///
896    /// * Determining whether your pooling allocator configuration supports
897    ///   instantiating this module.
898    ///
899    /// * Deciding how many of which `Module` you want to instantiate within a
900    ///   fixed amount of resources, e.g. determining whether to create 5
901    ///   instances of module X or 10 instances of module Y.
902    ///
903    /// # Example
904    ///
905    /// ```
906    /// # fn main() -> wasmtime::Result<()> {
907    /// use wasmtime::{Config, Engine, Module};
908    ///
909    /// let mut config = Config::new();
910    /// config.wasm_multi_memory(true);
911    /// let engine = Engine::new(&config)?;
912    ///
913    /// let module = Module::new(&engine, r#"
914    ///     (module
915    ///         ;; Import a memory. Doesn't count towards required resources.
916    ///         (import "a" "b" (memory 10))
917    ///         ;; Define two local memories. These count towards the required
918    ///         ;; resources.
919    ///         (memory 1)
920    ///         (memory 6)
921    ///     )
922    /// "#)?;
923    ///
924    /// let resources = module.resources_required();
925    ///
926    /// // Instantiating the module will require allocating two memories, and
927    /// // the maximum initial memory size is six Wasm pages.
928    /// assert_eq!(resources.num_memories, 2);
929    /// assert_eq!(resources.max_initial_memory_size, Some(6));
930    ///
931    /// // The module doesn't need any tables.
932    /// assert_eq!(resources.num_tables, 0);
933    /// assert_eq!(resources.max_initial_table_size, None);
934    /// # Ok(()) }
935    /// ```
936    pub fn resources_required(&self) -> ResourcesRequired {
937        let em = self.env_module();
938        let num_memories = u32::try_from(em.num_defined_memories()).unwrap();
939        let max_initial_memory_size = em
940            .memories
941            .values()
942            .skip(em.num_imported_memories)
943            .map(|memory| memory.limits.min)
944            .max();
945        let num_tables = u32::try_from(em.num_defined_tables()).unwrap();
946        let max_initial_table_size = em
947            .tables
948            .values()
949            .skip(em.num_imported_tables)
950            .map(|table| table.limits.min)
951            .max();
952        ResourcesRequired {
953            num_memories,
954            max_initial_memory_size,
955            num_tables,
956            max_initial_table_size,
957        }
958    }
959
960    /// Returns the range of bytes in memory where this module's compilation
961    /// image resides.
962    ///
963    /// The compilation image for a module contains executable code, data, debug
964    /// information, etc. This is roughly the same as the `Module::serialize`
965    /// but not the exact same.
966    ///
967    /// The range of memory reported here is exposed to allow low-level
968    /// manipulation of the memory in platform-specific manners such as using
969    /// `mlock` to force the contents to be paged in immediately or keep them
970    /// paged in after they're loaded.
971    ///
972    /// It is not safe to modify the memory in this range, nor is it safe to
973    /// modify the protections of memory in this range.
974    pub fn image_range(&self) -> Range<*const u8> {
975        self.compiled_module().mmap().image_range()
976    }
977
978    /// Force initialization of copy-on-write images to happen here-and-now
979    /// instead of when they're requested during first instantiation.
980    ///
981    /// When [copy-on-write memory
982    /// initialization](crate::Config::memory_init_cow) is enabled then Wasmtime
983    /// will lazily create the initialization image for a module. This method
984    /// can be used to explicitly dictate when this initialization happens.
985    ///
986    /// Note that this largely only matters on Linux when memfd is used.
987    /// Otherwise the copy-on-write image typically comes from disk and in that
988    /// situation the creation of the image is trivial as the image is always
989    /// sourced from disk. On Linux, though, when memfd is used a memfd is
990    /// created and the initialization image is written to it.
991    ///
992    /// Also note that this method is not required to be called, it's available
993    /// as a performance optimization if required but is otherwise handled
994    /// automatically.
995    pub fn initialize_copy_on_write_image(&self) -> Result<()> {
996        self.memory_images()?;
997        Ok(())
998    }
999
1000    /// Get the map from `.text` section offsets to Wasm binary offsets for this
1001    /// module.
1002    ///
1003    /// Each entry is a (`.text` section offset, Wasm binary offset) pair.
1004    ///
1005    /// Entries are yielded in order of `.text` section offset.
1006    ///
1007    /// Some entries are missing a Wasm binary offset. This is for code that is
1008    /// not associated with any single location in the Wasm binary, or for when
1009    /// source information was optimized away.
1010    ///
1011    /// Not every module has an address map, since address map generation can be
1012    /// turned off on `Config`.
1013    ///
1014    /// There is not an entry for every `.text` section offset. Every offset
1015    /// after an entry's offset, but before the next entry's offset, is
1016    /// considered to map to the same Wasm binary offset as the original
1017    /// entry. For example, the address map will not contain the following
1018    /// sequence of entries:
1019    ///
1020    /// ```ignore
1021    /// [
1022    ///     // ...
1023    ///     (10, Some(42)),
1024    ///     (11, Some(42)),
1025    ///     (12, Some(42)),
1026    ///     (13, Some(43)),
1027    ///     // ...
1028    /// ]
1029    /// ```
1030    ///
1031    /// Instead, it will drop the entries for offsets `11` and `12` since they
1032    /// are the same as the entry for offset `10`:
1033    ///
1034    /// ```ignore
1035    /// [
1036    ///     // ...
1037    ///     (10, Some(42)),
1038    ///     (13, Some(43)),
1039    ///     // ...
1040    /// ]
1041    /// ```
1042    pub fn address_map<'a>(&'a self) -> Option<impl Iterator<Item = (usize, Option<u32>)> + 'a> {
1043        Some(
1044            wasmtime_environ::iterate_address_map(
1045                self.code_object().code_memory().address_map_data(),
1046            )?
1047            .map(|(offset, file_pos)| (offset as usize, file_pos.file_offset())),
1048        )
1049    }
1050
1051    /// Get this module's code object's `.text` section, containing its compiled
1052    /// executable code.
1053    pub fn text(&self) -> &[u8] {
1054        self.code_object().code_memory().text()
1055    }
1056
1057    /// Get information about functions in this module's `.text` section: their
1058    /// index, name, and offset+length.
1059    ///
1060    /// Results are yielded in a ModuleFunction struct.
1061    pub fn functions<'a>(&'a self) -> impl ExactSizeIterator<Item = ModuleFunction> + 'a {
1062        let module = self.compiled_module();
1063        module.finished_functions().map(|(idx, _)| {
1064            let loc = module.func_loc(idx);
1065            let idx = module.module().func_index(idx);
1066            ModuleFunction {
1067                index: idx,
1068                name: module.func_name(idx).map(|n| n.to_string()),
1069                offset: loc.start as usize,
1070                len: loc.length as usize,
1071            }
1072        })
1073    }
1074
1075    pub(crate) fn id(&self) -> CompiledModuleId {
1076        self.inner.module.unique_id()
1077    }
1078
1079    pub(crate) fn offsets(&self) -> &VMOffsets<HostPtr> {
1080        &self.inner.offsets
1081    }
1082
1083    /// Return the address, in memory, of the trampoline that allows Wasm to
1084    /// call a array function of the given signature.
1085    pub(crate) fn wasm_to_array_trampoline(
1086        &self,
1087        signature: VMSharedTypeIndex,
1088    ) -> Option<NonNull<VMWasmCallFunction>> {
1089        log::trace!("Looking up trampoline for {signature:?}");
1090        let trampoline_shared_ty = self.inner.engine.signatures().trampoline_type(signature);
1091        let trampoline_module_ty = self
1092            .inner
1093            .code
1094            .signatures()
1095            .trampoline_type(trampoline_shared_ty)?;
1096        debug_assert!(
1097            self.inner
1098                .engine
1099                .signatures()
1100                .borrow(
1101                    self.inner
1102                        .code
1103                        .signatures()
1104                        .shared_type(trampoline_module_ty)
1105                        .unwrap()
1106                )
1107                .unwrap()
1108                .unwrap_func()
1109                .is_trampoline_type()
1110        );
1111
1112        let ptr = self
1113            .compiled_module()
1114            .wasm_to_array_trampoline(trampoline_module_ty)
1115            .expect("always have a trampoline for the trampoline type")
1116            .as_ptr()
1117            .cast::<VMWasmCallFunction>()
1118            .cast_mut();
1119        Some(NonNull::new(ptr).unwrap())
1120    }
1121
1122    pub(crate) fn memory_images(&self) -> Result<Option<&ModuleMemoryImages>> {
1123        let images = self
1124            .inner
1125            .memory_images
1126            .get_or_try_init(|| memory_images(&self.inner))?
1127            .as_ref();
1128        Ok(images)
1129    }
1130
1131    /// Lookup the stack map at a program counter value.
1132    #[cfg(feature = "gc")]
1133    pub(crate) fn lookup_stack_map(&self, pc: usize) -> Option<wasmtime_environ::StackMap<'_>> {
1134        let text_offset = u32::try_from(pc - self.inner.module.text().as_ptr() as usize).unwrap();
1135        let info = self.inner.code.code_memory().stack_map_data();
1136        wasmtime_environ::StackMap::lookup(text_offset, info)
1137    }
1138
1139    /// Obtain an exception-table parser on this module's exception metadata.
1140    #[cfg(feature = "gc")]
1141    pub(crate) fn exception_table<'a>(&'a self) -> ExceptionTable<'a> {
1142        ExceptionTable::parse(self.inner.code.code_memory().exception_tables())
1143            .expect("Exception tables were validated on module load")
1144    }
1145}
1146
1147/// Describes a function for a given module.
1148pub struct ModuleFunction {
1149    pub index: wasmtime_environ::FuncIndex,
1150    pub name: Option<String>,
1151    pub offset: usize,
1152    pub len: usize,
1153}
1154
1155impl Drop for ModuleInner {
1156    fn drop(&mut self) {
1157        // When a `Module` is being dropped that means that it's no longer
1158        // present in any `Store` and it's additionally not longer held by any
1159        // embedder. Take this opportunity to purge any lingering instantiations
1160        // within a pooling instance allocator, if applicable.
1161        self.engine
1162            .allocator()
1163            .purge_module(self.module.unique_id());
1164    }
1165}
1166
1167/// Describes the location of an export in a module.
1168#[derive(Copy, Clone)]
1169pub struct ModuleExport {
1170    /// The module that this export is defined in.
1171    pub(crate) module: CompiledModuleId,
1172    /// A raw index into the wasm module.
1173    pub(crate) entity: EntityIndex,
1174}
1175
1176fn _assert_send_sync() {
1177    fn _assert<T: Send + Sync>() {}
1178    _assert::<Module>();
1179}
1180
1181/// Helper method to construct a `ModuleMemoryImages` for an associated
1182/// `CompiledModule`.
1183fn memory_images(inner: &Arc<ModuleInner>) -> Result<Option<ModuleMemoryImages>> {
1184    // If initialization via copy-on-write is explicitly disabled in
1185    // configuration then this path is skipped entirely.
1186    if !inner.engine.tunables().memory_init_cow {
1187        return Ok(None);
1188    }
1189
1190    // ... otherwise logic is delegated to the `ModuleMemoryImages::new`
1191    // constructor.
1192    ModuleMemoryImages::new(
1193        &inner.engine,
1194        inner.module.module(),
1195        inner.code.code_memory(),
1196    )
1197}
1198
1199impl crate::vm::ModuleMemoryImageSource for CodeMemory {
1200    fn wasm_data(&self) -> &[u8] {
1201        <Self>::wasm_data(self)
1202    }
1203
1204    fn mmap(&self) -> Option<&MmapVec> {
1205        Some(<Self>::mmap(self))
1206    }
1207}
1208
1209#[cfg(test)]
1210mod tests {
1211    use crate::{Engine, Module};
1212    use wasmtime_environ::MemoryInitialization;
1213
1214    #[test]
1215    fn cow_on_by_default() {
1216        let engine = Engine::default();
1217        let module = Module::new(
1218            &engine,
1219            r#"
1220                (module
1221                    (memory 1)
1222                    (data (i32.const 100) "abcd")
1223                )
1224            "#,
1225        )
1226        .unwrap();
1227
1228        let init = &module.env_module().memory_initialization;
1229        assert!(matches!(init, MemoryInitialization::Static { .. }));
1230    }
1231}