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 the 32-bit register-register ``add`` instruction
124 of the the x86 architecture. ``def ADD32rr`` defines a record named
125 ``ADD32rr``, and the comment at the end of the line indicates the superclasses
126 of the definition. The body of the record contains all of the data that
127 TableGen assembled for the record, indicating that the instruction is part of
128 the "X86" namespace, the pattern indicating how the the instruction should be
129 emitted into the assembly file, that it is a two-address instruction, has a
130 particular encoding, etc. The contents and semantics of the information in the
131 record are specific to the needs of the X86 backend, and are only shown as an
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 record ("``ADD32rr``" above). In the general case ``def`` names can be formed
157 from 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 conflicts.
165 TableGen runs just like any other LLVM tool. The first (optional) argument
166 specifies the file to read. If a filename is not specified, ``llvm-tblgen``
167 reads from standard input.
169 To be useful, one of the `TableGen backends`_ must be used. These backends are
170 selectable on the command line (type '``llvm-tblgen -help``' for a list). For
171 example, to get a list of all of the definitions that subclass a particular type
172 (which can be useful for building up an enum list of these records), use the
173 ``-print-enums`` option:
177 $ llvm-tblgen X86.td -print-enums -class=Register
178 AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
179 ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
180 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
181 R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
182 R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
183 RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
184 XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
185 XMM6, XMM7, XMM8, XMM9,
187 $ llvm-tblgen X86.td -print-enums -class=Instruction
188 ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
189 ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
190 ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
191 ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
192 ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
194 The default backend prints out all of the records, as `described above`_.
196 If you plan to use TableGen, you will most likely have to `write a backend`_
197 that extracts the information specific to what you need and formats it in the
205 TableGen doesn't care about the meaning of data (that is up to the backend to
206 define), but it does care about syntax, and it enforces a simple type system.
207 This section describes the syntax and the constructs allowed in a TableGen file.
215 TableGen supports BCPL style "``//``" comments, which run to the end of the
216 line, and it also supports **nestable** "``/* */``" comments.
220 The TableGen type system
221 ^^^^^^^^^^^^^^^^^^^^^^^^
223 TableGen files are strongly typed, in a simple (but complete) type-system.
224 These types are used to perform automatic conversions, check for errors, and to
225 help interface designers constrain the input that they allow. Every `value
226 definition`_ is required to have an associated type.
228 TableGen supports a mixture of very low-level types (such as ``bit``) and very
229 high-level types (such as ``dag``). This flexibility is what allows it to
230 describe a wide range of information conveniently and compactly. The TableGen
234 A 'bit' is a boolean value that can hold either 0 or 1.
237 The 'int' type represents a simple 32-bit integer value, such as 5.
240 The 'string' type represents an ordered sequence of characters of arbitrary
244 A 'bits' type is an arbitrary, but fixed, size integer that is broken up
245 into individual bits. This type is useful because it can handle some bits
246 being defined while others are undefined.
249 This type represents a list whose elements are some other type. The
250 contained type is arbitrary: it can even be another list type.
253 Specifying a class name in a type context means that the defined value must
254 be a subclass of the specified class. This is useful in conjunction with
255 the ``list`` type, for example, to constrain the elements of the list to a
256 common base class (e.g., a ``list<Register>`` can only contain definitions
257 derived from the "``Register``" class).
260 This type represents a nestable directed graph of elements.
263 This represents a big hunk of text. This is lexically distinct from string
264 values because it doesn't require escaping double quotes and other common
265 characters that occur in code.
267 To date, these types have been sufficient for describing things that TableGen
268 has been used for, but it is straight-forward to extend this list if needed.
270 .. _TableGen expressions:
272 TableGen values and expressions
273 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
275 TableGen allows for a pretty reasonable number of different expression forms
276 when building up values. These forms allow the TableGen file to be written in a
277 natural syntax and flavor for the application. The current expression forms
287 octal integer value (indicated by a leading 0)
290 decimal integer value
293 hexadecimal integer value
301 ``[ X, Y, Z ]<type>``
302 list value. <type> is the type of the list element and is usually optional.
303 In rare cases, TableGen is unable to deduce the element type in which case
304 the user must specify it explicitly.
307 initializer for a "bits<3>" value
313 access to one bit of a value
316 access to multiple bits of a value
319 reference to a record definition
322 reference to a new anonymous definition of CLASS with the specified template
326 reference to the subfield of a value
329 A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
330 Elements may be included multiple times.
332 ``foreach <var> = [ <list> ] in { <body> }``
334 ``foreach <var> = [ <list> ] in <def>``
335 Replicate <body> or <def>, replacing instances of <var> with each value
336 in <list>. <var> is scoped at the level of the ``foreach`` loop and must
337 not conflict with any other object introduced in <body> or <def>. Currently
338 only ``def``\s are expanded within <body>.
340 ``foreach <var> = 0-15 in ...``
342 ``foreach <var> = {0-15,32-47} in ...``
343 Loop over ranges of integers. The braces are required for multiple ranges.
346 a dag value. The first element is required to be a record definition, the
347 remaining elements in the list may be arbitrary other values, including
348 nested ```dag``' values.
351 A string value that is the result of concatenating the 'a' and 'b' strings.
354 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
355 are not quoted strings, in which case an implicit !cast<string> is done on
356 the operand of the paste.
359 A symbol of type *type* obtained by looking up the string 'a' in the symbol
360 table. If the type of 'a' does not match *type*, TableGen aborts with an
361 error. !cast<string> is a special case in that the argument must be an
362 object defined by a 'def' construct.
365 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
366 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
368 ``!foreach(a, b, c)``
369 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
370 variable that should be declared as a member variable of an instantiated
371 class. This operation is analogous to $(foreach) in GNU make.
374 The first element of list 'a.'
377 The 2nd-N elements of list 'a.'
380 An integer {0,1} indicating whether list 'a' is empty.
383 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
386 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
387 on string, int and bit objects. Use !cast<string> to compare other types of
390 Note that all of the values have rules specifying how they convert to values
391 for different types. These rules allow you to assign a value like "``7``"
392 to a "``bits<4>``" value, for example.
394 Classes and definitions
395 -----------------------
397 As mentioned in the `intro`_, classes and definitions (collectively known as
398 'records') in TableGen are the main high-level unit of information that TableGen
399 collects. Records are defined with a ``def`` or ``class`` keyword, the record
400 name, and an optional list of "`template arguments`_". If the record has
401 superclasses, they are specified as a comma separated list that starts with a
402 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
403 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
404 the record ends with a semicolon.
406 Here is a simple TableGen file:
410 class C { bit V = 1; }
413 string Greeting = "hello";
416 This example defines two definitions, ``X`` and ``Y``, both of which derive from
417 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
418 definition also gets the Greeting member as well.
420 In general, classes are useful for collecting together the commonality between a
421 group of records and isolating it in a single place. Also, classes permit the
422 specification of default values for their subclasses, allowing the subclasses to
423 override them as they wish.
425 .. _value definition:
426 .. _value definitions:
431 Value definitions define named entries in records. A value must be defined
432 before it can be referred to as the operand for another value definition or
433 before the value is reset with a `let expression`_. A value is defined by
434 specifying a `TableGen type`_ and a name. If an initial value is available, it
435 may be specified after the type with an equal sign. Value definitions require
436 terminating semicolons.
440 .. _"let" expressions within a record:
445 A record-level let expression is used to change the value of a value definition
446 in a record. This is primarily useful when a superclass defines a value that a
447 derived class or definition wants to override. Let expressions consist of the
448 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
449 value. For example, a new class could be added to the example above, redefining
450 the ``V`` field for all of its subclasses:
454 class D : C { let V = 0; }
457 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
458 despite the fact that it derives (indirectly) from the ``C`` class, because the
459 ``D`` class overrode its value.
461 .. _template arguments:
463 Class template arguments
464 ^^^^^^^^^^^^^^^^^^^^^^^^
466 TableGen permits the definition of parameterized classes as well as normal
467 concrete classes. Parameterized TableGen classes specify a list of variable
468 bindings (which may optionally have defaults) that are bound when used. Here is
473 class FPFormat<bits<3> val> {
476 def NotFP : FPFormat<0>;
477 def ZeroArgFP : FPFormat<1>;
478 def OneArgFP : FPFormat<2>;
479 def OneArgFPRW : FPFormat<3>;
480 def TwoArgFP : FPFormat<4>;
481 def CompareFP : FPFormat<5>;
482 def CondMovFP : FPFormat<6>;
483 def SpecialFP : FPFormat<7>;
485 In this case, template arguments are used as a space efficient way to specify a
486 list of "enumeration values", each with a "``Value``" field set to the specified
489 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
490 with template arguments. As an example:
494 class ModRefVal<bits<2> val> {
498 def None : ModRefVal<0>;
499 def Mod : ModRefVal<1>;
500 def Ref : ModRefVal<2>;
501 def ModRef : ModRefVal<3>;
503 class Value<ModRefVal MR> {
504 // Decode some information into a more convenient format, while providing
505 // a nice interface to the user of the "Value" class.
506 bit isMod = MR.Value{0};
507 bit isRef = MR.Value{1};
513 def bork : Value<Mod>;
514 def zork : Value<Ref>;
515 def hork : Value<ModRef>;
517 This is obviously a contrived example, but it shows how template arguments can
518 be used to decouple the interface provided to the user of the class from the
519 actual internal data representation expected by the class. In this case,
520 running ``llvm-tblgen`` on the example prints the following definitions:
537 This shows that TableGen was able to dig into the argument and extract a piece
538 of information that was requested by the designer of the "Value" class. For
539 more realistic examples, please see existing users of TableGen, such as the X86
542 Multiclass definitions and instances
543 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
545 While classes with template arguments are a good way to factor commonality
546 between two instances of a definition, multiclasses allow a convenient notation
547 for defining multiple definitions at once (instances of implicitly constructed
548 classes). For example, consider an 3-address instruction set whose instructions
549 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
550 (e.g. SPARC). In this case, you'd like to specify in one place that this
551 commonality exists, then in a separate place indicate what all the ops are.
553 Here is an example TableGen fragment that shows this idea:
560 class inst<int opc, string asmstr, dag operandlist>;
562 multiclass ri_inst<int opc, string asmstr> {
563 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
564 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
565 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
566 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
569 // Instantiations of the ri_inst multiclass.
570 defm ADD : ri_inst<0b111, "add">;
571 defm SUB : ri_inst<0b101, "sub">;
572 defm MUL : ri_inst<0b100, "mul">;
575 The name of the resultant definitions has the multidef fragment names appended
576 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
577 inherit from multiple multiclasses, instantiating definitions from each
578 multiclass. Using a multiclass this way is exactly equivalent to instantiating
579 the classes multiple times yourself, e.g. by writing:
586 class inst<int opc, string asmstr, dag operandlist>;
588 class rrinst<int opc, string asmstr>
589 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
590 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
592 class riinst<int opc, string asmstr>
593 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
594 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
596 // Instantiations of the ri_inst multiclass.
597 def ADD_rr : rrinst<0b111, "add">;
598 def ADD_ri : riinst<0b111, "add">;
599 def SUB_rr : rrinst<0b101, "sub">;
600 def SUB_ri : riinst<0b101, "sub">;
601 def MUL_rr : rrinst<0b100, "mul">;
602 def MUL_ri : riinst<0b100, "mul">;
605 A ``defm`` can also be used inside a multiclass providing several levels of
606 multiclass instanciations.
610 class Instruction<bits<4> opc, string Name> {
611 bits<4> opcode = opc;
615 multiclass basic_r<bits<4> opc> {
616 def rr : Instruction<opc, "rr">;
617 def rm : Instruction<opc, "rm">;
620 multiclass basic_s<bits<4> opc> {
621 defm SS : basic_r<opc>;
622 defm SD : basic_r<opc>;
623 def X : Instruction<opc, "x">;
626 multiclass basic_p<bits<4> opc> {
627 defm PS : basic_r<opc>;
628 defm PD : basic_r<opc>;
629 def Y : Instruction<opc, "y">;
632 defm ADD : basic_s<0xf>, basic_p<0xf>;
645 ``defm`` declarations can inherit from classes too, the rule to follow is that
646 the class list must start after the last multiclass, and there must be at least
647 one multiclass before them.
651 class XD { bits<4> Prefix = 11; }
652 class XS { bits<4> Prefix = 12; }
654 class I<bits<4> op> {
672 bits<4> opcode = { 0, 0, 1, 0 };
673 bits<4> Prefix = { 1, 1, 0, 0 };
677 bits<4> opcode = { 0, 1, 0, 0 };
678 bits<4> Prefix = { 1, 0, 1, 1 };
687 TableGen supports the '``include``' token, which textually substitutes the
688 specified file in place of the include directive. The filename should be
689 specified as a double quoted string immediately after the '``include``' keyword.
699 "Let" expressions at file scope are similar to `"let" expressions within a
700 record`_, except they can specify a value binding for multiple records at a
701 time, and may be useful in certain other cases. File-scope let expressions are
702 really just another way that TableGen allows the end-user to factor out
703 commonality from the records.
705 File-scope "let" expressions take a comma-separated list of bindings to apply,
706 and one or more records to bind the values in. Here are some examples:
710 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
711 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
714 // All calls clobber the non-callee saved registers...
715 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
716 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
717 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
718 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
719 "call\t${dst:call}", []>;
720 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
721 "call\t{*}$dst", [(X86call GR32:$dst)]>;
722 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
723 "call\t{*}$dst", []>;
726 File-scope "let" expressions are often useful when a couple of definitions need
727 to be added to several records, and the records do not otherwise need to be
728 opened, as in the case with the ``CALL*`` instructions above.
730 It's also possible to use "let" expressions inside multiclasses, providing more
731 ways to factor out commonality from the records, specially if using several
732 levels of multiclass instanciations. This also avoids the need of using "let"
733 expressions within subsequent records inside a multiclass.
737 multiclass basic_r<bits<4> opc> {
738 let Predicates = [HasSSE2] in {
739 def rr : Instruction<opc, "rr">;
740 def rm : Instruction<opc, "rm">;
742 let Predicates = [HasSSE3] in
743 def rx : Instruction<opc, "rx">;
746 multiclass basic_ss<bits<4> opc> {
748 defm SS : basic_r<opc>;
751 defm SD : basic_r<opc>;
754 defm ADD : basic_ss<0xf>;
759 TableGen supports the '``foreach``' block, which textually replicates the loop
760 body, substituting iterator values for iterator references in the body.
765 foreach i = [0, 1, 2, 3] in {
766 def R#i : Register<...>;
767 def F#i : Register<...>;
770 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
771 may be nested. If there is only one item in the body the braces may be
776 foreach i = [0, 1, 2, 3] in
777 def R#i : Register<...>;
779 Code Generator backend info
780 ===========================
782 Expressions used by code generator to describe instructions and isel patterns:
785 an implicitly defined physical register. This tells the dag instruction
786 selection emitter the input pattern's extra definitions matches implicit
787 physical register definitions.
789 .. _TableGen backend:
790 .. _TableGen backends:
796 TODO: How they work, how to write one. This section should not contain details
797 about any particular backend, except maybe ``-print-enums`` as an example. This
798 should highlight the APIs in ``TableGen/Record.h``.