1 use crate::prelude::*; 2 #[cfg(feature = "std")] 3 use crate::runtime::vm::open_file_for_mmap; 4 use crate::runtime::vm::{CompiledModuleId, MmapVec, ModuleMemoryImages, VMWasmCallFunction}; 5 use crate::sync::OnceLock; 6 use crate::{ 7 Engine, 8 code::CodeObject, 9 code_memory::CodeMemory, 10 instantiate::CompiledModule, 11 resources::ResourcesRequired, 12 types::{ExportType, ExternType, ImportType}, 13 }; 14 use alloc::sync::Arc; 15 use core::fmt; 16 use core::ops::Range; 17 use core::ptr::NonNull; 18 #[cfg(feature = "std")] 19 use std::{fs::File, path::Path}; 20 use wasmparser::{Parser, ValidPayload, Validator}; 21 use wasmtime_environ::{ 22 CompiledModuleInfo, EntityIndex, HostPtr, ModuleTypes, ObjectKind, TypeTrace, VMOffsets, 23 VMSharedTypeIndex, 24 }; 25 mod registry; 26 27 pub 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)] 128 pub struct Module { 129 inner: Arc<ModuleInner>, 130 } 131 132 struct 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 162 impl 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 170 impl 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 178 impl 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 // SAFETY: the contract required by `load_code_raw` is the same as this 420 // function. 421 let code = unsafe { engine.load_code_raw(memory, ObjectKind::Module)? }; 422 Module::from_parts(engine, code, None) 423 } 424 425 /// Same as [`deserialize`], except that the contents of `path` are read to 426 /// deserialize into a [`Module`]. 427 /// 428 /// This method is provided because it can be faster than [`deserialize`] 429 /// since the data doesn't need to be copied around, but rather the module 430 /// can be used directly from an mmap'd view of the file provided. 431 /// 432 /// [`deserialize`]: Module::deserialize 433 /// 434 /// # Unsafety 435 /// 436 /// All of the reasons that [`deserialize`] is `unsafe` applies to this 437 /// function as well. Arbitrary data loaded from a file may trick Wasmtime 438 /// into arbitrary code execution since the contents of the file are not 439 /// validated to be a valid precompiled module. 440 /// 441 /// Additionally though this function is also `unsafe` because the file 442 /// referenced must remain unchanged and a valid precompiled module for the 443 /// entire lifetime of the [`Module`] returned. Any changes to the file on 444 /// disk may change future instantiations of the module to be incorrect. 445 /// This is because the file is mapped into memory and lazily loaded pages 446 /// reflect the current state of the file, not necessarily the original 447 /// state of the file. 448 #[cfg(feature = "std")] 449 pub unsafe fn deserialize_file(engine: &Engine, path: impl AsRef<Path>) -> Result<Module> { 450 let file = open_file_for_mmap(path.as_ref())?; 451 // SAFETY: the contract of `deserialize_open_file` is the samea s this 452 // function. 453 unsafe { 454 Self::deserialize_open_file(engine, file) 455 .with_context(|| format!("failed deserialization for: {}", path.as_ref().display())) 456 } 457 } 458 459 /// Same as [`deserialize_file`], except that it takes an open `File` 460 /// instead of a path. 461 /// 462 /// This method is provided because it can be used instead of 463 /// [`deserialize_file`] in situations where `wasmtime` is running with 464 /// limited file system permissions. In that case a process 465 /// with file system access can pass already opened files to `wasmtime`. 466 /// 467 /// [`deserialize_file`]: Module::deserialize_file 468 /// 469 /// Note that the corresponding will be mapped as private writeable 470 /// (copy-on-write) and executable. For `windows` this means the file needs 471 /// to be opened with at least `FILE_GENERIC_READ | FILE_GENERIC_EXECUTE` 472 /// [`access_mode`]. 473 /// 474 /// [`access_mode`]: https://doc.rust-lang.org/std/os/windows/fs/trait.OpenOptionsExt.html#tymethod.access_mode 475 /// 476 /// # Unsafety 477 /// 478 /// All of the reasons that [`deserialize_file`] is `unsafe` applies to this 479 /// function as well. 480 #[cfg(feature = "std")] 481 pub unsafe fn deserialize_open_file(engine: &Engine, file: File) -> Result<Module> { 482 let code = engine.load_code_file(file, ObjectKind::Module)?; 483 Module::from_parts(engine, code, None) 484 } 485 486 /// Entrypoint for creating a `Module` for all above functions, both 487 /// of the AOT and jit-compiled categories. 488 /// 489 /// In all cases the compilation artifact, `code_memory`, is provided here. 490 /// The `info_and_types` argument is `None` when a module is being 491 /// deserialized from a precompiled artifact or it's `Some` if it was just 492 /// compiled and the values are already available. 493 pub(crate) fn from_parts( 494 engine: &Engine, 495 code_memory: Arc<CodeMemory>, 496 info_and_types: Option<(CompiledModuleInfo, ModuleTypes)>, 497 ) -> Result<Self> { 498 // Acquire this module's metadata and type information, deserializing 499 // it from the provided artifact if it wasn't otherwise provided 500 // already. 501 let (mut info, mut types) = match info_and_types { 502 Some((info, types)) => (info, types), 503 None => postcard::from_bytes(code_memory.wasmtime_info())?, 504 }; 505 506 // Register function type signatures into the engine for the lifetime 507 // of the `Module` that will be returned. This notably also builds up 508 // maps for trampolines to be used for this module when inserted into 509 // stores. 510 // 511 // Note that the unsafety here should be ok since the `trampolines` 512 // field should only point to valid trampoline function pointers 513 // within the text section. 514 let signatures = 515 engine.register_and_canonicalize_types(&mut types, core::iter::once(&mut info.module)); 516 517 // Package up all our data into a `CodeObject` and delegate to the final 518 // step of module compilation. 519 let code = Arc::new(CodeObject::new(code_memory, signatures, types.into())); 520 Module::from_parts_raw(engine, code, info, true) 521 } 522 523 pub(crate) fn from_parts_raw( 524 engine: &Engine, 525 code: Arc<CodeObject>, 526 info: CompiledModuleInfo, 527 serializable: bool, 528 ) -> Result<Self> { 529 let module = 530 CompiledModule::from_artifacts(code.code_memory().clone(), info, engine.profiler())?; 531 532 // Validate the module can be used with the current instance allocator. 533 let offsets = VMOffsets::new(HostPtr, module.module()); 534 engine 535 .allocator() 536 .validate_module(module.module(), &offsets)?; 537 538 let _ = serializable; 539 540 Ok(Self { 541 inner: Arc::new(ModuleInner { 542 engine: engine.clone(), 543 code, 544 memory_images: OnceLock::new(), 545 module, 546 #[cfg(any(feature = "cranelift", feature = "winch"))] 547 serializable, 548 offsets, 549 }), 550 }) 551 } 552 553 /// Validates `binary` input data as a WebAssembly binary given the 554 /// configuration in `engine`. 555 /// 556 /// This function will perform a speedy validation of the `binary` input 557 /// WebAssembly module (which is in [binary form][binary], the text format 558 /// is not accepted by this function) and return either `Ok` or `Err` 559 /// depending on the results of validation. The `engine` argument indicates 560 /// configuration for WebAssembly features, for example, which are used to 561 /// indicate what should be valid and what shouldn't be. 562 /// 563 /// Validation automatically happens as part of [`Module::new`]. 564 /// 565 /// # Errors 566 /// 567 /// If validation fails for any reason (type check error, usage of a feature 568 /// that wasn't enabled, etc) then an error with a description of the 569 /// validation issue will be returned. 570 /// 571 /// [binary]: https://webassembly.github.io/spec/core/binary/index.html 572 pub fn validate(engine: &Engine, binary: &[u8]) -> Result<()> { 573 let mut validator = Validator::new_with_features(engine.features()); 574 575 let mut functions = Vec::new(); 576 for payload in Parser::new(0).parse_all(binary) { 577 let payload = payload?; 578 if let ValidPayload::Func(a, b) = validator.payload(&payload)? { 579 functions.push((a, b)); 580 } 581 if let wasmparser::Payload::Version { encoding, .. } = &payload { 582 if let wasmparser::Encoding::Component = encoding { 583 bail!("component passed to module validation"); 584 } 585 } 586 } 587 588 engine.run_maybe_parallel(functions, |(validator, body)| { 589 // FIXME: it would be best here to use a rayon-specific parallel 590 // iterator that maintains state-per-thread to share the function 591 // validator allocations (`Default::default` here) across multiple 592 // functions. 593 validator.into_validator(Default::default()).validate(&body) 594 })?; 595 Ok(()) 596 } 597 598 /// Serializes this module to a vector of bytes. 599 /// 600 /// This function is similar to the [`Engine::precompile_module`] method 601 /// where it produces an artifact of Wasmtime which is suitable to later 602 /// pass into [`Module::deserialize`]. If a module is never instantiated 603 /// then it's recommended to use [`Engine::precompile_module`] instead of 604 /// this method, but if a module is both instantiated and serialized then 605 /// this method can be useful to get the serialized version without 606 /// compiling twice. 607 #[cfg(any(feature = "cranelift", feature = "winch"))] 608 pub fn serialize(&self) -> Result<Vec<u8>> { 609 // The current representation of compiled modules within a compiled 610 // component means that it cannot be serialized. The mmap returned here 611 // is the mmap for the entire component and while it contains all 612 // necessary data to deserialize this particular module it's all 613 // embedded within component-specific information. 614 // 615 // It's not the hardest thing in the world to support this but it's 616 // expected that there's not much of a use case at this time. In theory 617 // all that needs to be done is to edit the `.wasmtime.info` section 618 // to contains this module's metadata instead of the metadata for the 619 // whole component. The metadata itself is fairly trivially 620 // recreateable here it's more that there's no easy one-off API for 621 // editing the sections of an ELF object to use here. 622 // 623 // Overall for now this simply always returns an error in this 624 // situation. If you're reading this and feel that the situation should 625 // be different please feel free to open an issue. 626 if !self.inner.serializable { 627 bail!("cannot serialize a module exported from a component"); 628 } 629 Ok(self.compiled_module().mmap().to_vec()) 630 } 631 632 pub(crate) fn compiled_module(&self) -> &CompiledModule { 633 &self.inner.module 634 } 635 636 pub(crate) fn code_object(&self) -> &Arc<CodeObject> { 637 &self.inner.code 638 } 639 640 pub(crate) fn env_module(&self) -> &Arc<wasmtime_environ::Module> { 641 self.compiled_module().module() 642 } 643 644 pub(crate) fn types(&self) -> &ModuleTypes { 645 self.inner.code.module_types() 646 } 647 648 #[cfg(any(feature = "component-model", feature = "gc-drc"))] 649 pub(crate) fn signatures(&self) -> &crate::type_registry::TypeCollection { 650 self.inner.code.signatures() 651 } 652 653 /// Returns identifier/name that this [`Module`] has. This name 654 /// is used in traps/backtrace details. 655 /// 656 /// Note that most LLVM/clang/Rust-produced modules do not have a name 657 /// associated with them, but other wasm tooling can be used to inject or 658 /// add a name. 659 /// 660 /// # Examples 661 /// 662 /// ``` 663 /// # use wasmtime::*; 664 /// # fn main() -> anyhow::Result<()> { 665 /// # let engine = Engine::default(); 666 /// let module = Module::new(&engine, "(module $foo)")?; 667 /// assert_eq!(module.name(), Some("foo")); 668 /// 669 /// let module = Module::new(&engine, "(module)")?; 670 /// assert_eq!(module.name(), None); 671 /// 672 /// # Ok(()) 673 /// # } 674 /// ``` 675 pub fn name(&self) -> Option<&str> { 676 self.compiled_module().module().name.as_deref() 677 } 678 679 /// Returns the list of imports that this [`Module`] has and must be 680 /// satisfied. 681 /// 682 /// This function returns the list of imports that the wasm module has, but 683 /// only the types of each import. The type of each import is used to 684 /// typecheck the [`Instance::new`](crate::Instance::new) method's `imports` 685 /// argument. The arguments to that function must match up 1-to-1 with the 686 /// entries in the array returned here. 687 /// 688 /// The imports returned reflect the order of the imports in the wasm module 689 /// itself, and note that no form of deduplication happens. 690 /// 691 /// # Examples 692 /// 693 /// Modules with no imports return an empty list here: 694 /// 695 /// ``` 696 /// # use wasmtime::*; 697 /// # fn main() -> anyhow::Result<()> { 698 /// # let engine = Engine::default(); 699 /// let module = Module::new(&engine, "(module)")?; 700 /// assert_eq!(module.imports().len(), 0); 701 /// # Ok(()) 702 /// # } 703 /// ``` 704 /// 705 /// and modules with imports will have a non-empty list: 706 /// 707 /// ``` 708 /// # use wasmtime::*; 709 /// # fn main() -> anyhow::Result<()> { 710 /// # let engine = Engine::default(); 711 /// let wat = r#" 712 /// (module 713 /// (import "host" "foo" (func)) 714 /// ) 715 /// "#; 716 /// let module = Module::new(&engine, wat)?; 717 /// assert_eq!(module.imports().len(), 1); 718 /// let import = module.imports().next().unwrap(); 719 /// assert_eq!(import.module(), "host"); 720 /// assert_eq!(import.name(), "foo"); 721 /// match import.ty() { 722 /// ExternType::Func(_) => { /* ... */ } 723 /// _ => panic!("unexpected import type!"), 724 /// } 725 /// # Ok(()) 726 /// # } 727 /// ``` 728 pub fn imports<'module>( 729 &'module self, 730 ) -> impl ExactSizeIterator<Item = ImportType<'module>> + 'module { 731 let module = self.compiled_module().module(); 732 let types = self.types(); 733 let engine = self.engine(); 734 module 735 .imports() 736 .map(move |(imp_mod, imp_field, ty)| { 737 debug_assert!(ty.is_canonicalized_for_runtime_usage()); 738 ImportType::new(imp_mod, imp_field, ty, types, engine) 739 }) 740 .collect::<Vec<_>>() 741 .into_iter() 742 } 743 744 /// Returns the list of exports that this [`Module`] has and will be 745 /// available after instantiation. 746 /// 747 /// This function will return the type of each item that will be returned 748 /// from [`Instance::exports`](crate::Instance::exports). Each entry in this 749 /// list corresponds 1-to-1 with that list, and the entries here will 750 /// indicate the name of the export along with the type of the export. 751 /// 752 /// # Examples 753 /// 754 /// Modules might not have any exports: 755 /// 756 /// ``` 757 /// # use wasmtime::*; 758 /// # fn main() -> anyhow::Result<()> { 759 /// # let engine = Engine::default(); 760 /// let module = Module::new(&engine, "(module)")?; 761 /// assert!(module.exports().next().is_none()); 762 /// # Ok(()) 763 /// # } 764 /// ``` 765 /// 766 /// When the exports are not empty, you can inspect each export: 767 /// 768 /// ``` 769 /// # use wasmtime::*; 770 /// # fn main() -> anyhow::Result<()> { 771 /// # let engine = Engine::default(); 772 /// let wat = r#" 773 /// (module 774 /// (func (export "foo")) 775 /// (memory (export "memory") 1) 776 /// ) 777 /// "#; 778 /// let module = Module::new(&engine, wat)?; 779 /// assert_eq!(module.exports().len(), 2); 780 /// 781 /// let mut exports = module.exports(); 782 /// let foo = exports.next().unwrap(); 783 /// assert_eq!(foo.name(), "foo"); 784 /// match foo.ty() { 785 /// ExternType::Func(_) => { /* ... */ } 786 /// _ => panic!("unexpected export type!"), 787 /// } 788 /// 789 /// let memory = exports.next().unwrap(); 790 /// assert_eq!(memory.name(), "memory"); 791 /// match memory.ty() { 792 /// ExternType::Memory(_) => { /* ... */ } 793 /// _ => panic!("unexpected export type!"), 794 /// } 795 /// # Ok(()) 796 /// # } 797 /// ``` 798 pub fn exports<'module>( 799 &'module self, 800 ) -> impl ExactSizeIterator<Item = ExportType<'module>> + 'module { 801 let module = self.compiled_module().module(); 802 let types = self.types(); 803 let engine = self.engine(); 804 module.exports.iter().map(move |(name, entity_index)| { 805 ExportType::new(name, module.type_of(*entity_index), types, engine) 806 }) 807 } 808 809 /// Looks up an export in this [`Module`] by name. 810 /// 811 /// This function will return the type of an export with the given name. 812 /// 813 /// # Examples 814 /// 815 /// There may be no export with that name: 816 /// 817 /// ``` 818 /// # use wasmtime::*; 819 /// # fn main() -> anyhow::Result<()> { 820 /// # let engine = Engine::default(); 821 /// let module = Module::new(&engine, "(module)")?; 822 /// assert!(module.get_export("foo").is_none()); 823 /// # Ok(()) 824 /// # } 825 /// ``` 826 /// 827 /// When there is an export with that name, it is returned: 828 /// 829 /// ``` 830 /// # use wasmtime::*; 831 /// # fn main() -> anyhow::Result<()> { 832 /// # let engine = Engine::default(); 833 /// let wat = r#" 834 /// (module 835 /// (func (export "foo")) 836 /// (memory (export "memory") 1) 837 /// ) 838 /// "#; 839 /// let module = Module::new(&engine, wat)?; 840 /// let foo = module.get_export("foo"); 841 /// assert!(foo.is_some()); 842 /// 843 /// let foo = foo.unwrap(); 844 /// match foo { 845 /// ExternType::Func(_) => { /* ... */ } 846 /// _ => panic!("unexpected export type!"), 847 /// } 848 /// 849 /// # Ok(()) 850 /// # } 851 /// ``` 852 pub fn get_export(&self, name: &str) -> Option<ExternType> { 853 let module = self.compiled_module().module(); 854 let entity_index = module.exports.get(name)?; 855 Some(ExternType::from_wasmtime( 856 self.engine(), 857 self.types(), 858 &module.type_of(*entity_index), 859 )) 860 } 861 862 /// Looks up an export in this [`Module`] by name to get its index. 863 /// 864 /// This function will return the index of an export with the given name. This can be useful 865 /// to avoid the cost of looking up the export by name multiple times. Instead the 866 /// [`ModuleExport`] can be stored and used to look up the export on the 867 /// [`Instance`](crate::Instance) later. 868 pub fn get_export_index(&self, name: &str) -> Option<ModuleExport> { 869 let compiled_module = self.compiled_module(); 870 let module = compiled_module.module(); 871 let entity = *module.exports.get(name)?; 872 Some(ModuleExport { 873 module: self.id(), 874 entity, 875 }) 876 } 877 878 /// Returns the [`Engine`] that this [`Module`] was compiled by. 879 pub fn engine(&self) -> &Engine { 880 &self.inner.engine 881 } 882 883 /// Returns a summary of the resources required to instantiate this 884 /// [`Module`]. 885 /// 886 /// Potential uses of the returned information: 887 /// 888 /// * Determining whether your pooling allocator configuration supports 889 /// instantiating this module. 890 /// 891 /// * Deciding how many of which `Module` you want to instantiate within a 892 /// fixed amount of resources, e.g. determining whether to create 5 893 /// instances of module X or 10 instances of module Y. 894 /// 895 /// # Example 896 /// 897 /// ``` 898 /// # fn main() -> wasmtime::Result<()> { 899 /// use wasmtime::{Config, Engine, Module}; 900 /// 901 /// let mut config = Config::new(); 902 /// config.wasm_multi_memory(true); 903 /// let engine = Engine::new(&config)?; 904 /// 905 /// let module = Module::new(&engine, r#" 906 /// (module 907 /// ;; Import a memory. Doesn't count towards required resources. 908 /// (import "a" "b" (memory 10)) 909 /// ;; Define two local memories. These count towards the required 910 /// ;; resources. 911 /// (memory 1) 912 /// (memory 6) 913 /// ) 914 /// "#)?; 915 /// 916 /// let resources = module.resources_required(); 917 /// 918 /// // Instantiating the module will require allocating two memories, and 919 /// // the maximum initial memory size is six Wasm pages. 920 /// assert_eq!(resources.num_memories, 2); 921 /// assert_eq!(resources.max_initial_memory_size, Some(6)); 922 /// 923 /// // The module doesn't need any tables. 924 /// assert_eq!(resources.num_tables, 0); 925 /// assert_eq!(resources.max_initial_table_size, None); 926 /// # Ok(()) } 927 /// ``` 928 pub fn resources_required(&self) -> ResourcesRequired { 929 let em = self.env_module(); 930 let num_memories = u32::try_from(em.num_defined_memories()).unwrap(); 931 let max_initial_memory_size = em 932 .memories 933 .values() 934 .skip(em.num_imported_memories) 935 .map(|memory| memory.limits.min) 936 .max(); 937 let num_tables = u32::try_from(em.num_defined_tables()).unwrap(); 938 let max_initial_table_size = em 939 .tables 940 .values() 941 .skip(em.num_imported_tables) 942 .map(|table| table.limits.min) 943 .max(); 944 ResourcesRequired { 945 num_memories, 946 max_initial_memory_size, 947 num_tables, 948 max_initial_table_size, 949 } 950 } 951 952 /// Returns the range of bytes in memory where this module's compilation 953 /// image resides. 954 /// 955 /// The compilation image for a module contains executable code, data, debug 956 /// information, etc. This is roughly the same as the `Module::serialize` 957 /// but not the exact same. 958 /// 959 /// The range of memory reported here is exposed to allow low-level 960 /// manipulation of the memory in platform-specific manners such as using 961 /// `mlock` to force the contents to be paged in immediately or keep them 962 /// paged in after they're loaded. 963 /// 964 /// It is not safe to modify the memory in this range, nor is it safe to 965 /// modify the protections of memory in this range. 966 pub fn image_range(&self) -> Range<*const u8> { 967 self.compiled_module().mmap().image_range() 968 } 969 970 /// Force initialization of copy-on-write images to happen here-and-now 971 /// instead of when they're requested during first instantiation. 972 /// 973 /// When [copy-on-write memory 974 /// initialization](crate::Config::memory_init_cow) is enabled then Wasmtime 975 /// will lazily create the initialization image for a module. This method 976 /// can be used to explicitly dictate when this initialization happens. 977 /// 978 /// Note that this largely only matters on Linux when memfd is used. 979 /// Otherwise the copy-on-write image typically comes from disk and in that 980 /// situation the creation of the image is trivial as the image is always 981 /// sourced from disk. On Linux, though, when memfd is used a memfd is 982 /// created and the initialization image is written to it. 983 /// 984 /// Also note that this method is not required to be called, it's available 985 /// as a performance optimization if required but is otherwise handled 986 /// automatically. 987 pub fn initialize_copy_on_write_image(&self) -> Result<()> { 988 self.memory_images()?; 989 Ok(()) 990 } 991 992 /// Get the map from `.text` section offsets to Wasm binary offsets for this 993 /// module. 994 /// 995 /// Each entry is a (`.text` section offset, Wasm binary offset) pair. 996 /// 997 /// Entries are yielded in order of `.text` section offset. 998 /// 999 /// Some entries are missing a Wasm binary offset. This is for code that is 1000 /// not associated with any single location in the Wasm binary, or for when 1001 /// source information was optimized away. 1002 /// 1003 /// Not every module has an address map, since address map generation can be 1004 /// turned off on `Config`. 1005 /// 1006 /// There is not an entry for every `.text` section offset. Every offset 1007 /// after an entry's offset, but before the next entry's offset, is 1008 /// considered to map to the same Wasm binary offset as the original 1009 /// entry. For example, the address map will not contain the following 1010 /// sequence of entries: 1011 /// 1012 /// ```ignore 1013 /// [ 1014 /// // ... 1015 /// (10, Some(42)), 1016 /// (11, Some(42)), 1017 /// (12, Some(42)), 1018 /// (13, Some(43)), 1019 /// // ... 1020 /// ] 1021 /// ``` 1022 /// 1023 /// Instead, it will drop the entries for offsets `11` and `12` since they 1024 /// are the same as the entry for offset `10`: 1025 /// 1026 /// ```ignore 1027 /// [ 1028 /// // ... 1029 /// (10, Some(42)), 1030 /// (13, Some(43)), 1031 /// // ... 1032 /// ] 1033 /// ``` 1034 pub fn address_map<'a>(&'a self) -> Option<impl Iterator<Item = (usize, Option<u32>)> + 'a> { 1035 Some( 1036 wasmtime_environ::iterate_address_map( 1037 self.code_object().code_memory().address_map_data(), 1038 )? 1039 .map(|(offset, file_pos)| (offset as usize, file_pos.file_offset())), 1040 ) 1041 } 1042 1043 /// Get this module's code object's `.text` section, containing its compiled 1044 /// executable code. 1045 pub fn text(&self) -> &[u8] { 1046 self.code_object().code_memory().text() 1047 } 1048 1049 /// Get information about functions in this module's `.text` section: their 1050 /// index, name, and offset+length. 1051 /// 1052 /// Results are yielded in a ModuleFunction struct. 1053 pub fn functions<'a>(&'a self) -> impl ExactSizeIterator<Item = ModuleFunction> + 'a { 1054 let module = self.compiled_module(); 1055 module.finished_functions().map(|(idx, _)| { 1056 let loc = module.func_loc(idx); 1057 let idx = module.module().func_index(idx); 1058 ModuleFunction { 1059 index: idx, 1060 name: module.func_name(idx).map(|n| n.to_string()), 1061 offset: loc.start as usize, 1062 len: loc.length as usize, 1063 } 1064 }) 1065 } 1066 1067 pub(crate) fn id(&self) -> CompiledModuleId { 1068 self.inner.module.unique_id() 1069 } 1070 1071 pub(crate) fn offsets(&self) -> &VMOffsets<HostPtr> { 1072 &self.inner.offsets 1073 } 1074 1075 /// Return the address, in memory, of the trampoline that allows Wasm to 1076 /// call a array function of the given signature. 1077 pub(crate) fn wasm_to_array_trampoline( 1078 &self, 1079 signature: VMSharedTypeIndex, 1080 ) -> Option<NonNull<VMWasmCallFunction>> { 1081 log::trace!("Looking up trampoline for {signature:?}"); 1082 let trampoline_shared_ty = self.inner.engine.signatures().trampoline_type(signature); 1083 let trampoline_module_ty = self 1084 .inner 1085 .code 1086 .signatures() 1087 .trampoline_type(trampoline_shared_ty)?; 1088 debug_assert!( 1089 self.inner 1090 .engine 1091 .signatures() 1092 .borrow( 1093 self.inner 1094 .code 1095 .signatures() 1096 .shared_type(trampoline_module_ty) 1097 .unwrap() 1098 ) 1099 .unwrap() 1100 .unwrap_func() 1101 .is_trampoline_type() 1102 ); 1103 1104 let ptr = self 1105 .compiled_module() 1106 .wasm_to_array_trampoline(trampoline_module_ty) 1107 .as_ptr() 1108 .cast::<VMWasmCallFunction>() 1109 .cast_mut(); 1110 Some(NonNull::new(ptr).unwrap()) 1111 } 1112 1113 pub(crate) fn memory_images(&self) -> Result<Option<&ModuleMemoryImages>> { 1114 let images = self 1115 .inner 1116 .memory_images 1117 .get_or_try_init(|| memory_images(&self.inner))? 1118 .as_ref(); 1119 Ok(images) 1120 } 1121 1122 /// Lookup the stack map at a program counter value. 1123 #[cfg(feature = "gc")] 1124 pub(crate) fn lookup_stack_map(&self, pc: usize) -> Option<wasmtime_environ::StackMap<'_>> { 1125 let text_offset = u32::try_from(pc - self.inner.module.text().as_ptr() as usize).unwrap(); 1126 let info = self.inner.code.code_memory().stack_map_data(); 1127 wasmtime_environ::StackMap::lookup(text_offset, info) 1128 } 1129 } 1130 1131 /// Describes a function for a given module. 1132 pub struct ModuleFunction { 1133 pub index: wasmtime_environ::FuncIndex, 1134 pub name: Option<String>, 1135 pub offset: usize, 1136 pub len: usize, 1137 } 1138 1139 impl Drop for ModuleInner { 1140 fn drop(&mut self) { 1141 // When a `Module` is being dropped that means that it's no longer 1142 // present in any `Store` and it's additionally not longer held by any 1143 // embedder. Take this opportunity to purge any lingering instantiations 1144 // within a pooling instance allocator, if applicable. 1145 self.engine 1146 .allocator() 1147 .purge_module(self.module.unique_id()); 1148 } 1149 } 1150 1151 /// Describes the location of an export in a module. 1152 #[derive(Copy, Clone)] 1153 pub struct ModuleExport { 1154 /// The module that this export is defined in. 1155 pub(crate) module: CompiledModuleId, 1156 /// A raw index into the wasm module. 1157 pub(crate) entity: EntityIndex, 1158 } 1159 1160 fn _assert_send_sync() { 1161 fn _assert<T: Send + Sync>() {} 1162 _assert::<Module>(); 1163 } 1164 1165 /// Helper method to construct a `ModuleMemoryImages` for an associated 1166 /// `CompiledModule`. 1167 fn memory_images(inner: &Arc<ModuleInner>) -> Result<Option<ModuleMemoryImages>> { 1168 // If initialization via copy-on-write is explicitly disabled in 1169 // configuration then this path is skipped entirely. 1170 if !inner.engine.tunables().memory_init_cow { 1171 return Ok(None); 1172 } 1173 1174 // ... otherwise logic is delegated to the `ModuleMemoryImages::new` 1175 // constructor. 1176 ModuleMemoryImages::new( 1177 &inner.engine, 1178 inner.module.module(), 1179 inner.code.code_memory(), 1180 ) 1181 } 1182 1183 impl crate::vm::ModuleMemoryImageSource for CodeMemory { 1184 fn wasm_data(&self) -> &[u8] { 1185 <Self>::wasm_data(self) 1186 } 1187 1188 fn mmap(&self) -> Option<&MmapVec> { 1189 Some(<Self>::mmap(self)) 1190 } 1191 } 1192 1193 #[cfg(test)] 1194 mod tests { 1195 use crate::{Engine, Module}; 1196 use wasmtime_environ::MemoryInitialization; 1197 1198 #[test] 1199 fn cow_on_by_default() { 1200 let engine = Engine::default(); 1201 let module = Module::new( 1202 &engine, 1203 r#" 1204 (module 1205 (memory 1) 1206 (data (i32.const 100) "abcd") 1207 ) 1208 "#, 1209 ) 1210 .unwrap(); 1211 1212 let init = &module.env_module().memory_initialization; 1213 assert!(matches!(init, MemoryInitialization::Static { .. })); 1214 } 1215 } 1216