1 ==============================
2 TableGen Language Introduction
3 ==============================
9 This document is extremely rough. If you find something lacking, please
10 fix it, file a documentation bug, or ask about it on llvmdev.
15 This document is not meant to be a normative spec about the TableGen language
16 in and of itself (i.e. how to understand a given construct in terms of how
17 it affects the final set of records represented by the TableGen file). For
18 the formal language specification, see :doc:`LangRef`.
23 TableGen doesn't care about the meaning of data (that is up to the backend to
24 define), but it does care about syntax, and it enforces a simple type system.
25 This section describes the syntax and the constructs allowed in a TableGen file.
33 TableGen supports C++ style "``//``" comments, which run to the end of the
34 line, and it also supports **nestable** "``/* */``" comments.
38 The TableGen type system
39 ^^^^^^^^^^^^^^^^^^^^^^^^
41 TableGen files are strongly typed, in a simple (but complete) type-system.
42 These types are used to perform automatic conversions, check for errors, and to
43 help interface designers constrain the input that they allow. Every `value
44 definition`_ is required to have an associated type.
46 TableGen supports a mixture of very low-level types (such as ``bit``) and very
47 high-level types (such as ``dag``). This flexibility is what allows it to
48 describe a wide range of information conveniently and compactly. The TableGen
52 A 'bit' is a boolean value that can hold either 0 or 1.
55 The 'int' type represents a simple 32-bit integer value, such as 5.
58 The 'string' type represents an ordered sequence of characters of arbitrary
62 A 'bits' type is an arbitrary, but fixed, size integer that is broken up
63 into individual bits. This type is useful because it can handle some bits
64 being defined while others are undefined.
67 This type represents a list whose elements are some other type. The
68 contained type is arbitrary: it can even be another list type.
71 Specifying a class name in a type context means that the defined value must
72 be a subclass of the specified class. This is useful in conjunction with
73 the ``list`` type, for example, to constrain the elements of the list to a
74 common base class (e.g., a ``list<Register>`` can only contain definitions
75 derived from the "``Register``" class).
78 This type represents a nestable directed graph of elements.
80 To date, these types have been sufficient for describing things that TableGen
81 has been used for, but it is straight-forward to extend this list if needed.
83 .. _TableGen expressions:
85 TableGen values and expressions
86 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88 TableGen allows for a pretty reasonable number of different expression forms
89 when building up values. These forms allow the TableGen file to be written in a
90 natural syntax and flavor for the application. The current expression forms
100 octal integer value (indicated by a leading 0)
103 decimal integer value
106 hexadecimal integer value
112 usually called a "code fragment", but is just a multiline string literal
114 ``[ X, Y, Z ]<type>``
115 list value. <type> is the type of the list element and is usually optional.
116 In rare cases, TableGen is unable to deduce the element type in which case
117 the user must specify it explicitly.
120 initializer for a "bits<3>" value
126 access to one bit of a value
129 access to multiple bits of a value
132 reference to a record definition
135 reference to a new anonymous definition of CLASS with the specified template
139 reference to the subfield of a value
142 A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
143 Elements may be included multiple times.
145 ``foreach <var> = [ <list> ] in { <body> }``
147 ``foreach <var> = [ <list> ] in <def>``
148 Replicate <body> or <def>, replacing instances of <var> with each value
149 in <list>. <var> is scoped at the level of the ``foreach`` loop and must
150 not conflict with any other object introduced in <body> or <def>. Currently
151 only ``def``\s are expanded within <body>.
153 ``foreach <var> = 0-15 in ...``
155 ``foreach <var> = {0-15,32-47} in ...``
156 Loop over ranges of integers. The braces are required for multiple ranges.
159 a dag value. The first element is required to be a record definition, the
160 remaining elements in the list may be arbitrary other values, including
161 nested ```dag``' values.
163 ``!listconcat(a, b, ...)``
164 A list value that is the result of concatenating the 'a' and 'b' lists.
165 The lists must have the same element type.
166 More than two arguments are accepted with the result being the concatenation
167 of all the lists given.
169 ``!strconcat(a, b, ...)``
170 A string value that is the result of concatenating the 'a' and 'b' strings.
171 More than two arguments are accepted with the result being the concatenation
172 of all the strings given.
175 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
176 are not quoted strings, in which case an implicit !cast<string> is done on
177 the operand of the paste.
180 A symbol of type *type* obtained by looking up the string 'a' in the symbol
181 table. If the type of 'a' does not match *type*, TableGen aborts with an
182 error. !cast<string> is a special case in that the argument must be an
183 object defined by a 'def' construct.
186 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
187 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
189 ``!foreach(a, b, c)``
190 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
191 variable that should be declared as a member variable of an instantiated
192 class. This operation is analogous to $(foreach) in GNU make.
195 The first element of list 'a.'
198 The 2nd-N elements of list 'a.'
201 An integer {0,1} indicating whether list 'a' is empty.
204 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
207 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
208 on string, int and bit objects. Use !cast<string> to compare other types of
211 Note that all of the values have rules specifying how they convert to values
212 for different types. These rules allow you to assign a value like "``7``"
213 to a "``bits<4>``" value, for example.
215 Classes and definitions
216 -----------------------
218 As mentioned in the :doc:`introduction <index>`, classes and definitions (collectively known as
219 'records') in TableGen are the main high-level unit of information that TableGen
220 collects. Records are defined with a ``def`` or ``class`` keyword, the record
221 name, and an optional list of "`template arguments`_". If the record has
222 superclasses, they are specified as a comma separated list that starts with a
223 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
224 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
225 the record ends with a semicolon.
227 Here is a simple TableGen file:
231 class C { bit V = 1; }
234 string Greeting = "hello";
237 This example defines two definitions, ``X`` and ``Y``, both of which derive from
238 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
239 definition also gets the Greeting member as well.
241 In general, classes are useful for collecting together the commonality between a
242 group of records and isolating it in a single place. Also, classes permit the
243 specification of default values for their subclasses, allowing the subclasses to
244 override them as they wish.
246 .. _value definition:
247 .. _value definitions:
252 Value definitions define named entries in records. A value must be defined
253 before it can be referred to as the operand for another value definition or
254 before the value is reset with a `let expression`_. A value is defined by
255 specifying a `TableGen type`_ and a name. If an initial value is available, it
256 may be specified after the type with an equal sign. Value definitions require
257 terminating semicolons.
261 .. _"let" expressions within a record:
266 A record-level let expression is used to change the value of a value definition
267 in a record. This is primarily useful when a superclass defines a value that a
268 derived class or definition wants to override. Let expressions consist of the
269 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
270 value. For example, a new class could be added to the example above, redefining
271 the ``V`` field for all of its subclasses:
275 class D : C { let V = 0; }
278 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
279 despite the fact that it derives (indirectly) from the ``C`` class, because the
280 ``D`` class overrode its value.
282 .. _template arguments:
284 Class template arguments
285 ^^^^^^^^^^^^^^^^^^^^^^^^
287 TableGen permits the definition of parameterized classes as well as normal
288 concrete classes. Parameterized TableGen classes specify a list of variable
289 bindings (which may optionally have defaults) that are bound when used. Here is
294 class FPFormat<bits<3> val> {
297 def NotFP : FPFormat<0>;
298 def ZeroArgFP : FPFormat<1>;
299 def OneArgFP : FPFormat<2>;
300 def OneArgFPRW : FPFormat<3>;
301 def TwoArgFP : FPFormat<4>;
302 def CompareFP : FPFormat<5>;
303 def CondMovFP : FPFormat<6>;
304 def SpecialFP : FPFormat<7>;
306 In this case, template arguments are used as a space efficient way to specify a
307 list of "enumeration values", each with a "``Value``" field set to the specified
310 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
311 with template arguments. As an example:
315 class ModRefVal<bits<2> val> {
319 def None : ModRefVal<0>;
320 def Mod : ModRefVal<1>;
321 def Ref : ModRefVal<2>;
322 def ModRef : ModRefVal<3>;
324 class Value<ModRefVal MR> {
325 // Decode some information into a more convenient format, while providing
326 // a nice interface to the user of the "Value" class.
327 bit isMod = MR.Value{0};
328 bit isRef = MR.Value{1};
334 def bork : Value<Mod>;
335 def zork : Value<Ref>;
336 def hork : Value<ModRef>;
338 This is obviously a contrived example, but it shows how template arguments can
339 be used to decouple the interface provided to the user of the class from the
340 actual internal data representation expected by the class. In this case,
341 running ``llvm-tblgen`` on the example prints the following definitions:
358 This shows that TableGen was able to dig into the argument and extract a piece
359 of information that was requested by the designer of the "Value" class. For
360 more realistic examples, please see existing users of TableGen, such as the X86
363 Multiclass definitions and instances
364 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
366 While classes with template arguments are a good way to factor commonality
367 between two instances of a definition, multiclasses allow a convenient notation
368 for defining multiple definitions at once (instances of implicitly constructed
369 classes). For example, consider an 3-address instruction set whose instructions
370 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
371 (e.g. SPARC). In this case, you'd like to specify in one place that this
372 commonality exists, then in a separate place indicate what all the ops are.
374 Here is an example TableGen fragment that shows this idea:
381 class inst<int opc, string asmstr, dag operandlist>;
383 multiclass ri_inst<int opc, string asmstr> {
384 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
385 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
386 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
387 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
390 // Instantiations of the ri_inst multiclass.
391 defm ADD : ri_inst<0b111, "add">;
392 defm SUB : ri_inst<0b101, "sub">;
393 defm MUL : ri_inst<0b100, "mul">;
396 The name of the resultant definitions has the multidef fragment names appended
397 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
398 inherit from multiple multiclasses, instantiating definitions from each
399 multiclass. Using a multiclass this way is exactly equivalent to instantiating
400 the classes multiple times yourself, e.g. by writing:
407 class inst<int opc, string asmstr, dag operandlist>;
409 class rrinst<int opc, string asmstr>
410 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
411 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
413 class riinst<int opc, string asmstr>
414 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
415 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
417 // Instantiations of the ri_inst multiclass.
418 def ADD_rr : rrinst<0b111, "add">;
419 def ADD_ri : riinst<0b111, "add">;
420 def SUB_rr : rrinst<0b101, "sub">;
421 def SUB_ri : riinst<0b101, "sub">;
422 def MUL_rr : rrinst<0b100, "mul">;
423 def MUL_ri : riinst<0b100, "mul">;
426 A ``defm`` can also be used inside a multiclass providing several levels of
427 multiclass instantiations.
431 class Instruction<bits<4> opc, string Name> {
432 bits<4> opcode = opc;
436 multiclass basic_r<bits<4> opc> {
437 def rr : Instruction<opc, "rr">;
438 def rm : Instruction<opc, "rm">;
441 multiclass basic_s<bits<4> opc> {
442 defm SS : basic_r<opc>;
443 defm SD : basic_r<opc>;
444 def X : Instruction<opc, "x">;
447 multiclass basic_p<bits<4> opc> {
448 defm PS : basic_r<opc>;
449 defm PD : basic_r<opc>;
450 def Y : Instruction<opc, "y">;
453 defm ADD : basic_s<0xf>, basic_p<0xf>;
466 ``defm`` declarations can inherit from classes too, the rule to follow is that
467 the class list must start after the last multiclass, and there must be at least
468 one multiclass before them.
472 class XD { bits<4> Prefix = 11; }
473 class XS { bits<4> Prefix = 12; }
475 class I<bits<4> op> {
493 bits<4> opcode = { 0, 0, 1, 0 };
494 bits<4> Prefix = { 1, 1, 0, 0 };
498 bits<4> opcode = { 0, 1, 0, 0 };
499 bits<4> Prefix = { 1, 0, 1, 1 };
508 TableGen supports the '``include``' token, which textually substitutes the
509 specified file in place of the include directive. The filename should be
510 specified as a double quoted string immediately after the '``include``' keyword.
520 "Let" expressions at file scope are similar to `"let" expressions within a
521 record`_, except they can specify a value binding for multiple records at a
522 time, and may be useful in certain other cases. File-scope let expressions are
523 really just another way that TableGen allows the end-user to factor out
524 commonality from the records.
526 File-scope "let" expressions take a comma-separated list of bindings to apply,
527 and one or more records to bind the values in. Here are some examples:
531 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
532 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
535 // All calls clobber the non-callee saved registers...
536 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
537 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
538 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
539 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
540 "call\t${dst:call}", []>;
541 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
542 "call\t{*}$dst", [(X86call GR32:$dst)]>;
543 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
544 "call\t{*}$dst", []>;
547 File-scope "let" expressions are often useful when a couple of definitions need
548 to be added to several records, and the records do not otherwise need to be
549 opened, as in the case with the ``CALL*`` instructions above.
551 It's also possible to use "let" expressions inside multiclasses, providing more
552 ways to factor out commonality from the records, specially if using several
553 levels of multiclass instantiations. This also avoids the need of using "let"
554 expressions within subsequent records inside a multiclass.
558 multiclass basic_r<bits<4> opc> {
559 let Predicates = [HasSSE2] in {
560 def rr : Instruction<opc, "rr">;
561 def rm : Instruction<opc, "rm">;
563 let Predicates = [HasSSE3] in
564 def rx : Instruction<opc, "rx">;
567 multiclass basic_ss<bits<4> opc> {
569 defm SS : basic_r<opc>;
572 defm SD : basic_r<opc>;
575 defm ADD : basic_ss<0xf>;
580 TableGen supports the '``foreach``' block, which textually replicates the loop
581 body, substituting iterator values for iterator references in the body.
586 foreach i = [0, 1, 2, 3] in {
587 def R#i : Register<...>;
588 def F#i : Register<...>;
591 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
592 may be nested. If there is only one item in the body the braces may be
597 foreach i = [0, 1, 2, 3] in
598 def R#i : Register<...>;
600 Code Generator backend info
601 ===========================
603 Expressions used by code generator to describe instructions and isel patterns:
606 an implicitly defined physical register. This tells the dag instruction
607 selection emitter the input pattern's extra definitions matches implicit
608 physical register definitions.