This is the fifth part of a series; see the first part for a table of contents.
With
bit sequences, we have already seen one unusual feature of TableGen that is geared towards its specific purpose.
DAG nodes are another; they look a bit like S-expressions:
def op1;
def op2;
def i32:
def Example {
dag x = (op1 $foo, (op2 i32:$bar, "Hi"));
}
In the example, there are two
DAG nodes, represented by a
DagInit object in the code. The first node has as its
operation the record
op1. The operation of a DAG node must be a record, but there are no other restrictions. This node has two children or
arguments: the first argument is named
foo but has no value. The second argument has no name, but it does have another DAG node as its value.
This second DAG node has the operation
op2 and two arguments. The first argument is named
bar and has value
i32, the second has no name and value
"Hi".
DAG nodes can have any number of arguments, and they can be nested arbitrarily. The values of arguments can have any type, at least as far as the TableGen frontend is concerned. So DAGs are an extremely free-form way of representing data, and they are really only given meaning by TableGen backends.
There are three main uses of DAGs:
- Describing the operands on machine instructions.
- Describing patterns for instruction selection.
- Describing register files with something called "set theory".
I have not yet had the opportunity to explore the last point in detail, so I will only give an overview of the first two uses here.
Describing the operands of machine instructions is fairly straightforward at its core, but the details can become quite elaborate.
I will illustrate some of this with the example of the
V_ADD_F32 instruction from the AMDGPU backend.
V_ADD_F32 is a standard 32-bit floating point addition, at least in its 32-bit-encoded variant, which the backend represents as
V_ADD_F32_e32.
Let's take a look at some of the fully resolved records produced by the TableGen frontend:
def V_ADD_F32_e32 { // Instruction AMDGPUInst ...
dag OutOperandList = (outs anonymous_503:$vdst);
dag InOperandList = (ins VSrc_f32:$src0, VGPR_32:$src1);
string AsmOperands = "$vdst, $src0, $src1";
...
}
def anonymous_503 { // DAGOperand RegisterOperand VOPDstOperand
RegisterClass RegClass = VGPR_32;
string PrintMethod = "printVOPDst";
...
}
As you'd expect, there is one
out operand. It is named
vdst and an anonymous record is used to describe more detailed information such as its register class (a 32-bit general purpose vector register) and the name of a special method for printing the operand in textual assembly output. (The string
"printVOPDst" will be used by the backend that generates the bulk of the instruction printer code, and refers to the method
AMDGPUInstPrinter::printVOPDst that is implemented manually.)
There are two
in operands.
src1 is a 32-bit general purpose vector register and requires no special handling, but
src0 supports more complex operands as described in the record
VSrc_f32 elsewhere.
Also note the string
AsmOperands, which is used as a template for the automatically generated instruction printer code. The operand names in that string refer to the names of the operands as defined in the DAG nodes.
This was a nice warmup, but didn't really demonstrate the full power and flexibility of DAG nodes. Let's look at
V_ADD_F32_e64, the 64-bit encoded version,
which has some additional features: the sign bits of the inputs can be reset or inverted, and the result (output) can be clamped and/or scaled by some fixed constants (0.5, 2, and 4). This will seem familiar to anybody who has worked with the old
OpenGL assembly program extensions or with DirectX shader assembly.
The fully resolved records produced by the TableGen frontend are quite a bit more involved:
def V_ADD_F32_e64 { // Instruction AMDGPUInst ...
dag OutOperandList = (outs anonymous_503:$vdst);
dag InOperandList =
(ins FP32InputMods:$src0_modifiers, VCSrc_f32:$src0,
FP32InputMods:$src1_modifiers, VCSrc_f32:$src1,
clampmod:$clamp, omod:$omod);
string AsmOperands = "$vdst, $src0_modifiers, $src1_modifiers$clamp$omod";
list<dag> Pattern =
[(set f32:$vdst, (fadd
(f32 (VOP3Mods0 f32:$src0, i32:$src0_modifiers,
i1:$clamp, i32:$omod)),
(f32 (VOP3Mods f32:$src1, i32:$src1_modifiers))))];
...
}
def FP32InputMods { // DAGOperand Operand InputMods FPInputMods
ValueType Type = i32;
string PrintMethod = "printOperandAndFPInputMods";
AsmOperandClass ParserMatchClass = FP32InputModsMatchClass;
...
}
def FP32InputModsMatchClass { // AsmOperandClass FPInputModsMatchClass
string Name = "RegOrImmWithFP32InputMods";
string PredicateMethod = "isRegOrImmWithFP32InputMods";
string ParserMethod = "parseRegOrImmWithFPInputMods";
...
}
The
out operand hasn't changed, but there are now many more special
in operands that describe whether those additional features of the instruction are used.
You can again see how records such as
FP32InputMods refer to manually implemented methods. Also note that the
AsmOperands string no longer refers to
src0 or
src1. Instead, the
printOperandAndFPInputMods method on
src0_modifiers and
src1_modifiers will print the source operand together with its sign modifiers. Similarly, the special
ParserMethod parseRegOrImmWithFPInputMods will be used by the assembly parser.
This kind of extensibility by combining generic automatically generated code with manually implemented methods is used throughout the TableGen backends for code generation.
Something else is new here: the
Pattern. This pattern, together will all the other patterns defined elsewhere, is compiled into a giant domain-specific bytecode that executes during instruction selection to turn the
SelectionDAG into machine instructions. Let's take this particular pattern apart:
(set f32:$vdst, (fadd ...))
We will match an
fadd selection DAG node that outputs a 32-bit floating point value, and this output will be linked to the out operand
vdst. (
set,
fadd and many others are defined in the target-independent
include/llvm/Target/TargetSelectionDAG.td.)
(fadd (f32 (VOP3Mods0 f32:$src0, i32:$src0_modifiers,
i1:$clamp, i32:$omod)),
(f32 (VOP3Mods f32:$src1, i32:$src1_modifiers)))
Both input operands of the fadd node must be 32-bit floating point values, and they will be handled by
complex patterns. Here's one of them:
def VOP3Mods { // ComplexPattern
string SelectFunc = "SelectVOP3Mods";
int NumOperands = 2;
...
}
As you'd expect, there's a manually implemented
SelectVOP3Mods method. Its signature is
bool SelectVOP3Mods(SDValue In, SDValue &Src,
SDValue &SrcMods) const;
It can reject the match by returning
false, otherwise it pattern matches a single input SelectionDAG node into nodes that will be placed into
src1 and
src1_modifiers in the particular pattern we were studying.
Patterns can be arbitrarily complex, and they can be defined outside of instructions as well. For example, here's a pattern for generating the
S_BFM_B32 instruction, which generates a bitfield mask:
def anonymous_2373anonymous_2371 { // Pattern Pat ...
dag PatternToMatch =
(i32 (shl (i32 (add (i32 (shl 1, i32:$a)), -1)), i32:$b));
list<dag> ResultInstrs = [(S_BFM_B32 ?:$a, ?:$b)];
...
}
The name of this record doesn't matter. The instruction selection TableGen backend simply looks for all records that have
Pattern as a superclass. In this case, we match an expression of the form
((1 << a) - 1) << b on 32-bit integers into a single machine instruction.
So far, we've mostly looked at how DAGs are interpreted by some of the key backends of TableGen. As it turns out, most backends generate their DAGs in a fairly static way, but there are some fancier techniques that can be used as well. This post is already quite long though, so we'll look at those in the next post.
