13 TableGen's purpose is to help a human develop and maintain records of
14 domain-specific information. Because there may be a large number of these
15 records, it is specifically designed to allow writing flexible descriptions and
16 for common features of these records to be factored out. This reduces the
17 amount of duplication in the description, reduces the chance of error, and makes
18 it easier to structure domain specific information.
20 The core part of TableGen `parses a file`_, instantiates the declarations, and
21 hands the result off to a domain-specific `TableGen backend`_ for processing.
22 The current major user of TableGen is the `LLVM code
23 generator <CodeGenerator.html>`_.
25 Note that if you work on TableGen much, and use emacs or vim, that you can find
26 an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and
27 ``llvm/utils/vim`` directories of your LLVM distribution, respectively.
34 TableGen files consist of two key parts: 'classes' and 'definitions', both of
35 which are considered 'records'.
37 **TableGen records** have a unique name, a list of values, and a list of
38 superclasses. The list of values is the main data that TableGen builds for each
39 record; it is this that holds the domain specific information for the
40 application. The interpretation of this data is left to a specific `TableGen
41 backend`_, but the structure and format rules are taken care of and are fixed by
44 **TableGen definitions** are the concrete form of 'records'. These generally do
45 not have any undefined values, and are marked with the '``def``' keyword.
47 **TableGen classes** are abstract records that are used to build and describe
48 other records. These 'classes' allow the end-user to build abstractions for
49 either the domain they are targeting (such as "Register", "RegisterClass", and
50 "Instruction" in the LLVM code generator) or for the implementor to help factor
51 out common properties of records (such as "FPInst", which is used to represent
52 floating point instructions in the X86 backend). TableGen keeps track of all of
53 the classes that are used to build up a definition, so the backend can find all
54 definitions of a particular class, such as "Instruction".
56 **TableGen multiclasses** are groups of abstract records that are instantiated
57 all at once. Each instantiation can result in multiple TableGen definitions.
58 If a multiclass inherits from another multiclass, the definitions in the
59 sub-multiclass become part of the current multiclass, as if they were declared
60 in the current multiclass.
67 With no other arguments, TableGen parses the specified file and prints out all
68 of the classes, then all of the definitions. This is a good way to see what the
69 various definitions expand to fully. Running this on the ``X86.td`` file prints
70 this (at the time of this writing):
75 def ADD32rr { // Instruction X86Inst I
76 string Namespace = "X86";
77 dag OutOperandList = (outs GR32:$dst);
78 dag InOperandList = (ins GR32:$src1, GR32:$src2);
79 string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
80 list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
81 list<Register> Uses = [];
82 list<Register> Defs = [EFLAGS];
83 list<Predicate> Predicates = [];
85 int AddedComplexity = 0;
88 bit isIndirectBranch = 0;
91 bit canFoldAsLoad = 0;
94 bit isImplicitDef = 0;
95 bit isConvertibleToThreeAddress = 1;
98 bit isReMaterializable = 0;
100 bit hasDelaySlot = 0;
101 bit usesCustomInserter = 0;
103 bit isNotDuplicable = 0;
104 bit hasSideEffects = 0;
105 bit neverHasSideEffects = 0;
106 InstrItinClass Itinerary = NoItinerary;
107 string Constraints = "";
108 string DisableEncoding = "";
109 bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
110 Format Form = MRMDestReg;
111 bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
112 ImmType ImmT = NoImm;
113 bits<3> ImmTypeBits = { 0, 0, 0 };
114 bit hasOpSizePrefix = 0;
115 bit hasAdSizePrefix = 0;
116 bits<4> Prefix = { 0, 0, 0, 0 };
117 bit hasREX_WPrefix = 0;
119 bits<3> FPFormBits = { 0, 0, 0 };
123 This definition corresponds to a 32-bit register-register add instruction in the
124 X86. The string after the '``def``' string indicates the name of the
125 record---"``ADD32rr``" in this case---and the comment at the end of the line
126 indicates the superclasses of the definition. The body of the record contains
127 all of the data that TableGen assembled for the record, indicating that the
128 instruction is part of the "X86" namespace, the pattern indicating how the the
129 instruction should be emitted into the assembly file, that it is a two-address
130 instruction, has a particular encoding, etc. The contents and semantics of the
131 information in the record is specific to the needs of the X86 backend, and is
132 only shown as an example.
134 As you can see, a lot of information is needed for every instruction supported
135 by the code generator, and specifying it all manually would be unmaintainable,
136 prone to bugs, and tiring to do in the first place. Because we are using
137 TableGen, all of the information was derived from the following definition:
142 isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
143 isConvertibleToThreeAddress = 1 in // Can transform into LEA.
144 def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
145 (ins GR32:$src1, GR32:$src2),
146 "add{l}\t{$src2, $dst|$dst, $src2}",
147 [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
149 This definition makes use of the custom class ``I`` (extended from the custom
150 class ``X86Inst``), which is defined in the X86-specific TableGen file, to
151 factor out the common features that instructions of its class share. A key
152 feature of TableGen is that it allows the end-user to define the abstractions
153 they prefer to use when describing their information.
155 Each def record has a special entry called "``NAME``." This is the name of the
156 def ("``ADD32rr``" above). In the general case def names can be formed from
157 various kinds of string processing expressions and ``NAME`` resolves to the
158 final value obtained after resolving all of those expressions. The user may
159 refer to ``NAME`` anywhere she desires to use the ultimate name of the def.
160 ``NAME`` should not be defined anywhere else in user code to avoid conflict
166 TableGen runs just like any other LLVM tool. The first (optional) argument
167 specifies the file to read. If a filename is not specified, ``llvm-tblgen``
168 reads from standard input.
170 To be useful, one of the `TableGen backends`_ must be used. These backends are
171 selectable on the command line (type '``llvm-tblgen -help``' for a list). For
172 example, to get a list of all of the definitions that subclass a particular type
173 (which can be useful for building up an enum list of these records), use the
174 ``-print-enums`` option:
178 $ llvm-tblgen X86.td -print-enums -class=Register
179 AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
180 ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
181 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
182 R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
183 R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
184 RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
185 XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
186 XMM6, XMM7, XMM8, XMM9,
188 $ llvm-tblgen X86.td -print-enums -class=Instruction
189 ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
190 ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
191 ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
192 ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
193 ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
195 The default backend prints out all of the records, as `described above`_.
197 If you plan to use TableGen, you will most likely have to `write a backend`_
198 that extracts the information specific to what you need and formats it in the
206 TableGen doesn't care about the meaning of data (that is up to the backend to
207 define), but it does care about syntax, and it enforces a simple type system.
208 This section describes the syntax and the constructs allowed in a TableGen file.
216 TableGen supports BCPL style "``//``" comments, which run to the end of the
217 line, and it also supports **nestable** "``/* */``" comments.
221 The TableGen type system
222 ^^^^^^^^^^^^^^^^^^^^^^^^
224 TableGen files are strongly typed, in a simple (but complete) type-system.
225 These types are used to perform automatic conversions, check for errors, and to
226 help interface designers constrain the input that they allow. Every `value
227 definition`_ is required to have an associated type.
229 TableGen supports a mixture of very low-level types (such as ``bit``) and very
230 high-level types (such as ``dag``). This flexibility is what allows it to
231 describe a wide range of information conveniently and compactly. The TableGen
235 A 'bit' is a boolean value that can hold either 0 or 1.
238 The 'int' type represents a simple 32-bit integer value, such as 5.
241 The 'string' type represents an ordered sequence of characters of arbitrary
245 A 'bits' type is an arbitrary, but fixed, size integer that is broken up
246 into individual bits. This type is useful because it can handle some bits
247 being defined while others are undefined.
250 This type represents a list whose elements are some other type. The
251 contained type is arbitrary: it can even be another list type.
254 Specifying a class name in a type context means that the defined value must
255 be a subclass of the specified class. This is useful in conjunction with
256 the ``list`` type, for example, to constrain the elements of the list to a
257 common base class (e.g., a ``list<Register>`` can only contain definitions
258 derived from the "``Register``" class).
261 This type represents a nestable directed graph of elements.
264 This represents a big hunk of text. This is lexically distinct from string
265 values because it doesn't require escaping double quotes and other common
266 characters that occur in code.
268 To date, these types have been sufficient for describing things that TableGen
269 has been used for, but it is straight-forward to extend this list if needed.
271 .. _TableGen expressions:
273 TableGen values and expressions
274 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
276 TableGen allows for a pretty reasonable number of different expression forms
277 when building up values. These forms allow the TableGen file to be written in a
278 natural syntax and flavor for the application. The current expression forms
288 octal integer value (indicated by a leading 0)
291 decimal integer value
294 hexadecimal integer value
302 ``[ X, Y, Z ]<type>``
303 list value. <type> is the type of the list element and is usually optional.
304 In rare cases, TableGen is unable to deduce the element type in which case
305 the user must specify it explicitly.
308 initializer for a "bits<3>" value
314 access to one bit of a value
317 access to multiple bits of a value
320 reference to a record definition
323 reference to a new anonymous definition of CLASS with the specified template
327 reference to the subfield of a value
330 A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
331 Elements may be included multiple times.
333 ``foreach <var> = [ <list> ] in { <body> }``
335 ``foreach <var> = [ <list> ] in <def>``
336 Replicate <body> or <def>, replacing instances of <var> with each value
337 in <list>. <var> is scoped at the level of the ``foreach`` loop and must
338 not conflict with any other object introduced in <body> or <def>. Currently
339 only ``def``\s are expanded within <body>.
341 ``foreach <var> = 0-15 in ...``
343 ``foreach <var> = {0-15,32-47} in ...``
344 Loop over ranges of integers. The braces are required for multiple ranges.
347 a dag value. The first element is required to be a record definition, the
348 remaining elements in the list may be arbitrary other values, including
349 nested ```dag``' values.
352 A string value that is the result of concatenating the 'a' and 'b' strings.
355 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
356 are not quoted strings, in which case an implicit !cast<string> is done on
357 the operand of the paste.
360 A symbol of type *type* obtained by looking up the string 'a' in the symbol
361 table. If the type of 'a' does not match *type*, TableGen aborts with an
362 error. !cast<string> is a special case in that the argument must be an
363 object defined by a 'def' construct.
366 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
367 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
369 ``!foreach(a, b, c)``
370 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
371 variable that should be declared as a member variable of an instantiated
372 class. This operation is analogous to $(foreach) in GNU make.
375 The first element of list 'a.'
378 The 2nd-N elements of list 'a.'
381 An integer {0,1} indicating whether list 'a' is empty.
384 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
387 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
388 on string, int and bit objects. Use !cast<string> to compare other types of
391 Note that all of the values have rules specifying how they convert to values
392 for different types. These rules allow you to assign a value like "``7``"
393 to a "``bits<4>``" value, for example.
395 Classes and definitions
396 -----------------------
398 As mentioned in the `intro`_, classes and definitions (collectively known as
399 'records') in TableGen are the main high-level unit of information that TableGen
400 collects. Records are defined with a ``def`` or ``class`` keyword, the record
401 name, and an optional list of "`template arguments`_". If the record has
402 superclasses, they are specified as a comma separated list that starts with a
403 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
404 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
405 the record ends with a semicolon.
407 Here is a simple TableGen file:
411 class C { bit V = 1; }
414 string Greeting = "hello";
417 This example defines two definitions, ``X`` and ``Y``, both of which derive from
418 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
419 definition also gets the Greeting member as well.
421 In general, classes are useful for collecting together the commonality between a
422 group of records and isolating it in a single place. Also, classes permit the
423 specification of default values for their subclasses, allowing the subclasses to
424 override them as they wish.
426 .. _value definition:
427 .. _value definitions:
432 Value definitions define named entries in records. A value must be defined
433 before it can be referred to as the operand for another value definition or
434 before the value is reset with a `let expression`_. A value is defined by
435 specifying a `TableGen type`_ and a name. If an initial value is available, it
436 may be specified after the type with an equal sign. Value definitions require
437 terminating semicolons.
441 .. _"let" expressions within a record:
446 A record-level let expression is used to change the value of a value definition
447 in a record. This is primarily useful when a superclass defines a value that a
448 derived class or definition wants to override. Let expressions consist of the
449 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
450 value. For example, a new class could be added to the example above, redefining
451 the ``V`` field for all of its subclasses:
455 class D : C { let V = 0; }
458 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
459 despite the fact that it derives (indirectly) from the ``C`` class, because the
460 ``D`` class overrode its value.
462 .. _template arguments:
464 Class template arguments
465 ^^^^^^^^^^^^^^^^^^^^^^^^
467 TableGen permits the definition of parameterized classes as well as normal
468 concrete classes. Parameterized TableGen classes specify a list of variable
469 bindings (which may optionally have defaults) that are bound when used. Here is
474 class FPFormat<bits<3> val> {
477 def NotFP : FPFormat<0>;
478 def ZeroArgFP : FPFormat<1>;
479 def OneArgFP : FPFormat<2>;
480 def OneArgFPRW : FPFormat<3>;
481 def TwoArgFP : FPFormat<4>;
482 def CompareFP : FPFormat<5>;
483 def CondMovFP : FPFormat<6>;
484 def SpecialFP : FPFormat<7>;
486 In this case, template arguments are used as a space efficient way to specify a
487 list of "enumeration values", each with a "``Value``" field set to the specified
490 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
491 with template arguments. As an example:
495 class ModRefVal<bits<2> val> {
499 def None : ModRefVal<0>;
500 def Mod : ModRefVal<1>;
501 def Ref : ModRefVal<2>;
502 def ModRef : ModRefVal<3>;
504 class Value<ModRefVal MR> {
505 // Decode some information into a more convenient format, while providing
506 // a nice interface to the user of the "Value" class.
507 bit isMod = MR.Value{0};
508 bit isRef = MR.Value{1};
514 def bork : Value<Mod>;
515 def zork : Value<Ref>;
516 def hork : Value<ModRef>;
518 This is obviously a contrived example, but it shows how template arguments can
519 be used to decouple the interface provided to the user of the class from the
520 actual internal data representation expected by the class. In this case,
521 running ``llvm-tblgen`` on the example prints the following definitions:
538 This shows that TableGen was able to dig into the argument and extract a piece
539 of information that was requested by the designer of the "Value" class. For
540 more realistic examples, please see existing users of TableGen, such as the X86
543 Multiclass definitions and instances
544 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
546 While classes with template arguments are a good way to factor commonality
547 between two instances of a definition, multiclasses allow a convenient notation
548 for defining multiple definitions at once (instances of implicitly constructed
549 classes). For example, consider an 3-address instruction set whose instructions
550 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
551 (e.g. SPARC). In this case, you'd like to specify in one place that this
552 commonality exists, then in a separate place indicate what all the ops are.
554 Here is an example TableGen fragment that shows this idea:
561 class inst<int opc, string asmstr, dag operandlist>;
563 multiclass ri_inst<int opc, string asmstr> {
564 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
565 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
566 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
567 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
570 // Instantiations of the ri_inst multiclass.
571 defm ADD : ri_inst<0b111, "add">;
572 defm SUB : ri_inst<0b101, "sub">;
573 defm MUL : ri_inst<0b100, "mul">;
576 The name of the resultant definitions has the multidef fragment names appended
577 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
578 inherit from multiple multiclasses, instantiating definitions from each
579 multiclass. Using a multiclass this way is exactly equivalent to instantiating
580 the classes multiple times yourself, e.g. by writing:
587 class inst<int opc, string asmstr, dag operandlist>;
589 class rrinst<int opc, string asmstr>
590 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
591 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
593 class riinst<int opc, string asmstr>
594 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
595 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
597 // Instantiations of the ri_inst multiclass.
598 def ADD_rr : rrinst<0b111, "add">;
599 def ADD_ri : riinst<0b111, "add">;
600 def SUB_rr : rrinst<0b101, "sub">;
601 def SUB_ri : riinst<0b101, "sub">;
602 def MUL_rr : rrinst<0b100, "mul">;
603 def MUL_ri : riinst<0b100, "mul">;
606 A ``defm`` can also be used inside a multiclass providing several levels of
607 multiclass instanciations.
611 class Instruction<bits<4> opc, string Name> {
612 bits<4> opcode = opc;
616 multiclass basic_r<bits<4> opc> {
617 def rr : Instruction<opc, "rr">;
618 def rm : Instruction<opc, "rm">;
621 multiclass basic_s<bits<4> opc> {
622 defm SS : basic_r<opc>;
623 defm SD : basic_r<opc>;
624 def X : Instruction<opc, "x">;
627 multiclass basic_p<bits<4> opc> {
628 defm PS : basic_r<opc>;
629 defm PD : basic_r<opc>;
630 def Y : Instruction<opc, "y">;
633 defm ADD : basic_s<0xf>, basic_p<0xf>;
646 ``defm`` declarations can inherit from classes too, the rule to follow is that
647 the class list must start after the last multiclass, and there must be at least
648 one multiclass before them.
652 class XD { bits<4> Prefix = 11; }
653 class XS { bits<4> Prefix = 12; }
655 class I<bits<4> op> {
673 bits<4> opcode = { 0, 0, 1, 0 };
674 bits<4> Prefix = { 1, 1, 0, 0 };
678 bits<4> opcode = { 0, 1, 0, 0 };
679 bits<4> Prefix = { 1, 0, 1, 1 };
688 TableGen supports the '``include``' token, which textually substitutes the
689 specified file in place of the include directive. The filename should be
690 specified as a double quoted string immediately after the '``include``' keyword.
700 "Let" expressions at file scope are similar to `"let" expressions within a
701 record`_, except they can specify a value binding for multiple records at a
702 time, and may be useful in certain other cases. File-scope let expressions are
703 really just another way that TableGen allows the end-user to factor out
704 commonality from the records.
706 File-scope "let" expressions take a comma-separated list of bindings to apply,
707 and one or more records to bind the values in. Here are some examples:
711 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
712 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
715 // All calls clobber the non-callee saved registers...
716 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
717 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
718 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
719 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
720 "call\t${dst:call}", []>;
721 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
722 "call\t{*}$dst", [(X86call GR32:$dst)]>;
723 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
724 "call\t{*}$dst", []>;
727 File-scope "let" expressions are often useful when a couple of definitions need
728 to be added to several records, and the records do not otherwise need to be
729 opened, as in the case with the ``CALL*`` instructions above.
731 It's also possible to use "let" expressions inside multiclasses, providing more
732 ways to factor out commonality from the records, specially if using several
733 levels of multiclass instanciations. This also avoids the need of using "let"
734 expressions within subsequent records inside a multiclass.
738 multiclass basic_r<bits<4> opc> {
739 let Predicates = [HasSSE2] in {
740 def rr : Instruction<opc, "rr">;
741 def rm : Instruction<opc, "rm">;
743 let Predicates = [HasSSE3] in
744 def rx : Instruction<opc, "rx">;
747 multiclass basic_ss<bits<4> opc> {
749 defm SS : basic_r<opc>;
752 defm SD : basic_r<opc>;
755 defm ADD : basic_ss<0xf>;
760 TableGen supports the '``foreach``' block, which textually replicates the loop
761 body, substituting iterator values for iterator references in the body.
766 foreach i = [0, 1, 2, 3] in {
767 def R#i : Register<...>;
768 def F#i : Register<...>;
771 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
772 may be nested. If there is only one item in the body the braces may be
777 foreach i = [0, 1, 2, 3] in
778 def R#i : Register<...>;
780 Code Generator backend info
781 ===========================
783 Expressions used by code generator to describe instructions and isel patterns:
786 an implicitly defined physical register. This tells the dag instruction
787 selection emitter the input pattern's extra definitions matches implicit
788 physical register definitions.
790 .. _TableGen backend:
791 .. _TableGen backends:
797 TODO: How they work, how to write one. This section should not contain details
798 about any particular backend, except maybe ``-print-enums`` as an example. This
799 should highlight the APIs in ``TableGen/Record.h``.