cranelift_codegen/ir/
function.rs

1//! Intermediate representation of a function.
2//!
3//! The `Function` struct defined in this module owns all of its basic blocks and
4//! instructions.
5
6use crate::entity::{PrimaryMap, SecondaryMap};
7use crate::ir::{
8    self, pcc::Fact, Block, DataFlowGraph, DynamicStackSlot, DynamicStackSlotData,
9    DynamicStackSlots, DynamicType, ExtFuncData, FuncRef, GlobalValue, GlobalValueData, Inst,
10    JumpTable, JumpTableData, Layout, MemoryType, MemoryTypeData, Opcode, SigRef, Signature,
11    SourceLocs, StackSlot, StackSlotData, StackSlots, Type,
12};
13use crate::isa::CallConv;
14use crate::write::write_function;
15use crate::HashMap;
16#[cfg(feature = "enable-serde")]
17use alloc::string::String;
18use core::fmt;
19
20#[cfg(feature = "enable-serde")]
21use serde::de::{Deserializer, Error};
22#[cfg(feature = "enable-serde")]
23use serde::ser::Serializer;
24#[cfg(feature = "enable-serde")]
25use serde::{Deserialize, Serialize};
26
27use super::entities::UserExternalNameRef;
28use super::extname::UserFuncName;
29use super::{RelSourceLoc, SourceLoc, UserExternalName};
30
31/// A version marker used to ensure that serialized clif ir is never deserialized with a
32/// different version of Cranelift.
33#[derive(Default, Copy, Clone, Debug, PartialEq, Hash)]
34pub struct VersionMarker;
35
36#[cfg(feature = "enable-serde")]
37impl Serialize for VersionMarker {
38    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
39    where
40        S: Serializer,
41    {
42        crate::VERSION.serialize(serializer)
43    }
44}
45
46#[cfg(feature = "enable-serde")]
47impl<'de> Deserialize<'de> for VersionMarker {
48    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
49    where
50        D: Deserializer<'de>,
51    {
52        let version = String::deserialize(deserializer)?;
53        if version != crate::VERSION {
54            return Err(D::Error::custom(&format!(
55                "Expected a clif ir function for version {}, found one for version {}",
56                crate::VERSION,
57                version,
58            )));
59        }
60        Ok(VersionMarker)
61    }
62}
63
64/// Function parameters used when creating this function, and that will become applied after
65/// compilation to materialize the final `CompiledCode`.
66#[derive(Clone, PartialEq)]
67#[cfg_attr(
68    feature = "enable-serde",
69    derive(serde_derive::Serialize, serde_derive::Deserialize)
70)]
71pub struct FunctionParameters {
72    /// The first `SourceLoc` appearing in the function, serving as a base for every relative
73    /// source loc in the function.
74    base_srcloc: Option<SourceLoc>,
75
76    /// External user-defined function references.
77    user_named_funcs: PrimaryMap<UserExternalNameRef, UserExternalName>,
78
79    /// Inverted mapping of `user_named_funcs`, to deduplicate internally.
80    user_ext_name_to_ref: HashMap<UserExternalName, UserExternalNameRef>,
81}
82
83impl FunctionParameters {
84    /// Creates a new `FunctionParameters` with the given name.
85    pub fn new() -> Self {
86        Self {
87            base_srcloc: None,
88            user_named_funcs: Default::default(),
89            user_ext_name_to_ref: Default::default(),
90        }
91    }
92
93    /// Returns the base `SourceLoc`.
94    ///
95    /// If it was never explicitly set with `ensure_base_srcloc`, will return an invalid
96    /// `SourceLoc`.
97    pub fn base_srcloc(&self) -> SourceLoc {
98        self.base_srcloc.unwrap_or_default()
99    }
100
101    /// Sets the base `SourceLoc`, if not set yet, and returns the base value.
102    pub fn ensure_base_srcloc(&mut self, srcloc: SourceLoc) -> SourceLoc {
103        match self.base_srcloc {
104            Some(val) => val,
105            None => {
106                self.base_srcloc = Some(srcloc);
107                srcloc
108            }
109        }
110    }
111
112    /// Retrieve a `UserExternalNameRef` for the given name, or add a new one.
113    ///
114    /// This method internally deduplicates same `UserExternalName` so they map to the same
115    /// reference.
116    pub fn ensure_user_func_name(&mut self, name: UserExternalName) -> UserExternalNameRef {
117        if let Some(reff) = self.user_ext_name_to_ref.get(&name) {
118            *reff
119        } else {
120            let reff = self.user_named_funcs.push(name.clone());
121            self.user_ext_name_to_ref.insert(name, reff);
122            reff
123        }
124    }
125
126    /// Resets an already existing user function name to a new value.
127    pub fn reset_user_func_name(&mut self, index: UserExternalNameRef, name: UserExternalName) {
128        if let Some(prev_name) = self.user_named_funcs.get_mut(index) {
129            self.user_ext_name_to_ref.remove(prev_name);
130            *prev_name = name.clone();
131            self.user_ext_name_to_ref.insert(name, index);
132        }
133    }
134
135    /// Returns the internal mapping of `UserExternalNameRef` to `UserExternalName`.
136    pub fn user_named_funcs(&self) -> &PrimaryMap<UserExternalNameRef, UserExternalName> {
137        &self.user_named_funcs
138    }
139
140    fn clear(&mut self) {
141        self.base_srcloc = None;
142        self.user_named_funcs.clear();
143        self.user_ext_name_to_ref.clear();
144    }
145}
146
147/// Function fields needed when compiling a function.
148///
149/// Additionally, these fields can be the same for two functions that would be compiled the same
150/// way, and finalized by applying `FunctionParameters` onto their `CompiledCodeStencil`.
151#[derive(Clone, PartialEq, Hash)]
152#[cfg_attr(
153    feature = "enable-serde",
154    derive(serde_derive::Serialize, serde_derive::Deserialize)
155)]
156pub struct FunctionStencil {
157    /// A version marker used to ensure that serialized clif ir is never deserialized with a
158    /// different version of Cranelift.
159    // Note: This must be the first field to ensure that Serde will deserialize it before
160    // attempting to deserialize other fields that are potentially changed between versions.
161    pub version_marker: VersionMarker,
162
163    /// Signature of this function.
164    pub signature: Signature,
165
166    /// Sized stack slots allocated in this function.
167    pub sized_stack_slots: StackSlots,
168
169    /// Dynamic stack slots allocated in this function.
170    pub dynamic_stack_slots: DynamicStackSlots,
171
172    /// Global values referenced.
173    pub global_values: PrimaryMap<ir::GlobalValue, ir::GlobalValueData>,
174
175    /// Global value proof-carrying-code facts.
176    pub global_value_facts: SecondaryMap<ir::GlobalValue, Option<Fact>>,
177
178    /// Memory types for proof-carrying code.
179    pub memory_types: PrimaryMap<ir::MemoryType, ir::MemoryTypeData>,
180
181    /// Data flow graph containing the primary definition of all instructions, blocks and values.
182    pub dfg: DataFlowGraph,
183
184    /// Layout of blocks and instructions in the function body.
185    pub layout: Layout,
186
187    /// Source locations.
188    ///
189    /// Track the original source location for each instruction. The source locations are not
190    /// interpreted by Cranelift, only preserved.
191    pub srclocs: SourceLocs,
192
193    /// An optional global value which represents an expression evaluating to
194    /// the stack limit for this function. This `GlobalValue` will be
195    /// interpreted in the prologue, if necessary, to insert a stack check to
196    /// ensure that a trap happens if the stack pointer goes below the
197    /// threshold specified here.
198    pub stack_limit: Option<ir::GlobalValue>,
199}
200
201impl FunctionStencil {
202    fn clear(&mut self) {
203        self.signature.clear(CallConv::Fast);
204        self.sized_stack_slots.clear();
205        self.dynamic_stack_slots.clear();
206        self.global_values.clear();
207        self.global_value_facts.clear();
208        self.memory_types.clear();
209        self.dfg.clear();
210        self.layout.clear();
211        self.srclocs.clear();
212        self.stack_limit = None;
213    }
214
215    /// Creates a jump table in the function, to be used by `br_table` instructions.
216    pub fn create_jump_table(&mut self, data: JumpTableData) -> JumpTable {
217        self.dfg.jump_tables.push(data)
218    }
219
220    /// Creates a sized stack slot in the function, to be used by `stack_load`, `stack_store`
221    /// and `stack_addr` instructions.
222    pub fn create_sized_stack_slot(&mut self, data: StackSlotData) -> StackSlot {
223        self.sized_stack_slots.push(data)
224    }
225
226    /// Creates a dynamic stack slot in the function, to be used by `dynamic_stack_load`,
227    /// `dynamic_stack_store` and `dynamic_stack_addr` instructions.
228    pub fn create_dynamic_stack_slot(&mut self, data: DynamicStackSlotData) -> DynamicStackSlot {
229        self.dynamic_stack_slots.push(data)
230    }
231
232    /// Adds a signature which can later be used to declare an external function import.
233    pub fn import_signature(&mut self, signature: Signature) -> SigRef {
234        self.dfg.signatures.push(signature)
235    }
236
237    /// Declares a global value accessible to the function.
238    pub fn create_global_value(&mut self, data: GlobalValueData) -> GlobalValue {
239        self.global_values.push(data)
240    }
241
242    /// Declares a memory type for use by the function.
243    pub fn create_memory_type(&mut self, data: MemoryTypeData) -> MemoryType {
244        self.memory_types.push(data)
245    }
246
247    /// Find the global dyn_scale value associated with given DynamicType.
248    pub fn get_dyn_scale(&self, ty: DynamicType) -> GlobalValue {
249        self.dfg.dynamic_types.get(ty).unwrap().dynamic_scale
250    }
251
252    /// Find the global dyn_scale for the given stack slot.
253    pub fn get_dynamic_slot_scale(&self, dss: DynamicStackSlot) -> GlobalValue {
254        let dyn_ty = self.dynamic_stack_slots.get(dss).unwrap().dyn_ty;
255        self.get_dyn_scale(dyn_ty)
256    }
257
258    /// Get a concrete `Type` from a user defined `DynamicType`.
259    pub fn get_concrete_dynamic_ty(&self, ty: DynamicType) -> Option<Type> {
260        self.dfg
261            .dynamic_types
262            .get(ty)
263            .unwrap_or_else(|| panic!("Undeclared dynamic vector type: {ty}"))
264            .concrete()
265    }
266
267    /// Find a presumed unique special-purpose function parameter value.
268    ///
269    /// Returns the value of the last `purpose` parameter, or `None` if no such parameter exists.
270    pub fn special_param(&self, purpose: ir::ArgumentPurpose) -> Option<ir::Value> {
271        let entry = self.layout.entry_block().expect("Function is empty");
272        self.signature
273            .special_param_index(purpose)
274            .map(|i| self.dfg.block_params(entry)[i])
275    }
276
277    /// Starts collection of debug information.
278    pub fn collect_debug_info(&mut self) {
279        self.dfg.collect_debug_info();
280    }
281
282    /// Rewrite the branch destination to `new_dest` if the destination matches `old_dest`.
283    /// Does nothing if called with a non-jump or non-branch instruction.
284    pub fn rewrite_branch_destination(&mut self, inst: Inst, old_dest: Block, new_dest: Block) {
285        for dest in self.dfg.insts[inst].branch_destination_mut(&mut self.dfg.jump_tables) {
286            if dest.block(&self.dfg.value_lists) == old_dest {
287                dest.set_block(new_dest, &mut self.dfg.value_lists)
288            }
289        }
290    }
291
292    /// Checks that the specified block can be encoded as a basic block.
293    ///
294    /// On error, returns the first invalid instruction and an error message.
295    pub fn is_block_basic(&self, block: Block) -> Result<(), (Inst, &'static str)> {
296        let dfg = &self.dfg;
297        let inst_iter = self.layout.block_insts(block);
298
299        // Ignore all instructions prior to the first branch.
300        let mut inst_iter = inst_iter.skip_while(|&inst| !dfg.insts[inst].opcode().is_branch());
301
302        // A conditional branch is permitted in a basic block only when followed
303        // by a terminal jump instruction.
304        if let Some(_branch) = inst_iter.next() {
305            if let Some(next) = inst_iter.next() {
306                match dfg.insts[next].opcode() {
307                    Opcode::Jump => (),
308                    _ => return Err((next, "post-branch instruction not jump")),
309                }
310            }
311        }
312
313        Ok(())
314    }
315
316    /// Returns an iterator over the blocks succeeding the given block.
317    pub fn block_successors(&self, block: Block) -> impl DoubleEndedIterator<Item = Block> + '_ {
318        self.layout.last_inst(block).into_iter().flat_map(|inst| {
319            self.dfg.insts[inst]
320                .branch_destination(&self.dfg.jump_tables)
321                .iter()
322                .map(|block| block.block(&self.dfg.value_lists))
323        })
324    }
325
326    /// Returns true if the function is function that doesn't call any other functions. This is not
327    /// to be confused with a "leaf function" in Windows terminology.
328    pub fn is_leaf(&self) -> bool {
329        // Conservative result: if there's at least one function signature referenced in this
330        // function, assume it is not a leaf.
331        let has_signatures = !self.dfg.signatures.is_empty();
332
333        // Under some TLS models, retrieving the address of a TLS variable requires calling a
334        // function. Conservatively assume that any function that references a tls global value
335        // is not a leaf.
336        let has_tls = self.global_values.values().any(|gv| match gv {
337            GlobalValueData::Symbol { tls, .. } => *tls,
338            _ => false,
339        });
340
341        !has_signatures && !has_tls
342    }
343
344    /// Replace the `dst` instruction's data with the `src` instruction's data
345    /// and then remove `src`.
346    ///
347    /// `src` and its result values should not be used at all, as any uses would
348    /// be left dangling after calling this method.
349    ///
350    /// `src` and `dst` must have the same number of resulting values, and
351    /// `src`'s i^th value must have the same type as `dst`'s i^th value.
352    pub fn transplant_inst(&mut self, dst: Inst, src: Inst) {
353        debug_assert_eq!(
354            self.dfg.inst_results(dst).len(),
355            self.dfg.inst_results(src).len()
356        );
357        debug_assert!(self
358            .dfg
359            .inst_results(dst)
360            .iter()
361            .zip(self.dfg.inst_results(src))
362            .all(|(a, b)| self.dfg.value_type(*a) == self.dfg.value_type(*b)));
363
364        self.dfg.insts[dst] = self.dfg.insts[src];
365        self.layout.remove_inst(src);
366    }
367
368    /// Size occupied by all stack slots associated with this function.
369    ///
370    /// Does not include any padding necessary due to offsets
371    pub fn fixed_stack_size(&self) -> u32 {
372        self.sized_stack_slots.values().map(|ss| ss.size).sum()
373    }
374
375    /// Returns the list of relative source locations for this function.
376    pub(crate) fn rel_srclocs(&self) -> &SecondaryMap<Inst, RelSourceLoc> {
377        &self.srclocs
378    }
379}
380
381/// Functions can be cloned, but it is not a very fast operation.
382/// The clone will have all the same entity numbers as the original.
383#[derive(Clone, PartialEq)]
384#[cfg_attr(feature = "enable-serde", derive(Serialize, Deserialize))]
385pub struct Function {
386    /// Name of this function.
387    ///
388    /// Mostly used by `.clif` files, only there for debugging / naming purposes.
389    pub name: UserFuncName,
390
391    /// All the fields required for compiling a function, independently of details irrelevant to
392    /// compilation and that are stored in the `FunctionParameters` `params` field instead.
393    pub stencil: FunctionStencil,
394
395    /// All the parameters that can be applied onto the function stencil, that is, that don't
396    /// matter when caching compilation artifacts.
397    pub params: FunctionParameters,
398}
399
400impl core::ops::Deref for Function {
401    type Target = FunctionStencil;
402
403    fn deref(&self) -> &Self::Target {
404        &self.stencil
405    }
406}
407
408impl core::ops::DerefMut for Function {
409    fn deref_mut(&mut self) -> &mut Self::Target {
410        &mut self.stencil
411    }
412}
413
414impl Function {
415    /// Create a function with the given name and signature.
416    pub fn with_name_signature(name: UserFuncName, sig: Signature) -> Self {
417        Self {
418            name,
419            stencil: FunctionStencil {
420                version_marker: VersionMarker,
421                signature: sig,
422                sized_stack_slots: StackSlots::new(),
423                dynamic_stack_slots: DynamicStackSlots::new(),
424                global_values: PrimaryMap::new(),
425                global_value_facts: SecondaryMap::new(),
426                memory_types: PrimaryMap::new(),
427                dfg: DataFlowGraph::new(),
428                layout: Layout::new(),
429                srclocs: SecondaryMap::new(),
430                stack_limit: None,
431            },
432            params: FunctionParameters::new(),
433        }
434    }
435
436    /// Clear all data structures in this function.
437    pub fn clear(&mut self) {
438        self.stencil.clear();
439        self.params.clear();
440        self.name = UserFuncName::default();
441    }
442
443    /// Create a new empty, anonymous function with a Fast calling convention.
444    pub fn new() -> Self {
445        Self::with_name_signature(Default::default(), Signature::new(CallConv::Fast))
446    }
447
448    /// Return an object that can display this function with correct ISA-specific annotations.
449    pub fn display(&self) -> DisplayFunction<'_> {
450        DisplayFunction(self)
451    }
452
453    /// Sets an absolute source location for the given instruction.
454    ///
455    /// If no base source location has been set yet, records it at the same time.
456    pub fn set_srcloc(&mut self, inst: Inst, srcloc: SourceLoc) {
457        let base = self.params.ensure_base_srcloc(srcloc);
458        self.stencil.srclocs[inst] = RelSourceLoc::from_base_offset(base, srcloc);
459    }
460
461    /// Returns an absolute source location for the given instruction.
462    pub fn srcloc(&self, inst: Inst) -> SourceLoc {
463        let base = self.params.base_srcloc();
464        self.stencil.srclocs[inst].expand(base)
465    }
466
467    /// Declare a user-defined external function import, to be referenced in `ExtFuncData::User` later.
468    pub fn declare_imported_user_function(
469        &mut self,
470        name: UserExternalName,
471    ) -> UserExternalNameRef {
472        self.params.ensure_user_func_name(name)
473    }
474
475    /// Declare an external function import.
476    pub fn import_function(&mut self, data: ExtFuncData) -> FuncRef {
477        self.stencil.dfg.ext_funcs.push(data)
478    }
479}
480
481/// Wrapper type capable of displaying a `Function`.
482pub struct DisplayFunction<'a>(&'a Function);
483
484impl<'a> fmt::Display for DisplayFunction<'a> {
485    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
486        write_function(fmt, self.0)
487    }
488}
489
490impl fmt::Display for Function {
491    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
492        write_function(fmt, self)
493    }
494}
495
496impl fmt::Debug for Function {
497    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
498        write_function(fmt, self)
499    }
500}
cranelift_codegen/ir/function.rs

cranelift_codegen/ir/
function.rs
