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

#![deny(missing_docs)]
#![no_std]

#[allow(unused_imports)] // #[macro_use] is required for no_std
#[macro_use]
extern crate alloc;

#[cfg(feature = "std")]
#[macro_use]
extern crate std;

#[cfg(not(feature = "std"))]
use hashbrown::HashMap;
#[cfg(feature = "std")]
use std::collections::HashMap;

pub use crate::frontend::{FuncInstBuilder, FunctionBuilder, FunctionBuilderContext};
pub use crate::switch::Switch;
pub use crate::variable::Variable;

mod frontend;
mod ssa;
mod switch;
mod variable;

/// Version number of this crate.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");