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 ``!shl(a,b)`` ``!srl(a,b)`` ``!sra(a,b)`` ``!add(a,b)``
212 The usual logical and arithmetic operators.
214 Note that all of the values have rules specifying how they convert to values
215 for different types. These rules allow you to assign a value like "``7``"
216 to a "``bits<4>``" value, for example.
218 Classes and definitions
219 -----------------------
221 As mentioned in the :doc:`introduction <index>`, classes and definitions (collectively known as
222 'records') in TableGen are the main high-level unit of information that TableGen
223 collects. Records are defined with a ``def`` or ``class`` keyword, the record
224 name, and an optional list of "`template arguments`_". If the record has
225 superclasses, they are specified as a comma separated list that starts with a
226 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
227 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
228 the record ends with a semicolon.
230 Here is a simple TableGen file:
234 class C { bit V = 1; }
237 string Greeting = "hello";
240 This example defines two definitions, ``X`` and ``Y``, both of which derive from
241 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
242 definition also gets the Greeting member as well.
244 In general, classes are useful for collecting together the commonality between a
245 group of records and isolating it in a single place. Also, classes permit the
246 specification of default values for their subclasses, allowing the subclasses to
247 override them as they wish.
249 .. _value definition:
250 .. _value definitions:
255 Value definitions define named entries in records. A value must be defined
256 before it can be referred to as the operand for another value definition or
257 before the value is reset with a `let expression`_. A value is defined by
258 specifying a `TableGen type`_ and a name. If an initial value is available, it
259 may be specified after the type with an equal sign. Value definitions require
260 terminating semicolons.
264 .. _"let" expressions within a record:
269 A record-level let expression is used to change the value of a value definition
270 in a record. This is primarily useful when a superclass defines a value that a
271 derived class or definition wants to override. Let expressions consist of the
272 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
273 value. For example, a new class could be added to the example above, redefining
274 the ``V`` field for all of its subclasses:
278 class D : C { let V = 0; }
281 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
282 despite the fact that it derives (indirectly) from the ``C`` class, because the
283 ``D`` class overrode its value.
285 .. _template arguments:
287 Class template arguments
288 ^^^^^^^^^^^^^^^^^^^^^^^^
290 TableGen permits the definition of parameterized classes as well as normal
291 concrete classes. Parameterized TableGen classes specify a list of variable
292 bindings (which may optionally have defaults) that are bound when used. Here is
297 class FPFormat<bits<3> val> {
300 def NotFP : FPFormat<0>;
301 def ZeroArgFP : FPFormat<1>;
302 def OneArgFP : FPFormat<2>;
303 def OneArgFPRW : FPFormat<3>;
304 def TwoArgFP : FPFormat<4>;
305 def CompareFP : FPFormat<5>;
306 def CondMovFP : FPFormat<6>;
307 def SpecialFP : FPFormat<7>;
309 In this case, template arguments are used as a space efficient way to specify a
310 list of "enumeration values", each with a "``Value``" field set to the specified
313 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
314 with template arguments. As an example:
318 class ModRefVal<bits<2> val> {
322 def None : ModRefVal<0>;
323 def Mod : ModRefVal<1>;
324 def Ref : ModRefVal<2>;
325 def ModRef : ModRefVal<3>;
327 class Value<ModRefVal MR> {
328 // Decode some information into a more convenient format, while providing
329 // a nice interface to the user of the "Value" class.
330 bit isMod = MR.Value{0};
331 bit isRef = MR.Value{1};
337 def bork : Value<Mod>;
338 def zork : Value<Ref>;
339 def hork : Value<ModRef>;
341 This is obviously a contrived example, but it shows how template arguments can
342 be used to decouple the interface provided to the user of the class from the
343 actual internal data representation expected by the class. In this case,
344 running ``llvm-tblgen`` on the example prints the following definitions:
361 This shows that TableGen was able to dig into the argument and extract a piece
362 of information that was requested by the designer of the "Value" class. For
363 more realistic examples, please see existing users of TableGen, such as the X86
366 Multiclass definitions and instances
367 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
369 While classes with template arguments are a good way to factor commonality
370 between two instances of a definition, multiclasses allow a convenient notation
371 for defining multiple definitions at once (instances of implicitly constructed
372 classes). For example, consider an 3-address instruction set whose instructions
373 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
374 (e.g. SPARC). In this case, you'd like to specify in one place that this
375 commonality exists, then in a separate place indicate what all the ops are.
377 Here is an example TableGen fragment that shows this idea:
384 class inst<int opc, string asmstr, dag operandlist>;
386 multiclass ri_inst<int opc, string asmstr> {
387 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
388 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
389 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
390 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
393 // Instantiations of the ri_inst multiclass.
394 defm ADD : ri_inst<0b111, "add">;
395 defm SUB : ri_inst<0b101, "sub">;
396 defm MUL : ri_inst<0b100, "mul">;
399 The name of the resultant definitions has the multidef fragment names appended
400 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
401 inherit from multiple multiclasses, instantiating definitions from each
402 multiclass. Using a multiclass this way is exactly equivalent to instantiating
403 the classes multiple times yourself, e.g. by writing:
410 class inst<int opc, string asmstr, dag operandlist>;
412 class rrinst<int opc, string asmstr>
413 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
414 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
416 class riinst<int opc, string asmstr>
417 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
418 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
420 // Instantiations of the ri_inst multiclass.
421 def ADD_rr : rrinst<0b111, "add">;
422 def ADD_ri : riinst<0b111, "add">;
423 def SUB_rr : rrinst<0b101, "sub">;
424 def SUB_ri : riinst<0b101, "sub">;
425 def MUL_rr : rrinst<0b100, "mul">;
426 def MUL_ri : riinst<0b100, "mul">;
429 A ``defm`` can also be used inside a multiclass providing several levels of
430 multiclass instantiations.
434 class Instruction<bits<4> opc, string Name> {
435 bits<4> opcode = opc;
439 multiclass basic_r<bits<4> opc> {
440 def rr : Instruction<opc, "rr">;
441 def rm : Instruction<opc, "rm">;
444 multiclass basic_s<bits<4> opc> {
445 defm SS : basic_r<opc>;
446 defm SD : basic_r<opc>;
447 def X : Instruction<opc, "x">;
450 multiclass basic_p<bits<4> opc> {
451 defm PS : basic_r<opc>;
452 defm PD : basic_r<opc>;
453 def Y : Instruction<opc, "y">;
456 defm ADD : basic_s<0xf>, basic_p<0xf>;
469 ``defm`` declarations can inherit from classes too, the rule to follow is that
470 the class list must start after the last multiclass, and there must be at least
471 one multiclass before them.
475 class XD { bits<4> Prefix = 11; }
476 class XS { bits<4> Prefix = 12; }
478 class I<bits<4> op> {
496 bits<4> opcode = { 0, 0, 1, 0 };
497 bits<4> Prefix = { 1, 1, 0, 0 };
501 bits<4> opcode = { 0, 1, 0, 0 };
502 bits<4> Prefix = { 1, 0, 1, 1 };
511 TableGen supports the '``include``' token, which textually substitutes the
512 specified file in place of the include directive. The filename should be
513 specified as a double quoted string immediately after the '``include``' keyword.
523 "Let" expressions at file scope are similar to `"let" expressions within a
524 record`_, except they can specify a value binding for multiple records at a
525 time, and may be useful in certain other cases. File-scope let expressions are
526 really just another way that TableGen allows the end-user to factor out
527 commonality from the records.
529 File-scope "let" expressions take a comma-separated list of bindings to apply,
530 and one or more records to bind the values in. Here are some examples:
534 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
535 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
538 // All calls clobber the non-callee saved registers...
539 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
540 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
541 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
542 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
543 "call\t${dst:call}", []>;
544 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
545 "call\t{*}$dst", [(X86call GR32:$dst)]>;
546 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
547 "call\t{*}$dst", []>;
550 File-scope "let" expressions are often useful when a couple of definitions need
551 to be added to several records, and the records do not otherwise need to be
552 opened, as in the case with the ``CALL*`` instructions above.
554 It's also possible to use "let" expressions inside multiclasses, providing more
555 ways to factor out commonality from the records, specially if using several
556 levels of multiclass instantiations. This also avoids the need of using "let"
557 expressions within subsequent records inside a multiclass.
561 multiclass basic_r<bits<4> opc> {
562 let Predicates = [HasSSE2] in {
563 def rr : Instruction<opc, "rr">;
564 def rm : Instruction<opc, "rm">;
566 let Predicates = [HasSSE3] in
567 def rx : Instruction<opc, "rx">;
570 multiclass basic_ss<bits<4> opc> {
572 defm SS : basic_r<opc>;
575 defm SD : basic_r<opc>;
578 defm ADD : basic_ss<0xf>;
583 TableGen supports the '``foreach``' block, which textually replicates the loop
584 body, substituting iterator values for iterator references in the body.
589 foreach i = [0, 1, 2, 3] in {
590 def R#i : Register<...>;
591 def F#i : Register<...>;
594 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
595 may be nested. If there is only one item in the body the braces may be
600 foreach i = [0, 1, 2, 3] in
601 def R#i : Register<...>;
603 Code Generator backend info
604 ===========================
606 Expressions used by code generator to describe instructions and isel patterns:
609 an implicitly defined physical register. This tells the dag instruction
610 selection emitter the input pattern's extra definitions matches implicit
611 physical register definitions.