-TableGen allows for a pretty reasonable number of different expression forms +
TableGen allows for a pretty reasonable number of different expression forms when building up values. These forms allow the TableGen file to be written in a natural syntax and flavor for the application. The current expression forms -supported include: -
- --
-
- ? - Uninitialized field. -
- 0b1001011 - Binary integer value. -
- 07654321 - Octal integer value (indicated by a leading 0). -
- 7 - Decimal integer value. -
- 0x7F - Hexadecimal integer value. -
- "foo" - String value. -
- [{ .... }] - Code fragment. -
- [ X, Y, Z ] - List value. -
- { a, b, c } - Initializer for a "bits<3>" value. -
- value - Value reference. -
- value{17} - Access to one or more bits of a value. -
- DEF - Reference to a record definition. -
- X.Y - Reference to the subfield of a value. - -
- (DEF a, b) - A dag value. The first element is required to be a record -definition, the remaining elements in the list may be arbitrary other values, -including nested 'dag' values. - -
-Note that all of the values have rules specifying how they convert to to values -for different types. These rules allow you to assign a value like "7" to a -"bits<4>" value, for example. -
- - +supported include: + +-
+
- ? +
- uninitialized field +
- 0b1001011 +
- binary integer value +
- 07654321 +
- octal integer value (indicated by a leading 0) +
- 7 +
- decimal integer value +
- 0x7F +
- hexadecimal integer value +
- "foo" +
- string value +
- [{ ... }] +
- code fragment +
- [ X, Y, Z ] +
- list value. +
- { a, b, c } +
- initializer for a "bits<3>" value +
- value +
- value reference +
- value{17} +
- access to one bit of a value +
- value{15-17} +
- access to multiple bits of a value +
- DEF +
- reference to a record definition +
- CLASS<val list> +
- reference to a new anonymous definition of CLASS with the specified + template arguments. +
- X.Y +
- reference to the subfield of a value +
- list[4-7,17,2-3] +
- A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from + it. Elements may be included multiple times. +
- (DEF a, b) +
- a dag value. The first element is required to be a record definition, the + remaining elements in the list may be arbitrary other values, including nested + `dag' values. +
- !strconcat(a, b) +
- A string value that is the result of concatenating the 'a' and 'b' + strings. +
Note that all of the values have rules specifying how they convert to values +for different types. These rules allow you to assign a value like "7" +to a "bits<4>" value, for example.
-As mentioned in the intro, classes and definitions +
As mentioned in the intro, classes and definitions (collectively known as 'records') in TableGen are the main high-level unit of information that TableGen collects. Records are defined with a def or class keyword, the record name, and an optional list of "template arguments". If the record has superclasses, -they are specified as a comma seperated list that starts with a colon character -(":"). If value definitions or let -expressions are needed for the class they are enclosed in curly braces -("{}"), otherwise the record ends with a semicolon. Here is a simple TableGen -file: -
+href="#templateargs">template arguments". If the record has superclasses, +they are specified as a comma separated list that starts with a colon character +(":"). If value definitions or let expressions are needed for the class, they are +enclosed in curly braces ("{}"); otherwise, the record ends with a +semicolon. -
-class C { bit V = 1; }
-def X : C;
-def Y : C {
- string Greeting = "hello";
+Here is a simple TableGen file:
+
+
+
+class C { bit V = 1; }
+def X : C;
+def Y : C {
+ string Greeting = "hello";
}
-
+
+
-
-This example defines two definitions, X and Y, both of which
-derive from the C class. Because of this, they both get the V
-bit value. The Y definition also gets the Greeting member as well.
-
+This example defines two definitions, X and Y, both of
+which derive from the C class. Because of this, they both get the
+V bit value. The Y definition also gets the Greeting member
+as well.
+
+In general, classes are useful for collecting together the commonality
+between a group of records and isolating it in a single place. Also, classes
+permit the specification of default values for their subclasses, allowing the
+subclasses to override them as they wish.
-Value definitions define named entries in records. A value must be defined -before it can be referred to as the operand for another value definition, or + +
Value definitions define named entries in records. A value must be defined +before it can be referred to as the operand for another value definition or before the value is reset with a let expression. A value is defined by specifying a TableGen type and a name. If an initial value is available, it may be specified after the type with an -equal sign. Value definitions require terminating semicolons. +equal sign. Value definitions require terminating semicolons.
+-A record-level let expression is used to change the value of a value definition -in a record. This is primarily useful when a superclass defines a value that a -derived class or definitions wants to override. Let expressions consist of the -'let' keyword, followed by a value name, an equal sign ("="), and a new -value for example, a new class could be added to the example above, redefining -the V field for all of its subclasses:
- -
-class D : C { let V = 0; }
-def Z : D;
-
--In this case, the Z definition will have a zero value for its "V" +
A record-level let expression is used to change the value of a value +definition in a record. This is primarily useful when a superclass defines a +value that a derived class or definition wants to override. Let expressions +consist of the 'let' keyword followed by a value name, an equal sign +("="), and a new value. For example, a new class could be added to the +example above, redefining the V field for all of its subclasses:
+ +
+class D : C { let V = 0; }
+def Z : D;
+
+In this case, the Z definition will have a zero value for its "V" value, despite the fact that it derives (indirectly) from the C class, -because the D class overrode its value. -
+because the D class overrode its value.TableGen permits the definition of parameterized classes as well as normal +concrete classes. Parameterized TableGen classes specify a list of variable +bindings (which may optionally have defaults) that are bound when used. Here is +a simple example:
+ +
+class FPFormat<bits<3> val> {
+ bits<3> Value = val;
+}
+def NotFP : FPFormat<0>;
+def ZeroArgFP : FPFormat<1>;
+def OneArgFP : FPFormat<2>;
+def OneArgFPRW : FPFormat<3>;
+def TwoArgFP : FPFormat<4>;
+def CompareFP : FPFormat<5>;
+def CondMovFP : FPFormat<6>;
+def SpecialFP : FPFormat<7>;
+
In this case, template arguments are used as a space efficient way to specify +a list of "enumeration values", each with a "Value" field set to the +specified integer.
+The more esoteric forms of TableGen expressions are +useful in conjunction with template arguments. As an example:
- - +
+class ModRefVal<bits<2> val> {
+ bits<2> Value = val;
+}
-
-
- File inclusion
+def None : ModRefVal<0>;
+def Mod : ModRefVal<1>;
+def Ref : ModRefVal<2>;
+def ModRef : ModRefVal<3>;
+
+class Value<ModRefVal MR> {
+ // Decode some information into a more convenient format, while providing
+ // a nice interface to the user of the "Value" class.
+ bit isMod = MR.Value{0};
+ bit isRef = MR.Value{1};
+
+ // other stuff...
+}
+
+// Example uses
+def bork : Value<Mod>;
+def zork : Value<Ref>;
+def hork : Value<ModRef>;
+
-
-
-TableGen supports the 'include' token, which textually substitutes the
-specified file in place of the include directive. The filename should be
-specified as a double quoted string immediately after the 'include'
-keyword. Example:
+
This is obviously a contrived example, but it shows how template arguments
+can be used to decouple the interface provided to the user of the class from the
+actual internal data representation expected by the class. In this case,
+running tblgen on the example prints the following definitions:
+
+
+
+def bork { // Value
+ bit isMod = 1;
+ bit isRef = 0;
+}
+def hork { // Value
+ bit isMod = 1;
+ bit isRef = 1;
+}
+def zork { // Value
+ bit isMod = 0;
+ bit isRef = 1;
+}
+
+
-
- include "foo.td"
-
+ This shows that TableGen was able to dig into the argument and extract a
+piece of information that was requested by the designer of the "Value" class.
+For more realistic examples, please see existing users of TableGen, such as the
+X86 backend.
-
+
+
-"let" expressions at file scope are similar to "let"
-expressions within a record, except they can specify a value binding for
-multiple records at a time, and may be useful in certain other cases.
-File-scope let expressions are really just another way that TableGen allows the
-end-user to factor out commonality from the records.
+While classes with template arguments are a good way to factor commonality
+between two instances of a definition, multiclasses allow a convenient notation
+for defining multiple definitions at once (instances of implicitly constructed
+classes). For example, consider an 3-address instruction set whose instructions
+come in two forms: "reg = reg op reg" and "reg = reg op imm"
+(e.g. SPARC). In this case, you'd like to specify in one place that this
+commonality exists, then in a separate place indicate what all the ops are.
-File-scope "let" expressions take a comma-seperated list of bindings to apply,
-and one of more records to bind the values in. Here are some examples:
+Here is an example TableGen fragment that shows this idea:
-
-let isTerminator = 1, isReturn = 1 in
- def RET : X86Inst<"ret", 0xC3, RawFrm, NoArg>;
+
+
+def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+multiclass ri_inst<int opc, string asmstr> {
+ def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+ def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+}
-let isCall = 1 in
- // All calls clobber the non-callee saved registers...
- let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6] in {
- def CALLpcrel32 : X86Inst<"call", 0xE8, RawFrm, NoArg>;
- def CALLr32 : X86Inst<"call", 0xFF, MRMS2r, Arg32>;
- def CALLm32 : X86Inst<"call", 0xFF, MRMS2m, Arg32>;
- }
-
+// Instantiations of the ri_inst multiclass.
+defm ADD : ri_inst<0b111, "add">;
+defm SUB : ri_inst<0b101, "sub">;
+defm MUL : ri_inst<0b100, "mul">;
+...
+
+
-
-File-scope "let" expressions are often useful when a couple of definitions need
-to be added to several records, and the records do not otherwise need to be
-opened, as in the case with the CALL* instructions above.
-
+The name of the resultant definitions has the multidef fragment names
+ appended to them, so this defines ADD_rr, ADD_ri,
+ SUB_rr, etc. Using a multiclass this way is exactly equivalent to
+ instantiating the classes multiple times yourself, e.g. by writing:
+
+
+
+def ops;
+def GPR;
+def Imm;
+class inst<int opc, string asmstr, dag operandlist>;
+
+class rrinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
+
+class riinst<int opc, string asmstr>
+ : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
+ (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
+
+// Instantiations of the ri_inst multiclass.
+def ADD_rr : rrinst<0b111, "add">;
+def ADD_ri : riinst<0b111, "add">;
+def SUB_rr : rrinst<0b101, "sub">;
+def SUB_ri : riinst<0b101, "sub">;
+def MUL_rr : rrinst<0b100, "mul">;
+def MUL_ri : riinst<0b100, "mul">;
+...
+
+
-
-
-
+
+
+
+
+
+ File inclusion
+
+TableGen supports the 'include' token, which textually substitutes
+the specified file in place of the include directive. The filename should be
+specified as a double quoted string immediately after the 'include'
+keyword. Example:
-
-How they work, how to write one. This section should not contain details about
-any particular backend, except maybe -print-enums as an example. This should
-highlight the APIs in TableGen/Record.h.
-
+
+
+include "foo.td"
+
+
+
+
+
+
+
+
+"Let" expressions at file scope are similar to "let"
+expressions within a record, except they can specify a value binding for
+multiple records at a time, and may be useful in certain other cases.
+File-scope let expressions are really just another way that TableGen allows the
+end-user to factor out commonality from the records.
+
+File-scope "let" expressions take a comma-separated list of bindings to
+apply, and one of more records to bind the values in. Here are some
+examples:
+
+
+
+let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
+ def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
+
+let isCall = 1 in
+ // All calls clobber the non-callee saved registers...
+ let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
+ MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
+ XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
+ def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
+ "call\t${dst:call}", []>;
+ def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
+ "call\t{*}$dst", [(X86call GR32:$dst)]>;
+ def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
+ "call\t{*}$dst", []>;
+ }
+
+
+
+File-scope "let" expressions are often useful when a couple of definitions
+need to be added to several records, and the records do not otherwise need to be
+opened, as in the case with the CALL* instructions above.
+
+
-
+
-
-This is just a temporary, convenient, place to put stuff about the code
-generator before it gets its own document. This should describe all of the
-tablegen backends used by the code generator and the classes/definitions they
-expect.
-
+TODO: How they work, how to write one. This section should not contain
+details about any particular backend, except maybe -print-enums as an example.
+This should highlight the APIs in TableGen/Record.h.
-
-
+
-
- Chris Lattner
- The LLVM Compiler Infrastructure
-
+
+ 
+ 
+
+ Chris Lattner
+ LLVM Compiler Infrastructure
Last modified: $Date$
-
+