Module cranelift_codegen::machinst

This module exposes the machine-specific backend definition pieces.

The MachInst infrastructure is the compiler backend, from CLIF (ir::Function) to machine code. The purpose of this infrastructure is, at a high level, to do instruction selection/lowering (to machine instructions), register allocation, and then perform all the fixups to branches, constant data references, etc., needed to actually generate machine code.

The container for machine instructions, at various stages of construction, is the VCode struct. We refer to a sequence of machine instructions organized into basic blocks as “vcode”. This is short for “virtual-register code”, though it’s a bit of a misnomer because near the end of the pipeline, vcode has all real registers. Nevertheless, the name is catchy and we like it.

The compilation pipeline, from an ir::Function (already optimized as much as you like by machine-independent optimization passes) onward, is as follows. (N.B.: though we show the VCode separately at each stage, the passes mutate the VCode in place; these are not separate copies of the code.)

    ir::Function                (SSA IR, machine-independent opcodes)
        |
        |  [lower]
        |
    VCode<arch_backend::Inst>   (machine instructions:
        |                        - mostly virtual registers.
        |                        - cond branches in two-target form.
        |                        - branch targets are block indices.
        |                        - in-memory constants held by insns,
        |                          with unknown offsets.
        |                        - critical edges (actually all edges)
        |                          are split.)
        | [regalloc]
        |
    VCode<arch_backend::Inst>   (machine instructions:
        |                        - all real registers.
        |                        - new instruction sequence returned
        |                          out-of-band in RegAllocResult.
        |                        - instruction sequence has spills,
        |                          reloads, and moves inserted.
        |                        - other invariants same as above.)
        |
        | [preamble/postamble]
        |
    VCode<arch_backend::Inst>   (machine instructions:
        |                        - stack-frame size known.
        |                        - out-of-band instruction sequence
        |                          has preamble prepended to entry
        |                          block, and postamble injected before
        |                          every return instruction.
        |                        - all symbolic stack references to
        |                          stackslots and spillslots are resolved
        |                          to concrete FP-offset mem addresses.)
        |
        | [binary emission via MachBuffer
        |  with streaming branch resolution/simplification]
        |
    Vec<u8>                     (machine code!)

Re-exports

pub use lower::*;
pub use vcode::*;
pub use compile::*;
pub use blockorder::*;
pub use abi::*;
pub use abi_impl::*;
pub use buffer::*;
pub use adapter::*;
pub use helpers::*;
pub use inst_common::*;
pub use valueregs::*;

Modules

abi	ABI definitions.
abi_impl	Implementation of a vanilla ABI, shared between several machines. The implementation here assumes that arguments will be passed in registers first, then additional args on the stack; that the stack grows downward, contains a standard frame (return address and frame pointer), and the compiler is otherwise free to allocate space below that with its choice of layout; and that the machine has some notion of caller- and callee-save registers. Most modern machines, e.g. x86-64 and AArch64, should fit this mold and thus both of these backends use this shared implementation.
adapter	Adapter for a MachBackend to implement the TargetIsa trait.
blockorder	Computation of basic block order in emitted code.
buffer	In-memory representation of compiled machine code, with labels and fixups to refer to those labels. Handles constant-pool island insertion and also veneer insertion for out-of-range jumps.
compile	Compilation backend pipeline: optimized IR to VCode / binemit.
debug	Debug info analysis: computes value-label ranges from value-label markers in generated VCode.
helpers	Miscellaneous helpers for machine backends.
inst_common	A place to park MachInst::Inst fragments which are common across multiple architectures.
lower	This module implements lowering (instruction selection) from Cranelift IR to machine instructions with virtual registers. This is almost the final machine code, except for register allocation.
valueregs	Data structure for tracking the (possibly multiple) registers that hold one SSA Value.
vcode	This implements the VCode container: a CFG of Insts that have been lowered.

Structs

MachCompileResult

The result of a MachBackend::compile_function() call. Contains machine code (as bytes) and a disassembly, if requested.

Enums

MachInstStackOpInfo	Info about an operation that loads or stores from/to the stack.
MachTerminator	Describes a block terminator (not call) in the vcode, when its branches have not yet been finalized (so a branch may have two targets).
UnwindInfoKind	Expected unwind info type.

Traits

MachBackend	Top-level machine backend trait, which wraps all monomorphized code and allows a virtual call from the machine-independent Function::compile().
MachInst	A machine instruction.
MachInstEmit	A trait describing the ability to encode a MachInst into binary machine code.
MachInstEmitInfo	Constant information used to emit an instruction.
MachInstEmitState	A trait describing the emission state carried between MachInsts when emitting a function body.
MachInstLabelUse	A descriptor of a label reference (use) in an instruction set.