wasmtime/runtime/
module.rs

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