cranelift_frontend/
lib.rs

1//! Cranelift IR builder library.
2//!
3//! Provides a straightforward way to create a Cranelift IR function and fill it with instructions
4//! corresponding to your source program written in another language.
5//!
6//! To get started, create an [`FunctionBuilderContext`](struct.FunctionBuilderContext.html) and
7//! pass it as an argument to a [`FunctionBuilder`](struct.FunctionBuilder.html).
8//!
9//! # Mutable variables and Cranelift IR values
10//!
11//! The most interesting feature of this API is that it provides a single way to deal with all your
12//! variable problems. Indeed, the [`FunctionBuilder`](struct.FunctionBuilder.html) struct has a
13//! type `Variable` that should be an index of your source language variables. Then, through
14//! calling the functions
15//! [`declare_var`](struct.FunctionBuilder.html#method.declare_var),
16//! [`def_var`](struct.FunctionBuilder.html#method.def_var) and
17//! [`use_var`](struct.FunctionBuilder.html#method.use_var), the
18//! [`FunctionBuilder`](struct.FunctionBuilder.html) will create for you all the Cranelift IR
19//! values corresponding to your variables.
20//!
21//! This API has been designed to help you translate your mutable variables into
22//! [`SSA`](https://en.wikipedia.org/wiki/Static_single_assignment_form) form.
23//! [`use_var`](struct.FunctionBuilder.html#method.use_var) will return the Cranelift IR value
24//! that corresponds to your mutable variable at a precise point in the program. However, if you know
25//! beforehand that one of your variables is defined only once, for instance if it is the result
26//! of an intermediate expression in an expression-based language, then you can translate it
27//! directly by the Cranelift IR value returned by the instruction builder. Using the
28//! [`use_var`](struct.FunctionBuilder.html#method.use_var) API for such an immutable variable
29//! would also work but with a slight additional overhead (the SSA algorithm does not know
30//! beforehand if a variable is immutable or not).
31//!
32//! The moral is that you should use these three functions to handle all your mutable variables,
33//! even those that are not present in the source code but artifacts of the translation. It is up
34//! to you to keep a mapping between the mutable variables of your language and their `Variable`
35//! index that is used by Cranelift. Caution: as the `Variable` is used by Cranelift to index an
36//! array containing information about your mutable variables, when you create a new `Variable`
37//! with [`Variable::new(var_index)`] you should make sure that `var_index` is provided by a
38//! counter incremented by 1 each time you encounter a new mutable variable.
39//!
40//! # Example
41//!
42//! Here is a pseudo-program we want to transform into Cranelift IR:
43//!
44//! ```clif
45//! function(x) {
46//! x, y, z : i32
47//! block0:
48//!    y = 2;
49//!    z = x + y;
50//!    jump block1
51//! block1:
52//!    z = z + y;
53//!    brif y, block3, block2
54//! block2:
55//!    z = z - x;
56//!    return y
57//! block3:
58//!    y = y - x
59//!    jump block1
60//! }
61//! ```
62//!
63//! Here is how you build the corresponding Cranelift IR function using `FunctionBuilderContext`:
64//!
65//! ```rust
66//! extern crate cranelift_codegen;
67//! extern crate cranelift_frontend;
68//!
69//! use cranelift_codegen::entity::EntityRef;
70//! use cranelift_codegen::ir::types::*;
71//! use cranelift_codegen::ir::{AbiParam, UserFuncName, Function, InstBuilder, Signature};
72//! use cranelift_codegen::isa::CallConv;
73//! use cranelift_codegen::settings;
74//! use cranelift_codegen::verifier::verify_function;
75//! use cranelift_frontend::{FunctionBuilder, FunctionBuilderContext, Variable};
76//!
77//! let mut sig = Signature::new(CallConv::SystemV);
78//! sig.returns.push(AbiParam::new(I32));
79//! sig.params.push(AbiParam::new(I32));
80//! let mut fn_builder_ctx = FunctionBuilderContext::new();
81//! let mut func = Function::with_name_signature(UserFuncName::user(0, 0), sig);
82//! {
83//!     let mut builder = FunctionBuilder::new(&mut func, &mut fn_builder_ctx);
84//!
85//!     let block0 = builder.create_block();
86//!     let block1 = builder.create_block();
87//!     let block2 = builder.create_block();
88//!     let block3 = builder.create_block();
89//!     let x = Variable::new(0);
90//!     let y = Variable::new(1);
91//!     let z = Variable::new(2);
92//!     builder.declare_var(x, I32);
93//!     builder.declare_var(y, I32);
94//!     builder.declare_var(z, I32);
95//!     builder.append_block_params_for_function_params(block0);
96//!
97//!     builder.switch_to_block(block0);
98//!     builder.seal_block(block0);
99//!     {
100//!         let tmp = builder.block_params(block0)[0]; // the first function parameter
101//!         builder.def_var(x, tmp);
102//!     }
103//!     {
104//!         let tmp = builder.ins().iconst(I32, 2);
105//!         builder.def_var(y, tmp);
106//!     }
107//!     {
108//!         let arg1 = builder.use_var(x);
109//!         let arg2 = builder.use_var(y);
110//!         let tmp = builder.ins().iadd(arg1, arg2);
111//!         builder.def_var(z, tmp);
112//!     }
113//!     builder.ins().jump(block1, &[]);
114//!
115//!     builder.switch_to_block(block1);
116//!     {
117//!         let arg1 = builder.use_var(y);
118//!         let arg2 = builder.use_var(z);
119//!         let tmp = builder.ins().iadd(arg1, arg2);
120//!         builder.def_var(z, tmp);
121//!     }
122//!     {
123//!         let arg = builder.use_var(y);
124//!         builder.ins().brif(arg, block3, &[], block2, &[]);
125//!     }
126//!
127//!     builder.switch_to_block(block2);
128//!     builder.seal_block(block2);
129//!     {
130//!         let arg1 = builder.use_var(z);
131//!         let arg2 = builder.use_var(x);
132//!         let tmp = builder.ins().isub(arg1, arg2);
133//!         builder.def_var(z, tmp);
134//!     }
135//!     {
136//!         let arg = builder.use_var(y);
137//!         builder.ins().return_(&[arg]);
138//!     }
139//!
140//!     builder.switch_to_block(block3);
141//!     builder.seal_block(block3);
142//!
143//!     {
144//!         let arg1 = builder.use_var(y);
145//!         let arg2 = builder.use_var(x);
146//!         let tmp = builder.ins().isub(arg1, arg2);
147//!         builder.def_var(y, tmp);
148//!     }
149//!     builder.ins().jump(block1, &[]);
150//!     builder.seal_block(block1);
151//!
152//!     builder.finalize();
153//! }
154//!
155//! let flags = settings::Flags::new(settings::builder());
156//! let res = verify_function(&func, &flags);
157//! println!("{}", func.display());
158//! if let Err(errors) = res {
159//!     panic!("{}", errors);
160//! }
161//! ```
162
163#![deny(missing_docs, trivial_numeric_casts, unused_extern_crates)]
164#![warn(unused_import_braces)]
165#![cfg_attr(feature = "std", deny(unstable_features))]
166#![cfg_attr(feature = "cargo-clippy", allow(clippy::new_without_default))]
167#![cfg_attr(
168    feature = "cargo-clippy",
169    warn(
170        clippy::float_arithmetic,
171        clippy::mut_mut,
172        clippy::nonminimal_bool,
173        clippy::map_unwrap_or,
174        clippy::clippy::print_stdout,
175        clippy::unicode_not_nfc,
176        clippy::use_self
177    )
178)]
179#![no_std]
180
181#[allow(unused_imports)] // #[macro_use] is required for no_std
182#[macro_use]
183extern crate alloc;
184
185#[cfg(feature = "std")]
186#[macro_use]
187extern crate std;
188
189#[cfg(not(feature = "std"))]
190use hashbrown::HashMap;
191#[cfg(feature = "std")]
192use std::collections::HashMap;
193
194pub use crate::frontend::{FunctionBuilder, FunctionBuilderContext};
195pub use crate::switch::Switch;
196pub use crate::variable::Variable;
197
198mod frontend;
199mod ssa;
200mod switch;
201mod variable;
202
203/// Version number of this crate.
204pub const VERSION: &str = env!("CARGO_PKG_VERSION");
cranelift_frontend/lib.rs

cranelift_frontend/
lib.rs
