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}