wasmer_compiler_cranelift/translator/func_environ.rs
1// This file contains code from external sources.
2// Attributions: https://github.com/wasmerio/wasmer/blob/main/docs/ATTRIBUTIONS.md
3
4//! All the runtime support necessary for the wasm to cranelift translation is formalized by the
5//! traits `FunctionEnvMutironment`.
6
7use super::func_state::FuncTranslationState;
8use super::translation_utils::reference_type;
9use crate::heap::{Heap, HeapData};
10use core::convert::From;
11use cranelift_codegen::cursor::FuncCursor;
12use cranelift_codegen::ir::immediates::Offset32;
13use cranelift_codegen::ir::{self, InstBuilder};
14use cranelift_codegen::isa::TargetFrontendConfig;
15use cranelift_frontend::FunctionBuilder;
16use wasmer_compiler::wasmparser::{HeapType, Operator};
17use wasmer_types::entity::PrimaryMap;
18use wasmer_types::{
19 FunctionIndex, FunctionType, GlobalIndex, LocalFunctionIndex, MemoryIndex, SignatureIndex,
20 TableIndex, Type as WasmerType, WasmResult,
21};
22
23/// The value of a WebAssembly global variable.
24#[derive(Clone, Copy)]
25pub enum GlobalVariable {
26 #[allow(dead_code)]
27 /// This is a constant global with a value known at compile time.
28 Const(ir::Value),
29
30 /// This is a variable in memory that should be referenced through a `GlobalValue`.
31 Memory {
32 /// The address of the global variable storage.
33 gv: ir::GlobalValue,
34 /// An offset to add to the address.
35 offset: Offset32,
36 /// The global variable's type.
37 ty: ir::Type,
38 },
39
40 #[allow(dead_code)]
41 /// This is a global variable that needs to be handled by the environment.
42 Custom,
43}
44
45#[allow(dead_code)]
46/// How to return from functions.
47#[derive(Copy, Clone, PartialEq, Eq, Debug)]
48pub enum ReturnMode {
49 /// Use normal return instructions as needed.
50 NormalReturns,
51}
52
53/// Environment affecting the translation of a WebAssembly.
54pub trait TargetEnvironment {
55 /// Get the information needed to produce Cranelift IR for the given target.
56 fn target_config(&self) -> TargetFrontendConfig;
57
58 /// Get the Cranelift integer type to use for native pointers.
59 ///
60 /// This returns `I64` for 64-bit architectures and `I32` for 32-bit architectures.
61 fn pointer_type(&self) -> ir::Type {
62 ir::Type::int(u16::from(self.target_config().pointer_bits())).unwrap()
63 }
64
65 /// Get the size of a native pointer, in bytes.
66 #[allow(dead_code)]
67 fn pointer_bytes(&self) -> u8 {
68 self.target_config().pointer_bytes()
69 }
70
71 /// Get the Cranelift reference type to use for native references.
72 ///
73 /// This returns the target pointer type for both `funcref` and `externref`.
74 fn reference_type(&self) -> ir::Type {
75 reference_type(self.target_config()).expect("expected reference type")
76 }
77}
78
79/// Environment affecting the translation of a single WebAssembly function.
80///
81/// A `FuncEnvironment` trait object is required to translate a WebAssembly function to Cranelift
82/// IR. The function environment provides information about the WebAssembly module as well as the
83/// runtime environment.
84pub trait FuncEnvironment: TargetEnvironment {
85 /// Whether to enable Spectre mitigations for heap accesses.
86 fn heap_access_spectre_mitigation(&self) -> bool;
87
88 /// Whether to add proof-carrying-code facts to verify memory accesses.
89 fn proof_carrying_code(&self) -> bool;
90
91 /// Is the given parameter of the given function a wasm-level parameter, as opposed to a hidden
92 /// parameter added for use by the implementation?
93 fn is_wasm_parameter(&self, signature: &ir::Signature, index: usize) -> bool {
94 signature.params[index].purpose == ir::ArgumentPurpose::Normal
95 }
96
97 /// Is the given return of the given function a wasm-level parameter, as
98 /// opposed to a hidden parameter added for use by the implementation?
99 fn is_wasm_return(&self, signature: &ir::Signature, index: usize) -> bool {
100 signature.returns[index].purpose == ir::ArgumentPurpose::Normal
101 }
102
103 /// Should the code be structured to use a single `fallthrough_return` instruction at the end
104 /// of the function body, rather than `return` instructions as needed? This is used by VMs
105 /// to append custom epilogues.
106 fn return_mode(&self) -> ReturnMode {
107 ReturnMode::NormalReturns
108 }
109
110 /// Set up the necessary preamble definitions in `func` to access the global variable
111 /// identified by `index`.
112 ///
113 /// The index space covers both imported globals and globals defined by the module.
114 ///
115 /// Return the global variable reference that should be used to access the global and the
116 /// WebAssembly type of the global.
117 fn make_global(
118 &mut self,
119 func: &mut ir::Function,
120 index: GlobalIndex,
121 ) -> WasmResult<GlobalVariable>;
122
123 /// Inserts code before updating a global.
124 fn update_global(
125 &mut self,
126 _builder: &mut FunctionBuilder,
127 _global_index: u32,
128 _value: ir::Value,
129 ) {
130 }
131
132 /// Get the heaps for this function environment.
133 ///
134 /// The returned map should provide heap format details (encoded in
135 /// `HeapData`) for each `Heap` that was previously returned by
136 /// `make_heap()`. The translator will first call make_heap for each Wasm
137 /// memory, and then later when translating code, will invoke `heaps()` to
138 /// learn how to access the environment's implementation of each memory.
139 fn heaps(&self) -> &PrimaryMap<Heap, HeapData>;
140
141 /// Set up the necessary preamble definitions in `func` to access the linear memory identified
142 /// by `index`.
143 ///
144 /// The index space covers both imported and locally declared memories.
145 fn make_heap(&mut self, func: &mut ir::Function, index: MemoryIndex) -> WasmResult<Heap>;
146
147 /// Set up a signature definition in the preamble of `func` that can be used for an indirect
148 /// call with signature `index`.
149 ///
150 /// The signature may contain additional arguments needed for an indirect call, but the
151 /// arguments marked as `ArgumentPurpose::Normal` must correspond to the WebAssembly signature
152 /// arguments.
153 ///
154 /// The signature will only be used for indirect calls, even if the module has direct function
155 /// calls with the same WebAssembly type.
156 fn make_indirect_sig(
157 &mut self,
158 func: &mut ir::Function,
159 index: SignatureIndex,
160 ) -> WasmResult<ir::SigRef>;
161
162 /// Set up an external function definition in the preamble of `func` that can be used to
163 /// directly call the function `index`.
164 ///
165 /// The index space covers both imported functions and functions defined in the current module.
166 ///
167 /// The function's signature may contain additional arguments needed for a direct call, but the
168 /// arguments marked as `ArgumentPurpose::Normal` must correspond to the WebAssembly signature
169 /// arguments.
170 ///
171 /// The function's signature will only be used for direct calls, even if the module has
172 /// indirect calls with the same WebAssembly type.
173 fn make_direct_func(
174 &mut self,
175 func: &mut ir::Function,
176 index: FunctionIndex,
177 ) -> WasmResult<ir::FuncRef>;
178
179 /// Translate a `call` WebAssembly instruction at `pos`.
180 ///
181 /// Insert instructions at `pos` for a direct call to the function `callee_index`.
182 ///
183 /// The function reference `callee` was previously created by `make_direct_func()`.
184 ///
185 /// Return the call instruction whose results are the WebAssembly return values.
186 fn translate_call(
187 &mut self,
188 builder: &mut FunctionBuilder,
189 _callee_index: FunctionIndex,
190 callee: ir::FuncRef,
191 call_args: &[ir::Value],
192 ) -> WasmResult<ir::Inst> {
193 Ok(builder.ins().call(callee, call_args))
194 }
195
196 /// Translate a `call_indirect` WebAssembly instruction at `pos`.
197 ///
198 /// Insert instructions at `pos` for an indirect call to the function `callee` in the table
199 /// `table_index` with WebAssembly signature `sig_index`. The `callee` value will have type
200 /// `i32`.
201 ///
202 /// The signature `sig_ref` was previously created by `make_indirect_sig()`.
203 ///
204 /// Return the call instruction whose results are the WebAssembly return values.
205 /// Returns `None` if this statically traps instead of creating a call
206 /// instruction.
207 fn translate_call_indirect(
208 &mut self,
209 builder: &mut FunctionBuilder,
210 table_index: TableIndex,
211 sig_index: SignatureIndex,
212 sig_ref: ir::SigRef,
213 callee: ir::Value,
214 call_args: &[ir::Value],
215 ) -> WasmResult<ir::Inst>;
216
217 /// Translate a `memory.grow` WebAssembly instruction.
218 ///
219 /// The `index` provided identifies the linear memory to grow, and `heap` is the heap reference
220 /// returned by `make_heap` for the same index.
221 ///
222 /// The `val` value is the requested memory size in pages.
223 ///
224 /// Returns the old size (in pages) of the memory.
225 fn translate_memory_grow(
226 &mut self,
227 pos: FuncCursor,
228 index: MemoryIndex,
229 heap: Heap,
230 val: ir::Value,
231 ) -> WasmResult<ir::Value>;
232
233 /// Translates a `memory.size` WebAssembly instruction.
234 ///
235 /// The `index` provided identifies the linear memory to query, and `heap` is the heap reference
236 /// returned by `make_heap` for the same index.
237 ///
238 /// Returns the size in pages of the memory.
239 fn translate_memory_size(
240 &mut self,
241 pos: FuncCursor,
242 index: MemoryIndex,
243 heap: Heap,
244 ) -> WasmResult<ir::Value>;
245
246 /// Translate a `memory.copy` WebAssembly instruction.
247 ///
248 /// The `index` provided identifies the linear memory to query, and `heap` is the heap reference
249 /// returned by `make_heap` for the same index.
250 #[allow(clippy::too_many_arguments)]
251 fn translate_memory_copy(
252 &mut self,
253 pos: FuncCursor,
254 src_index: MemoryIndex,
255 src_heap: Heap,
256 dst_index: MemoryIndex,
257 dst_heap: Heap,
258 dst: ir::Value,
259 src: ir::Value,
260 len: ir::Value,
261 ) -> WasmResult<()>;
262
263 /// Translate a `memory.fill` WebAssembly instruction.
264 ///
265 /// The `index` provided identifies the linear memory to query, and `heap` is the heap reference
266 /// returned by `make_heap` for the same index.
267 fn translate_memory_fill(
268 &mut self,
269 pos: FuncCursor,
270 index: MemoryIndex,
271 heap: Heap,
272 dst: ir::Value,
273 val: ir::Value,
274 len: ir::Value,
275 ) -> WasmResult<()>;
276
277 /// Translate a `memory.init` WebAssembly instruction.
278 ///
279 /// The `index` provided identifies the linear memory to query, and `heap` is the heap reference
280 /// returned by `make_heap` for the same index. `seg_index` is the index of the segment to copy
281 /// from.
282 #[allow(clippy::too_many_arguments)]
283 fn translate_memory_init(
284 &mut self,
285 pos: FuncCursor,
286 index: MemoryIndex,
287 heap: Heap,
288 seg_index: u32,
289 dst: ir::Value,
290 src: ir::Value,
291 len: ir::Value,
292 ) -> WasmResult<()>;
293
294 /// Translate a `data.drop` WebAssembly instruction.
295 fn translate_data_drop(&mut self, pos: FuncCursor, seg_index: u32) -> WasmResult<()>;
296
297 /// Translate a `table.size` WebAssembly instruction.
298 fn translate_table_size(&mut self, pos: FuncCursor, index: TableIndex)
299 -> WasmResult<ir::Value>;
300
301 /// Translate a `table.grow` WebAssembly instruction.
302 fn translate_table_grow(
303 &mut self,
304 pos: FuncCursor,
305 table_index: TableIndex,
306 delta: ir::Value,
307 init_value: ir::Value,
308 ) -> WasmResult<ir::Value>;
309
310 /// Translate a `table.get` WebAssembly instruction.
311 fn translate_table_get(
312 &mut self,
313 builder: &mut FunctionBuilder,
314 table_index: TableIndex,
315 index: ir::Value,
316 ) -> WasmResult<ir::Value>;
317
318 /// Translate a `table.set` WebAssembly instruction.
319 fn translate_table_set(
320 &mut self,
321 builder: &mut FunctionBuilder,
322 table_index: TableIndex,
323 value: ir::Value,
324 index: ir::Value,
325 ) -> WasmResult<()>;
326
327 /// Translate a `table.copy` WebAssembly instruction.
328 #[allow(clippy::too_many_arguments)]
329 fn translate_table_copy(
330 &mut self,
331 pos: FuncCursor,
332 dst_table_index: TableIndex,
333 src_table_index: TableIndex,
334 dst: ir::Value,
335 src: ir::Value,
336 len: ir::Value,
337 ) -> WasmResult<()>;
338
339 /// Translate a `table.fill` WebAssembly instruction.
340 fn translate_table_fill(
341 &mut self,
342 pos: FuncCursor,
343 table_index: TableIndex,
344 dst: ir::Value,
345 val: ir::Value,
346 len: ir::Value,
347 ) -> WasmResult<()>;
348
349 /// Translate a `table.init` WebAssembly instruction.
350 #[allow(clippy::too_many_arguments)]
351 fn translate_table_init(
352 &mut self,
353 pos: FuncCursor,
354 seg_index: u32,
355 table_index: TableIndex,
356 dst: ir::Value,
357 src: ir::Value,
358 len: ir::Value,
359 ) -> WasmResult<()>;
360
361 /// Translate a `elem.drop` WebAssembly instruction.
362 fn translate_elem_drop(&mut self, pos: FuncCursor, seg_index: u32) -> WasmResult<()>;
363
364 /// Translate a `ref.null T` WebAssembly instruction.
365 ///
366 /// By default, translates into a null reference type.
367 ///
368 /// Override this if you don't use Cranelift reference types for all Wasm
369 /// reference types (e.g. you use a raw pointer for `funcref`s) or if the
370 /// null sentinel is not a null reference type pointer for your type. If you
371 /// override this method, then you should also override
372 /// `translate_ref_is_null` as well.
373 fn translate_ref_null(&mut self, mut pos: FuncCursor, ty: HeapType) -> WasmResult<ir::Value> {
374 let _ = ty;
375 Ok(pos.ins().iconst(self.reference_type(), 0))
376 }
377
378 /// Translate a `ref.is_null` WebAssembly instruction.
379 ///
380 /// By default, assumes that `value` is a Cranelift reference type, and that
381 /// a null Cranelift reference type is the null value for all Wasm reference
382 /// types.
383 ///
384 /// If you override this method, you probably also want to override
385 /// `translate_ref_null` as well.
386 fn translate_ref_is_null(
387 &mut self,
388 mut pos: FuncCursor,
389 value: ir::Value,
390 ) -> WasmResult<ir::Value> {
391 let is_null = pos
392 .ins()
393 .icmp_imm(cranelift_codegen::ir::condcodes::IntCC::Equal, value, 0);
394 Ok(pos.ins().uextend(ir::types::I32, is_null))
395 }
396
397 /// Translate a `ref.func` WebAssembly instruction.
398 fn translate_ref_func(
399 &mut self,
400 pos: FuncCursor,
401 func_index: FunctionIndex,
402 ) -> WasmResult<ir::Value>;
403
404 /// Translate a `global.get` WebAssembly instruction at `pos` for a global
405 /// that is custom.
406 fn translate_custom_global_get(
407 &mut self,
408 pos: FuncCursor,
409 global_index: GlobalIndex,
410 ) -> WasmResult<ir::Value>;
411
412 /// Translate a `global.set` WebAssembly instruction at `pos` for a global
413 /// that is custom.
414 fn translate_custom_global_set(
415 &mut self,
416 pos: FuncCursor,
417 global_index: GlobalIndex,
418 val: ir::Value,
419 ) -> WasmResult<()>;
420
421 /// Translate an `i32.atomic.wait` or `i64.atomic.wait` WebAssembly instruction.
422 /// The `index` provided identifies the linear memory containing the value
423 /// to wait on, and `heap` is the heap reference returned by `make_heap`
424 /// for the same index. Whether the waited-on value is 32- or 64-bit can be
425 /// determined by examining the type of `expected`, which must be only I32 or I64.
426 ///
427 /// Returns an i32, which is negative if the helper call failed.
428 fn translate_atomic_wait(
429 &mut self,
430 pos: FuncCursor,
431 index: MemoryIndex,
432 heap: Heap,
433 addr: ir::Value,
434 expected: ir::Value,
435 timeout: ir::Value,
436 ) -> WasmResult<ir::Value>;
437
438 /// Translate an `atomic.notify` WebAssembly instruction.
439 /// The `index` provided identifies the linear memory containing the value
440 /// to wait on, and `heap` is the heap reference returned by `make_heap`
441 /// for the same index.
442 ///
443 /// Returns an i64, which is negative if the helper call failed.
444 fn translate_atomic_notify(
445 &mut self,
446 pos: FuncCursor,
447 index: MemoryIndex,
448 heap: Heap,
449 addr: ir::Value,
450 count: ir::Value,
451 ) -> WasmResult<ir::Value>;
452
453 /// Emit code at the beginning of every wasm loop.
454 ///
455 /// This can be used to insert explicit interrupt or safepoint checking at
456 /// the beginnings of loops.
457 fn translate_loop_header(&mut self, _pos: FuncCursor) -> WasmResult<()> {
458 // By default, don't emit anything.
459 Ok(())
460 }
461
462 /// Optional callback for the `FunctionEnvMutironment` performing this translation to maintain
463 /// internal state or prepare custom state for the operator to translate
464 fn before_translate_operator(
465 &mut self,
466 _op: &Operator,
467 _builder: &mut FunctionBuilder,
468 _state: &FuncTranslationState,
469 ) -> WasmResult<()> {
470 Ok(())
471 }
472
473 /// Optional callback for the `FunctionEnvMutironment` performing this translation to maintain
474 /// internal state or finalize custom state for the operator that was translated
475 fn after_translate_operator(
476 &mut self,
477 _op: &Operator,
478 _builder: &mut FunctionBuilder,
479 _state: &FuncTranslationState,
480 ) -> WasmResult<()> {
481 Ok(())
482 }
483
484 /// Optional callback for the `FuncEnvironment` performing this translation
485 /// to maintain, prepare, or finalize custom, internal state when we
486 /// statically determine that a Wasm memory access will unconditionally
487 /// trap, rendering the rest of the block unreachable. Called just before
488 /// the unconditional trap is emitted.
489 fn before_unconditionally_trapping_memory_access(
490 &mut self,
491 _builder: &mut FunctionBuilder,
492 ) -> WasmResult<()> {
493 Ok(())
494 }
495
496 /// Get the type of the global at the given index.
497 #[allow(dead_code)]
498 fn get_global_type(&self, global_index: GlobalIndex) -> Option<WasmerType>;
499
500 /// Push a local declaration on to the stack to track the type of locals.
501 fn push_local_decl_on_stack(&mut self, ty: WasmerType);
502
503 /// Push locals for a the params of a function on to the stack.
504 fn push_params_on_stack(&mut self, function_index: LocalFunctionIndex);
505
506 /// Get the type of the local at the given index.
507 #[allow(dead_code)]
508 fn get_local_type(&self, local_index: u32) -> Option<WasmerType>;
509
510 /// Get the types of all the current locals.
511 #[allow(dead_code)]
512 fn get_local_types(&self) -> &[WasmerType];
513
514 /// Get the type of the local at the given index.
515 #[allow(dead_code)]
516 fn get_function_type(&self, function_index: FunctionIndex) -> Option<&FunctionType>;
517
518 /// Get the type of a function with the given signature index.
519 #[allow(dead_code)]
520 fn get_function_sig(&self, sig_index: SignatureIndex) -> Option<&FunctionType>;
521
522 /// Inserts code before a function return.
523 fn handle_before_return(&mut self, _retvals: &[ir::Value], _builder: &mut FunctionBuilder) {}
524
525 /// Inserts code before a load.
526 fn before_load(
527 &mut self,
528 _builder: &mut FunctionBuilder,
529 _val_size: u8,
530 _addr: ir::Value,
531 _offset: u64,
532 ) {
533 }
534
535 /// Inserts code before a store.
536 fn before_store(
537 &mut self,
538 _builder: &mut FunctionBuilder,
539 _val_size: u8,
540 _addr: ir::Value,
541 _offset: u64,
542 ) {
543 }
544}