11 TableGen's purpose is to help a human develop and maintain records of
12 domain-specific information. Because there may be a large number of these
13 records, it is specifically designed to allow writing flexible descriptions and
14 for common features of these records to be factored out. This reduces the
15 amount of duplication in the description, reduces the chance of error, and makes
16 it easier to structure domain specific information.
18 The core part of TableGen `parses a file`_, instantiates the declarations, and
19 hands the result off to a domain-specific `TableGen backend`_ for processing.
20 The current major user of TableGen is the `LLVM code
21 generator <CodeGenerator.html>`_.
23 Note that if you work on TableGen much, and use emacs or vim, that you can find
24 an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and
25 ``llvm/utils/vim`` directories of your LLVM distribution, respectively.
32 TableGen files consist of two key parts: 'classes' and 'definitions', both of
33 which are considered 'records'.
35 **TableGen records** have a unique name, a list of values, and a list of
36 superclasses. The list of values is the main data that TableGen builds for each
37 record; it is this that holds the domain specific information for the
38 application. The interpretation of this data is left to a specific `TableGen
39 backend`_, but the structure and format rules are taken care of and are fixed by
42 **TableGen definitions** are the concrete form of 'records'. These generally do
43 not have any undefined values, and are marked with the '``def``' keyword.
45 **TableGen classes** are abstract records that are used to build and describe
46 other records. These 'classes' allow the end-user to build abstractions for
47 either the domain they are targeting (such as "Register", "RegisterClass", and
48 "Instruction" in the LLVM code generator) or for the implementor to help factor
49 out common properties of records (such as "FPInst", which is used to represent
50 floating point instructions in the X86 backend). TableGen keeps track of all of
51 the classes that are used to build up a definition, so the backend can find all
52 definitions of a particular class, such as "Instruction".
54 **TableGen multiclasses** are groups of abstract records that are instantiated
55 all at once. Each instantiation can result in multiple TableGen definitions.
56 If a multiclass inherits from another multiclass, the definitions in the
57 sub-multiclass become part of the current multiclass, as if they were declared
58 in the current multiclass.
65 With no other arguments, TableGen parses the specified file and prints out all
66 of the classes, then all of the definitions. This is a good way to see what the
67 various definitions expand to fully. Running this on the ``X86.td`` file prints
68 this (at the time of this writing):
73 def ADD32rr { // Instruction X86Inst I
74 string Namespace = "X86";
75 dag OutOperandList = (outs GR32:$dst);
76 dag InOperandList = (ins GR32:$src1, GR32:$src2);
77 string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
78 list<dag> Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
79 list<Register> Uses = [];
80 list<Register> Defs = [EFLAGS];
81 list<Predicate> Predicates = [];
83 int AddedComplexity = 0;
86 bit isIndirectBranch = 0;
89 bit canFoldAsLoad = 0;
92 bit isImplicitDef = 0;
93 bit isConvertibleToThreeAddress = 1;
96 bit isReMaterializable = 0;
99 bit usesCustomInserter = 0;
101 bit isNotDuplicable = 0;
102 bit hasSideEffects = 0;
103 bit neverHasSideEffects = 0;
104 InstrItinClass Itinerary = NoItinerary;
105 string Constraints = "";
106 string DisableEncoding = "";
107 bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
108 Format Form = MRMDestReg;
109 bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
110 ImmType ImmT = NoImm;
111 bits<3> ImmTypeBits = { 0, 0, 0 };
112 bit hasOpSizePrefix = 0;
113 bit hasAdSizePrefix = 0;
114 bits<4> Prefix = { 0, 0, 0, 0 };
115 bit hasREX_WPrefix = 0;
117 bits<3> FPFormBits = { 0, 0, 0 };
121 This definition corresponds to the 32-bit register-register ``add`` instruction
122 of the x86 architecture. ``def ADD32rr`` defines a record named
123 ``ADD32rr``, and the comment at the end of the line indicates the superclasses
124 of the definition. The body of the record contains all of the data that
125 TableGen assembled for the record, indicating that the instruction is part of
126 the "X86" namespace, the pattern indicating how the instruction should be
127 emitted into the assembly file, that it is a two-address instruction, has a
128 particular encoding, etc. The contents and semantics of the information in the
129 record are specific to the needs of the X86 backend, and are only shown as an
132 As you can see, a lot of information is needed for every instruction supported
133 by the code generator, and specifying it all manually would be unmaintainable,
134 prone to bugs, and tiring to do in the first place. Because we are using
135 TableGen, all of the information was derived from the following definition:
140 isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
141 isConvertibleToThreeAddress = 1 in // Can transform into LEA.
142 def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
143 (ins GR32:$src1, GR32:$src2),
144 "add{l}\t{$src2, $dst|$dst, $src2}",
145 [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
147 This definition makes use of the custom class ``I`` (extended from the custom
148 class ``X86Inst``), which is defined in the X86-specific TableGen file, to
149 factor out the common features that instructions of its class share. A key
150 feature of TableGen is that it allows the end-user to define the abstractions
151 they prefer to use when describing their information.
153 Each ``def`` record has a special entry called "NAME". This is the name of the
154 record ("``ADD32rr``" above). In the general case ``def`` names can be formed
155 from various kinds of string processing expressions and ``NAME`` resolves to the
156 final value obtained after resolving all of those expressions. The user may
157 refer to ``NAME`` anywhere she desires to use the ultimate name of the ``def``.
158 ``NAME`` should not be defined anywhere else in user code to avoid conflicts.
163 TableGen runs just like any other LLVM tool. The first (optional) argument
164 specifies the file to read. If a filename is not specified, ``llvm-tblgen``
165 reads from standard input.
167 To be useful, one of the `TableGen backends`_ must be used. These backends are
168 selectable on the command line (type '``llvm-tblgen -help``' for a list). For
169 example, to get a list of all of the definitions that subclass a particular type
170 (which can be useful for building up an enum list of these records), use the
171 ``-print-enums`` option:
175 $ llvm-tblgen X86.td -print-enums -class=Register
176 AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
177 ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
178 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
179 R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
180 R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
181 RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
182 XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
183 XMM6, XMM7, XMM8, XMM9,
185 $ llvm-tblgen X86.td -print-enums -class=Instruction
186 ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
187 ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
188 ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
189 ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
190 ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
192 The default backend prints out all of the records, as `described above`_.
194 If you plan to use TableGen, you will most likely have to `write a backend`_
195 that extracts the information specific to what you need and formats it in the
203 TableGen doesn't care about the meaning of data (that is up to the backend to
204 define), but it does care about syntax, and it enforces a simple type system.
205 This section describes the syntax and the constructs allowed in a TableGen file.
213 TableGen supports BCPL style "``//``" comments, which run to the end of the
214 line, and it also supports **nestable** "``/* */``" comments.
218 The TableGen type system
219 ^^^^^^^^^^^^^^^^^^^^^^^^
221 TableGen files are strongly typed, in a simple (but complete) type-system.
222 These types are used to perform automatic conversions, check for errors, and to
223 help interface designers constrain the input that they allow. Every `value
224 definition`_ is required to have an associated type.
226 TableGen supports a mixture of very low-level types (such as ``bit``) and very
227 high-level types (such as ``dag``). This flexibility is what allows it to
228 describe a wide range of information conveniently and compactly. The TableGen
232 A 'bit' is a boolean value that can hold either 0 or 1.
235 The 'int' type represents a simple 32-bit integer value, such as 5.
238 The 'string' type represents an ordered sequence of characters of arbitrary
242 A 'bits' type is an arbitrary, but fixed, size integer that is broken up
243 into individual bits. This type is useful because it can handle some bits
244 being defined while others are undefined.
247 This type represents a list whose elements are some other type. The
248 contained type is arbitrary: it can even be another list type.
251 Specifying a class name in a type context means that the defined value must
252 be a subclass of the specified class. This is useful in conjunction with
253 the ``list`` type, for example, to constrain the elements of the list to a
254 common base class (e.g., a ``list<Register>`` can only contain definitions
255 derived from the "``Register``" class).
258 This type represents a nestable directed graph of elements.
260 To date, these types have been sufficient for describing things that TableGen
261 has been used for, but it is straight-forward to extend this list if needed.
263 .. _TableGen expressions:
265 TableGen values and expressions
266 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
268 TableGen allows for a pretty reasonable number of different expression forms
269 when building up values. These forms allow the TableGen file to be written in a
270 natural syntax and flavor for the application. The current expression forms
280 octal integer value (indicated by a leading 0)
283 decimal integer value
286 hexadecimal integer value
292 usually called a "code fragment", but is just a multiline string literal
294 ``[ X, Y, Z ]<type>``
295 list value. <type> is the type of the list element and is usually optional.
296 In rare cases, TableGen is unable to deduce the element type in which case
297 the user must specify it explicitly.
300 initializer for a "bits<3>" value
306 access to one bit of a value
309 access to multiple bits of a value
312 reference to a record definition
315 reference to a new anonymous definition of CLASS with the specified template
319 reference to the subfield of a value
322 A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
323 Elements may be included multiple times.
325 ``foreach <var> = [ <list> ] in { <body> }``
327 ``foreach <var> = [ <list> ] in <def>``
328 Replicate <body> or <def>, replacing instances of <var> with each value
329 in <list>. <var> is scoped at the level of the ``foreach`` loop and must
330 not conflict with any other object introduced in <body> or <def>. Currently
331 only ``def``\s are expanded within <body>.
333 ``foreach <var> = 0-15 in ...``
335 ``foreach <var> = {0-15,32-47} in ...``
336 Loop over ranges of integers. The braces are required for multiple ranges.
339 a dag value. The first element is required to be a record definition, the
340 remaining elements in the list may be arbitrary other values, including
341 nested ```dag``' values.
344 A string value that is the result of concatenating the 'a' and 'b' strings.
347 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
348 are not quoted strings, in which case an implicit !cast<string> is done on
349 the operand of the paste.
352 A symbol of type *type* obtained by looking up the string 'a' in the symbol
353 table. If the type of 'a' does not match *type*, TableGen aborts with an
354 error. !cast<string> is a special case in that the argument must be an
355 object defined by a 'def' construct.
358 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
359 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
361 ``!foreach(a, b, c)``
362 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
363 variable that should be declared as a member variable of an instantiated
364 class. This operation is analogous to $(foreach) in GNU make.
367 The first element of list 'a.'
370 The 2nd-N elements of list 'a.'
373 An integer {0,1} indicating whether list 'a' is empty.
376 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
379 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
380 on string, int and bit objects. Use !cast<string> to compare other types of
383 Note that all of the values have rules specifying how they convert to values
384 for different types. These rules allow you to assign a value like "``7``"
385 to a "``bits<4>``" value, for example.
387 Classes and definitions
388 -----------------------
390 As mentioned in the `intro`_, classes and definitions (collectively known as
391 'records') in TableGen are the main high-level unit of information that TableGen
392 collects. Records are defined with a ``def`` or ``class`` keyword, the record
393 name, and an optional list of "`template arguments`_". If the record has
394 superclasses, they are specified as a comma separated list that starts with a
395 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
396 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
397 the record ends with a semicolon.
399 Here is a simple TableGen file:
403 class C { bit V = 1; }
406 string Greeting = "hello";
409 This example defines two definitions, ``X`` and ``Y``, both of which derive from
410 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
411 definition also gets the Greeting member as well.
413 In general, classes are useful for collecting together the commonality between a
414 group of records and isolating it in a single place. Also, classes permit the
415 specification of default values for their subclasses, allowing the subclasses to
416 override them as they wish.
418 .. _value definition:
419 .. _value definitions:
424 Value definitions define named entries in records. A value must be defined
425 before it can be referred to as the operand for another value definition or
426 before the value is reset with a `let expression`_. A value is defined by
427 specifying a `TableGen type`_ and a name. If an initial value is available, it
428 may be specified after the type with an equal sign. Value definitions require
429 terminating semicolons.
433 .. _"let" expressions within a record:
438 A record-level let expression is used to change the value of a value definition
439 in a record. This is primarily useful when a superclass defines a value that a
440 derived class or definition wants to override. Let expressions consist of the
441 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
442 value. For example, a new class could be added to the example above, redefining
443 the ``V`` field for all of its subclasses:
447 class D : C { let V = 0; }
450 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
451 despite the fact that it derives (indirectly) from the ``C`` class, because the
452 ``D`` class overrode its value.
454 .. _template arguments:
456 Class template arguments
457 ^^^^^^^^^^^^^^^^^^^^^^^^
459 TableGen permits the definition of parameterized classes as well as normal
460 concrete classes. Parameterized TableGen classes specify a list of variable
461 bindings (which may optionally have defaults) that are bound when used. Here is
466 class FPFormat<bits<3> val> {
469 def NotFP : FPFormat<0>;
470 def ZeroArgFP : FPFormat<1>;
471 def OneArgFP : FPFormat<2>;
472 def OneArgFPRW : FPFormat<3>;
473 def TwoArgFP : FPFormat<4>;
474 def CompareFP : FPFormat<5>;
475 def CondMovFP : FPFormat<6>;
476 def SpecialFP : FPFormat<7>;
478 In this case, template arguments are used as a space efficient way to specify a
479 list of "enumeration values", each with a "``Value``" field set to the specified
482 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
483 with template arguments. As an example:
487 class ModRefVal<bits<2> val> {
491 def None : ModRefVal<0>;
492 def Mod : ModRefVal<1>;
493 def Ref : ModRefVal<2>;
494 def ModRef : ModRefVal<3>;
496 class Value<ModRefVal MR> {
497 // Decode some information into a more convenient format, while providing
498 // a nice interface to the user of the "Value" class.
499 bit isMod = MR.Value{0};
500 bit isRef = MR.Value{1};
506 def bork : Value<Mod>;
507 def zork : Value<Ref>;
508 def hork : Value<ModRef>;
510 This is obviously a contrived example, but it shows how template arguments can
511 be used to decouple the interface provided to the user of the class from the
512 actual internal data representation expected by the class. In this case,
513 running ``llvm-tblgen`` on the example prints the following definitions:
530 This shows that TableGen was able to dig into the argument and extract a piece
531 of information that was requested by the designer of the "Value" class. For
532 more realistic examples, please see existing users of TableGen, such as the X86
535 Multiclass definitions and instances
536 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
538 While classes with template arguments are a good way to factor commonality
539 between two instances of a definition, multiclasses allow a convenient notation
540 for defining multiple definitions at once (instances of implicitly constructed
541 classes). For example, consider an 3-address instruction set whose instructions
542 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
543 (e.g. SPARC). In this case, you'd like to specify in one place that this
544 commonality exists, then in a separate place indicate what all the ops are.
546 Here is an example TableGen fragment that shows this idea:
553 class inst<int opc, string asmstr, dag operandlist>;
555 multiclass ri_inst<int opc, string asmstr> {
556 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
557 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
558 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
559 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
562 // Instantiations of the ri_inst multiclass.
563 defm ADD : ri_inst<0b111, "add">;
564 defm SUB : ri_inst<0b101, "sub">;
565 defm MUL : ri_inst<0b100, "mul">;
568 The name of the resultant definitions has the multidef fragment names appended
569 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
570 inherit from multiple multiclasses, instantiating definitions from each
571 multiclass. Using a multiclass this way is exactly equivalent to instantiating
572 the classes multiple times yourself, e.g. by writing:
579 class inst<int opc, string asmstr, dag operandlist>;
581 class rrinst<int opc, string asmstr>
582 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
583 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
585 class riinst<int opc, string asmstr>
586 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
587 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
589 // Instantiations of the ri_inst multiclass.
590 def ADD_rr : rrinst<0b111, "add">;
591 def ADD_ri : riinst<0b111, "add">;
592 def SUB_rr : rrinst<0b101, "sub">;
593 def SUB_ri : riinst<0b101, "sub">;
594 def MUL_rr : rrinst<0b100, "mul">;
595 def MUL_ri : riinst<0b100, "mul">;
598 A ``defm`` can also be used inside a multiclass providing several levels of
599 multiclass instantiations.
603 class Instruction<bits<4> opc, string Name> {
604 bits<4> opcode = opc;
608 multiclass basic_r<bits<4> opc> {
609 def rr : Instruction<opc, "rr">;
610 def rm : Instruction<opc, "rm">;
613 multiclass basic_s<bits<4> opc> {
614 defm SS : basic_r<opc>;
615 defm SD : basic_r<opc>;
616 def X : Instruction<opc, "x">;
619 multiclass basic_p<bits<4> opc> {
620 defm PS : basic_r<opc>;
621 defm PD : basic_r<opc>;
622 def Y : Instruction<opc, "y">;
625 defm ADD : basic_s<0xf>, basic_p<0xf>;
638 ``defm`` declarations can inherit from classes too, the rule to follow is that
639 the class list must start after the last multiclass, and there must be at least
640 one multiclass before them.
644 class XD { bits<4> Prefix = 11; }
645 class XS { bits<4> Prefix = 12; }
647 class I<bits<4> op> {
665 bits<4> opcode = { 0, 0, 1, 0 };
666 bits<4> Prefix = { 1, 1, 0, 0 };
670 bits<4> opcode = { 0, 1, 0, 0 };
671 bits<4> Prefix = { 1, 0, 1, 1 };
680 TableGen supports the '``include``' token, which textually substitutes the
681 specified file in place of the include directive. The filename should be
682 specified as a double quoted string immediately after the '``include``' keyword.
692 "Let" expressions at file scope are similar to `"let" expressions within a
693 record`_, except they can specify a value binding for multiple records at a
694 time, and may be useful in certain other cases. File-scope let expressions are
695 really just another way that TableGen allows the end-user to factor out
696 commonality from the records.
698 File-scope "let" expressions take a comma-separated list of bindings to apply,
699 and one or more records to bind the values in. Here are some examples:
703 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
704 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
707 // All calls clobber the non-callee saved registers...
708 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
709 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
710 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
711 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
712 "call\t${dst:call}", []>;
713 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
714 "call\t{*}$dst", [(X86call GR32:$dst)]>;
715 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
716 "call\t{*}$dst", []>;
719 File-scope "let" expressions are often useful when a couple of definitions need
720 to be added to several records, and the records do not otherwise need to be
721 opened, as in the case with the ``CALL*`` instructions above.
723 It's also possible to use "let" expressions inside multiclasses, providing more
724 ways to factor out commonality from the records, specially if using several
725 levels of multiclass instantiations. This also avoids the need of using "let"
726 expressions within subsequent records inside a multiclass.
730 multiclass basic_r<bits<4> opc> {
731 let Predicates = [HasSSE2] in {
732 def rr : Instruction<opc, "rr">;
733 def rm : Instruction<opc, "rm">;
735 let Predicates = [HasSSE3] in
736 def rx : Instruction<opc, "rx">;
739 multiclass basic_ss<bits<4> opc> {
741 defm SS : basic_r<opc>;
744 defm SD : basic_r<opc>;
747 defm ADD : basic_ss<0xf>;
752 TableGen supports the '``foreach``' block, which textually replicates the loop
753 body, substituting iterator values for iterator references in the body.
758 foreach i = [0, 1, 2, 3] in {
759 def R#i : Register<...>;
760 def F#i : Register<...>;
763 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
764 may be nested. If there is only one item in the body the braces may be
769 foreach i = [0, 1, 2, 3] in
770 def R#i : Register<...>;
772 Code Generator backend info
773 ===========================
775 Expressions used by code generator to describe instructions and isel patterns:
778 an implicitly defined physical register. This tells the dag instruction
779 selection emitter the input pattern's extra definitions matches implicit
780 physical register definitions.
782 .. _TableGen backend:
783 .. _TableGen backends:
789 Until we get a step-by-step HowTo for writing TableGen backends, you can at
790 least grab the boilerplate (build system, new files, etc.) from Clang's
793 TODO: How they work, how to write one. This section should not contain details
794 about any particular backend, except maybe ``-print-enums`` as an example. This
795 should highlight the APIs in ``TableGen/Record.h``.