llvm.org GIT mirror llvm / a5b283a
Recover TableGen/LangRef, make it official Making the new TableGen documentation official and marking the old file as "Moved". Also, reverting the original LangRef as the normative formal description of the language, while keeping the "new" LangRef as LangIntro for the less inlcined to reading language grammars. We should remove TableGenFundamentals.rst one day, but for now, just a warning that it moved will have to do, while we make sure there are no more links to it from elsewhere. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@205289 91177308-0d34-0410-b5e6-96231b3b80d8 Renato Golin 5 years ago
5 changed file(s) with 980 addition(s) and 1376 deletion(s). Raw diff Collapse all Expand all
0 ==============================
1 TableGen Language Introduction
2 ==============================
3
4 .. contents::
5 :local:
6
7 .. warning::
8 This document is extremely rough. If you find something lacking, please
9 fix it, file a documentation bug, or ask about it on llvmdev.
10
11 Introduction
12 ============
13
14 This document is not meant to be a normative spec about the TableGen language
15 in and of itself (i.e. how to understand a given construct in terms of how
16 it affects the final set of records represented by the TableGen file). For
17 the formal language specification, see :doc:`LangRef`.
18
19 TableGen syntax
20 ===============
21
22 TableGen doesn't care about the meaning of data (that is up to the backend to
23 define), but it does care about syntax, and it enforces a simple type system.
24 This section describes the syntax and the constructs allowed in a TableGen file.
25
26 TableGen primitives
27 -------------------
28
29 TableGen comments
30 ^^^^^^^^^^^^^^^^^
31
32 TableGen supports C++ style "``//``" comments, which run to the end of the
33 line, and it also supports **nestable** "``/* */``" comments.
34
35 .. _TableGen type:
36
37 The TableGen type system
38 ^^^^^^^^^^^^^^^^^^^^^^^^
39
40 TableGen files are strongly typed, in a simple (but complete) type-system.
41 These types are used to perform automatic conversions, check for errors, and to
42 help interface designers constrain the input that they allow. Every `value
43 definition`_ is required to have an associated type.
44
45 TableGen supports a mixture of very low-level types (such as ``bit``) and very
46 high-level types (such as ``dag``). This flexibility is what allows it to
47 describe a wide range of information conveniently and compactly. The TableGen
48 types are:
49
50 ``bit``
51 A 'bit' is a boolean value that can hold either 0 or 1.
52
53 ``int``
54 The 'int' type represents a simple 32-bit integer value, such as 5.
55
56 ``string``
57 The 'string' type represents an ordered sequence of characters of arbitrary
58 length.
59
60 ``bits``
61 A 'bits' type is an arbitrary, but fixed, size integer that is broken up
62 into individual bits. This type is useful because it can handle some bits
63 being defined while others are undefined.
64
65 ``list``
66 This type represents a list whose elements are some other type. The
67 contained type is arbitrary: it can even be another list type.
68
69 Class type
70 Specifying a class name in a type context means that the defined value must
71 be a subclass of the specified class. This is useful in conjunction with
72 the ``list`` type, for example, to constrain the elements of the list to a
73 common base class (e.g., a ``list`` can only contain definitions
74 derived from the "``Register``" class).
75
76 ``dag``
77 This type represents a nestable directed graph of elements.
78
79 To date, these types have been sufficient for describing things that TableGen
80 has been used for, but it is straight-forward to extend this list if needed.
81
82 .. _TableGen expressions:
83
84 TableGen values and expressions
85 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
86
87 TableGen allows for a pretty reasonable number of different expression forms
88 when building up values. These forms allow the TableGen file to be written in a
89 natural syntax and flavor for the application. The current expression forms
90 supported include:
91
92 ``?``
93 uninitialized field
94
95 ``0b1001011``
96 binary integer value
97
98 ``07654321``
99 octal integer value (indicated by a leading 0)
100
101 ``7``
102 decimal integer value
103
104 ``0x7F``
105 hexadecimal integer value
106
107 ``"foo"``
108 string value
109
110 ``[{ ... }]``
111 usually called a "code fragment", but is just a multiline string literal
112
113 ``[ X, Y, Z ]``
114 list value. is the type of the list element and is usually optional.
115 In rare cases, TableGen is unable to deduce the element type in which case
116 the user must specify it explicitly.
117
118 ``{ a, b, c }``
119 initializer for a "bits<3>" value
120
121 ``value``
122 value reference
123
124 ``value{17}``
125 access to one bit of a value
126
127 ``value{15-17}``
128 access to multiple bits of a value
129
130 ``DEF``
131 reference to a record definition
132
133 ``CLASS``
134 reference to a new anonymous definition of CLASS with the specified template
135 arguments.
136
137 ``X.Y``
138 reference to the subfield of a value
139
140 ``list[4-7,17,2-3]``
141 A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
142 Elements may be included multiple times.
143
144 ``foreach = [ ] in { }``
145
146 ``foreach = [ ] in ``
147 Replicate or , replacing instances of with each value
148 in . is scoped at the level of the ``foreach`` loop and must
149 not conflict with any other object introduced in or . Currently
150 only ``def``\s are expanded within .
151
152 ``foreach = 0-15 in ...``
153
154 ``foreach = {0-15,32-47} in ...``
155 Loop over ranges of integers. The braces are required for multiple ranges.
156
157 ``(DEF a, b)``
158 a dag value. The first element is required to be a record definition, the
159 remaining elements in the list may be arbitrary other values, including
160 nested ```dag``' values.
161
162 ``!strconcat(a, b)``
163 A string value that is the result of concatenating the 'a' and 'b' strings.
164
165 ``str1#str2``
166 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
167 are not quoted strings, in which case an implicit !cast is done on
168 the operand of the paste.
169
170 ``!cast(a)``
171 A symbol of type *type* obtained by looking up the string 'a' in the symbol
172 table. If the type of 'a' does not match *type*, TableGen aborts with an
173 error. !cast is a special case in that the argument must be an
174 object defined by a 'def' construct.
175
176 ``!subst(a, b, c)``
177 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
178 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
179
180 ``!foreach(a, b, c)``
181 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
182 variable that should be declared as a member variable of an instantiated
183 class. This operation is analogous to $(foreach) in GNU make.
184
185 ``!head(a)``
186 The first element of list 'a.'
187
188 ``!tail(a)``
189 The 2nd-N elements of list 'a.'
190
191 ``!empty(a)``
192 An integer {0,1} indicating whether list 'a' is empty.
193
194 ``!if(a,b,c)``
195 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
196
197 ``!eq(a,b)``
198 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
199 on string, int and bit objects. Use !cast to compare other types of
200 objects.
201
202 Note that all of the values have rules specifying how they convert to values
203 for different types. These rules allow you to assign a value like "``7``"
204 to a "``bits<4>``" value, for example.
205
206 Classes and definitions
207 -----------------------
208
209 As mentioned in the :doc:`introduction `, classes and definitions (collectively known as
210 'records') in TableGen are the main high-level unit of information that TableGen
211 collects. Records are defined with a ``def`` or ``class`` keyword, the record
212 name, and an optional list of "`template arguments`_". If the record has
213 superclasses, they are specified as a comma separated list that starts with a
214 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
215 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
216 the record ends with a semicolon.
217
218 Here is a simple TableGen file:
219
220 .. code-block:: llvm
221
222 class C { bit V = 1; }
223 def X : C;
224 def Y : C {
225 string Greeting = "hello";
226 }
227
228 This example defines two definitions, ``X`` and ``Y``, both of which derive from
229 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
230 definition also gets the Greeting member as well.
231
232 In general, classes are useful for collecting together the commonality between a
233 group of records and isolating it in a single place. Also, classes permit the
234 specification of default values for their subclasses, allowing the subclasses to
235 override them as they wish.
236
237 .. _value definition:
238 .. _value definitions:
239
240 Value definitions
241 ^^^^^^^^^^^^^^^^^
242
243 Value definitions define named entries in records. A value must be defined
244 before it can be referred to as the operand for another value definition or
245 before the value is reset with a `let expression`_. A value is defined by
246 specifying a `TableGen type`_ and a name. If an initial value is available, it
247 may be specified after the type with an equal sign. Value definitions require
248 terminating semicolons.
249
250 .. _let expression:
251 .. _let expressions:
252 .. _"let" expressions within a record:
253
254 'let' expressions
255 ^^^^^^^^^^^^^^^^^
256
257 A record-level let expression is used to change the value of a value definition
258 in a record. This is primarily useful when a superclass defines a value that a
259 derived class or definition wants to override. Let expressions consist of the
260 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
261 value. For example, a new class could be added to the example above, redefining
262 the ``V`` field for all of its subclasses:
263
264 .. code-block:: llvm
265
266 class D : C { let V = 0; }
267 def Z : D;
268
269 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
270 despite the fact that it derives (indirectly) from the ``C`` class, because the
271 ``D`` class overrode its value.
272
273 .. _template arguments:
274
275 Class template arguments
276 ^^^^^^^^^^^^^^^^^^^^^^^^
277
278 TableGen permits the definition of parameterized classes as well as normal
279 concrete classes. Parameterized TableGen classes specify a list of variable
280 bindings (which may optionally have defaults) that are bound when used. Here is
281 a simple example:
282
283 .. code-block:: llvm
284
285 class FPFormat val> {
286 bits<3> Value = val;
287 }
288 def NotFP : FPFormat<0>;
289 def ZeroArgFP : FPFormat<1>;
290 def OneArgFP : FPFormat<2>;
291 def OneArgFPRW : FPFormat<3>;
292 def TwoArgFP : FPFormat<4>;
293 def CompareFP : FPFormat<5>;
294 def CondMovFP : FPFormat<6>;
295 def SpecialFP : FPFormat<7>;
296
297 In this case, template arguments are used as a space efficient way to specify a
298 list of "enumeration values", each with a "``Value``" field set to the specified
299 integer.
300
301 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
302 with template arguments. As an example:
303
304 .. code-block:: llvm
305
306 class ModRefVal val> {
307 bits<2> Value = val;
308 }
309
310 def None : ModRefVal<0>;
311 def Mod : ModRefVal<1>;
312 def Ref : ModRefVal<2>;
313 def ModRef : ModRefVal<3>;
314
315 class Value {
316 // Decode some information into a more convenient format, while providing
317 // a nice interface to the user of the "Value" class.
318 bit isMod = MR.Value{0};
319 bit isRef = MR.Value{1};
320
321 // other stuff...
322 }
323
324 // Example uses
325 def bork : Value;
326 def zork : Value;
327 def hork : Value;
328
329 This is obviously a contrived example, but it shows how template arguments can
330 be used to decouple the interface provided to the user of the class from the
331 actual internal data representation expected by the class. In this case,
332 running ``llvm-tblgen`` on the example prints the following definitions:
333
334 .. code-block:: llvm
335
336 def bork { // Value
337 bit isMod = 1;
338 bit isRef = 0;
339 }
340 def hork { // Value
341 bit isMod = 1;
342 bit isRef = 1;
343 }
344 def zork { // Value
345 bit isMod = 0;
346 bit isRef = 1;
347 }
348
349 This shows that TableGen was able to dig into the argument and extract a piece
350 of information that was requested by the designer of the "Value" class. For
351 more realistic examples, please see existing users of TableGen, such as the X86
352 backend.
353
354 Multiclass definitions and instances
355 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
356
357 While classes with template arguments are a good way to factor commonality
358 between two instances of a definition, multiclasses allow a convenient notation
359 for defining multiple definitions at once (instances of implicitly constructed
360 classes). For example, consider an 3-address instruction set whose instructions
361 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
362 (e.g. SPARC). In this case, you'd like to specify in one place that this
363 commonality exists, then in a separate place indicate what all the ops are.
364
365 Here is an example TableGen fragment that shows this idea:
366
367 .. code-block:: llvm
368
369 def ops;
370 def GPR;
371 def Imm;
372 class inst;
373
374 multiclass ri_inst {
375 def _rr : inst
376 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
377 def _ri : inst
378 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
379 }
380
381 // Instantiations of the ri_inst multiclass.
382 defm ADD : ri_inst<0b111, "add">;
383 defm SUB : ri_inst<0b101, "sub">;
384 defm MUL : ri_inst<0b100, "mul">;
385 ...
386
387 The name of the resultant definitions has the multidef fragment names appended
388 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
389 inherit from multiple multiclasses, instantiating definitions from each
390 multiclass. Using a multiclass this way is exactly equivalent to instantiating
391 the classes multiple times yourself, e.g. by writing:
392
393 .. code-block:: llvm
394
395 def ops;
396 def GPR;
397 def Imm;
398 class inst;
399
400 class rrinst
401 : inst
402 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
403
404 class riinst
405 : inst
406 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
407
408 // Instantiations of the ri_inst multiclass.
409 def ADD_rr : rrinst<0b111, "add">;
410 def ADD_ri : riinst<0b111, "add">;
411 def SUB_rr : rrinst<0b101, "sub">;
412 def SUB_ri : riinst<0b101, "sub">;
413 def MUL_rr : rrinst<0b100, "mul">;
414 def MUL_ri : riinst<0b100, "mul">;
415 ...
416
417 A ``defm`` can also be used inside a multiclass providing several levels of
418 multiclass instantiations.
419
420 .. code-block:: llvm
421
422 class Instruction opc, string Name> {
423 bits<4> opcode = opc;
424 string name = Name;
425 }
426
427 multiclass basic_r opc> {
428 def rr : Instruction;
429 def rm : Instruction;
430 }
431
432 multiclass basic_s opc> {
433 defm SS : basic_r;
434 defm SD : basic_r;
435 def X : Instruction;
436 }
437
438 multiclass basic_p opc> {
439 defm PS : basic_r;
440 defm PD : basic_r;
441 def Y : Instruction;
442 }
443
444 defm ADD : basic_s<0xf>, basic_p<0xf>;
445 ...
446
447 // Results
448 def ADDPDrm { ...
449 def ADDPDrr { ...
450 def ADDPSrm { ...
451 def ADDPSrr { ...
452 def ADDSDrm { ...
453 def ADDSDrr { ...
454 def ADDY { ...
455 def ADDX { ...
456
457 ``defm`` declarations can inherit from classes too, the rule to follow is that
458 the class list must start after the last multiclass, and there must be at least
459 one multiclass before them.
460
461 .. code-block:: llvm
462
463 class XD { bits<4> Prefix = 11; }
464 class XS { bits<4> Prefix = 12; }
465
466 class I op> {
467 bits<4> opcode = op;
468 }
469
470 multiclass R {
471 def rr : I<4>;
472 def rm : I<2>;
473 }
474
475 multiclass Y {
476 defm SS : R, XD;
477 defm SD : R, XS;
478 }
479
480 defm Instr : Y;
481
482 // Results
483 def InstrSDrm {
484 bits<4> opcode = { 0, 0, 1, 0 };
485 bits<4> Prefix = { 1, 1, 0, 0 };
486 }
487 ...
488 def InstrSSrr {
489 bits<4> opcode = { 0, 1, 0, 0 };
490 bits<4> Prefix = { 1, 0, 1, 1 };
491 }
492
493 File scope entities
494 -------------------
495
496 File inclusion
497 ^^^^^^^^^^^^^^
498
499 TableGen supports the '``include``' token, which textually substitutes the
500 specified file in place of the include directive. The filename should be
501 specified as a double quoted string immediately after the '``include``' keyword.
502 Example:
503
504 .. code-block:: llvm
505
506 include "foo.td"
507
508 'let' expressions
509 ^^^^^^^^^^^^^^^^^
510
511 "Let" expressions at file scope are similar to `"let" expressions within a
512 record`_, except they can specify a value binding for multiple records at a
513 time, and may be useful in certain other cases. File-scope let expressions are
514 really just another way that TableGen allows the end-user to factor out
515 commonality from the records.
516
517 File-scope "let" expressions take a comma-separated list of bindings to apply,
518 and one or more records to bind the values in. Here are some examples:
519
520 .. code-block:: llvm
521
522 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
523 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
524
525 let isCall = 1 in
526 // All calls clobber the non-callee saved registers...
527 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
528 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
529 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
530 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
531 "call\t${dst:call}", []>;
532 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
533 "call\t{*}$dst", [(X86call GR32:$dst)]>;
534 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
535 "call\t{*}$dst", []>;
536 }
537
538 File-scope "let" expressions are often useful when a couple of definitions need
539 to be added to several records, and the records do not otherwise need to be
540 opened, as in the case with the ``CALL*`` instructions above.
541
542 It's also possible to use "let" expressions inside multiclasses, providing more
543 ways to factor out commonality from the records, specially if using several
544 levels of multiclass instantiations. This also avoids the need of using "let"
545 expressions within subsequent records inside a multiclass.
546
547 .. code-block:: llvm
548
549 multiclass basic_r opc> {
550 let Predicates = [HasSSE2] in {
551 def rr : Instruction;
552 def rm : Instruction;
553 }
554 let Predicates = [HasSSE3] in
555 def rx : Instruction;
556 }
557
558 multiclass basic_ss opc> {
559 let IsDouble = 0 in
560 defm SS : basic_r;
561
562 let IsDouble = 1 in
563 defm SD : basic_r;
564 }
565
566 defm ADD : basic_ss<0xf>;
567
568 Looping
569 ^^^^^^^
570
571 TableGen supports the '``foreach``' block, which textually replicates the loop
572 body, substituting iterator values for iterator references in the body.
573 Example:
574
575 .. code-block:: llvm
576
577 foreach i = [0, 1, 2, 3] in {
578 def R#i : Register<...>;
579 def F#i : Register<...>;
580 }
581
582 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
583 may be nested. If there is only one item in the body the braces may be
584 elided:
585
586 .. code-block:: llvm
587
588 foreach i = [0, 1, 2, 3] in
589 def R#i : Register<...>;
590
591 Code Generator backend info
592 ===========================
593
594 Expressions used by code generator to describe instructions and isel patterns:
595
596 ``(implicit a)``
597 an implicitly defined physical register. This tells the dag instruction
598 selection emitter the input pattern's extra definitions matches implicit
599 physical register definitions.
600
0 ===========================
11 TableGen Language Reference
22 ===========================
3
4 .. sectionauthor:: Sean Silva
35
46 .. contents::
57 :local:
1517 in and of itself (i.e. how to understand a given construct in terms of how
1618 it affects the final set of records represented by the TableGen file). If
1719 you are unsure if this document is really what you are looking for, please
18 read :doc:`the introduction ` first.
19
20 TableGen syntax
21 ===============
22
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.
26
27 TableGen primitives
28 -------------------
29
30 TableGen comments
31 ^^^^^^^^^^^^^^^^^
32
33 TableGen supports C++ style "``//``" comments, which run to the end of the
34 line, and it also supports **nestable** "``/* */``" comments.
35
36 .. _TableGen type:
37
38 The TableGen type system
39 ^^^^^^^^^^^^^^^^^^^^^^^^
40
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.
45
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
49 types are:
50
51 ``bit``
52 A 'bit' is a boolean value that can hold either 0 or 1.
53
54 ``int``
55 The 'int' type represents a simple 32-bit integer value, such as 5.
56
57 ``string``
58 The 'string' type represents an ordered sequence of characters of arbitrary
59 length.
60
61 ``bits``
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.
65
66 ``list``
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.
69
70 Class 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`` can only contain definitions
75 derived from the "``Register``" class).
76
77 ``dag``
78 This type represents a nestable directed graph of elements.
79
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.
82
83 .. _TableGen expressions:
84
85 TableGen values and expressions
86 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
87
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
91 supported include:
92
93 ``?``
94 uninitialized field
95
96 ``0b1001011``
97 binary integer value
98
99 ``07654321``
100 octal integer value (indicated by a leading 0)
101
102 ``7``
103 decimal integer value
104
105 ``0x7F``
106 hexadecimal integer value
107
108 ``"foo"``
109 string value
110
111 ``[{ ... }]``
112 usually called a "code fragment", but is just a multiline string literal
113
114 ``[ X, Y, Z ]``
115 list value. 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.
118
119 ``{ a, b, c }``
120 initializer for a "bits<3>" value
121
122 ``value``
123 value reference
124
125 ``value{17}``
126 access to one bit of a value
127
128 ``value{15-17}``
129 access to multiple bits of a value
130
131 ``DEF``
132 reference to a record definition
133
134 ``CLASS``
135 reference to a new anonymous definition of CLASS with the specified template
136 arguments.
137
138 ``X.Y``
139 reference to the subfield of a value
140
141 ``list[4-7,17,2-3]``
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.
144
145 ``foreach = [ ] in { }``
146
147 ``foreach = [ ] in ``
148 Replicate or , replacing instances of with each value
149 in . is scoped at the level of the ``foreach`` loop and must
150 not conflict with any other object introduced in or . Currently
151 only ``def``\s are expanded within .
152
153 ``foreach = 0-15 in ...``
154
155 ``foreach = {0-15,32-47} in ...``
156 Loop over ranges of integers. The braces are required for multiple ranges.
157
158 ``(DEF a, b)``
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.
162
163 ``!strconcat(a, b)``
164 A string value that is the result of concatenating the 'a' and 'b' strings.
165
166 ``str1#str2``
167 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
168 are not quoted strings, in which case an implicit !cast is done on
169 the operand of the paste.
170
171 ``!cast(a)``
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 is a special case in that the argument must be an
175 object defined by a 'def' construct.
176
177 ``!subst(a, b, c)``
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.
180
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.
185
186 ``!head(a)``
187 The first element of list 'a.'
188
189 ``!tail(a)``
190 The 2nd-N elements of list 'a.'
191
192 ``!empty(a)``
193 An integer {0,1} indicating whether list 'a' is empty.
194
195 ``!if(a,b,c)``
196 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
197
198 ``!eq(a,b)``
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 to compare other types of
201 objects.
202
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.
206
207 Classes and definitions
208 -----------------------
209
210 As mentioned in the :doc:`introduction `, 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.
218
219 Here is a simple TableGen file:
220
221 .. code-block:: llvm
222
223 class C { bit V = 1; }
224 def X : C;
225 def Y : C {
226 string Greeting = "hello";
227 }
228
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.
232
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.
237
238 .. _value definition:
239 .. _value definitions:
240
241 Value definitions
242 ^^^^^^^^^^^^^^^^^
243
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.
250
251 .. _let expression:
252 .. _let expressions:
253 .. _"let" expressions within a record:
254
255 'let' expressions
256 ^^^^^^^^^^^^^^^^^
257
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:
264
265 .. code-block:: llvm
266
267 class D : C { let V = 0; }
268 def Z : D;
269
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.
273
274 .. _template arguments:
275
276 Class template arguments
277 ^^^^^^^^^^^^^^^^^^^^^^^^
278
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
282 a simple example:
283
284 .. code-block:: llvm
285
286 class FPFormat val> {
287 bits<3> Value = val;
288 }
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>;
297
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
300 integer.
301
302 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
303 with template arguments. As an example:
304
305 .. code-block:: llvm
306
307 class ModRefVal val> {
308 bits<2> Value = val;
309 }
310
311 def None : ModRefVal<0>;
312 def Mod : ModRefVal<1>;
313 def Ref : ModRefVal<2>;
314 def ModRef : ModRefVal<3>;
315
316 class Value {
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};
321
322 // other stuff...
323 }
324
325 // Example uses
326 def bork : Value;
327 def zork : Value;
328 def hork : Value;
329
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:
334
335 .. code-block:: llvm
336
337 def bork { // Value
338 bit isMod = 1;
339 bit isRef = 0;
340 }
341 def hork { // Value
342 bit isMod = 1;
343 bit isRef = 1;
344 }
345 def zork { // Value
346 bit isMod = 0;
347 bit isRef = 1;
348 }
349
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
353 backend.
354
355 Multiclass definitions and instances
356 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
357
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.
365
366 Here is an example TableGen fragment that shows this idea:
367
368 .. code-block:: llvm
369
370 def ops;
371 def GPR;
372 def Imm;
373 class inst;
374
375 multiclass ri_inst {
376 def _rr : inst
377 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
378 def _ri : inst
379 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
380 }
381
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">;
386 ...
387
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:
393
394 .. code-block:: llvm
395
396 def ops;
397 def GPR;
398 def Imm;
399 class inst;
400
401 class rrinst
402 : inst
403 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
404
405 class riinst
406 : inst
407 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
408
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">;
416 ...
417
418 A ``defm`` can also be used inside a multiclass providing several levels of
419 multiclass instantiations.
420
421 .. code-block:: llvm
422
423 class Instruction opc, string Name> {
424 bits<4> opcode = opc;
425 string name = Name;
426 }
427
428 multiclass basic_r opc> {
429 def rr : Instruction;
430 def rm : Instruction;
431 }
432
433 multiclass basic_s opc> {
434 defm SS : basic_r;
435 defm SD : basic_r;
436 def X : Instruction;
437 }
438
439 multiclass basic_p opc> {
440 defm PS : basic_r;
441 defm PD : basic_r;
442 def Y : Instruction;
443 }
444
445 defm ADD : basic_s<0xf>, basic_p<0xf>;
446 ...
447
448 // Results
449 def ADDPDrm { ...
450 def ADDPDrr { ...
451 def ADDPSrm { ...
452 def ADDPSrr { ...
453 def ADDSDrm { ...
454 def ADDSDrr { ...
455 def ADDY { ...
456 def ADDX { ...
457
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.
461
462 .. code-block:: llvm
463
464 class XD { bits<4> Prefix = 11; }
465 class XS { bits<4> Prefix = 12; }
466
467 class I op> {
468 bits<4> opcode = op;
469 }
470
471 multiclass R {
472 def rr : I<4>;
473 def rm : I<2>;
474 }
475
476 multiclass Y {
477 defm SS : R, XD;
478 defm SD : R, XS;
479 }
480
481 defm Instr : Y;
482
483 // Results
484 def InstrSDrm {
485 bits<4> opcode = { 0, 0, 1, 0 };
486 bits<4> Prefix = { 1, 1, 0, 0 };
487 }
488 ...
489 def InstrSSrr {
490 bits<4> opcode = { 0, 1, 0, 0 };
491 bits<4> Prefix = { 1, 0, 1, 1 };
492 }
493
494 File scope entities
495 -------------------
496
497 File inclusion
498 ^^^^^^^^^^^^^^
499
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.
503 Example:
504
505 .. code-block:: llvm
506
507 include "foo.td"
508
509 'let' expressions
510 ^^^^^^^^^^^^^^^^^
511
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.
517
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:
520
521 .. code-block:: llvm
522
523 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
524 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
525
526 let isCall = 1 in
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", []>;
537 }
538
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.
542
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.
547
548 .. code-block:: llvm
549
550 multiclass basic_r opc> {
551 let Predicates = [HasSSE2] in {
552 def rr : Instruction;
553 def rm : Instruction;
554 }
555 let Predicates = [HasSSE3] in
556 def rx : Instruction;
557 }
558
559 multiclass basic_ss opc> {
560 let IsDouble = 0 in
561 defm SS : basic_r;
562
563 let IsDouble = 1 in
564 defm SD : basic_r;
565 }
566
567 defm ADD : basic_ss<0xf>;
568
569 Looping
570 ^^^^^^^
571
572 TableGen supports the '``foreach``' block, which textually replicates the loop
573 body, substituting iterator values for iterator references in the body.
574 Example:
575
576 .. code-block:: llvm
577
578 foreach i = [0, 1, 2, 3] in {
579 def R#i : Register<...>;
580 def F#i : Register<...>;
581 }
582
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
585 elided:
586
587 .. code-block:: llvm
588
589 foreach i = [0, 1, 2, 3] in
590 def R#i : Register<...>;
591
592 Code Generator backend info
593 ===========================
594
595 Expressions used by code generator to describe instructions and isel patterns:
596
597 ``(implicit a)``
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.
601
20 read :doc:`/TableGenFundamentals` first.
21
22 Notation
23 ========
24
25 The lexical and syntax notation used here is intended to imitate
26 `Python's`_. In particular, for lexical definitions, the productions
27 operate at the character level and there is no implied whitespace between
28 elements. The syntax definitions operate at the token level, so there is
29 implied whitespace between tokens.
30
31 .. _`Python's`: http://docs.python.org/py3k/reference/introduction.html#notation
32
33 Lexical Analysis
34 ================
35
36 TableGen supports BCPL (``// ...``) and nestable C-style (``/* ... */``)
37 comments.
38
39 The following is a listing of the basic punctuation tokens::
40
41 - + [ ] { } ( ) < > : ; . = ? #
42
43 Numeric literals take one of the following forms:
44
45 .. TableGen actually will lex some pretty strange sequences an interpret
46 them as numbers. What is shown here is an attempt to approximate what it
47 "should" accept.
48
49 .. productionlist::
50 TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`
51 DecimalInteger: ["+" | "-"] ("0"..."9")+
52 HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
53 BinInteger: "0b" ("0" | "1")+
54
55 One aspect to note is that the :token:`DecimalInteger` token *includes* the
56 ``+`` or ``-``, as opposed to having ``+`` and ``-`` be unary operators as
57 most languages do.
58
59 TableGen has identifier-like tokens:
60
61 .. productionlist::
62 ualpha: "a"..."z" | "A"..."Z" | "_"
63 TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*
64 TokVarName: "$" `ualpha` (`ualpha` | "0"..."9")*
65
66 Note that unlike most languages, TableGen allows :token:`TokIdentifier` to
67 begin with a number. In case of ambiguity, a token will be interpreted as a
68 numeric literal rather than an identifier.
69
70 TableGen also has two string-like literals:
71
72 .. productionlist::
73 TokString: '"' '"'
74 TokCodeFragment: "[{" "}]"
75
76 :token:`TokCodeFragment` is essentially a multiline string literal
77 delimited by ``[{`` and ``}]``.
78
79 .. note::
80 The current implementation accepts the following C-like escapes::
81
82 \\ \' \" \t \n
83
84 TableGen also has the following keywords::
85
86 bit bits class code dag
87 def foreach defm field in
88 int let list multiclass string
89
90 TableGen also has "bang operators" which have a
91 wide variety of meanings:
92
93 .. productionlist::
94 BangOperator: one of
95 :!eq !if !head !tail !con
96 :!add !shl !sra !srl
97 :!cast !empty !subst !foreach !strconcat
98
99 Syntax
100 ======
101
102 TableGen has an ``include`` mechanism. It does not play a role in the
103 syntax per se, since it is lexically replaced with the contents of the
104 included file.
105
106 .. productionlist::
107 IncludeDirective: "include" `TokString`
108
109 TableGen's top-level production consists of "objects".
110
111 .. productionlist::
112 TableGenFile: `Object`*
113 Object: `Class` | `Def` | `Defm` | `Let` | `MultiClass` | `Foreach`
114
115 ``class``\es
116 ------------
117
118 .. productionlist::
119 Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`
120
121 A ``class`` declaration creates a record which other records can inherit
122 from. A class can be parametrized by a list of "template arguments", whose
123 values can be used in the class body.
124
125 A given class can only be defined once. A ``class`` declaration is
126 considered to define the class if any of the following is true:
127
128 .. break ObjectBody into its consituents so that they are present here?
129
130 #. The :token:`TemplateArgList` is present.
131 #. The :token:`Body` in the :token:`ObjectBody` is present and is not empty.
132 #. The :token:`BaseClassList` in the :token:`ObjectBody` is present.
133
134 You can declare an empty class by giving and empty :token:`TemplateArgList`
135 and an empty :token:`ObjectBody`. This can serve as a restricted form of
136 forward declaration: note that records deriving from the forward-declared
137 class will inherit no fields from it since the record expansion is done
138 when the record is parsed.
139
140 .. productionlist::
141 TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
142
143 Declarations
144 ------------
145
146 .. Omitting mention of arcane "field" prefix to discourage its use.
147
148 The declaration syntax is pretty much what you would expect as a C++
149 programmer.
150
151 .. productionlist::
152 Declaration: `Type` `TokIdentifier` ["=" `Value`]
153
154 It assigns the value to the identifer.
155
156 Types
157 -----
158
159 .. productionlist::
160 Type: "string" | "code" | "bit" | "int" | "dag"
161 :| "bits" "<" `TokInteger` ">"
162 :| "list" "<" `Type` ">"
163 :| `ClassID`
164 ClassID: `TokIdentifier`
165
166 Both ``string`` and ``code`` correspond to the string type; the difference
167 is purely to indicate programmer intention.
168
169 The :token:`ClassID` must identify a class that has been previously
170 declared or defined.
171
172 Values
173 ------
174
175 .. productionlist::
176 Value: `SimpleValue` `ValueSuffix`*
177 ValueSuffix: "{" `RangeList` "}"
178 :| "[" `RangeList` "]"
179 :| "." `TokIdentifier`
180 RangeList: `RangePiece` ("," `RangePiece`)*
181 RangePiece: `TokInteger`
182 :| `TokInteger` "-" `TokInteger`
183 :| `TokInteger` `TokInteger`
184
185 The peculiar last form of :token:`RangePiece` is due to the fact that the
186 "``-``" is included in the :token:`TokInteger`, hence ``1-5`` gets lexed as
187 two consecutive :token:`TokInteger`'s, with values ``1`` and ``-5``,
188 instead of "1", "-", and "5".
189 The :token:`RangeList` can be thought of as specifying "list slice" in some
190 contexts.
191
192
193 :token:`SimpleValue` has a number of forms:
194
195
196 .. productionlist::
197 SimpleValue: `TokIdentifier`
198
199 The value will be the variable referenced by the identifier. It can be one
200 of:
201
202 .. The code for this is exceptionally abstruse. These examples are a
203 best-effort attempt.
204
205 * name of a ``def``, such as the use of ``Bar`` in::
206
207 def Bar : SomeClass {
208 int X = 5;
209 }
210
211 def Foo {
212 SomeClass Baz = Bar;
213 }
214
215 * value local to a ``def``, such as the use of ``Bar`` in::
216
217 def Foo {
218 int Bar = 5;
219 int Baz = Bar;
220 }
221
222 * a template arg of a ``class``, such as the use of ``Bar`` in::
223
224 class Foo {
225 int Baz = Bar;
226 }
227
228 * value local to a ``multiclass``, such as the use of ``Bar`` in::
229
230 multiclass Foo {
231 int Bar = 5;
232 int Baz = Bar;
233 }
234
235 * a template arg to a ``multiclass``, such as the use of ``Bar`` in::
236
237 multiclass Foo {
238 int Baz = Bar;
239 }
240
241 .. productionlist::
242 SimpleValue: `TokInteger`
243
244 This represents the numeric value of the integer.
245
246 .. productionlist::
247 SimpleValue: `TokString`+
248
249 Multiple adjacent string literals are concatenated like in C/C++. The value
250 is the concatenation of the strings.
251
252 .. productionlist::
253 SimpleValue: `TokCodeFragment`
254
255 The value is the string value of the code fragment.
256
257 .. productionlist::
258 SimpleValue: "?"
259
260 ``?`` represents an "unset" initializer.
261
262 .. productionlist::
263 SimpleValue: "{" `ValueList` "}"
264 ValueList: [`ValueListNE`]
265 ValueListNE: `Value` ("," `Value`)*
266
267 This represents a sequence of bits, as would be used to initialize a
268 ``bits`` field (where ``n`` is the number of bits).
269
270 .. productionlist::
271 SimpleValue: `ClassID` "<" `ValueListNE` ">"
272
273 This generates a new anonymous record definition (as would be created by an
274 unnamed ``def`` inheriting from the given class with the given template
275 arguments) and the value is the value of that record definition.
276
277 .. productionlist::
278 SimpleValue: "[" `ValueList` "]" ["<" `Type` ">"]
279
280 A list initializer. The optional :token:`Type` can be used to indicate a
281 specific element type, otherwise the element type will be deduced from the
282 given values.
283
284 .. The initial `DagArg` of the dag must start with an identifier or
285 !cast, but this is more of an implementation detail and so for now just
286 leave it out.
287
288 .. productionlist::
289 SimpleValue: "(" `DagArg` `DagArgList` ")"
290 DagArgList: `DagArg` ("," `DagArg`)*
291 DagArg: `Value` [":" `TokVarName`] | `TokVarName`
292
293 The initial :token:`DagArg` is called the "operator" of the dag.
294
295 .. productionlist::
296 SimpleValue: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
297
298 Bodies
299 ------
300
301 .. productionlist::
302 ObjectBody: `BaseClassList` `Body`
303 BaseClassList: [":" `BaseClassListNE`]
304 BaseClassListNE: `SubClassRef` ("," `SubClassRef`)*
305 SubClassRef: (`ClassID` | `MultiClassID`) ["<" `ValueList` ">"]
306 DefmID: `TokIdentifier`
307
308 The version with the :token:`MultiClassID` is only valid in the
309 :token:`BaseClassList` of a ``defm``.
310 The :token:`MultiClassID` should be the name of a ``multiclass``.
311
312 .. put this somewhere else
313
314 It is after parsing the base class list that the "let stack" is applied.
315
316 .. productionlist::
317 Body: ";" | "{" BodyList "}"
318 BodyList: BodyItem*
319 BodyItem: `Declaration` ";"
320 :| "let" `TokIdentifier` [`RangeList`] "=" `Value` ";"
321
322 The ``let`` form allows overriding the value of an inherited field.
323
324 ``def``
325 -------
326
327 .. TODO::
328 There can be pastes in the names here, like ``#NAME#``. Look into that
329 and document it (it boils down to ParseIDValue with IDParseMode ==
330 ParseNameMode). ParseObjectName calls into the general ParseValue, with
331 the only different from "arbitrary expression parsing" being IDParseMode
332 == Mode.
333
334 .. productionlist::
335 Def: "def" `TokIdentifier` `ObjectBody`
336
337 Defines a record whose name is given by the :token:`TokIdentifier`. The
338 fields of the record are inherited from the base classes and defined in the
339 body.
340
341 Special handling occurs if this ``def`` appears inside a ``multiclass`` or
342 a ``foreach``.
343
344 ``defm``
345 --------
346
347 .. productionlist::
348 Defm: "defm" `TokIdentifier` ":" `BaseClassListNE` ";"
349
350 Note that in the :token:`BaseClassList`, all of the ``multiclass``'s must
351 precede any ``class``'s that appear.
352
353 ``foreach``
354 -----------
355
356 .. productionlist::
357 Foreach: "foreach" `Declaration` "in" "{" `Object`* "}"
358 :| "foreach" `Declaration` "in" `Object`
359
360 The value assigned to the variable in the declaration is iterated over and
361 the object or object list is reevaluated with the variable set at each
362 iterated value.
363
364 Top-Level ``let``
365 -----------------
366
367 .. productionlist::
368 Let: "let" `LetList` "in" "{" `Object`* "}"
369 :| "let" `LetList` "in" `Object`
370 LetList: `LetItem` ("," `LetItem`)*
371 LetItem: `TokIdentifier` [`RangeList`] "=" `Value`
372
373 This is effectively equivalent to ``let`` inside the body of a record
374 except that it applies to multiple records at a time. The bindings are
375 applied at the end of parsing the base classes of a record.
376
377 ``multiclass``
378 --------------
379
380 .. productionlist::
381 MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
382 : [":" `BaseMultiClassList`] "{" `MultiClassObject`+ "}"
383 BaseMultiClassList: `MultiClassID` ("," `MultiClassID`)*
384 MultiClassID: `TokIdentifier`
385 MultiClassObject: `Def` | `Defm` | `Let` | `Foreach`
99
1010 BackEnds
1111 LangRef
12 LangIntro
1213 Deficiencies
1314
1415 Introduction
254255
255256
256257
257 See the `TableGen Language Reference `_ for more information.
258 See the :doc:`TableGen Language Introduction ` for more generic
259 information on the usage of the language, and the
260 :doc:`TableGen Language Reference ` for more in-depth description
261 of the formal language specification.
258262
259263 .. _backend:
260264 .. _backends:
11 TableGen Fundamentals
22 =====================
33
4 .. contents::
5 :local:
4 Moved
5 =====
66
7 Introduction
8 ============
9
10 TableGen's purpose is to help a human develop and maintain records of
11 domain-specific information. Because there may be a large number of these
12 records, it is specifically designed to allow writing flexible descriptions and
13 for common features of these records to be factored out. This reduces the
14 amount of duplication in the description, reduces the chance of error, and makes
15 it easier to structure domain specific information.
16
17 The core part of TableGen `parses a file`_, instantiates the declarations, and
18 hands the result off to a domain-specific `TableGen backend`_ for processing.
19 The current major user of TableGen is the `LLVM code
20 generator `_.
21
22 Note that if you work on TableGen much, and use emacs or vim, that you can find
23 an emacs "TableGen mode" and a vim language file in the ``llvm/utils/emacs`` and
24 ``llvm/utils/vim`` directories of your LLVM distribution, respectively.
25
26 .. _intro:
27
28 Basic concepts
29 --------------
30
31 TableGen files consist of two key parts: 'classes' and 'definitions', both of
32 which are considered 'records'.
33
34 **TableGen records** have a unique name, a list of values, and a list of
35 superclasses. The list of values is the main data that TableGen builds for each
36 record; it is this that holds the domain specific information for the
37 application. The interpretation of this data is left to a specific `TableGen
38 backend`_, but the structure and format rules are taken care of and are fixed by
39 TableGen.
40
41 **TableGen definitions** are the concrete form of 'records'. These generally do
42 not have any undefined values, and are marked with the '``def``' keyword.
43
44 **TableGen classes** are abstract records that are used to build and describe
45 other records. These 'classes' allow the end-user to build abstractions for
46 either the domain they are targeting (such as "Register", "RegisterClass", and
47 "Instruction" in the LLVM code generator) or for the implementor to help factor
48 out common properties of records (such as "FPInst", which is used to represent
49 floating point instructions in the X86 backend). TableGen keeps track of all of
50 the classes that are used to build up a definition, so the backend can find all
51 definitions of a particular class, such as "Instruction".
52
53 **TableGen multiclasses** are groups of abstract records that are instantiated
54 all at once. Each instantiation can result in multiple TableGen definitions.
55 If a multiclass inherits from another multiclass, the definitions in the
56 sub-multiclass become part of the current multiclass, as if they were declared
57 in the current multiclass.
58
59 .. _described above:
60
61 An example record
62 -----------------
63
64 With no other arguments, TableGen parses the specified file and prints out all
65 of the classes, then all of the definitions. This is a good way to see what the
66 various definitions expand to fully. Running this on the ``X86.td`` file prints
67 this (at the time of this writing):
68
69 .. code-block:: llvm
70
71 ...
72 def ADD32rr { // Instruction X86Inst I
73 string Namespace = "X86";
74 dag OutOperandList = (outs GR32:$dst);
75 dag InOperandList = (ins GR32:$src1, GR32:$src2);
76 string AsmString = "add{l}\t{$src2, $dst|$dst, $src2}";
77 list Pattern = [(set GR32:$dst, (add GR32:$src1, GR32:$src2))];
78 list Uses = [];
79 list Defs = [EFLAGS];
80 list Predicates = [];
81 int CodeSize = 3;
82 int AddedComplexity = 0;
83 bit isReturn = 0;
84 bit isBranch = 0;
85 bit isIndirectBranch = 0;
86 bit isBarrier = 0;
87 bit isCall = 0;
88 bit canFoldAsLoad = 0;
89 bit mayLoad = 0;
90 bit mayStore = 0;
91 bit isImplicitDef = 0;
92 bit isConvertibleToThreeAddress = 1;
93 bit isCommutable = 1;
94 bit isTerminator = 0;
95 bit isReMaterializable = 0;
96 bit isPredicable = 0;
97 bit hasDelaySlot = 0;
98 bit usesCustomInserter = 0;
99 bit hasCtrlDep = 0;
100 bit isNotDuplicable = 0;
101 bit hasSideEffects = 0;
102 bit neverHasSideEffects = 0;
103 InstrItinClass Itinerary = NoItinerary;
104 string Constraints = "";
105 string DisableEncoding = "";
106 bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
107 Format Form = MRMDestReg;
108 bits<6> FormBits = { 0, 0, 0, 0, 1, 1 };
109 ImmType ImmT = NoImm;
110 bits<3> ImmTypeBits = { 0, 0, 0 };
111 bit hasOpSizePrefix = 0;
112 bit hasAdSizePrefix = 0;
113 bits<4> Prefix = { 0, 0, 0, 0 };
114 bit hasREX_WPrefix = 0;
115 FPFormat FPForm = ?;
116 bits<3> FPFormBits = { 0, 0, 0 };
117 }
118 ...
119
120 This definition corresponds to the 32-bit register-register ``add`` instruction
121 of the x86 architecture. ``def ADD32rr`` defines a record named
122 ``ADD32rr``, and the comment at the end of the line indicates the superclasses
123 of the definition. The body of the record contains all of the data that
124 TableGen assembled for the record, indicating that the instruction is part of
125 the "X86" namespace, the pattern indicating how the instruction should be
126 emitted into the assembly file, that it is a two-address instruction, has a
127 particular encoding, etc. The contents and semantics of the information in the
128 record are specific to the needs of the X86 backend, and are only shown as an
129 example.
130
131 As you can see, a lot of information is needed for every instruction supported
132 by the code generator, and specifying it all manually would be unmaintainable,
133 prone to bugs, and tiring to do in the first place. Because we are using
134 TableGen, all of the information was derived from the following definition:
135
136 .. code-block:: llvm
137
138 let Defs = [EFLAGS],
139 isCommutable = 1, // X = ADD Y,Z --> X = ADD Z,Y
140 isConvertibleToThreeAddress = 1 in // Can transform into LEA.
141 def ADD32rr : I<0x01, MRMDestReg, (outs GR32:$dst),
142 (ins GR32:$src1, GR32:$src2),
143 "add{l}\t{$src2, $dst|$dst, $src2}",
144 [(set GR32:$dst, (add GR32:$src1, GR32:$src2))]>;
145
146 This definition makes use of the custom class ``I`` (extended from the custom
147 class ``X86Inst``), which is defined in the X86-specific TableGen file, to
148 factor out the common features that instructions of its class share. A key
149 feature of TableGen is that it allows the end-user to define the abstractions
150 they prefer to use when describing their information.
151
152 Each ``def`` record has a special entry called "NAME". This is the name of the
153 record ("``ADD32rr``" above). In the general case ``def`` names can be formed
154 from various kinds of string processing expressions and ``NAME`` resolves to the
155 final value obtained after resolving all of those expressions. The user may
156 refer to ``NAME`` anywhere she desires to use the ultimate name of the ``def``.
157 ``NAME`` should not be defined anywhere else in user code to avoid conflicts.
158
159 Running TableGen
160 ----------------
161
162 TableGen runs just like any other LLVM tool. The first (optional) argument
163 specifies the file to read. If a filename is not specified, ``llvm-tblgen``
164 reads from standard input.
165
166 To be useful, one of the `TableGen backends`_ must be used. These backends are
167 selectable on the command line (type '``llvm-tblgen -help``' for a list). For
168 example, to get a list of all of the definitions that subclass a particular type
169 (which can be useful for building up an enum list of these records), use the
170 ``-print-enums`` option:
171
172 .. code-block:: bash
173
174 $ llvm-tblgen X86.td -print-enums -class=Register
175 AH, AL, AX, BH, BL, BP, BPL, BX, CH, CL, CX, DH, DI, DIL, DL, DX, EAX, EBP, EBX,
176 ECX, EDI, EDX, EFLAGS, EIP, ESI, ESP, FP0, FP1, FP2, FP3, FP4, FP5, FP6, IP,
177 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, R10, R10B, R10D, R10W, R11, R11B, R11D,
178 R11W, R12, R12B, R12D, R12W, R13, R13B, R13D, R13W, R14, R14B, R14D, R14W, R15,
179 R15B, R15D, R15W, R8, R8B, R8D, R8W, R9, R9B, R9D, R9W, RAX, RBP, RBX, RCX, RDI,
180 RDX, RIP, RSI, RSP, SI, SIL, SP, SPL, ST0, ST1, ST2, ST3, ST4, ST5, ST6, ST7,
181 XMM0, XMM1, XMM10, XMM11, XMM12, XMM13, XMM14, XMM15, XMM2, XMM3, XMM4, XMM5,
182 XMM6, XMM7, XMM8, XMM9,
183
184 $ llvm-tblgen X86.td -print-enums -class=Instruction
185 ABS_F, ABS_Fp32, ABS_Fp64, ABS_Fp80, ADC32mi, ADC32mi8, ADC32mr, ADC32ri,
186 ADC32ri8, ADC32rm, ADC32rr, ADC64mi32, ADC64mi8, ADC64mr, ADC64ri32, ADC64ri8,
187 ADC64rm, ADC64rr, ADD16mi, ADD16mi8, ADD16mr, ADD16ri, ADD16ri8, ADD16rm,
188 ADD16rr, ADD32mi, ADD32mi8, ADD32mr, ADD32ri, ADD32ri8, ADD32rm, ADD32rr,
189 ADD64mi32, ADD64mi8, ADD64mr, ADD64ri32, ...
190
191 The default backend prints out all of the records, as `described above`_.
192
193 If you plan to use TableGen, you will most likely have to `write a backend`_
194 that extracts the information specific to what you need and formats it in the
195 appropriate way.
196
197 .. _parses a file:
198
199 TableGen syntax
200 ===============
201
202 TableGen doesn't care about the meaning of data (that is up to the backend to
203 define), but it does care about syntax, and it enforces a simple type system.
204 This section describes the syntax and the constructs allowed in a TableGen file.
205
206 TableGen primitives
207 -------------------
208
209 TableGen comments
210 ^^^^^^^^^^^^^^^^^
211
212 TableGen supports BCPL style "``//``" comments, which run to the end of the
213 line, and it also supports **nestable** "``/* */``" comments.
214
215 .. _TableGen type:
216
217 The TableGen type system
218 ^^^^^^^^^^^^^^^^^^^^^^^^
219
220 TableGen files are strongly typed, in a simple (but complete) type-system.
221 These types are used to perform automatic conversions, check for errors, and to
222 help interface designers constrain the input that they allow. Every `value
223 definition`_ is required to have an associated type.
224
225 TableGen supports a mixture of very low-level types (such as ``bit``) and very
226 high-level types (such as ``dag``). This flexibility is what allows it to
227 describe a wide range of information conveniently and compactly. The TableGen
228 types are:
229
230 ``bit``
231 A 'bit' is a boolean value that can hold either 0 or 1.
232
233 ``int``
234 The 'int' type represents a simple 32-bit integer value, such as 5.
235
236 ``string``
237 The 'string' type represents an ordered sequence of characters of arbitrary
238 length.
239
240 ``bits``
241 A 'bits' type is an arbitrary, but fixed, size integer that is broken up
242 into individual bits. This type is useful because it can handle some bits
243 being defined while others are undefined.
244
245 ``list``
246 This type represents a list whose elements are some other type. The
247 contained type is arbitrary: it can even be another list type.
248
249 Class type
250 Specifying a class name in a type context means that the defined value must
251 be a subclass of the specified class. This is useful in conjunction with
252 the ``list`` type, for example, to constrain the elements of the list to a
253 common base class (e.g., a ``list`` can only contain definitions
254 derived from the "``Register``" class).
255
256 ``dag``
257 This type represents a nestable directed graph of elements.
258
259 To date, these types have been sufficient for describing things that TableGen
260 has been used for, but it is straight-forward to extend this list if needed.
261
262 .. _TableGen expressions:
263
264 TableGen values and expressions
265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
266
267 TableGen allows for a pretty reasonable number of different expression forms
268 when building up values. These forms allow the TableGen file to be written in a
269 natural syntax and flavor for the application. The current expression forms
270 supported include:
271
272 ``?``
273 uninitialized field
274
275 ``0b1001011``
276 binary integer value
277
278 ``07654321``
279 octal integer value (indicated by a leading 0)
280
281 ``7``
282 decimal integer value
283
284 ``0x7F``
285 hexadecimal integer value
286
287 ``"foo"``
288 string value
289
290 ``[{ ... }]``
291 usually called a "code fragment", but is just a multiline string literal
292
293 ``[ X, Y, Z ]``
294 list value. is the type of the list element and is usually optional.
295 In rare cases, TableGen is unable to deduce the element type in which case
296 the user must specify it explicitly.
297
298 ``{ a, b, c }``
299 initializer for a "bits<3>" value
300
301 ``value``
302 value reference
303
304 ``value{17}``
305 access to one bit of a value
306
307 ``value{15-17}``
308 access to multiple bits of a value
309
310 ``DEF``
311 reference to a record definition
312
313 ``CLASS``
314 reference to a new anonymous definition of CLASS with the specified template
315 arguments.
316
317 ``X.Y``
318 reference to the subfield of a value
319
320 ``list[4-7,17,2-3]``
321 A slice of the 'list' list, including elements 4,5,6,7,17,2, and 3 from it.
322 Elements may be included multiple times.
323
324 ``foreach = [ ] in { }``
325
326 ``foreach = [ ] in ``
327 Replicate or , replacing instances of with each value
328 in . is scoped at the level of the ``foreach`` loop and must
329 not conflict with any other object introduced in or . Currently
330 only ``def``\s are expanded within .
331
332 ``foreach = 0-15 in ...``
333
334 ``foreach = {0-15,32-47} in ...``
335 Loop over ranges of integers. The braces are required for multiple ranges.
336
337 ``(DEF a, b)``
338 a dag value. The first element is required to be a record definition, the
339 remaining elements in the list may be arbitrary other values, including
340 nested ```dag``' values.
341
342 ``!strconcat(a, b)``
343 A string value that is the result of concatenating the 'a' and 'b' strings.
344
345 ``str1#str2``
346 "#" (paste) is a shorthand for !strconcat. It may concatenate things that
347 are not quoted strings, in which case an implicit !cast is done on
348 the operand of the paste.
349
350 ``!cast(a)``
351 A symbol of type *type* obtained by looking up the string 'a' in the symbol
352 table. If the type of 'a' does not match *type*, TableGen aborts with an
353 error. !cast is a special case in that the argument must be an
354 object defined by a 'def' construct.
355
356 ``!subst(a, b, c)``
357 If 'a' and 'b' are of string type or are symbol references, substitute 'b'
358 for 'a' in 'c.' This operation is analogous to $(subst) in GNU make.
359
360 ``!foreach(a, b, c)``
361 For each member 'b' of dag or list 'a' apply operator 'c.' 'b' is a dummy
362 variable that should be declared as a member variable of an instantiated
363 class. This operation is analogous to $(foreach) in GNU make.
364
365 ``!head(a)``
366 The first element of list 'a.'
367
368 ``!tail(a)``
369 The 2nd-N elements of list 'a.'
370
371 ``!empty(a)``
372 An integer {0,1} indicating whether list 'a' is empty.
373
374 ``!if(a,b,c)``
375 'b' if the result of 'int' or 'bit' operator 'a' is nonzero, 'c' otherwise.
376
377 ``!eq(a,b)``
378 'bit 1' if string a is equal to string b, 0 otherwise. This only operates
379 on string, int and bit objects. Use !cast to compare other types of
380 objects.
381
382 Note that all of the values have rules specifying how they convert to values
383 for different types. These rules allow you to assign a value like "``7``"
384 to a "``bits<4>``" value, for example.
385
386 Classes and definitions
387 -----------------------
388
389 As mentioned in the `intro`_, classes and definitions (collectively known as
390 'records') in TableGen are the main high-level unit of information that TableGen
391 collects. Records are defined with a ``def`` or ``class`` keyword, the record
392 name, and an optional list of "`template arguments`_". If the record has
393 superclasses, they are specified as a comma separated list that starts with a
394 colon character ("``:``"). If `value definitions`_ or `let expressions`_ are
395 needed for the class, they are enclosed in curly braces ("``{}``"); otherwise,
396 the record ends with a semicolon.
397
398 Here is a simple TableGen file:
399
400 .. code-block:: llvm
401
402 class C { bit V = 1; }
403 def X : C;
404 def Y : C {
405 string Greeting = "hello";
406 }
407
408 This example defines two definitions, ``X`` and ``Y``, both of which derive from
409 the ``C`` class. Because of this, they both get the ``V`` bit value. The ``Y``
410 definition also gets the Greeting member as well.
411
412 In general, classes are useful for collecting together the commonality between a
413 group of records and isolating it in a single place. Also, classes permit the
414 specification of default values for their subclasses, allowing the subclasses to
415 override them as they wish.
416
417 .. _value definition:
418 .. _value definitions:
419
420 Value definitions
421 ^^^^^^^^^^^^^^^^^
422
423 Value definitions define named entries in records. A value must be defined
424 before it can be referred to as the operand for another value definition or
425 before the value is reset with a `let expression`_. A value is defined by
426 specifying a `TableGen type`_ and a name. If an initial value is available, it
427 may be specified after the type with an equal sign. Value definitions require
428 terminating semicolons.
429
430 .. _let expression:
431 .. _let expressions:
432 .. _"let" expressions within a record:
433
434 'let' expressions
435 ^^^^^^^^^^^^^^^^^
436
437 A record-level let expression is used to change the value of a value definition
438 in a record. This is primarily useful when a superclass defines a value that a
439 derived class or definition wants to override. Let expressions consist of the
440 '``let``' keyword followed by a value name, an equal sign ("``=``"), and a new
441 value. For example, a new class could be added to the example above, redefining
442 the ``V`` field for all of its subclasses:
443
444 .. code-block:: llvm
445
446 class D : C { let V = 0; }
447 def Z : D;
448
449 In this case, the ``Z`` definition will have a zero value for its ``V`` value,
450 despite the fact that it derives (indirectly) from the ``C`` class, because the
451 ``D`` class overrode its value.
452
453 .. _template arguments:
454
455 Class template arguments
456 ^^^^^^^^^^^^^^^^^^^^^^^^
457
458 TableGen permits the definition of parameterized classes as well as normal
459 concrete classes. Parameterized TableGen classes specify a list of variable
460 bindings (which may optionally have defaults) that are bound when used. Here is
461 a simple example:
462
463 .. code-block:: llvm
464
465 class FPFormat val> {
466 bits<3> Value = val;
467 }
468 def NotFP : FPFormat<0>;
469 def ZeroArgFP : FPFormat<1>;
470 def OneArgFP : FPFormat<2>;
471 def OneArgFPRW : FPFormat<3>;
472 def TwoArgFP : FPFormat<4>;
473 def CompareFP : FPFormat<5>;
474 def CondMovFP : FPFormat<6>;
475 def SpecialFP : FPFormat<7>;
476
477 In this case, template arguments are used as a space efficient way to specify a
478 list of "enumeration values", each with a "``Value``" field set to the specified
479 integer.
480
481 The more esoteric forms of `TableGen expressions`_ are useful in conjunction
482 with template arguments. As an example:
483
484 .. code-block:: llvm
485
486 class ModRefVal val> {
487 bits<2> Value = val;
488 }
489
490 def None : ModRefVal<0>;
491 def Mod : ModRefVal<1>;
492 def Ref : ModRefVal<2>;
493 def ModRef : ModRefVal<3>;
494
495 class Value {
496 // Decode some information into a more convenient format, while providing
497 // a nice interface to the user of the "Value" class.
498 bit isMod = MR.Value{0};
499 bit isRef = MR.Value{1};
500
501 // other stuff...
502 }
503
504 // Example uses
505 def bork : Value;
506 def zork : Value;
507 def hork : Value;
508
509 This is obviously a contrived example, but it shows how template arguments can
510 be used to decouple the interface provided to the user of the class from the
511 actual internal data representation expected by the class. In this case,
512 running ``llvm-tblgen`` on the example prints the following definitions:
513
514 .. code-block:: llvm
515
516 def bork { // Value
517 bit isMod = 1;
518 bit isRef = 0;
519 }
520 def hork { // Value
521 bit isMod = 1;
522 bit isRef = 1;
523 }
524 def zork { // Value
525 bit isMod = 0;
526 bit isRef = 1;
527 }
528
529 This shows that TableGen was able to dig into the argument and extract a piece
530 of information that was requested by the designer of the "Value" class. For
531 more realistic examples, please see existing users of TableGen, such as the X86
532 backend.
533
534 Multiclass definitions and instances
535 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
536
537 While classes with template arguments are a good way to factor commonality
538 between two instances of a definition, multiclasses allow a convenient notation
539 for defining multiple definitions at once (instances of implicitly constructed
540 classes). For example, consider an 3-address instruction set whose instructions
541 come in two forms: "``reg = reg op reg``" and "``reg = reg op imm``"
542 (e.g. SPARC). In this case, you'd like to specify in one place that this
543 commonality exists, then in a separate place indicate what all the ops are.
544
545 Here is an example TableGen fragment that shows this idea:
546
547 .. code-block:: llvm
548
549 def ops;
550 def GPR;
551 def Imm;
552 class inst;
553
554 multiclass ri_inst {
555 def _rr : inst
556 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
557 def _ri : inst
558 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
559 }
560
561 // Instantiations of the ri_inst multiclass.
562 defm ADD : ri_inst<0b111, "add">;
563 defm SUB : ri_inst<0b101, "sub">;
564 defm MUL : ri_inst<0b100, "mul">;
565 ...
566
567 The name of the resultant definitions has the multidef fragment names appended
568 to them, so this defines ``ADD_rr``, ``ADD_ri``, ``SUB_rr``, etc. A defm may
569 inherit from multiple multiclasses, instantiating definitions from each
570 multiclass. Using a multiclass this way is exactly equivalent to instantiating
571 the classes multiple times yourself, e.g. by writing:
572
573 .. code-block:: llvm
574
575 def ops;
576 def GPR;
577 def Imm;
578 class inst;
579
580 class rrinst
581 : inst
582 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
583
584 class riinst
585 : inst
586 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
587
588 // Instantiations of the ri_inst multiclass.
589 def ADD_rr : rrinst<0b111, "add">;
590 def ADD_ri : riinst<0b111, "add">;
591 def SUB_rr : rrinst<0b101, "sub">;
592 def SUB_ri : riinst<0b101, "sub">;
593 def MUL_rr : rrinst<0b100, "mul">;
594 def MUL_ri : riinst<0b100, "mul">;
595 ...
596
597 A ``defm`` can also be used inside a multiclass providing several levels of
598 multiclass instantiations.
599
600 .. code-block:: llvm
601
602 class Instruction opc, string Name> {
603 bits<4> opcode = opc;
604 string name = Name;
605 }
606
607 multiclass basic_r opc> {
608 def rr : Instruction;
609 def rm : Instruction;
610 }
611
612 multiclass basic_s opc> {
613 defm SS : basic_r;
614 defm SD : basic_r;
615 def X : Instruction;
616 }
617
618 multiclass basic_p opc> {
619 defm PS : basic_r;
620 defm PD : basic_r;
621 def Y : Instruction;
622 }
623
624 defm ADD : basic_s<0xf>, basic_p<0xf>;
625 ...
626
627 // Results
628 def ADDPDrm { ...
629 def ADDPDrr { ...
630 def ADDPSrm { ...
631 def ADDPSrr { ...
632 def ADDSDrm { ...
633 def ADDSDrr { ...
634 def ADDY { ...
635 def ADDX { ...
636
637 ``defm`` declarations can inherit from classes too, the rule to follow is that
638 the class list must start after the last multiclass, and there must be at least
639 one multiclass before them.
640
641 .. code-block:: llvm
642
643 class XD { bits<4> Prefix = 11; }
644 class XS { bits<4> Prefix = 12; }
645
646 class I op> {
647 bits<4> opcode = op;
648 }
649
650 multiclass R {
651 def rr : I<4>;
652 def rm : I<2>;
653 }
654
655 multiclass Y {
656 defm SS : R, XD;
657 defm SD : R, XS;
658 }
659
660 defm Instr : Y;
661
662 // Results
663 def InstrSDrm {
664 bits<4> opcode = { 0, 0, 1, 0 };
665 bits<4> Prefix = { 1, 1, 0, 0 };
666 }
667 ...
668 def InstrSSrr {
669 bits<4> opcode = { 0, 1, 0, 0 };
670 bits<4> Prefix = { 1, 0, 1, 1 };
671 }
672
673 File scope entities
674 -------------------
675
676 File inclusion
677 ^^^^^^^^^^^^^^
678
679 TableGen supports the '``include``' token, which textually substitutes the
680 specified file in place of the include directive. The filename should be
681 specified as a double quoted string immediately after the '``include``' keyword.
682 Example:
683
684 .. code-block:: llvm
685
686 include "foo.td"
687
688 'let' expressions
689 ^^^^^^^^^^^^^^^^^
690
691 "Let" expressions at file scope are similar to `"let" expressions within a
692 record`_, except they can specify a value binding for multiple records at a
693 time, and may be useful in certain other cases. File-scope let expressions are
694 really just another way that TableGen allows the end-user to factor out
695 commonality from the records.
696
697 File-scope "let" expressions take a comma-separated list of bindings to apply,
698 and one or more records to bind the values in. Here are some examples:
699
700 .. code-block:: llvm
701
702 let isTerminator = 1, isReturn = 1, isBarrier = 1, hasCtrlDep = 1 in
703 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
704
705 let isCall = 1 in
706 // All calls clobber the non-callee saved registers...
707 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
708 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7,
709 XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
710 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst,variable_ops),
711 "call\t${dst:call}", []>;
712 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
713 "call\t{*}$dst", [(X86call GR32:$dst)]>;
714 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
715 "call\t{*}$dst", []>;
716 }
717
718 File-scope "let" expressions are often useful when a couple of definitions need
719 to be added to several records, and the records do not otherwise need to be
720 opened, as in the case with the ``CALL*`` instructions above.
721
722 It's also possible to use "let" expressions inside multiclasses, providing more
723 ways to factor out commonality from the records, specially if using several
724 levels of multiclass instantiations. This also avoids the need of using "let"
725 expressions within subsequent records inside a multiclass.
726
727 .. code-block:: llvm
728
729 multiclass basic_r opc> {
730 let Predicates = [HasSSE2] in {
731 def rr : Instruction;
732 def rm : Instruction;
733 }
734 let Predicates = [HasSSE3] in
735 def rx : Instruction;
736 }
737
738 multiclass basic_ss opc> {
739 let IsDouble = 0 in
740 defm SS : basic_r;
741
742 let IsDouble = 1 in
743 defm SD : basic_r;
744 }
745
746 defm ADD : basic_ss<0xf>;
747
748 Looping
749 ^^^^^^^
750
751 TableGen supports the '``foreach``' block, which textually replicates the loop
752 body, substituting iterator values for iterator references in the body.
753 Example:
754
755 .. code-block:: llvm
756
757 foreach i = [0, 1, 2, 3] in {
758 def R#i : Register<...>;
759 def F#i : Register<...>;
760 }
761
762 This will create objects ``R0``, ``R1``, ``R2`` and ``R3``. ``foreach`` blocks
763 may be nested. If there is only one item in the body the braces may be
764 elided:
765
766 .. code-block:: llvm
767
768 foreach i = [0, 1, 2, 3] in
769 def R#i : Register<...>;
770
771 Code Generator backend info
772 ===========================
773
774 Expressions used by code generator to describe instructions and isel patterns:
775
776 ``(implicit a)``
777 an implicitly defined physical register. This tells the dag instruction
778 selection emitter the input pattern's extra definitions matches implicit
779 physical register definitions.
780
781 .. _TableGen backend:
782 .. _TableGen backends:
783 .. _write a backend:
784
785 TableGen backends
786 =================
787
788 Until we get a step-by-step HowTo for writing TableGen backends, you can at
789 least grab the boilerplate (build system, new files, etc.) from Clang's
790 r173931.
791
792 TODO: How they work, how to write one. This section should not contain details
793 about any particular backend, except maybe ``-print-enums`` as an example. This
794 should highlight the APIs in ``TableGen/Record.h``.
7 The TableGen fundamentals documentation has moved to a directory on its own
8 and is now available at :doc:`TableGen/index`. Please, change your links to
9 that page.
247247 working on retargetting LLVM to a new architecture, designing a new codegen
248248 pass, or enhancing existing components.
249249
250 :doc:`TableGenFundamentals`
250 :doc:`TableGen Fundamentals `
251251 Describes the TableGen tool, which is used heavily by the LLVM code
252252 generator.
253253