T0b1/wasmtime
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

cranelift: Remove EBB references from docs (#6235)

Browse Source 
* Remove ebb references from compare-llvm.md

* Remove EBB references from ir.md

* Remove EBB references from testing.md

* Fix grammar

* Clean up discussion of conditionals terminating BBs

* Remove a reference to boolean types
This commit is contained in:
Trevor Elliott
2023-04-18 16:01:45 -07:00
committed by GitHub
parent 51ed20ab4d
commit c17a3d89f7
3 changed files with 43 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
cranelift/docs/compare-llvm.md
View File

@@ -125,20 +125,13 @@ the [cranelift-module](https://docs.rs/cranelift-module/) crate. It provides
facilities for working with modules, which can contain multiple functions as facilities for working with modules, which can contain multiple functions as
well as data objects, and it links them together. well as data objects, and it links them together.
An LLVM IR function is a graph of *basic blocks*. A Cranelift IR function is a Both LLVM and Cranelift use a graph of *basic blocks* as their IR for functions.
graph of *extended basic blocks* that may contain internal branch instructions. However, LLVM uses
The main difference is that an LLVM conditional branch instruction has two [phi instructions](https://llvm.org/docs/LangRef.html#phi-instruction) in its
target basic blocks---a true and a false edge. A Cranelift branch instruction SSA representation while Cranelift passes arguments to BBs instead. The two
only has a single target and falls through to the next instruction when its representations are equivalent, but the BB arguments are better suited to handle
condition is false. The Cranelift representation is closer to how machine code BBs that may contain multiple branches to the same destination block with
works; LLVM's representation is more abstract. different arguments. Passing arguments to a BB looks a lot like passing
LLVM uses
[phi instructions](https://llvm.org/docs/LangRef.html#phi-instruction)
in its SSA representation. Cranelift passes arguments to EBBs instead. The two
representations are equivalent, but the EBB arguments are better suited to
handle EBBs that may contain multiple branches to the same destination block
with different arguments. Passing arguments to an EBB looks a lot like passing
arguments to a function call, and the register allocator treats them very arguments to a function call, and the register allocator treats them very
similarly. Arguments are assigned to registers or stack locations. similarly. Arguments are assigned to registers or stack locations.

96
cranelift/docs/ir.md
View File

@@ -86,10 +86,10 @@ Then follows the [function preamble] which declares a number of entities
that can be referenced inside the function. In the example above, the preamble that can be referenced inside the function. In the example above, the preamble
declares a single explicit stack slot, `ss0`. declares a single explicit stack slot, `ss0`.
After the preamble follows the [function body] which consists of After the preamble follows the [function body] which consists of [basic block]s
[extended basic block]s (EBBs), the first of which is the (BBs), the first of which is the [entry block]. Every BB ends with a
[entry block]. Every EBB ends with a [terminator instruction], so [terminator instruction], so execution can never fall through to the next BB
execution can never fall through to the next EBB without an explicit branch. without an explicit branch.
A `.clif` file consists of a sequence of independent function definitions: A `.clif` file consists of a sequence of independent function definitions:
@@ -97,7 +97,7 @@ A `.clif` file consists of a sequence of independent function definitions:
function_list : { function } function_list : { function }
function : "function" function_name signature "{" preamble function_body "}" function : "function" function_name signature "{" preamble function_body "}"
preamble : { preamble_decl } preamble : { preamble_decl }
function_body : { extended_basic_block } function_body : { basic_block }
``` ```
### Static single assignment form ### Static single assignment form
@@ -106,18 +106,18 @@ The instructions in the function body use and produce *values* in SSA form. This
means that every value is defined exactly once, and every use of a value must be means that every value is defined exactly once, and every use of a value must be
dominated by the definition. dominated by the definition.
Cranelift does not have phi instructions but uses [EBB parameter]s Cranelift does not have phi instructions but uses [BB parameter]s
instead. An EBB can be defined with a list of typed parameters. Whenever control instead. A BB can be defined with a list of typed parameters. Whenever control
is transferred to the EBB, argument values for the parameters must be provided. is transferred to the BB, argument values for the parameters must be provided.
When entering a function, the incoming function parameters are passed as When entering a function, the incoming function parameters are passed as
arguments to the entry EBB's parameters. arguments to the entry BB's parameters.
Instructions define zero, one, or more result values. All SSA values are either Instructions define zero, one, or more result values. All SSA values are either
EBB parameters or instruction results. BB parameters or instruction results.
In the example above, the loop induction variable `i` is represented In the example above, the loop induction variable `i` is represented
as three SSA values: In `block2`, `v3` is the initial value. In the as three SSA values: In `block2`, `v3` is the initial value. In the
loop block `block3`, the EBB parameter `v4` represents the value of the loop block `block3`, the BB parameter `v4` represents the value of the
induction variable during each iteration. Finally, `v11` is computed induction variable during each iteration. Finally, `v11` is computed
as the induction variable value for the next iteration. as the induction variable value for the next iteration.
@@ -248,7 +248,7 @@ Mem
Any type that can be stored in memory: `Int` or `Float`. Any type that can be stored in memory: `Int` or `Float`.
Testable Testable
Either `b1` or `iN`. `iN`
### Immediate operand types ### Immediate operand types
@@ -321,24 +321,14 @@ Signaling NaNs
## Control flow ## Control flow
Branches transfer control to a new EBB and provide values for the target EBB's Branches transfer control to a new BB and provide values for the target BB's
arguments, if it has any. Conditional branches only take the branch if their arguments, if it has any. Conditional branches terminate a BB, and transfer to
condition is satisfied, otherwise execution continues at the following the first BB if the condition is satisfied, and the second otherwise.
instruction in the EBB.
JT = jump_table [EBB0, EBB1, ..., EBBn] The `br_table v, BB(args), [BB1(args)...BBn(args)]` looks up the index `v` in
Declare a jump table in the [function preamble]. the inline jump table given as the third argument, and jumps to that BB. If `v`
is out of bounds for the jump table, the default BB (second argument) is used
This declares a jump table for use by the `br_table` indirect branch instead.
instruction. Entries in the table are EBB names.
The EBBs listed must belong to the current function, and they can't have
any arguments.
:arg EBB0: Target EBB when `x = 0`.
:arg EBB1: Target EBB when `x = 1`.
:arg EBBn: Target EBB when `x = n`.
:result: A jump table identifier. (Not an SSA value).
Traps stop the program because something went wrong. The exact behavior depends Traps stop the program because something went wrong. The exact behavior depends
on the target instruction set architecture and operating system. There are on the target instruction set architecture and operating system. There are
@@ -711,10 +701,10 @@ implementation will panic.
Number of instructions in a function Number of instructions in a function
At most :math:`2^{31} - 1`. At most :math:`2^{31} - 1`.
Number of EBBs in a function Number of BBs in a function
At most :math:`2^{31} - 1`. At most :math:`2^{31} - 1`.
Every EBB needs at least a terminator instruction anyway. Every BB needs at least a terminator instruction anyway.
Number of secondary values in a function Number of secondary values in a function
At most :math:`2^{31} - 1`. At most :math:`2^{31} - 1`.
@@ -728,13 +718,13 @@ Other entities declared in the preamble
This covers things like stack slots, jump tables, external functions, and This covers things like stack slots, jump tables, external functions, and
function signatures, etc. function signatures, etc.
Number of arguments to an EBB Number of arguments to a BB
At most :math:`2^{16}`. At most :math:`2^{16}`.
Number of arguments to a function Number of arguments to a function
At most :math:`2^{16}`. At most :math:`2^{16}`.
This follows from the limit on arguments to the entry EBB. Note that This follows from the limit on arguments to the entry BB. Note that
Cranelift may add a handful of ABI register arguments as function signatures Cranelift may add a handful of ABI register arguments as function signatures
are lowered. This is for representing things like the link register, the are lowered. This is for representing things like the link register, the
incoming frame pointer, and callee-saved registers that are saved in the incoming frame pointer, and callee-saved registers that are saved in the
@@ -767,37 +757,21 @@ Size of function call arguments on the stack
the last instruction. the last instruction.
entry block entry block
The [EBB] that is executed first in a function. Currently, a The [BB] that is executed first in a function. Currently, a
Cranelift function must have exactly one entry block which must be the Cranelift function must have exactly one entry block which must be the
first block in the function. The types of the entry block arguments must first block in the function. The types of the entry block arguments must
match the types of arguments in the function signature. match the types of arguments in the function signature.
extended basic block BB parameter
EBB A formal parameter for a BB is an SSA value that dominates everything
A maximal sequence of instructions that can only be entered from the in the BB. For each parameter declared by a BB, a corresponding
top, and that contains no [terminator instruction]s except for argument value must be passed when branching to the BB. The function's
the last one. An EBB can contain conditional branches that can fall entry BB has parameters that correspond to the function's parameters.
through to the following instructions in the block, but only the first
instruction in the EBB can be a branch target.
The last instruction in an EBB must be a [terminator instruction], BB argument
so execution cannot flow through to the next EBB in the function. (But Similar to function arguments, BB arguments must be provided when
there may be a branch to the next EBB.) branching to a BB that declares formal parameters. When execution
begins at the top of a BB, the formal parameters have the values of
Note that some textbooks define an EBB as a maximal *subtree* in the
control flow graph where only the root can be a join node. This
definition is not equivalent to Cranelift EBBs.
EBB parameter
A formal parameter for an EBB is an SSA value that dominates everything
in the EBB. For each parameter declared by an EBB, a corresponding
argument value must be passed when branching to the EBB. The function's
entry EBB has parameters that correspond to the function's parameters.
EBB argument
Similar to function arguments, EBB arguments must be provided when
branching to an EBB that declares formal parameters. When execution
begins at the top of an EBB, the formal parameters have the values of
the arguments passed in the branch. the arguments passed in the branch.
function signature function signature
@@ -824,8 +798,8 @@ Size of function call arguments on the stack
- Function flags and attributes that are not part of the signature. - Function flags and attributes that are not part of the signature.
function body function body
The extended basic blocks which contain all the executable code in a The basic blocks which contain all the executable code in a function.
function. The function body follows the function preamble. The function body follows the function preamble.
intermediate representation intermediate representation
IR IR

2
cranelift/docs/testing.md
View File

@@ -205,7 +205,7 @@ Compute the dominator tree of each function and validate it against the
} }
``` ```
Every reachable extended basic block except for the entry block has an Every reachable basic block except for the entry block has an
*immediate dominator* which is a jump or branch instruction. This test passes *immediate dominator* which is a jump or branch instruction. This test passes
if the `dominates:` annotations on the immediate dominator instructions are if the `dominates:` annotations on the immediate dominator instructions are
both correct and complete. both correct and complete.