167 releases (99 breaking)
0.114.0 | Nov 20, 2024 |
---|---|
0.113.0 | Oct 22, 2024 |
0.110.1 | Jul 22, 2024 |
0.106.0 | Mar 20, 2024 |
0.17.0 | Jul 24, 2018 |
#35 in Programming languages
512,414 downloads per month
Used in 505 crates
(20 directly)
4.5MB
104K
SLoC
This crate provides a straightforward way to create a
Cranelift IR function and fill it with
instructions translated from another language. It contains an SSA construction
module that provides convenient methods for translating non-SSA variables into
SSA Cranelift IR values via use_var
and def_var
calls.
lib.rs
:
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
and
pass it as an argument to a FunctionBuilder
.
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 has a
type Variable
that should be an index of your source language variables. Then, through
calling the functions
declare_var
, def_var
and
use_var
, the FunctionBuilder
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
form.
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
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:
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
:
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);
}
Dependencies
~5MB
~92K SLoC