wasmtime_environ/component/translate/adapt.rs
1//! Identification and creation of fused adapter modules in Wasmtime.
2//!
3//! A major piece of the component model is the ability for core wasm modules to
4//! talk to each other through the use of lifted and lowered functions. For
5//! example one core wasm module can export a function which is lifted. Another
6//! component could import that lifted function, lower it, and pass it as the
7//! import to another core wasm module. This is what Wasmtime calls "adapter
8//! fusion" where two core wasm functions are coming together through the
9//! component model.
10//!
11//! There are a few ingredients during adapter fusion:
12//!
13//! * A core wasm function which is "lifted".
14//! * A "lift type" which is the type that the component model function had in
15//! the original component
16//! * A "lower type" which is the type that the component model function has
17//! in the destination component (the one the uses `canon lower`)
18//! * Configuration options for both the lift and the lower operations such as
19//! memories, reallocs, etc.
20//!
21//! With these ingredients combined Wasmtime must produce a function which
22//! connects the two components through the options specified. The fused adapter
23//! performs tasks such as validation of passed values, copying data between
24//! linear memories, etc.
25//!
26//! Wasmtime's current implementation of fused adapters is designed to reduce
27//! complexity elsewhere as much as possible while also being suitable for being
28//! used as a polyfill for the component model in JS environments as well. To
29//! that end Wasmtime implements a fused adapter with another wasm module that
30//! it itself generates on the fly. The usage of WebAssembly for fused adapters
31//! has a number of advantages:
32//!
33//! * There is no need to create a raw Cranelift-based compiler. This is where
34//! majority of "unsafety" lives in Wasmtime so reducing the need to lean on
35//! this or audit another compiler is predicted to weed out a whole class of
36//! bugs in the fused adapter compiler.
37//!
38//! * As mentioned above generation of WebAssembly modules means that this is
39//! suitable for use in JS environments. For example a hypothetical tool which
40//! polyfills a component onto the web today would need to do something for
41//! adapter modules, and ideally the adapters themselves are speedy. While
42//! this could all be written in JS the adapting process is quite nontrivial
43//! so sharing code with Wasmtime would be ideal.
44//!
45//! * Using WebAssembly insulates the implementation to bugs to a certain
46//! degree. While logic bugs are still possible it should be much more
47//! difficult to have segfaults or things like that. With adapters exclusively
48//! executing inside a WebAssembly sandbox like everything else the failure
49//! modes to the host at least should be minimized.
50//!
51//! * Integration into the runtime is relatively simple, the adapter modules are
52//! just another kind of wasm module to instantiate and wire up at runtime.
53//! The goal is that the `GlobalInitializer` list that is processed at runtime
54//! will have all of its `Adapter`-using variants erased by the time it makes
55//! its way all the way up to Wasmtime. This means that the support in
56//! Wasmtime prior to adapter modules is actually the same as the support
57//! after adapter modules are added, keeping the runtime fiddly bits quite
58//! minimal.
59//!
60//! This isn't to say that this approach isn't without its disadvantages of
61//! course. For now though this seems to be a reasonable set of tradeoffs for
62//! the development stage of the component model proposal.
63//!
64//! ## Creating adapter modules
65//!
66//! With WebAssembly itself being used to implement fused adapters, Wasmtime
67//! still has the question of how to organize the adapter functions into actual
68//! wasm modules.
69//!
70//! The first thing you might reach for is to put all the adapters into the same
71//! wasm module. This cannot be done, however, because some adapters may depend
72//! on other adapters (transitively) to be created. This means that if
73//! everything were in the same module there would be no way to instantiate the
74//! module. An example of this dependency is an adapter (A) used to create a
75//! core wasm instance (M) whose exported memory is then referenced by another
76//! adapter (B). In this situation the adapter B cannot be in the same module
77//! as adapter A because B needs the memory of M but M is created with A which
78//! would otherwise create a circular dependency.
79//!
80//! The second possibility of organizing adapter modules would be to place each
81//! fused adapter into its own module. Each `canon lower` would effectively
82//! become a core wasm module instantiation at that point. While this works it's
83//! currently believed to be a bit too fine-grained. For example it would mean
84//! that importing a dozen lowered functions into a module could possibly result
85//! in up to a dozen different adapter modules. While this possibility could
86//! work it has been ruled out as "probably too expensive at runtime".
87//!
88//! Thus the purpose and existence of this module is now evident -- this module
89//! exists to identify what exactly goes into which adapter module. This will
90//! evaluate the `GlobalInitializer` lists coming out of the `inline` pass and
91//! insert `InstantiateModule` entries for where adapter modules should be
92//! created.
93//!
94//! ## Partitioning adapter modules
95//!
96//! Currently this module does not attempt to be really all that fancy about
97//! grouping adapters into adapter modules. The main idea is that most items
98//! within an adapter module are likely to be close together since they're
99//! theoretically going to be used for an instantiation of a core wasm module
100//! just after the fused adapter was declared. With that in mind the current
101//! algorithm is a one-pass approach to partitioning everything into adapter
102//! modules.
103//!
104//! Adapters were identified in-order as part of the inlining phase of
105//! translation where we're guaranteed that once an adapter is identified
106//! it can't depend on anything identified later. The pass implemented here is
107//! to visit all transitive dependencies of an adapter. If one of the
108//! dependencies of an adapter is an adapter in the current adapter module
109//! being built then the current module is finished and a new adapter module is
110//! started. This should quickly partition adapters into contiugous chunks of
111//! their index space which can be in adapter modules together.
112//!
113//! There's probably more general algorithms for this but for now this should be
114//! fast enough as it's "just" a linear pass. As we get more components over
115//! time this may want to be revisited if too many adapter modules are being
116//! created.
117
118use crate::EntityType;
119use crate::component::translate::*;
120use crate::fact;
121use std::collections::HashSet;
122
123/// Metadata information about a fused adapter.
124#[derive(Debug, Clone, Hash, Eq, PartialEq)]
125pub struct Adapter {
126 /// The type used when the original core wasm function was lifted.
127 ///
128 /// Note that this could be different than `lower_ty` (but still matches
129 /// according to subtyping rules).
130 pub lift_ty: TypeFuncIndex,
131 /// Canonical ABI options used when the function was lifted.
132 pub lift_options: AdapterOptions,
133 /// The type used when the function was lowered back into a core wasm
134 /// function.
135 ///
136 /// Note that this could be different than `lift_ty` (but still matches
137 /// according to subtyping rules).
138 pub lower_ty: TypeFuncIndex,
139 /// Canonical ABI options used when the function was lowered.
140 pub lower_options: AdapterOptions,
141 /// The original core wasm function which was lifted.
142 pub func: dfg::CoreDef,
143}
144
145/// The data model for objects that are not unboxed in locals.
146#[derive(Debug, Clone, Hash, Eq, PartialEq)]
147pub enum DataModel {
148 /// Data is stored in GC objects.
149 Gc {},
150
151 /// Data is stored in a linear memory.
152 LinearMemory {
153 /// An optional memory definition supplied.
154 memory: Option<dfg::CoreExport<MemoryIndex>>,
155 /// If `memory` is specified, whether it's a 64-bit memory.
156 memory64: bool,
157 /// An optional definition of `realloc` to used.
158 realloc: Option<dfg::CoreDef>,
159 },
160}
161
162/// Configuration options which can be specified as part of the canonical ABI
163/// in the component model.
164#[derive(Debug, Clone, Hash, Eq, PartialEq)]
165pub struct AdapterOptions {
166 /// The Wasmtime-assigned component instance index where the options were
167 /// originally specified.
168 pub instance: RuntimeComponentInstanceIndex,
169 /// How strings are encoded.
170 pub string_encoding: StringEncoding,
171 /// The async callback function used by these options, if specified.
172 pub callback: Option<dfg::CoreDef>,
173 /// An optional definition of a `post-return` to use.
174 pub post_return: Option<dfg::CoreDef>,
175 /// Whether to use the async ABI for lifting or lowering.
176 pub async_: bool,
177 /// The core function type that is being lifted from / lowered to.
178 pub core_type: ModuleInternedTypeIndex,
179 /// The data model used by this adapter: linear memory or GC objects.
180 pub data_model: DataModel,
181}
182
183impl<'data> Translator<'_, 'data> {
184 /// This is the entrypoint of functionality within this module which
185 /// performs all the work of identifying adapter usages and organizing
186 /// everything into adapter modules.
187 ///
188 /// This will mutate the provided `component` in-place and fill out the dfg
189 /// metadata for adapter modules.
190 pub(super) fn partition_adapter_modules(&mut self, component: &mut dfg::ComponentDfg) {
191 // Visit each adapter, in order of its original definition, during the
192 // partitioning. This allows for the guarantee that dependencies are
193 // visited in a topological fashion ideally.
194 let mut state = PartitionAdapterModules::default();
195 for (id, adapter) in component.adapters.iter() {
196 state.adapter(component, id, adapter);
197 }
198 state.finish_adapter_module();
199
200 // Now that all adapters have been partitioned into modules this loop
201 // generates a core wasm module for each adapter module, translates
202 // the module using standard core wasm translation, and then fills out
203 // the dfg metadata for each adapter.
204 for (module_id, adapter_module) in state.adapter_modules.iter() {
205 let mut module =
206 fact::Module::new(self.types.types(), self.tunables.debug_adapter_modules);
207 let mut names = Vec::with_capacity(adapter_module.adapters.len());
208 for adapter in adapter_module.adapters.iter() {
209 let name = format!("adapter{}", adapter.as_u32());
210 module.adapt(&name, &component.adapters[*adapter]);
211 names.push(name);
212 }
213 let wasm = module.encode();
214 let imports = module.imports().to_vec();
215
216 // Extend the lifetime of the owned `wasm: Vec<u8>` on the stack to
217 // a higher scope defined by our original caller. That allows to
218 // transform `wasm` into `&'data [u8]` which is much easier to work
219 // with here.
220 let wasm = &*self.scope_vec.push(wasm);
221 if log::log_enabled!(log::Level::Trace) {
222 match wasmprinter::print_bytes(wasm) {
223 Ok(s) => log::trace!("generated adapter module:\n{}", s),
224 Err(e) => log::trace!("failed to print adapter module: {}", e),
225 }
226 }
227
228 // With the wasm binary this is then pushed through general
229 // translation, validation, etc. Note that multi-memory is
230 // specifically enabled here since the adapter module is highly
231 // likely to use that if anything is actually indirected through
232 // memory.
233 self.validator.reset();
234 let translation = ModuleEnvironment::new(
235 self.tunables,
236 &mut self.validator,
237 self.types.module_types_builder(),
238 )
239 .translate(Parser::new(0), wasm)
240 .expect("invalid adapter module generated");
241
242 // Record, for each adapter in this adapter module, the module that
243 // the adapter was placed within as well as the function index of
244 // the adapter in the wasm module generated. Note that adapters are
245 // paritioned in-order so we're guaranteed to push the adapters
246 // in-order here as well. (with an assert to double-check)
247 for (adapter, name) in adapter_module.adapters.iter().zip(&names) {
248 let index = translation.module.exports[name];
249 let i = component.adapter_partitionings.push((module_id, index));
250 assert_eq!(i, *adapter);
251 }
252
253 // Finally the metadata necessary to instantiate this adapter
254 // module is also recorded in the dfg. This metadata will be used
255 // to generate `GlobalInitializer` entries during the linearization
256 // final phase.
257 assert_eq!(imports.len(), translation.module.imports().len());
258 let args = imports
259 .iter()
260 .zip(translation.module.imports())
261 .map(|(arg, (_, _, ty))| fact_import_to_core_def(component, arg, ty))
262 .collect::<Vec<_>>();
263 let static_index = self.static_modules.push(translation);
264 let id = component.adapter_modules.push((static_index, args));
265 assert_eq!(id, module_id);
266 }
267 }
268}
269
270fn fact_import_to_core_def(
271 dfg: &mut dfg::ComponentDfg,
272 import: &fact::Import,
273 ty: EntityType,
274) -> dfg::CoreDef {
275 fn unwrap_memory(def: &dfg::CoreDef) -> dfg::CoreExport<MemoryIndex> {
276 match def {
277 dfg::CoreDef::Export(e) => e.clone().map_index(|i| match i {
278 EntityIndex::Memory(i) => i,
279 _ => unreachable!(),
280 }),
281 _ => unreachable!(),
282 }
283 }
284
285 let mut simple_intrinsic = |trampoline: dfg::Trampoline| {
286 let signature = ty.unwrap_func();
287 let index = dfg
288 .trampolines
289 .push((signature.unwrap_module_type_index(), trampoline));
290 dfg::CoreDef::Trampoline(index)
291 };
292 match import {
293 fact::Import::CoreDef(def) => def.clone(),
294 fact::Import::Transcode {
295 op,
296 from,
297 from64,
298 to,
299 to64,
300 } => {
301 let from = dfg.memories.push(unwrap_memory(from));
302 let to = dfg.memories.push(unwrap_memory(to));
303 let signature = ty.unwrap_func();
304 let index = dfg.trampolines.push((
305 signature.unwrap_module_type_index(),
306 dfg::Trampoline::Transcoder {
307 op: *op,
308 from,
309 from64: *from64,
310 to,
311 to64: *to64,
312 },
313 ));
314 dfg::CoreDef::Trampoline(index)
315 }
316 fact::Import::ResourceTransferOwn => simple_intrinsic(dfg::Trampoline::ResourceTransferOwn),
317 fact::Import::ResourceTransferBorrow => {
318 simple_intrinsic(dfg::Trampoline::ResourceTransferBorrow)
319 }
320 fact::Import::ResourceEnterCall => simple_intrinsic(dfg::Trampoline::ResourceEnterCall),
321 fact::Import::ResourceExitCall => simple_intrinsic(dfg::Trampoline::ResourceExitCall),
322 fact::Import::PrepareCall { memory } => simple_intrinsic(dfg::Trampoline::PrepareCall {
323 memory: memory.as_ref().map(|v| dfg.memories.push(unwrap_memory(v))),
324 }),
325 fact::Import::SyncStartCall { callback } => {
326 simple_intrinsic(dfg::Trampoline::SyncStartCall {
327 callback: callback.clone().map(|v| dfg.callbacks.push(v)),
328 })
329 }
330 fact::Import::AsyncStartCall {
331 callback,
332 post_return,
333 } => simple_intrinsic(dfg::Trampoline::AsyncStartCall {
334 callback: callback.clone().map(|v| dfg.callbacks.push(v)),
335 post_return: post_return.clone().map(|v| dfg.post_returns.push(v)),
336 }),
337 fact::Import::FutureTransfer => simple_intrinsic(dfg::Trampoline::FutureTransfer),
338 fact::Import::StreamTransfer => simple_intrinsic(dfg::Trampoline::StreamTransfer),
339 fact::Import::ErrorContextTransfer => {
340 simple_intrinsic(dfg::Trampoline::ErrorContextTransfer)
341 }
342 }
343}
344
345#[derive(Default)]
346struct PartitionAdapterModules {
347 /// The next adapter module that's being created. This may be empty.
348 next_module: AdapterModuleInProgress,
349
350 /// The set of items which are known to be defined which the adapter module
351 /// in progress is allowed to depend on.
352 defined_items: HashSet<Def>,
353
354 /// Finished adapter modules that won't be added to.
355 ///
356 /// In theory items could be added to preexisting modules here but to keep
357 /// this pass linear this is never modified after insertion.
358 adapter_modules: PrimaryMap<dfg::AdapterModuleId, AdapterModuleInProgress>,
359}
360
361#[derive(Default)]
362struct AdapterModuleInProgress {
363 /// The adapters which have been placed into this module.
364 adapters: Vec<dfg::AdapterId>,
365}
366
367/// Items that adapters can depend on.
368///
369/// Note that this is somewhat of a flat list and is intended to mostly model
370/// core wasm instances which are side-effectful unlike other host items like
371/// lowerings or always-trapping functions.
372#[derive(Copy, Clone, Hash, Eq, PartialEq)]
373enum Def {
374 Adapter(dfg::AdapterId),
375 Instance(dfg::InstanceId),
376}
377
378impl PartitionAdapterModules {
379 fn adapter(&mut self, dfg: &dfg::ComponentDfg, id: dfg::AdapterId, adapter: &Adapter) {
380 // Visit all dependencies of this adapter and if anything depends on
381 // the current adapter module in progress then a new adapter module is
382 // started.
383 self.adapter_options(dfg, &adapter.lift_options);
384 self.adapter_options(dfg, &adapter.lower_options);
385 self.core_def(dfg, &adapter.func);
386
387 // With all dependencies visited this adapter is added to the next
388 // module.
389 //
390 // This will either get added the preexisting module if this adapter
391 // didn't depend on anything in that module itself or it will be added
392 // to a fresh module if this adapter depended on something that the
393 // current adapter module created.
394 log::debug!("adding {id:?} to adapter module");
395 self.next_module.adapters.push(id);
396 }
397
398 fn adapter_options(&mut self, dfg: &dfg::ComponentDfg, options: &AdapterOptions) {
399 if let Some(def) = &options.callback {
400 self.core_def(dfg, def);
401 }
402 if let Some(def) = &options.post_return {
403 self.core_def(dfg, def);
404 }
405 match &options.data_model {
406 DataModel::Gc {} => {
407 // Nothing to do here yet.
408 }
409 DataModel::LinearMemory {
410 memory,
411 memory64: _,
412 realloc,
413 } => {
414 if let Some(memory) = memory {
415 self.core_export(dfg, memory);
416 }
417 if let Some(def) = realloc {
418 self.core_def(dfg, def);
419 }
420 }
421 }
422 }
423
424 fn core_def(&mut self, dfg: &dfg::ComponentDfg, def: &dfg::CoreDef) {
425 match def {
426 dfg::CoreDef::Export(e) => self.core_export(dfg, e),
427 dfg::CoreDef::Adapter(id) => {
428 // If this adapter is already defined then we can safely depend
429 // on it with no consequences.
430 if self.defined_items.contains(&Def::Adapter(*id)) {
431 log::debug!("using existing adapter {id:?} ");
432 return;
433 }
434
435 log::debug!("splitting module needing {id:?} ");
436
437 // .. otherwise we found a case of an adapter depending on an
438 // adapter-module-in-progress meaning that the current adapter
439 // module must be completed and then a new one is started.
440 self.finish_adapter_module();
441 assert!(self.defined_items.contains(&Def::Adapter(*id)));
442 }
443
444 // These items can't transitively depend on an adapter
445 dfg::CoreDef::Trampoline(_) | dfg::CoreDef::InstanceFlags(_) => {}
446 }
447 }
448
449 fn core_export<T>(&mut self, dfg: &dfg::ComponentDfg, export: &dfg::CoreExport<T>) {
450 // When an adapter depends on an exported item it actually depends on
451 // the instance of that exported item. The caveat here is that the
452 // adapter not only depends on that particular instance, but also all
453 // prior instances to that instance as well because instance
454 // instantiation order is fixed and cannot change.
455 //
456 // To model this the instance index space is looped over here and while
457 // an instance hasn't been visited it's visited. Note that if an
458 // instance has already been visited then all prior instances have
459 // already been visited so there's no need to continue.
460 let mut instance = export.instance;
461 while self.defined_items.insert(Def::Instance(instance)) {
462 self.instance(dfg, instance);
463 if instance.as_u32() == 0 {
464 break;
465 }
466 instance = dfg::InstanceId::from_u32(instance.as_u32() - 1);
467 }
468 }
469
470 fn instance(&mut self, dfg: &dfg::ComponentDfg, instance: dfg::InstanceId) {
471 log::debug!("visiting instance {instance:?}");
472
473 // ... otherwise if this is the first timet he instance has been seen
474 // then the instances own arguments are recursively visited to find
475 // transitive dependencies on adapters.
476 match &dfg.instances[instance] {
477 dfg::Instance::Static(_, args) => {
478 for arg in args.iter() {
479 self.core_def(dfg, arg);
480 }
481 }
482 dfg::Instance::Import(_, args) => {
483 for (_, values) in args {
484 for (_, def) in values {
485 self.core_def(dfg, def);
486 }
487 }
488 }
489 }
490 }
491
492 fn finish_adapter_module(&mut self) {
493 if self.next_module.adapters.is_empty() {
494 return;
495 }
496
497 // Reset the state of the current module-in-progress and then flag all
498 // pending adapters as now defined since the current module is being
499 // committed.
500 let module = mem::take(&mut self.next_module);
501 for adapter in module.adapters.iter() {
502 let inserted = self.defined_items.insert(Def::Adapter(*adapter));
503 assert!(inserted);
504 }
505 let idx = self.adapter_modules.push(module);
506 log::debug!("finishing adapter module {idx:?}");
507 }
508}