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.
164 A string value that is the result of concatenating the 'a' and 'b' strings.
167 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
168 are not quoted strings, in which case an implicit !cast<string> is done on
169 the operand of the paste.
172 A symbol of type *type* obtained by looking up the string 'a' in the symbol
173 table. If the type of 'a' does not match *type*, TableGen aborts with an
174 error. !cast<string> is a special case in that the argument must be an
175 object defined by a 'def' construct.
178 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
179 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
181 ``!foreach(a, b, c)``
182 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
183 variable that should be declared as a member variable of an instantiated
184 class. This operation is analogous to $(foreach) in GNU make.
187 The first element of list 'a.'
190 The 2nd-N elements of list 'a.'
193 An integer {0,1} indicating whether list 'a' is empty.
196 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
199 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
200 on string, int and bit objects. Use !cast<string> to compare other types of
203 Note that all of the values have rules specifying how they convert to values
204 for different types. These rules allow you to assign a value like "``7``"
205 to a "``bits<4>``" value, for example.
207 Classes and definitions
208 -----------------------
210 As mentioned in the :doc:`introduction <index>`, classes and definitions (collectively known as
211 'records') in TableGen are the main high-level unit of information that TableGen
212 collects. Records are defined with a ``def`` or ``class`` keyword, the record
213 name, and an optional list of "`template arguments`_". If the record has
214 superclasses, they are specified as a comma separated list that starts with a
215 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
216 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
217 the record ends with a semicolon.
219 Here is a simple TableGen file:
223 class C { bit V = 1; }
226 string Greeting = "hello";
229 This example defines two definitions, ``X`` and ``Y``, both of which derive from
230 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
231 definition also gets the Greeting member as well.
233 In general, classes are useful for collecting together the commonality between a
234 group of records and isolating it in a single place. Also, classes permit the
235 specification of default values for their subclasses, allowing the subclasses to
236 override them as they wish.
238 .. _value definition:
239 .. _value definitions:
244 Value definitions define named entries in records. A value must be defined
245 before it can be referred to as the operand for another value definition or
246 before the value is reset with a `let expression`_. A value is defined by
247 specifying a `TableGen type`_ and a name. If an initial value is available, it
248 may be specified after the type with an equal sign. Value definitions require
249 terminating semicolons.
253 .. _"let" expressions within a record:
258 A record-level let expression is used to change the value of a value definition
259 in a record. This is primarily useful when a superclass defines a value that a
260 derived class or definition wants to override. Let expressions consist of the
261 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
262 value. For example, a new class could be added to the example above, redefining
263 the ``V`` field for all of its subclasses:
267 class D : C { let V = 0; }
270 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
271 despite the fact that it derives (indirectly) from the ``C`` class, because the
272 ``D`` class overrode its value.
274 .. _template arguments:
276 Class template arguments
277 ^^^^^^^^^^^^^^^^^^^^^^^^
279 TableGen permits the definition of parameterized classes as well as normal
280 concrete classes. Parameterized TableGen classes specify a list of variable
281 bindings (which may optionally have defaults) that are bound when used. Here is
286 class FPFormat<bits<3> val> {
289 def NotFP : FPFormat<0>;
290 def ZeroArgFP : FPFormat<1>;
291 def OneArgFP : FPFormat<2>;
292 def OneArgFPRW : FPFormat<3>;
293 def TwoArgFP : FPFormat<4>;
294 def CompareFP : FPFormat<5>;
295 def CondMovFP : FPFormat<6>;
296 def SpecialFP : FPFormat<7>;
298 In this case, template arguments are used as a space efficient way to specify a
299 list of "enumeration values", each with a "``Value``" field set to the specified
302 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
303 with template arguments. As an example:
307 class ModRefVal<bits<2> val> {
311 def None : ModRefVal<0>;
312 def Mod : ModRefVal<1>;
313 def Ref : ModRefVal<2>;
314 def ModRef : ModRefVal<3>;
316 class Value<ModRefVal MR> {
317 // Decode some information into a more convenient format, while providing
318 // a nice interface to the user of the "Value" class.
319 bit isMod = MR.Value{0};
320 bit isRef = MR.Value{1};
326 def bork : Value<Mod>;
327 def zork : Value<Ref>;
328 def hork : Value<ModRef>;
330 This is obviously a contrived example, but it shows how template arguments can
331 be used to decouple the interface provided to the user of the class from the
332 actual internal data representation expected by the class. In this case,
333 running ``llvm-tblgen`` on the example prints the following definitions:
350 This shows that TableGen was able to dig into the argument and extract a piece
351 of information that was requested by the designer of the "Value" class. For
352 more realistic examples, please see existing users of TableGen, such as the X86
355 Multiclass definitions and instances
356 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
358 While classes with template arguments are a good way to factor commonality
359 between two instances of a definition, multiclasses allow a convenient notation
360 for defining multiple definitions at once (instances of implicitly constructed
361 classes). For example, consider an 3-address instruction set whose instructions
362 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
363 (e.g. SPARC). In this case, you'd like to specify in one place that this
364 commonality exists, then in a separate place indicate what all the ops are.
366 Here is an example TableGen fragment that shows this idea:
373 class inst<int opc, string asmstr, dag operandlist>;
375 multiclass ri_inst<int opc, string asmstr> {
376 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
377 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
378 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
379 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
382 // Instantiations of the ri_inst multiclass.
383 defm ADD : ri_inst<0b111, "add">;
384 defm SUB : ri_inst<0b101, "sub">;
385 defm MUL : ri_inst<0b100, "mul">;
388 The name of the resultant definitions has the multidef fragment names appended
389 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
390 inherit from multiple multiclasses, instantiating definitions from each
391 multiclass. Using a multiclass this way is exactly equivalent to instantiating
392 the classes multiple times yourself, e.g. by writing:
399 class inst<int opc, string asmstr, dag operandlist>;
401 class rrinst<int opc, string asmstr>
402 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
403 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
405 class riinst<int opc, string asmstr>
406 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
407 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
409 // Instantiations of the ri_inst multiclass.
410 def ADD_rr : rrinst<0b111, "add">;
411 def ADD_ri : riinst<0b111, "add">;
412 def SUB_rr : rrinst<0b101, "sub">;
413 def SUB_ri : riinst<0b101, "sub">;
414 def MUL_rr : rrinst<0b100, "mul">;
415 def MUL_ri : riinst<0b100, "mul">;
418 A ``defm`` can also be used inside a multiclass providing several levels of
419 multiclass instantiations.
423 class Instruction<bits<4> opc, string Name> {
424 bits<4> opcode = opc;
428 multiclass basic_r<bits<4> opc> {
429 def rr : Instruction<opc, "rr">;
430 def rm : Instruction<opc, "rm">;
433 multiclass basic_s<bits<4> opc> {
434 defm SS : basic_r<opc>;
435 defm SD : basic_r<opc>;
436 def X : Instruction<opc, "x">;
439 multiclass basic_p<bits<4> opc> {
440 defm PS : basic_r<opc>;
441 defm PD : basic_r<opc>;
442 def Y : Instruction<opc, "y">;
445 defm ADD : basic_s<0xf>, basic_p<0xf>;
458 ``defm`` declarations can inherit from classes too, the rule to follow is that
459 the class list must start after the last multiclass, and there must be at least
460 one multiclass before them.
464 class XD { bits<4> Prefix = 11; }
465 class XS { bits<4> Prefix = 12; }
467 class I<bits<4> op> {
485 bits<4> opcode = { 0, 0, 1, 0 };
486 bits<4> Prefix = { 1, 1, 0, 0 };
490 bits<4> opcode = { 0, 1, 0, 0 };
491 bits<4> Prefix = { 1, 0, 1, 1 };
500 TableGen supports the '``include``' token, which textually substitutes the
501 specified file in place of the include directive. The filename should be
502 specified as a double quoted string immediately after the '``include``' keyword.
512 "Let" expressions at file scope are similar to `"let" expressions within a
513 record`_, except they can specify a value binding for multiple records at a
514 time, and may be useful in certain other cases. File-scope let expressions are
515 really just another way that TableGen allows the end-user to factor out
516 commonality from the records.
518 File-scope "let" expressions take a comma-separated list of bindings to apply,
519 and one or more records to bind the values in. Here are some examples:
523 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
524 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
527 // All calls clobber the non-callee saved registers...
528 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
529 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
530 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
531 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
532 "call\t${dst:call}", []>;
533 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
534 "call\t{*}$dst", [(X86call GR32:$dst)]>;
535 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
536 "call\t{*}$dst", []>;
539 File-scope "let" expressions are often useful when a couple of definitions need
540 to be added to several records, and the records do not otherwise need to be
541 opened, as in the case with the ``CALL*`` instructions above.
543 It's also possible to use "let" expressions inside multiclasses, providing more
544 ways to factor out commonality from the records, specially if using several
545 levels of multiclass instantiations. This also avoids the need of using "let"
546 expressions within subsequent records inside a multiclass.
550 multiclass basic_r<bits<4> opc> {
551 let Predicates = [HasSSE2] in {
552 def rr : Instruction<opc, "rr">;
553 def rm : Instruction<opc, "rm">;
555 let Predicates = [HasSSE3] in
556 def rx : Instruction<opc, "rx">;
559 multiclass basic_ss<bits<4> opc> {
561 defm SS : basic_r<opc>;
564 defm SD : basic_r<opc>;
567 defm ADD : basic_ss<0xf>;
572 TableGen supports the '``foreach``' block, which textually replicates the loop
573 body, substituting iterator values for iterator references in the body.
578 foreach i = [0, 1, 2, 3] in {
579 def R#i : Register<...>;
580 def F#i : Register<...>;
583 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
584 may be nested. If there is only one item in the body the braces may be
589 foreach i = [0, 1, 2, 3] in
590 def R#i : Register<...>;
592 Code Generator backend info
593 ===========================
595 Expressions used by code generator to describe instructions and isel patterns:
598 an implicitly defined physical register. This tells the dag instruction
599 selection emitter the input pattern's extra definitions matches implicit
600 physical register definitions.