Debian Codegraph @

llvm/docs/TableGen/ProgRef.rst

raw
1 ===============================
2 TableGen Programmer's Reference
3 ===============================
4
5 .. sectnum::
6
7 .. contents::
8 :local:
9
10 Introduction
11 ============
12
13 The purpose of TableGen is to generate complex output files based on
14 information from source files that are significantly easier to code than the
15 output files would be, and also easier to maintain and modify over time. The
16 information is coded in a declarative style involving classes and records,
17 which are then processed by TableGen. The internalized records are passed on
18 to various *backends*, which extract information from a subset of the records
19 and generate one or more output files. These output files are typically
20 ``.inc`` files for C++, but may be any type of file that the backend
21 developer needs.
22
23 This document describes the LLVM TableGen facility in detail. It is intended
24 for the programmer who is using TableGen to produce code for a project. If
25 you are looking for a simple overview, check out the :doc:`TableGen Overview
26 <./index>`. The various ``*-tblgen`` commands used to invoke TableGen are
27 described in :doc:`tblgen Family - Description to C++
28 Code<../CommandGuide/tblgen>`.
29
30 An example of a backend is ``RegisterInfo``, which generates the register
31 file information for a particular target machine, for use by the LLVM
32 target-independent code generator. See :doc:`TableGen Backends <./BackEnds>`
33 for a description of the LLVM TableGen backends, and :doc:`TableGen
34 Backend Developer's Guide <./BackGuide>` for a guide to writing a new
35 backend.
36
37 Here are a few of the things backends can do.
38
39 * Generate the register file information for a particular target machine.
40
41 * Generate the instruction definitions for a target.
42
43 * Generate the patterns that the code generator uses to match instructions
44 to intermediate representation (IR) nodes.
45
46 * Generate semantic attribute identifiers for Clang.
47
48 * Generate abstract syntax tree (AST) declaration node definitions for Clang.
49
50 * Generate AST statement node definitions for Clang.
51
52
53 Concepts
54 --------
55
56 TableGen source files contain two primary items: *abstract records* and
57 *concrete records*. In this and other TableGen documents, abstract records
58 are called *classes.* (These classes are different from C++ classes and do
59 not map onto them.) In addition, concrete records are usually just called
60 records, although sometimes the term *record* refers to both classes and
61 concrete records. The distinction should be clear in context.
62
63 Classes and concrete records have a unique *name*, either chosen by
64 the programmer or generated by TableGen. Associated with that name
65 is a list of *fields* with values and an optional list of *parent classes*
66 (sometimes called base or super classes). The fields are the primary data that
67 backends will process. Note that TableGen assigns no meaning to fields; the
68 meanings are entirely up to the backends and the programs that incorporate
69 the output of those backends.
70
71 .. note::
72
73 The term "parent class" can refer to a class that is a parent of another
74 class, and also to a class from which a concrete record inherits. This
75 nonstandard use of the term arises because TableGen treats classes and
76 concrete records similarly.
77
78 A backend processes some subset of the concrete records built by the
79 TableGen parser and emits the output files. These files are usually C++
80 ``.inc`` files that are included by the programs that require the data in
81 those records. However, a backend can produce any type of output files. For
82 example, it could produce a data file containing messages tagged with
83 identifiers and substitution parameters. In a complex use case such as the
84 LLVM code generator, there can be many concrete records and some of them can
85 have an unexpectedly large number of fields, resulting in large output files.
86
87 In order to reduce the complexity of TableGen files, classes are used to
88 abstract out groups of record fields. For example, a few classes may
89 abstract the concept of a machine register file, while other classes may
90 abstract the instruction formats, and still others may abstract the
91 individual instructions. TableGen allows an arbitrary hierarchy of classes,
92 so that the abstract classes for two concepts can share a third superclass that
93 abstracts common "sub-concepts" from the two original concepts.
94
95 In order to make classes more useful, a concrete record (or another class)
96 can request a class as a parent class and pass *template arguments* to it.
97 These template arguments can be used in the fields of the parent class to
98 initialize them in a custom manner. That is, record or class ``A`` can
99 request parent class ``S`` with one set of template arguments, while record or class
100 ``B`` can request ``S`` with a different set of arguments. Without template
101 arguments, many more classes would be required, one for each combination of
102 the template arguments.
103
104 Both classes and concrete records can include fields that are uninitialized.
105 The uninitialized "value" is represented by a question mark (``?``). Classes
106 often have uninitialized fields that are expected to be filled in when those
107 classes are inherited by concrete records. Even so, some fields of concrete
108 records may remain uninitialized.
109
110 TableGen provides *multiclasses* to collect a group of record definitions in
111 one place. A multiclass is a sort of macro that can be "invoked" to define
112 multiple concrete records all at once. A multiclass can inherit from other
113 multiclasses, which means that the multiclass inherits all the definitions
114 from its parent multiclasses.
115
116 `Appendix C: Sample Record`_ illustrates a complex record in the Intel X86
117 target and the simple way in which it is defined.
118
119 Source Files
120 ============
121
122 TableGen source files are plain ASCII text files. The files can contain
123 statements, comments, and blank lines (see `Lexical Analysis`_). The standard file
124 extension for TableGen files is ``.td``.
125
126 TableGen files can grow quite large, so there is an include mechanism that
127 allows one file to include the content of another file (see `Include
128 Files`_). This allows large files to be broken up into smaller ones, and
129 also provides a simple library mechanism where multiple source files can
130 include the same library file.
131
132 TableGen supports a simple preprocessor that can be used to conditionalize
133 portions of ``.td`` files. See `Preprocessing Facilities`_ for more
134 information.
135
136 Lexical Analysis
137 ================
138
139 The lexical and syntax notation used here is intended to imitate
140 `Python's`_ notation. In particular, for lexical definitions, the productions
141 operate at the character level and there is no implied whitespace between
142 elements. The syntax definitions operate at the token level, so there is
143 implied whitespace between tokens.
144
145 .. _`Python's`: http://docs.python.org/py3k/reference/introduction.html#notation
146
147 TableGen supports BCPL-style comments (``// ...``) and nestable C-style
148 comments (``/* ... */``).
149 TableGen also provides simple `Preprocessing Facilities`_.
150
151 Formfeed characters may be used freely in files to produce page breaks when
152 the file is printed for review.
153
154 The following are the basic punctuation tokens::
155
156 - + [ ] { } ( ) < > : ; . ... = ? #
157
158 Literals
159 --------
160
161 Numeric literals take one of the following forms:
162
163 .. productionlist::
164 TokInteger: `DecimalInteger` | `HexInteger` | `BinInteger`
165 DecimalInteger: ["+" | "-"] ("0"..."9")+
166 HexInteger: "0x" ("0"..."9" | "a"..."f" | "A"..."F")+
167 BinInteger: "0b" ("0" | "1")+
168
169 Observe that the :token:`DecimalInteger` token includes the optional ``+``
170 or ``-`` sign, unlike most languages where the sign would be treated as a
171 unary operator.
172
173 TableGen has two kinds of string literals:
174
175 .. productionlist::
176 TokString: '"' (non-'"' characters and escapes) '"'
177 TokCode: "[{" (text not containing "}]") "}]"
178
179 A :token:`TokCode` is nothing more than a multi-line string literal
180 delimited by ``[{`` and ``}]``. It can break across lines and the
181 line breaks are retained in the string.
182
183 The current implementation accepts the following escape sequences::
184
185 \\ \' \" \t \n
186
187 Identifiers
188 -----------
189
190 TableGen has name- and identifier-like tokens, which are case-sensitive.
191
192 .. productionlist::
193 ualpha: "a"..."z" | "A"..."Z" | "_"
194 TokIdentifier: ("0"..."9")* `ualpha` (`ualpha` | "0"..."9")*
195 TokVarName: "$" `ualpha` (`ualpha` | "0"..."9")*
196
197 Note that, unlike most languages, TableGen allows :token:`TokIdentifier` to
198 begin with an integer. In case of ambiguity, a token is interpreted as a
199 numeric literal rather than an identifier.
200
201 TableGen has the following reserved keywords, which cannot be used as
202 identifiers::
203
204 assert bit bits class code
205 dag def dump else false
206 foreach defm defset defvar field
207 if in include int let
208 list multiclass string then true
209
210 .. warning::
211 The ``field`` reserved word is deprecated, except when used with the
212 CodeEmitterGen backend where it's used to distinguish normal record
213 fields from encoding fields.
214
215 Bang operators
216 --------------
217
218 TableGen provides "bang operators" that have a wide variety of uses:
219
220 .. productionlist::
221 BangOperator: one of
222 : !add !and !cast !con !dag
223 : !div !empty !eq !exists !filter
224 : !find !foldl !foreach !ge !getdagarg
225 : !getdagname !getdagop !getdagopname !gt !head
226 : !if !initialized !instances !interleave !isa
227 : !le !listconcat !listflatten !listremove !listsplat
228 : !logtwo !lt !match !mul !ne
229 : !not !or !range !repr !setdagarg
230 : !setdagname !setdagop !setdagopname !shl !size
231 : !sra !srl !strconcat !sub !subst
232 : !substr !tail !tolower !toupper !xor
233
234 The ``!cond`` operator has a slightly different
235 syntax compared to other bang operators, so it is defined separately:
236
237 .. productionlist::
238 CondOperator: !cond
239
240 See `Appendix A: Bang Operators`_ for a description of each bang operator.
241
242 Include files
243 -------------
244
245 TableGen has an include mechanism. The content of the included file
246 lexically replaces the ``include`` directive and is then parsed as if it were
247 originally in the main file.
248
249 .. productionlist::
250 IncludeDirective: "include" `TokString`
251
252 Portions of the main file and included files can be conditionalized using
253 preprocessor directives.
254
255 .. productionlist::
256 PreprocessorDirective: "#define" | "#ifdef" | "#ifndef"
257
258 Types
259 =====
260
261 The TableGen language is statically typed, using a simple but complete type
262 system. Types are used to check for errors, to perform implicit conversions,
263 and to help interface designers constrain the allowed input. Every value is
264 required to have an associated type.
265
266 TableGen supports a mixture of low-level types (e.g., ``bit``) and
267 high-level types (e.g., ``dag``). This flexibility allows you to describe a
268 wide range of records conveniently and compactly.
269
270 .. productionlist::
271 Type: "bit" | "int" | "string" | "dag" | "code"
272 :| "bits" "<" `TokInteger` ">"
273 :| "list" "<" `Type` ">"
274 :| `ClassID`
275 ClassID: `TokIdentifier`
276
277 ``bit``
278 A ``bit`` is a boolean value that can be 0 or 1.
279
280 ``int``
281 The ``int`` type represents a simple 64-bit integer value, such as 5 or
282 -42.
283
284 ``string``
285 The ``string`` type represents an ordered sequence of characters of arbitrary
286 length.
287
288 ``code``
289 The keyword ``code`` is an alias for ``string`` which may be used to
290 indicate string values that are code.
291
292 ``bits<``\ *n*\ ``>``
293 The ``bits`` type is a fixed-sized integer of arbitrary length *n* that
294 is treated as separate bits. These bits can be accessed individually.
295 A field of this type is useful for representing an instruction operation
296 code, register number, or address mode/register/displacement. The bits of
297 the field can be set individually or as subfields. For example, in an
298 instruction address, the addressing mode, base register number, and
299 displacement can be set separately.
300
301 ``list<``\ *type*\ ``>``
302 This type represents a list whose elements are of the *type* specified in
303 angle brackets. The element type is arbitrary; it can even be another
304 list type. List elements are indexed from 0.
305
306 ``dag``
307 This type represents a nestable directed acyclic graph (DAG) of nodes.
308 Each node has an *operator* and zero or more *arguments* (or *operands*).
309 An argument can be
310 another ``dag`` object, allowing an arbitrary tree of nodes and edges.
311 As an example, DAGs are used to represent code patterns for use by
312 the code generator instruction selection algorithms. See `Directed
313 acyclic graphs (DAGs)`_ for more details;
314
315 :token:`ClassID`
316 Specifying a class name in a type context indicates
317 that the type of the defined value must
318 be a subclass of the specified class. This is useful in conjunction with
319 the ``list`` type; for example, to constrain the elements of the list to a
320 common base class (e.g., a ``list<Register>`` can only contain definitions
321 derived from the ``Register`` class).
322 The :token:`ClassID` must name a class that has been previously
323 declared or defined.
324
325
326 Values and Expressions
327 ======================
328
329 There are many contexts in TableGen statements where a value is required. A
330 common example is in the definition of a record, where each field is
331 specified by a name and an optional value. TableGen allows for a reasonable
332 number of different forms when building up value expressions. These forms
333 allow the TableGen file to be written in a syntax that is natural for the
334 application.
335
336 Note that all of the values have rules for converting them from one type to
337 another. For example, these rules allow you to assign a value like ``7``
338 to an entity of type ``bits<4>``.
339
340 .. productionlist::
341 Value: `SimpleValue` `ValueSuffix`*
342 :| `Value` "#" [`Value`]
343 ValueSuffix: "{" `RangeList` "}"
344 :| "[" `SliceElements` "]"
345 :| "." `TokIdentifier`
346 RangeList: `RangePiece` ("," `RangePiece`)*
347 RangePiece: `TokInteger`
348 :| `TokInteger` "..." `TokInteger`
349 :| `TokInteger` "-" `TokInteger`
350 :| `TokInteger` `TokInteger`
351 SliceElements: (`SliceElement` ",")* `SliceElement` ","?
352 SliceElement: `Value`
353 :| `Value` "..." `Value`
354 :| `Value` "-" `Value`
355 :| `Value` `TokInteger`
356
357 .. warning::
358 The peculiar last form of :token:`RangePiece` and :token:`SliceElement` is
359 due to the fact that the "``-``" is included in the :token:`TokInteger`,
360 hence ``1-5`` gets lexed as two consecutive tokens, with values ``1`` and
361 ``-5``, instead of "1", "-", and "5".
362 The use of hyphen as the range punctuation is deprecated.
363
364 Simple values
365 -------------
366
367 The :token:`SimpleValue` has a number of forms.
368
369 .. productionlist::
370 SimpleValue: `SimpleValue1`
371 :| `SimpleValue2`
372 :| `SimpleValue3`
373 :| `SimpleValue4`
374 :| `SimpleValue5`
375 :| `SimpleValue6`
376 :| `SimpleValue7`
377 :| `SimpleValue8`
378 :| `SimpleValue9`
379 SimpleValue1: `TokInteger` | `TokString`+ | `TokCode`
380
381 A value can be an integer literal, a string literal, or a code literal.
382 Multiple adjacent string literals are concatenated as in C/C++; the simple
383 value is the concatenation of the strings. Code literals become strings and
384 are then indistinguishable from them.
385
386 .. productionlist::
387 SimpleValue2: "true" | "false"
388
389 The ``true`` and ``false`` literals are essentially syntactic sugar for the
390 integer values 1 and 0. They improve the readability of TableGen files when
391 boolean values are used in field initializations, bit sequences, ``if``
392 statements, etc. When parsed, these literals are converted to integers.
393
394 .. note::
395
396 Although ``true`` and ``false`` are literal names for 1 and 0, we
397 recommend as a stylistic rule that you use them for boolean
398 values only.
399
400 .. productionlist::
401 SimpleValue3: "?"
402
403 A question mark represents an uninitialized value.
404
405 .. productionlist::
406 SimpleValue4: "{" [`ValueList`] "}"
407 ValueList: `ValueListNE`
408 ValueListNE: `Value` ("," `Value`)*
409
410 This value represents a sequence of bits, which can be used to initialize a
411 ``bits<``\ *n*\ ``>`` field (note the braces). When doing so, the values
412 must represent a total of *n* bits.
413
414 .. productionlist::
415 SimpleValue5: "[" `ValueList` "]" ["<" `Type` ">"]
416
417 This value is a list initializer (note the brackets). The values in brackets
418 are the elements of the list. The optional :token:`Type` can be used to
419 indicate a specific element type; otherwise the element type is inferred
420 from the given values. TableGen can usually infer the type, although
421 sometimes not when the value is the empty list (``[]``).
422
423 .. productionlist::
424 SimpleValue6: "(" `DagArg` [`DagArgList`] ")"
425 DagArgList: `DagArg` ("," `DagArg`)*
426 DagArg: `Value` [":" `TokVarName`] | `TokVarName`
427
428 This represents a DAG initializer (note the parentheses). The first
429 :token:`DagArg` is called the "operator" of the DAG and must be a record.
430 See `Directed acyclic graphs (DAGs)`_ for more details.
431
432 .. productionlist::
433 SimpleValue7: `TokIdentifier`
434
435 The resulting value is the value of the entity named by the identifier. The
436 possible identifiers are described here, but the descriptions will make more
437 sense after reading the remainder of this guide.
438
439 .. The code for this is exceptionally abstruse. These examples are a
440 best-effort attempt.
441
442 * A template argument of a ``class``, such as the use of ``Bar`` in::
443
444 class Foo <int Bar> {
445 int Baz = Bar;
446 }
447
448 * The implicit template argument ``NAME`` in a ``class`` or ``multiclass``
449 definition (see `NAME`_).
450
451 * A field local to a ``class``, such as the use of ``Bar`` in::
452
453 class Foo {
454 int Bar = 5;
455 int Baz = Bar;
456 }
457
458 * The name of a record definition, such as the use of ``Bar`` in the
459 definition of ``Foo``::
460
461 def Bar : SomeClass {
462 int X = 5;
463 }
464
465 def Foo {
466 SomeClass Baz = Bar;
467 }
468
469 * A field local to a record definition, such as the use of ``Bar`` in::
470
471 def Foo {
472 int Bar = 5;
473 int Baz = Bar;
474 }
475
476 Fields inherited from the record's parent classes can be accessed the same way.
477
478 * A template argument of a ``multiclass``, such as the use of ``Bar`` in::
479
480 multiclass Foo <int Bar> {
481 def : SomeClass<Bar>;
482 }
483
484 * A variable defined with the ``defvar`` or ``defset`` statements.
485
486 * The iteration variable of a ``foreach``, such as the use of ``i`` in::
487
488 foreach i = 0...5 in
489 def Foo#i;
490
491 .. productionlist::
492 SimpleValue8: `ClassID` "<" `ArgValueList` ">"
493
494 This form creates a new anonymous record definition (as would be created by an
495 unnamed ``def`` inheriting from the given class with the given template
496 arguments; see `def`_) and the value is that record. A field of the record can be
497 obtained using a suffix; see `Suffixed Values`_.
498
499 Invoking a class in this manner can provide a simple subroutine facility.
500 See `Using Classes as Subroutines`_ for more information.
501
502 .. productionlist::
503 SimpleValue9: `BangOperator` ["<" `Type` ">"] "(" `ValueListNE` ")"
504 :| `CondOperator` "(" `CondClause` ("," `CondClause`)* ")"
505 CondClause: `Value` ":" `Value`
506
507 The bang operators provide functions that are not available with the other
508 simple values. Except in the case of ``!cond``, a bang operator takes a list
509 of arguments enclosed in parentheses and performs some function on those
510 arguments, producing a value for that bang operator. The ``!cond`` operator
511 takes a list of pairs of arguments separated by colons. See `Appendix A:
512 Bang Operators`_ for a description of each bang operator.
513
514 The `Type` is only accepted for certain bang operators, and must not be
515 ``code``.
516
517 Suffixed values
518 ---------------
519
520 The :token:`SimpleValue` values described above can be specified with
521 certain suffixes. The purpose of a suffix is to obtain a subvalue of the
522 primary value. Here are the possible suffixes for some primary *value*.
523
524 *value*\ ``{17}``
525 The final value is bit 17 of the integer *value* (note the braces).
526
527 *value*\ ``{8...15}``
528 The final value is bits 8--15 of the integer *value*. The order of the
529 bits can be reversed by specifying ``{15...8}``.
530
531 *value*\ ``[i]``
532 The final value is element `i` of the list *value* (note the brackets).
533 In other words, the brackets act as a subscripting operator on the list.
534 This is the case only when a single element is specified.
535
536 *value*\ ``[i,]``
537 The final value is a list that contains a single element `i` of the list.
538 In short, a list slice with a single element.
539
540 *value*\ ``[4...7,17,2...3,4]``
541 The final value is a new list that is a slice of the list *value*.
542 The new list contains elements 4, 5, 6, 7, 17, 2, 3, and 4.
543 Elements may be included multiple times and in any order. This is the result
544 only when more than one element is specified.
545
546 *value*\ ``[i,m...n,j,ls]``
547 Each element may be an expression (variables, bang operators).
548 The type of `m` and `n` should be `int`.
549 The type of `i`, `j`, and `ls` should be either `int` or `list<int>`.
550
551 *value*\ ``.``\ *field*
552 The final value is the value of the specified *field* in the specified
553 record *value*.
554
555 The paste operator
556 ------------------
557
558 The paste operator (``#``) is the only infix operator available in TableGen
559 expressions. It allows you to concatenate strings or lists, but has a few
560 unusual features.
561
562 The paste operator can be used when specifying the record name in a
563 :token:`Def` or :token:`Defm` statement, in which case it must construct a
564 string. If an operand is an undefined name (:token:`TokIdentifier`) or the
565 name of a global :token:`Defvar` or :token:`Defset`, it is treated as a
566 verbatim string of characters. The value of a global name is not used.
567
568 The paste operator can be used in all other value expressions, in which case
569 it can construct a string or a list. Rather oddly, but consistent with the
570 previous case, if the *right-hand-side* operand is an undefined name or a
571 global name, it is treated as a verbatim string of characters. The
572 left-hand-side operand is treated normally.
573
574 Values can have a trailing paste operator, in which case the left-hand-side
575 operand is concatenated to an empty string.
576
577 `Appendix B: Paste Operator Examples`_ presents examples of the behavior of
578 the paste operator.
579
580 Statements
581 ==========
582
583 The following statements may appear at the top level of TableGen source
584 files.
585
586 .. productionlist::
587 TableGenFile: (`Statement` | `IncludeDirective`
588 :| `PreprocessorDirective`)*
589 Statement: `Assert` | `Class` | `Def` | `Defm` | `Defset` | `Deftype`
590 :| `Defvar` | `Dump` | `Foreach` | `If` | `Let` | `MultiClass`
591
592 The following sections describe each of these top-level statements.
593
594
595 ``class`` --- define an abstract record class
596 ---------------------------------------------
597
598 A ``class`` statement defines an abstract record class from which other
599 classes and records can inherit.
600
601 .. productionlist::
602 Class: "class" `ClassID` [`TemplateArgList`] `RecordBody`
603 TemplateArgList: "<" `TemplateArgDecl` ("," `TemplateArgDecl`)* ">"
604 TemplateArgDecl: `Type` `TokIdentifier` ["=" `Value`]
605
606 A class can be parameterized by a list of "template arguments," whose values
607 can be used in the class's record body. These template arguments are
608 specified each time the class is inherited by another class or record.
609
610 If a template argument is not assigned a default value with ``=``, it is
611 uninitialized (has the "value" ``?``) and must be specified in the template
612 argument list when the class is inherited (required argument). If an
613 argument is assigned a default value, then it need not be specified in the
614 argument list (optional argument). In the declaration, all required template
615 arguments must precede any optional arguments. The template argument default
616 values are evaluated from left to right.
617
618 The :token:`RecordBody` is defined below. It can include a list of
619 parent classes from which the current class inherits, along with field
620 definitions and other statements. When a class ``C`` inherits from another
621 class ``D``, the fields of ``D`` are effectively merged into the fields of
622 ``C``.
623
624 A given class can only be defined once. A ``class`` statement is
625 considered to define the class if *any* of the following are true (the
626 :token:`RecordBody` elements are described below).
627
628 * The :token:`TemplateArgList` is present, or
629 * The :token:`ParentClassList` in the :token:`RecordBody` is present, or
630 * The :token:`Body` in the :token:`RecordBody` is present and not empty.
631
632 You can declare an empty class by specifying an empty :token:`TemplateArgList`
633 and an empty :token:`RecordBody`. This can serve as a restricted form of
634 forward declaration. Note that records derived from a forward-declared
635 class will inherit no fields from it, because those records are built when
636 their declarations are parsed, and thus before the class is finally defined.
637
638 .. _NAME:
639
640 Every class has an implicit template argument named ``NAME`` (uppercase),
641 which is bound to the name of the :token:`Def` or :token:`Defm` inheriting
642 from the class. If the class is inherited by an anonymous record, the name
643 is unspecified but globally unique.
644
645 See `Examples: classes and records`_ for examples.
646
647 Record Bodies
648 `````````````
649
650 Record bodies appear in both class and record definitions. A record body can
651 include a parent class list, which specifies the classes from which the
652 current class or record inherits fields. Such classes are called the
653 parent classes of the class or record. The record body also
654 includes the main body of the definition, which contains the specification
655 of the fields of the class or record.
656
657 .. productionlist::
658 RecordBody: `ParentClassList` `Body`
659 ParentClassList: [":" `ParentClassListNE`]
660 ParentClassListNE: `ClassRef` ("," `ClassRef`)*
661 ClassRef: (`ClassID` | `MultiClassID`) ["<" [`ArgValueList`] ">"]
662 ArgValueList: `PostionalArgValueList` [","] `NamedArgValueList`
663 PostionalArgValueList: [`Value` {"," `Value`}*]
664 NamedArgValueList: [`NameValue` "=" `Value` {"," `NameValue` "=" `Value`}*]
665
666 A :token:`ParentClassList` containing a :token:`MultiClassID` is valid only
667 in the class list of a ``defm`` statement. In that case, the ID must be the
668 name of a multiclass.
669
670 The argument values can be specified in two forms:
671
672 * Positional argument (``value``). The value is assigned to the argument in the
673 corresponding position. For ``Foo<a0, a1>``, ``a0`` will be assigned to the first
674 argument and ``a1`` will be assigned to the second argument.
675 * Named argument (``name=value``). The value is assigned to the argument with
676 the specified name. For ``Foo<a=a0, b=a1>``, ``a0`` will be assigned to the
677 argument with name ``a`` and ``a1`` will be assigned to the argument with
678 name ``b``.
679
680 Required arguments can also be specified as a named argument.
681
682 Note that the argument can only be specified once regardless of the way (named
683 or positional) to specify and positional arguments should precede named
684 arguments.
685
686 .. productionlist::
687 Body: ";" | "{" `BodyItem`* "}"
688 BodyItem: `Type` `TokIdentifier` ["=" `Value`] ";"
689 :| "let" `TokIdentifier` ["{" `RangeList` "}"] "=" `Value` ";"
690 :| "defvar" `TokIdentifier` "=" `Value` ";"
691 :| `Assert`
692
693 A field definition in the body specifies a field to be included in the class
694 or record. If no initial value is specified, then the field's value is
695 uninitialized. The type must be specified; TableGen will not infer it from
696 the value.
697
698 The ``let`` form is used to reset a field to a new value. This can be done
699 for fields defined directly in the body or fields inherited from parent
700 classes. A :token:`RangeList` can be specified to reset certain bits in a
701 ``bit<n>`` field.
702
703 The ``defvar`` form defines a variable whose value can be used in other
704 value expressions within the body. The variable is not a field: it does not
705 become a field of the class or record being defined. Variables are provided
706 to hold temporary values while processing the body. See `Defvar in a Record
707 Body`_ for more details.
708
709 When class ``C2`` inherits from class ``C1``, it acquires all the field
710 definitions of ``C1``. As those definitions are merged into class ``C2``, any
711 template arguments passed to ``C1`` by ``C2`` are substituted into the
712 definitions. In other words, the abstract record fields defined by ``C1`` are
713 expanded with the template arguments before being merged into ``C2``.
714
715
716 .. _def:
717
718 ``def`` --- define a concrete record
719 ------------------------------------
720
721 A ``def`` statement defines a new concrete record.
722
723 .. productionlist::
724 Def: "def" [`NameValue`] `RecordBody`
725 NameValue: `Value` (parsed in a special mode)
726
727 The name value is optional. If specified, it is parsed in a special mode
728 where undefined (unrecognized) identifiers are interpreted as literal
729 strings. In particular, global identifiers are considered unrecognized.
730 These include global variables defined by ``defvar`` and ``defset``. A
731 record name can be the null string.
732
733 If no name value is given, the record is *anonymous*. The final name of an
734 anonymous record is unspecified but globally unique.
735
736 Special handling occurs if a ``def`` appears inside a ``multiclass``
737 statement. See the ``multiclass`` section below for details.
738
739 A record can inherit from one or more classes by specifying the
740 :token:`ParentClassList` clause at the beginning of its record body. All of
741 the fields in the parent classes are added to the record. If two or more
742 parent classes provide the same field, the record ends up with the field value
743 of the last parent class.
744
745 As a special case, the name of a record can be passed as a template argument
746 to that record's parent classes. For example:
747
748 .. code-block:: text
749
750 class A <dag d> {
751 dag the_dag = d;
752 }
753
754 def rec1 : A<(ops rec1)>;
755
756 The DAG ``(ops rec1)`` is passed as a template argument to class ``A``. Notice
757 that the DAG includes ``rec1``, the record being defined.
758
759 The steps taken to create a new record are somewhat complex. See `How
760 records are built`_.
761
762 See `Examples: classes and records`_ for examples.
763
764
765 Examples: classes and records
766 -----------------------------
767
768 Here is a simple TableGen file with one class and two record definitions.
769
770 .. code-block:: text
771
772 class C {
773 bit V = true;
774 }
775
776 def X : C;
777 def Y : C {
778 let V = false;
779 string Greeting = "Hello!";
780 }
781
782 First, the abstract class ``C`` is defined. It has one field named ``V``
783 that is a bit initialized to true.
784
785 Next, two records are defined, derived from class ``C``; that is, with ``C``
786 as their parent class. Thus they both inherit the ``V`` field. Record ``Y``
787 also defines another string field, ``Greeting``, which is initialized to
788 ``"Hello!"``. In addition, ``Y`` overrides the inherited ``V`` field,
789 setting it to false.
790
791 A class is useful for isolating the common features of multiple records in
792 one place. A class can initialize common fields to default values, but
793 records inheriting from that class can override the defaults.
794
795 TableGen supports the definition of parameterized classes as well as
796 nonparameterized ones. Parameterized classes specify a list of variable
797 declarations, which may optionally have defaults, that are bound when the
798 class is specified as a parent class of another class or record.
799
800 .. code-block:: text
801
802 class FPFormat <bits<3> val> {
803 bits<3> Value = val;
804 }
805
806 def NotFP : FPFormat<0>;
807 def ZeroArgFP : FPFormat<1>;
808 def OneArgFP : FPFormat<2>;
809 def OneArgFPRW : FPFormat<3>;
810 def TwoArgFP : FPFormat<4>;
811 def CompareFP : FPFormat<5>;
812 def CondMovFP : FPFormat<6>;
813 def SpecialFP : FPFormat<7>;
814
815 The purpose of the ``FPFormat`` class is to act as a sort of enumerated
816 type. It provides a single field, ``Value``, which holds a 3-bit number. Its
817 template argument, ``val``, is used to set the ``Value`` field. Each of the
818 eight records is defined with ``FPFormat`` as its parent class. The
819 enumeration value is passed in angle brackets as the template argument. Each
820 record will inherit the ``Value`` field with the appropriate enumeration
821 value.
822
823 Here is a more complex example of classes with template arguments. First, we
824 define a class similar to the ``FPFormat`` class above. It takes a template
825 argument and uses it to initialize a field named ``Value``. Then we define
826 four records that inherit the ``Value`` field with its four different
827 integer values.
828
829 .. code-block:: text
830
831 class ModRefVal <bits<2> val> {
832 bits<2> Value = val;
833 }
834
835 def None : ModRefVal<0>;
836 def Mod : ModRefVal<1>;
837 def Ref : ModRefVal<2>;
838 def ModRef : ModRefVal<3>;
839
840 This is somewhat contrived, but let's say we would like to examine the two
841 bits of the ``Value`` field independently. We can define a class that
842 accepts a ``ModRefVal`` record as a template argument and splits up its
843 value into two fields, one bit each. Then we can define records that inherit from
844 ``ModRefBits`` and so acquire two fields from it, one for each bit in the
845 ``ModRefVal`` record passed as the template argument.
846
847 .. code-block:: text
848
849 class ModRefBits <ModRefVal mrv> {
850 // Break the value up into its bits, which can provide a nice
851 // interface to the ModRefVal values.
852 bit isMod = mrv.Value{0};
853 bit isRef = mrv.Value{1};
854 }
855
856 // Example uses.
857 def foo : ModRefBits<Mod>;
858 def bar : ModRefBits<Ref>;
859 def snork : ModRefBits<ModRef>;
860
861 This illustrates how one class can be defined to reorganize the
862 fields in another class, thus hiding the internal representation of that
863 other class.
864
865 Running ``llvm-tblgen`` on the example prints the following definitions:
866
867 .. code-block:: text
868
869 def bar { // Value
870 bit isMod = 0;
871 bit isRef = 1;
872 }
873 def foo { // Value
874 bit isMod = 1;
875 bit isRef = 0;
876 }
877 def snork { // Value
878 bit isMod = 1;
879 bit isRef = 1;
880 }
881
882 ``let`` --- override fields in classes or records
883 -------------------------------------------------
884
885 A ``let`` statement collects a set of field values (sometimes called
886 *bindings*) and applies them to all the classes and records defined by
887 statements within the scope of the ``let``.
888
889 .. productionlist::
890 Let: "let" `LetList` "in" "{" `Statement`* "}"
891 :| "let" `LetList` "in" `Statement`
892 LetList: `LetItem` ("," `LetItem`)*
893 LetItem: `TokIdentifier` ["<" `RangeList` ">"] "=" `Value`
894
895 The ``let`` statement establishes a scope, which is a sequence of statements
896 in braces or a single statement with no braces. The bindings in the
897 :token:`LetList` apply to the statements in that scope.
898
899 The field names in the :token:`LetList` must name fields in classes inherited by
900 the classes and records defined in the statements. The field values are
901 applied to the classes and records *after* the records inherit all the fields from
902 their parent classes. So the ``let`` acts to override inherited field
903 values. A ``let`` cannot override the value of a template argument.
904
905 Top-level ``let`` statements are often useful when a few fields need to be
906 overridden in several records. Here are two examples. Note that ``let``
907 statements can be nested.
908
909 .. code-block:: text
910
911 let isTerminator = true, isReturn = true, isBarrier = true, hasCtrlDep = true in
912 def RET : I<0xC3, RawFrm, (outs), (ins), "ret", [(X86retflag 0)]>;
913
914 let isCall = true in
915 // All calls clobber the non-callee saved registers...
916 let Defs = [EAX, ECX, EDX, FP0, FP1, FP2, FP3, FP4, FP5, FP6, ST0,
917 MM0, MM1, MM2, MM3, MM4, MM5, MM6, MM7, XMM0, XMM1, XMM2,
918 XMM3, XMM4, XMM5, XMM6, XMM7, EFLAGS] in {
919 def CALLpcrel32 : Ii32<0xE8, RawFrm, (outs), (ins i32imm:$dst, variable_ops),
920 "call\t${dst:call}", []>;
921 def CALL32r : I<0xFF, MRM2r, (outs), (ins GR32:$dst, variable_ops),
922 "call\t{*}$dst", [(X86call GR32:$dst)]>;
923 def CALL32m : I<0xFF, MRM2m, (outs), (ins i32mem:$dst, variable_ops),
924 "call\t{*}$dst", []>;
925 }
926
927 Note that a top-level ``let`` will not override fields defined in the classes or records
928 themselves.
929
930
931 ``multiclass`` --- define multiple records
932 ------------------------------------------
933
934 While classes with template arguments are a good way to factor out commonality
935 between multiple records, multiclasses allow a convenient method for
936 defining many records at once. For example, consider a 3-address
937 instruction architecture whose instructions come in two formats: ``reg = reg
938 op reg`` and ``reg = reg op imm`` (e.g., SPARC). We would like to specify in
939 one place that these two common formats exist, then in a separate place
940 specify what all the operations are. The ``multiclass`` and ``defm``
941 statements accomplish this goal. You can think of a multiclass as a macro or
942 template that expands into multiple records.
943
944 .. productionlist::
945 MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
946 : `ParentClassList`
947 : "{" `MultiClassStatement`+ "}"
948 MultiClassID: `TokIdentifier`
949 MultiClassStatement: `Assert` | `Def` | `Defm` | `Defvar` | `Foreach` | `If` | `Let`
950
951 As with regular classes, the multiclass has a name and can accept template
952 arguments. A multiclass can inherit from other multiclasses, which causes
953 the other multiclasses to be expanded and contribute to the record
954 definitions in the inheriting multiclass. The body of the multiclass
955 contains a series of statements that define records, using :token:`Def` and
956 :token:`Defm`. In addition, :token:`Defvar`, :token:`Foreach`, and
957 :token:`Let` statements can be used to factor out even more common elements.
958 The :token:`If` and :token:`Assert` statements can also be used.
959
960 Also as with regular classes, the multiclass has the implicit template
961 argument ``NAME`` (see NAME_). When a named (non-anonymous) record is
962 defined in a multiclass and the record's name does not include a use of the
963 template argument ``NAME``, such a use is automatically *prepended*
964 to the name. That is, the following are equivalent inside a multiclass::
965
966 def Foo ...
967 def NAME # Foo ...
968
969 The records defined in a multiclass are created when the multiclass is
970 "instantiated" or "invoked" by a ``defm`` statement outside the multiclass
971 definition. Each ``def`` statement in the multiclass produces a record. As
972 with top-level ``def`` statements, these definitions can inherit from
973 multiple parent classes.
974
975 See `Examples: multiclasses and defms`_ for examples.
976
977
978 ``defm`` --- invoke multiclasses to define multiple records
979 -----------------------------------------------------------
980
981 Once multiclasses have been defined, you use the ``defm`` statement to
982 "invoke" them and process the multiple record definitions in those
983 multiclasses. Those record definitions are specified by ``def``
984 statements in the multiclasses, and indirectly by ``defm`` statements.
985
986 .. productionlist::
987 Defm: "defm" [`NameValue`] `ParentClassList` ";"
988
989 The optional :token:`NameValue` is formed in the same way as the name of a
990 ``def``. The :token:`ParentClassList` is a colon followed by a list of at
991 least one multiclass and any number of regular classes. The multiclasses
992 must precede the regular classes. Note that the ``defm`` does not have a
993 body.
994
995 This statement instantiates all the records defined in all the specified
996 multiclasses, either directly by ``def`` statements or indirectly by
997 ``defm`` statements. These records also receive the fields defined in any
998 regular classes included in the parent class list. This is useful for adding
999 a common set of fields to all the records created by the ``defm``.
1000
1001 The name is parsed in the same special mode used by ``def``. If the name is
1002 not included, an unspecified but globally unique name is provided. That is,
1003 the following examples end up with different names::
1004
1005 defm : SomeMultiClass<...>; // A globally unique name.
1006 defm "" : SomeMultiClass<...>; // An empty name.
1007
1008 The ``defm`` statement can be used in a multiclass body. When this occurs,
1009 the second variant is equivalent to::
1010
1011 defm NAME : SomeMultiClass<...>;
1012
1013 More generally, when ``defm`` occurs in a multiclass and its name does not
1014 include a use of the implicit template argument ``NAME``, then ``NAME`` will
1015 be prepended automatically. That is, the following are equivalent inside a
1016 multiclass::
1017
1018 defm Foo : SomeMultiClass<...>;
1019 defm NAME # Foo : SomeMultiClass<...>;
1020
1021 See `Examples: multiclasses and defms`_ for examples.
1022
1023 Examples: multiclasses and defms
1024 --------------------------------
1025
1026 Here is a simple example using ``multiclass`` and ``defm``. Consider a
1027 3-address instruction architecture whose instructions come in two formats:
1028 ``reg = reg op reg`` and ``reg = reg op imm`` (immediate). The SPARC is an
1029 example of such an architecture.
1030
1031 .. code-block:: text
1032
1033 def ops;
1034 def GPR;
1035 def Imm;
1036 class inst <int opc, string asmstr, dag operandlist>;
1037
1038 multiclass ri_inst <int opc, string asmstr> {
1039 def _rr : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
1040 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
1041 def _ri : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
1042 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
1043 }
1044
1045 // Define records for each instruction in the RR and RI formats.
1046 defm ADD : ri_inst<0b111, "add">;
1047 defm SUB : ri_inst<0b101, "sub">;
1048 defm MUL : ri_inst<0b100, "mul">;
1049
1050 Each use of the ``ri_inst`` multiclass defines two records, one with the
1051 ``_rr`` suffix and one with ``_ri``. Recall that the name of the ``defm``
1052 that uses a multiclass is prepended to the names of the records defined in
1053 that multiclass. So the resulting definitions are named::
1054
1055 ADD_rr, ADD_ri
1056 SUB_rr, SUB_ri
1057 MUL_rr, MUL_ri
1058
1059 Without the ``multiclass`` feature, the instructions would have to be
1060 defined as follows.
1061
1062 .. code-block:: text
1063
1064 def ops;
1065 def GPR;
1066 def Imm;
1067 class inst <int opc, string asmstr, dag operandlist>;
1068
1069 class rrinst <int opc, string asmstr>
1070 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
1071 (ops GPR:$dst, GPR:$src1, GPR:$src2)>;
1072
1073 class riinst <int opc, string asmstr>
1074 : inst<opc, !strconcat(asmstr, " $dst, $src1, $src2"),
1075 (ops GPR:$dst, GPR:$src1, Imm:$src2)>;
1076
1077 // Define records for each instruction in the RR and RI formats.
1078 def ADD_rr : rrinst<0b111, "add">;
1079 def ADD_ri : riinst<0b111, "add">;
1080 def SUB_rr : rrinst<0b101, "sub">;
1081 def SUB_ri : riinst<0b101, "sub">;
1082 def MUL_rr : rrinst<0b100, "mul">;
1083 def MUL_ri : riinst<0b100, "mul">;
1084
1085 A ``defm`` can be used in a multiclass to "invoke" other multiclasses and
1086 create the records defined in those multiclasses in addition to the records
1087 defined in the current multiclass. In the following example, the ``basic_s``
1088 and ``basic_p`` multiclasses contain ``defm`` statements that refer to the
1089 ``basic_r`` multiclass. The ``basic_r`` multiclass contains only ``def``
1090 statements.
1091
1092 .. code-block:: text
1093
1094 class Instruction <bits<4> opc, string Name> {
1095 bits<4> opcode = opc;
1096 string name = Name;
1097 }
1098
1099 multiclass basic_r <bits<4> opc> {
1100 def rr : Instruction<opc, "rr">;
1101 def rm : Instruction<opc, "rm">;
1102 }
1103
1104 multiclass basic_s <bits<4> opc> {
1105 defm SS : basic_r<opc>;
1106 defm SD : basic_r<opc>;
1107 def X : Instruction<opc, "x">;
1108 }
1109
1110 multiclass basic_p <bits<4> opc> {
1111 defm PS : basic_r<opc>;
1112 defm PD : basic_r<opc>;
1113 def Y : Instruction<opc, "y">;
1114 }
1115
1116 defm ADD : basic_s<0xf>, basic_p<0xf>;
1117
1118 The final ``defm`` creates the following records, five from the ``basic_s``
1119 multiclass and five from the ``basic_p`` multiclass::
1120
1121 ADDSSrr, ADDSSrm
1122 ADDSDrr, ADDSDrm
1123 ADDX
1124 ADDPSrr, ADDPSrm
1125 ADDPDrr, ADDPDrm
1126 ADDY
1127
1128 A ``defm`` statement, both at top level and in a multiclass, can inherit
1129 from regular classes in addition to multiclasses. The rule is that the
1130 regular classes must be listed after the multiclasses, and there must be at least
1131 one multiclass.
1132
1133 .. code-block:: text
1134
1135 class XD {
1136 bits<4> Prefix = 11;
1137 }
1138 class XS {
1139 bits<4> Prefix = 12;
1140 }
1141 class I <bits<4> op> {
1142 bits<4> opcode = op;
1143 }
1144
1145 multiclass R {
1146 def rr : I<4>;
1147 def rm : I<2>;
1148 }
1149
1150 multiclass Y {
1151 defm SS : R, XD; // First multiclass R, then regular class XD.
1152 defm SD : R, XS;
1153 }
1154
1155 defm Instr : Y;
1156
1157 This example will create four records, shown here in alphabetical order with
1158 their fields.
1159
1160 .. code-block:: text
1161
1162 def InstrSDrm {
1163 bits<4> opcode = { 0, 0, 1, 0 };
1164 bits<4> Prefix = { 1, 1, 0, 0 };
1165 }
1166
1167 def InstrSDrr {
1168 bits<4> opcode = { 0, 1, 0, 0 };
1169 bits<4> Prefix = { 1, 1, 0, 0 };
1170 }
1171
1172 def InstrSSrm {
1173 bits<4> opcode = { 0, 0, 1, 0 };
1174 bits<4> Prefix = { 1, 0, 1, 1 };
1175 }
1176
1177 def InstrSSrr {
1178 bits<4> opcode = { 0, 1, 0, 0 };
1179 bits<4> Prefix = { 1, 0, 1, 1 };
1180 }
1181
1182 It's also possible to use ``let`` statements inside multiclasses, providing
1183 another way to factor out commonality from the records, especially when
1184 using several levels of multiclass instantiations.
1185
1186 .. code-block:: text
1187
1188 multiclass basic_r <bits<4> opc> {
1189 let Predicates = [HasSSE2] in {
1190 def rr : Instruction<opc, "rr">;
1191 def rm : Instruction<opc, "rm">;
1192 }
1193 let Predicates = [HasSSE3] in
1194 def rx : Instruction<opc, "rx">;
1195 }
1196
1197 multiclass basic_ss <bits<4> opc> {
1198 let IsDouble = false in
1199 defm SS : basic_r<opc>;
1200
1201 let IsDouble = true in
1202 defm SD : basic_r<opc>;
1203 }
1204
1205 defm ADD : basic_ss<0xf>;
1206
1207
1208 ``defset`` --- create a definition set
1209 --------------------------------------
1210
1211 The ``defset`` statement is used to collect a set of records into a global
1212 list of records.
1213
1214 .. productionlist::
1215 Defset: "defset" `Type` `TokIdentifier` "=" "{" `Statement`* "}"
1216
1217 All records defined inside the braces via ``def`` and ``defm`` are defined
1218 as usual, and they are also collected in a global list of the given name
1219 (:token:`TokIdentifier`).
1220
1221 The specified type must be ``list<``\ *class*\ ``>``, where *class* is some
1222 record class. The ``defset`` statement establishes a scope for its
1223 statements. It is an error to define a record in the scope of the
1224 ``defset`` that is not of type *class*.
1225
1226 The ``defset`` statement can be nested. The inner ``defset`` adds the
1227 records to its own set, and all those records are also added to the outer
1228 set.
1229
1230 Anonymous records created inside initialization expressions using the
1231 ``ClassID<...>`` syntax are not collected in the set.
1232
1233 ``deftype`` --- define a type
1234 --------------------------------
1235
1236 A ``deftype`` statement defines a type. The type can be used throughout the
1237 statements that follow the definition.
1238
1239 .. productionlist::
1240 Deftype: "deftype" `TokIdentifier` "=" `Type` ";"
1241
1242 The identifier on the left of the ``=`` is defined to be a type name
1243 whose actual type is given by the type expression on the right of the ``=``.
1244
1245 Currently, only primitive types and type aliases are supported to be the source
1246 type and `deftype` statements can only appear at the top level.
1247
1248 ``defvar`` --- define a variable
1249 --------------------------------
1250
1251 A ``defvar`` statement defines a global variable. Its value can be used
1252 throughout the statements that follow the definition.
1253
1254 .. productionlist::
1255 Defvar: "defvar" `TokIdentifier` "=" `Value` ";"
1256
1257 The identifier on the left of the ``=`` is defined to be a global variable
1258 whose value is given by the value expression on the right of the ``=``. The
1259 type of the variable is automatically inferred.
1260
1261 Once a variable has been defined, it cannot be set to another value.
1262
1263 Variables defined in a top-level ``foreach`` go out of scope at the end of
1264 each loop iteration, so their value in one iteration is not available in
1265 the next iteration. The following ``defvar`` will not work::
1266
1267 defvar i = !add(i, 1);
1268
1269 Variables can also be defined with ``defvar`` in a record body. See
1270 `Defvar in a Record Body`_ for more details.
1271
1272 ``foreach`` --- iterate over a sequence of statements
1273 -----------------------------------------------------
1274
1275 The ``foreach`` statement iterates over a series of statements, varying a
1276 variable over a sequence of values.
1277
1278 .. productionlist::
1279 Foreach: "foreach" `ForeachIterator` "in" "{" `Statement`* "}"
1280 :| "foreach" `ForeachIterator` "in" `Statement`
1281 ForeachIterator: `TokIdentifier` "=" ("{" `RangeList` "}" | `RangePiece` | `Value`)
1282
1283 The body of the ``foreach`` is a series of statements in braces or a
1284 single statement with no braces. The statements are re-evaluated once for
1285 each value in the range list, range piece, or single value. On each
1286 iteration, the :token:`TokIdentifier` variable is set to the value and can
1287 be used in the statements.
1288
1289 The statement list establishes an inner scope. Variables local to a
1290 ``foreach`` go out of scope at the end of each loop iteration, so their
1291 values do not carry over from one iteration to the next. Foreach loops may
1292 be nested.
1293
1294 .. Note that the productions involving RangeList and RangePiece have precedence
1295 over the more generic value parsing based on the first token.
1296
1297 .. code-block:: text
1298
1299 foreach i = [0, 1, 2, 3] in {
1300 def R#i : Register<...>;
1301 def F#i : Register<...>;
1302 }
1303
1304 This loop defines records named ``R0``, ``R1``, ``R2``, and ``R3``, along
1305 with ``F0``, ``F1``, ``F2``, and ``F3``.
1306
1307 ``dump`` --- print messages to stderr
1308 -------------------------------------
1309
1310 A ``dump`` statement prints the input string to standard error
1311 output. It is intended for debugging purposes.
1312
1313 * At top level, the message is printed immediately.
1314
1315 * Within a record/class/multiclass, `dump` gets evaluated at each
1316 instantiation point of the containing record.
1317
1318 .. productionlist::
1319 Dump: "dump" `Value` ";"
1320
1321 The :token:`Value` is an arbitrary string expression.
1322 For example, it can be used in combination with `!repr` to investigate
1323 the values passed to a multiclass:
1324
1325 .. code-block:: text
1326
1327 multiclass MC<dag s> {
1328 dump "s = " # !repr(s);
1329 }
1330
1331
1332 ``if`` --- select statements based on a test
1333 --------------------------------------------
1334
1335 The ``if`` statement allows one of two statement groups to be selected based
1336 on the value of an expression.
1337
1338 .. productionlist::
1339 If: "if" `Value` "then" `IfBody`
1340 :| "if" `Value` "then" `IfBody` "else" `IfBody`
1341 IfBody: "{" `Statement`* "}" | `Statement`
1342
1343 The value expression is evaluated. If it evaluates to true (in the same
1344 sense used by the bang operators), then the statements following the
1345 ``then`` reserved word are processed. Otherwise, if there is an ``else``
1346 reserved word, the statements following the ``else`` are processed. If the
1347 value is false and there is no ``else`` arm, no statements are processed.
1348
1349 Because the braces around the ``then`` statements are optional, this grammar rule
1350 has the usual ambiguity with "dangling else" clauses, and it is resolved in
1351 the usual way: in a case like ``if v1 then if v2 then {...} else {...}``, the
1352 ``else`` associates with the inner ``if`` rather than the outer one.
1353
1354 The :token:`IfBody` of the then and else arms of the ``if`` establish an
1355 inner scope. Any ``defvar`` variables defined in the bodies go out of scope
1356 when the bodies are finished (see `Defvar in a Record Body`_ for more details).
1357
1358 The ``if`` statement can also be used in a record :token:`Body`.
1359
1360
1361 ``assert`` --- check that a condition is true
1362 ---------------------------------------------
1363
1364 The ``assert`` statement checks a boolean condition to be sure that it is true
1365 and prints an error message if it is not.
1366
1367 .. productionlist::
1368 Assert: "assert" `Value` "," `Value` ";"
1369
1370 The first :token:`Value` is a boolean condition. If it is true, the
1371 statement does nothing. If the condition is false, it prints a nonfatal
1372 error message. The second :token:`Value` is a message, which can be an
1373 arbitrary string expression. It is included in the error message as a
1374 note. The exact behavior of the ``assert`` statement depends on its
1375 placement.
1376
1377 * At top level, the assertion is checked immediately.
1378
1379 * In a record definition, the statement is saved and all assertions are
1380 checked after the record is completely built.
1381
1382 * In a class definition, the assertions are saved and inherited by all
1383 the subclasses and records that inherit from the class. The assertions are
1384 then checked when the records are completely built.
1385
1386 * In a multiclass definition, the assertions are saved with the other
1387 components of the multiclass and then checked each time the multiclass
1388 is instantiated with ``defm``.
1389
1390 Using assertions in TableGen files can simplify record checking in TableGen
1391 backends. Here is an example of an ``assert`` in two class definitions.
1392
1393 .. code-block:: text
1394
1395 class PersonName<string name> {
1396 assert !le(!size(name), 32), "person name is too long: " # name;
1397 string Name = name;
1398 }
1399
1400 class Person<string name, int age> : PersonName<name> {
1401 assert !and(!ge(age, 1), !le(age, 120)), "person age is invalid: " # age;
1402 int Age = age;
1403 }
1404
1405 def Rec20 : Person<"Donald Knuth", 60> {
1406 ...
1407 }
1408
1409
1410 Additional Details
1411 ==================
1412
1413 Directed acyclic graphs (DAGs)
1414 ------------------------------
1415
1416 A directed acyclic graph can be represented directly in TableGen using the
1417 ``dag`` datatype. A DAG node consists of an operator and zero or more
1418 arguments (or operands). Each argument can be of any desired type. By using
1419 another DAG node as an argument, an arbitrary graph of DAG nodes can be
1420 built.
1421
1422 The syntax of a ``dag`` instance is:
1423
1424 ``(`` *operator* *argument1*\ ``,`` *argument2*\ ``,`` ... ``)``
1425
1426 The operator must be present and must be a record. There can be zero or more
1427 arguments, separated by commas. The operator and arguments can have three
1428 formats.
1429
1430 ====================== =============================================
1431 Format Meaning
1432 ====================== =============================================
1433 *value* argument value
1434 *value*\ ``:``\ *name* argument value and associated name
1435 *name* argument name with unset (uninitialized) value
1436 ====================== =============================================
1437
1438 The *value* can be any TableGen value. The *name*, if present, must be a
1439 :token:`TokVarName`, which starts with a dollar sign (``$``). The purpose of
1440 a name is to tag an operator or argument in a DAG with a particular meaning,
1441 or to associate an argument in one DAG with a like-named argument in another
1442 DAG.
1443
1444 The following bang operators are useful for working with DAGs:
1445 ``!con``, ``!dag``, ``!empty``, ``!foreach``, ``!getdagarg``, ``!getdagname``,
1446 ``!getdagop``, ``!getdagopname``, ``!setdagarg``, ``!setdagname``, ``!setdagop``,
1447 ``!setdagopname``, ``!size``.
1448
1449 Defvar in a record body
1450 -----------------------
1451
1452 In addition to defining global variables, the ``defvar`` statement can
1453 be used inside the :token:`Body` of a class or record definition to define
1454 local variables. Template arguments of ``class`` or ``multiclass`` can be
1455 used in the value expression. The scope of the variable extends from the
1456 ``defvar`` statement to the end of the body. It cannot be set to a different
1457 value within its scope. The ``defvar`` statement can also be used in the statement
1458 list of a ``foreach``, which establishes a scope.
1459
1460 A variable named ``V`` in an inner scope shadows (hides) any variables ``V``
1461 in outer scopes. In particular, there are several cases:
1462
1463 * ``V`` in a record body shadows a global ``V``.
1464
1465 * ``V`` in a record body shadows template argument ``V``.
1466
1467 * ``V`` in template arguments shadows a global ``V``.
1468
1469 * ``V`` in a ``foreach`` statement list shadows any ``V`` in surrounding record or
1470 global scopes.
1471
1472 Variables defined in a ``foreach`` go out of scope at the end of
1473 each loop iteration, so their value in one iteration is not available in
1474 the next iteration. The following ``defvar`` will not work::
1475
1476 defvar i = !add(i, 1)
1477
1478 How records are built
1479 ---------------------
1480
1481 The following steps are taken by TableGen when a record is built. Classes are simply
1482 abstract records and so go through the same steps.
1483
1484 1. Build the record name (:token:`NameValue`) and create an empty record.
1485
1486 2. Parse the parent classes in the :token:`ParentClassList` from left to
1487 right, visiting each parent class's ancestor classes from top to bottom.
1488
1489 a. Add the fields from the parent class to the record.
1490 b. Substitute the template arguments into those fields.
1491 c. Add the parent class to the record's list of inherited classes.
1492
1493 3. Apply any top-level ``let`` bindings to the record. Recall that top-level
1494 bindings only apply to inherited fields.
1495
1496 4. Parse the body of the record.
1497
1498 * Add any fields to the record.
1499 * Modify the values of fields according to local ``let`` statements.
1500 * Define any ``defvar`` variables.
1501
1502 5. Make a pass over all the fields to resolve any inter-field references.
1503
1504 6. Add the record to the final record list.
1505
1506 Because references between fields are resolved (step 5) after ``let`` bindings are
1507 applied (step 3), the ``let`` statement has unusual power. For example:
1508
1509 .. code-block:: text
1510
1511 class C <int x> {
1512 int Y = x;
1513 int Yplus1 = !add(Y, 1);
1514 int xplus1 = !add(x, 1);
1515 }
1516
1517 let Y = 10 in {
1518 def rec1 : C<5> {
1519 }
1520 }
1521
1522 def rec2 : C<5> {
1523 let Y = 10;
1524 }
1525
1526 In both cases, one where a top-level ``let`` is used to bind ``Y`` and one
1527 where a local ``let`` does the same thing, the results are:
1528
1529 .. code-block:: text
1530
1531 def rec1 { // C
1532 int Y = 10;
1533 int Yplus1 = 11;
1534 int xplus1 = 6;
1535 }
1536 def rec2 { // C
1537 int Y = 10;
1538 int Yplus1 = 11;
1539 int xplus1 = 6;
1540 }
1541
1542 ``Yplus1`` is 11 because the ``let Y`` is performed before the ``!add(Y,
1543 1)`` is resolved. Use this power wisely.
1544
1545
1546 Using Classes as Subroutines
1547 ============================
1548
1549 As described in `Simple values`_, a class can be invoked in an expression
1550 and passed template arguments. This causes TableGen to create a new anonymous
1551 record inheriting from that class. As usual, the record receives all the
1552 fields defined in the class.
1553
1554 This feature can be employed as a simple subroutine facility. The class can
1555 use the template arguments to define various variables and fields, which end
1556 up in the anonymous record. Those fields can then be retrieved in the
1557 expression invoking the class as follows. Assume that the field ``ret``
1558 contains the final value of the subroutine.
1559
1560 .. code-block:: text
1561
1562 int Result = ... CalcValue<arg>.ret ...;
1563
1564 The ``CalcValue`` class is invoked with the template argument ``arg``. It
1565 calculates a value for the ``ret`` field, which is then retrieved at the
1566 "point of call" in the initialization for the Result field. The anonymous
1567 record created in this example serves no other purpose than to carry the
1568 result value.
1569
1570 Here is a practical example. The class ``isValidSize`` determines whether a
1571 specified number of bytes represents a valid data size. The bit ``ret`` is
1572 set appropriately. The field ``ValidSize`` obtains its initial value by
1573 invoking ``isValidSize`` with the data size and retrieving the ``ret`` field
1574 from the resulting anonymous record.
1575
1576 .. code-block:: text
1577
1578 class isValidSize<int size> {
1579 bit ret = !cond(!eq(size, 1): 1,
1580 !eq(size, 2): 1,
1581 !eq(size, 4): 1,
1582 !eq(size, 8): 1,
1583 !eq(size, 16): 1,
1584 true: 0);
1585 }
1586
1587 def Data1 {
1588 int Size = ...;
1589 bit ValidSize = isValidSize<Size>.ret;
1590 }
1591
1592 Preprocessing Facilities
1593 ========================
1594
1595 The preprocessor embedded in TableGen is intended only for simple
1596 conditional compilation. It supports the following directives, which are
1597 specified somewhat informally.
1598
1599 .. productionlist::
1600 LineBegin: beginning of line
1601 LineEnd: newline | return | EOF
1602 WhiteSpace: space | tab
1603 CComment: "/*" ... "*/"
1604 BCPLComment: "//" ... `LineEnd`
1605 WhiteSpaceOrCComment: `WhiteSpace` | `CComment`
1606 WhiteSpaceOrAnyComment: `WhiteSpace` | `CComment` | `BCPLComment`
1607 MacroName: `ualpha` (`ualpha` | "0"..."9")*
1608 PreDefine: `LineBegin` (`WhiteSpaceOrCComment`)*
1609 : "#define" (`WhiteSpace`)+ `MacroName`
1610 : (`WhiteSpaceOrAnyComment`)* `LineEnd`
1611 PreIfdef: `LineBegin` (`WhiteSpaceOrCComment`)*
1612 : ("#ifdef" | "#ifndef") (`WhiteSpace`)+ `MacroName`
1613 : (`WhiteSpaceOrAnyComment`)* `LineEnd`
1614 PreElse: `LineBegin` (`WhiteSpaceOrCComment`)*
1615 : "#else" (`WhiteSpaceOrAnyComment`)* `LineEnd`
1616 PreEndif: `LineBegin` (`WhiteSpaceOrCComment`)*
1617 : "#endif" (`WhiteSpaceOrAnyComment`)* `LineEnd`
1618
1619 ..
1620 PreRegContentException: `PreIfdef` | `PreElse` | `PreEndif` | EOF
1621 PreRegion: .* - `PreRegContentException`
1622 :| `PreIfdef`
1623 : (`PreRegion`)*
1624 : [`PreElse`]
1625 : (`PreRegion`)*
1626 : `PreEndif`
1627
1628 A :token:`MacroName` can be defined anywhere in a TableGen file. The name has
1629 no value; it can only be tested to see whether it is defined.
1630
1631 A macro test region begins with an ``#ifdef`` or ``#ifndef`` directive. If
1632 the macro name is defined (``#ifdef``) or undefined (``#ifndef``), then the
1633 source code between the directive and the corresponding ``#else`` or
1634 ``#endif`` is processed. If the test fails but there is an ``#else``
1635 clause, the source code between the ``#else`` and the ``#endif`` is
1636 processed. If the test fails and there is no ``#else`` clause, then no
1637 source code in the test region is processed.
1638
1639 Test regions may be nested, but they must be properly nested. A region
1640 started in a file must end in that file; that is, must have its
1641 ``#endif`` in the same file.
1642
1643 A :token:`MacroName` may be defined externally using the ``-D`` option on the
1644 ``*-tblgen`` command line::
1645
1646 llvm-tblgen self-reference.td -Dmacro1 -Dmacro3
1647
1648 Appendix A: Bang Operators
1649 ==========================
1650
1651 Bang operators act as functions in value expressions. A bang operator takes
1652 one or more arguments, operates on them, and produces a result. If the
1653 operator produces a boolean result, the result value will be 1 for true or 0
1654 for false. When an operator tests a boolean argument, it interprets 0 as false
1655 and non-0 as true.
1656
1657 ``!add(``\ *a*\ ``,`` *b*\ ``, ...)``
1658 This operator adds *a*, *b*, etc., and produces the sum.
1659
1660 ``!and(``\ *a*\ ``,`` *b*\ ``, ...)``
1661 This operator does a bitwise AND on *a*, *b*, etc., and produces the
1662 result. A logical AND can be performed if all the arguments are either
1663 0 or 1. This operator is short-circuit to 0 when the left-most operand
1664 is 0.
1665
1666 ``!cast<``\ *type*\ ``>(``\ *a*\ ``)``
1667 This operator performs a cast on *a* and produces the result.
1668 If *a* is not a string, then a straightforward cast is performed, say
1669 between an ``int`` and a ``bit``, or between record types. This allows
1670 casting a record to a class. If a record is cast to ``string``, the
1671 record's name is produced.
1672
1673 If *a* is a string, then it is treated as a record name and looked up in
1674 the list of all defined records. The resulting record is expected to be of
1675 the specified *type*.
1676
1677 For example, if ``!cast<``\ *type*\ ``>(``\ *name*\ ``)``
1678 appears in a multiclass definition, or in a
1679 class instantiated inside a multiclass definition, and the *name* does not
1680 reference any template arguments of the multiclass, then a record by
1681 that name must have been instantiated earlier
1682 in the source file. If *name* does reference
1683 a template argument, then the lookup is delayed until ``defm`` statements
1684 instantiating the multiclass (or later, if the defm occurs in another
1685 multiclass and template arguments of the inner multiclass that are
1686 referenced by *name* are substituted by values that themselves contain
1687 references to template arguments of the outer multiclass).
1688
1689 If the type of *a* does not match *type*, TableGen raises an error.
1690
1691 ``!con(``\ *a*\ ``,`` *b*\ ``, ...)``
1692 This operator concatenates the DAG nodes *a*, *b*, etc. Their operations
1693 must equal.
1694
1695 ``!con((op:$lhs a1:$name1, a2:$name2), (op:$rhs b1:$name3))``
1696
1697 results in the DAG node ``(op:$lhs a1:$name1, a2:$name2, b1:$name3)``.
1698 The name of the dag operator is derived from the LHS DAG node if it is
1699 set, otherwise from the RHS DAG node.
1700
1701 ``!cond(``\ *cond1* ``:`` *val1*\ ``,`` *cond2* ``:`` *val2*\ ``, ...,`` *condn* ``:`` *valn*\ ``)``
1702 This operator tests *cond1* and returns *val1* if the result is true.
1703 If false, the operator tests *cond2* and returns *val2* if the result is
1704 true. And so forth. An error is reported if no conditions are true.
1705
1706 This example produces the sign word for an integer::
1707
1708 !cond(!lt(x, 0) : "negative", !eq(x, 0) : "zero", true : "positive")
1709
1710 ``!dag(``\ *op*\ ``,`` *arguments*\ ``,`` *names*\ ``)``
1711 This operator creates a DAG node with the given operator and
1712 arguments. The *arguments* and *names* arguments must be lists
1713 of equal length or uninitialized (``?``). The *names* argument
1714 must be of type ``list<string>``.
1715
1716 Due to limitations of the type system, *arguments* must be a list of items
1717 of a common type. In practice, this means that they should either have the
1718 same type or be records with a common parent class. Mixing ``dag`` and
1719 non-``dag`` items is not possible. However, ``?`` can be used.
1720
1721 Example: ``!dag(op, [a1, a2, ?], ["name1", "name2", "name3"])`` results in
1722 ``(op a1-value:$name1, a2-value:$name2, ?:$name3)``.
1723
1724 ``!div(``\ *a*\ ``,`` *b*\ ``)``
1725 This operator performs signed division of *a* by *b*, and produces the quotient.
1726 Division by 0 produces an error. Division of ``INT64_MIN`` by -1 produces an error.
1727
1728 ``!empty(``\ *a*\ ``)``
1729 This operator produces 1 if the string, list, or DAG *a* is empty; 0 otherwise.
1730 A dag is empty if it has no arguments; the operator does not count.
1731
1732 ``!eq(`` *a*\ `,` *b*\ ``)``
1733 This operator produces 1 if *a* is equal to *b*; 0 otherwise.
1734 The arguments must be ``bit``, ``bits``, ``int``, ``string``, or
1735 record values. Use ``!cast<string>`` to compare other types of objects.
1736
1737 ``!exists<``\ *type*\ ``>(``\ *name*\ ``)``
1738 This operator produces 1 if a record of the given *type* whose name is *name*
1739 exists; 0 otherwise. *name* should be of type *string*.
1740
1741 ``!filter(``\ *var*\ ``,`` *list*\ ``,`` *predicate*\ ``)``
1742
1743 This operator creates a new ``list`` by filtering the elements in
1744 *list*. To perform the filtering, TableGen binds the variable *var* to each
1745 element and then evaluates the *predicate* expression, which presumably
1746 refers to *var*. The predicate must
1747 produce a boolean value (``bit``, ``bits``, or ``int``). The value is
1748 interpreted as with ``!if``:
1749 if the value is 0, the element is not included in the new list. If the value
1750 is anything else, the element is included.
1751
1752 ``!find(``\ *string1*\ ``,`` *string2*\ [``,`` *start*]\ ``)``
1753 This operator searches for *string2* in *string1* and produces its
1754 position. The starting position of the search may be specified by *start*,
1755 which can range between 0 and the length of *string1*; the default is 0.
1756 If the string is not found, the result is -1.
1757
1758 ``!foldl(``\ *init*\ ``,`` *list*\ ``,`` *acc*\ ``,`` *var*\ ``,`` *expr*\ ``)``
1759 This operator performs a left-fold over the items in *list*. The
1760 variable *acc* acts as the accumulator and is initialized to *init*.
1761 The variable *var* is bound to each element in the *list*. The
1762 expression is evaluated for each element and presumably uses *acc* and
1763 *var* to calculate the accumulated value, which ``!foldl`` stores back in
1764 *acc*. The type of *acc* is the same as *init*; the type of *var* is the
1765 same as the elements of *list*; *expr* must have the same type as *init*.
1766
1767 The following example computes the total of the ``Number`` field in the
1768 list of records in ``RecList``::
1769
1770 int x = !foldl(0, RecList, total, rec, !add(total, rec.Number));
1771
1772 If your goal is to filter the list and produce a new list that includes only
1773 some of the elements, see ``!filter``.
1774
1775 ``!foreach(``\ *var*\ ``,`` *sequence*\ ``,`` *expr*\ ``)``
1776 This operator creates a new ``list``/``dag`` in which each element is a
1777 function of the corresponding element in the *sequence* ``list``/``dag``.
1778 To perform the function, TableGen binds the variable *var* to an element
1779 and then evaluates the expression. The expression presumably refers
1780 to the variable *var* and calculates the result value.
1781
1782 If you simply want to create a list of a certain length containing
1783 the same value repeated multiple times, see ``!listsplat``.
1784
1785 ``!ge(``\ *a*\ `,` *b*\ ``)``
1786 This operator produces 1 if *a* is greater than or equal to *b*; 0 otherwise.
1787 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
1788
1789 ``!getdagarg<``\ *type*\ ``>(``\ *dag*\ ``,``\ *key*\ ``)``
1790 This operator retrieves the argument from the given *dag* node by the
1791 specified *key*, which is either an integer index or a string name. If that
1792 argument is not convertible to the specified *type*, ``?`` is returned.
1793
1794 ``!getdagname(``\ *dag*\ ``,``\ *index*\ ``)``
1795 This operator retrieves the argument name from the given *dag* node by the
1796 specified *index*. If that argument has no name associated, ``?`` is
1797 returned.
1798
1799 ``!getdagop(``\ *dag*\ ``)`` --or-- ``!getdagop<``\ *type*\ ``>(``\ *dag*\ ``)``
1800 This operator produces the operator of the given *dag* node.
1801 Example: ``!getdagop((foo 1, 2))`` results in ``foo``. Recall that
1802 DAG operators are always records.
1803
1804 The result of ``!getdagop`` can be used directly in a context where
1805 any record class at all is acceptable (typically placing it into
1806 another dag value). But in other contexts, it must be explicitly
1807 cast to a particular class. The ``<``\ *type*\ ``>`` syntax is
1808 provided to make this easy.
1809
1810 For example, to assign the result to a value of type ``BaseClass``, you
1811 could write either of these::
1812
1813 BaseClass b = !getdagop<BaseClass>(someDag);
1814 BaseClass b = !cast<BaseClass>(!getdagop(someDag));
1815
1816 But to create a new DAG node that reuses the operator from another, no
1817 cast is necessary::
1818
1819 dag d = !dag(!getdagop(someDag), args, names);
1820
1821 ``!getdagopname(``\ *dag*\ ``)``
1822 This operator retrieves the name of the given *dag* operator. If the operator
1823 has no name associated, ``?`` is returned.
1824
1825 ``!gt(``\ *a*\ `,` *b*\ ``)``
1826 This operator produces 1 if *a* is greater than *b*; 0 otherwise.
1827 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
1828
1829 ``!head(``\ *a*\ ``)``
1830 This operator produces the zeroth element of the list *a*.
1831 (See also ``!tail``.)
1832
1833 ``!if(``\ *test*\ ``,`` *then*\ ``,`` *else*\ ``)``
1834 This operator evaluates the *test*, which must produce a ``bit`` or
1835 ``int``. If the result is not 0, the *then* expression is produced; otherwise
1836 the *else* expression is produced.
1837
1838 ``!initialized(``\ *a*\ ``)``
1839 This operator produces 1 if *a* is not the uninitialized value (``?``) and 0
1840 otherwise.
1841
1842 ``!instances<``\ *type*\ ``>([``\ *regex*\ ``])``
1843 This operator produces a list of records whose type is *type*. If *regex*
1844 is provided, only records whose name matches the regular expression *regex*
1845 will be included. The format of *regex* is ERE (Extended POSIX Regular
1846 Expressions).
1847
1848 If ``!instances`` is in a class/multiclass/foreach, only these records of
1849 *type* that have been instantiated will be considered.
1850
1851 ``!interleave(``\ *list*\ ``,`` *delim*\ ``)``
1852 This operator concatenates the items in the *list*, interleaving the
1853 *delim* string between each pair, and produces the resulting string.
1854 The list can be a list of string, int, bits, or bit. An empty list
1855 results in an empty string. The delimiter can be the empty string.
1856
1857 ``!isa<``\ *type*\ ``>(``\ *a*\ ``)``
1858 This operator produces 1 if the type of *a* is a subtype of the given *type*; 0
1859 otherwise.
1860
1861 ``!le(``\ *a*\ ``,`` *b*\ ``)``
1862 This operator produces 1 if *a* is less than or equal to *b*; 0 otherwise.
1863 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
1864
1865 ``!listconcat(``\ *list1*\ ``,`` *list2*\ ``, ...)``
1866 This operator concatenates the list arguments *list1*, *list2*, etc., and
1867 produces the resulting list. The lists must have the same element type.
1868
1869 ``!listflatten(``\ *list*\ ``)``
1870 This operator flattens a list of lists *list* and produces a list with all
1871 elements of the constituent lists concatenated. If *list* is of type
1872 ``list<list<X>>`` the resulting list is of type ``list<X>``. If *list*'s
1873 element type is not a list, the result is *list* itself.
1874
1875 ``!listremove(``\ *list1*\ ``,`` *list2*\ ``)``
1876 This operator returns a copy of *list1* removing all elements that also occur in
1877 *list2*. The lists must have the same element type.
1878
1879 ``!listsplat(``\ *value*\ ``,`` *count*\ ``)``
1880 This operator produces a list of length *count* whose elements are all
1881 equal to the *value*. For example, ``!listsplat(42, 3)`` results in
1882 ``[42, 42, 42]``.
1883
1884 ``!logtwo(``\ *a*\ ``)``
1885 This operator produces the base 2 log of *a* and produces the integer
1886 result. The log of 0 or a negative number produces an error. This
1887 is a flooring operation.
1888
1889 ``!lt(``\ *a*\ `,` *b*\ ``)``
1890 This operator produces 1 if *a* is less than *b*; 0 otherwise.
1891 The arguments must be ``bit``, ``bits``, ``int``, or ``string`` values.
1892
1893 ``!match(``\ *str*\ `,` *regex*\ ``)``
1894 This operator produces 1 if the *str* matches the regular expression
1895 *regex*. The format of *regex* is ERE (Extended POSIX Regular Expressions).
1896
1897 ``!mul(``\ *a*\ ``,`` *b*\ ``, ...)``
1898 This operator multiplies *a*, *b*, etc., and produces the product.
1899
1900 ``!ne(``\ *a*\ `,` *b*\ ``)``
1901 This operator produces 1 if *a* is not equal to *b*; 0 otherwise.
1902 The arguments must be ``bit``, ``bits``, ``int``, ``string``,
1903 or record values. Use ``!cast<string>`` to compare other types of objects.
1904
1905 ``!not(``\ *a*\ ``)``
1906 This operator performs a logical NOT on *a*, which must be
1907 an integer. The argument 0 results in 1 (true); any other
1908 argument results in 0 (false).
1909
1910 ``!or(``\ *a*\ ``,`` *b*\ ``, ...)``
1911 This operator does a bitwise OR on *a*, *b*, etc., and produces the
1912 result. A logical OR can be performed if all the arguments are either
1913 0 or 1. This operator is short-circuit to -1 (all ones) when the left-most
1914 operand is -1.
1915
1916 ``!range([``\ *start*\ ``,]`` *end*\ ``[,``\ *step*\ ``])``
1917 This operator produces half-open range sequence ``[start : end : step)`` as
1918 ``list<int>``. *start* is ``0`` and *step* is ``1`` by default. *step* can
1919 be negative and cannot be 0. If *start* ``<`` *end* and *step* is negative,
1920 or *start* ``>`` *end* and *step* is positive, the result is an empty list
1921 ``[]<int>``.
1922
1923 For example:
1924
1925 * ``!range(4)`` is equivalent to ``!range(0, 4, 1)`` and the result is
1926 `[0, 1, 2, 3]`.
1927 * ``!range(1, 4)`` is equivalent to ``!range(1, 4, 1)`` and the result is
1928 `[1, 2, 3]`.
1929 * The result of ``!range(0, 4, 2)`` is `[0, 2]`.
1930 * The results of ``!range(0, 4, -1)`` and ``!range(4, 0, 1)`` are empty.
1931
1932 ``!range(``\ *list*\ ``)``
1933 Equivalent to ``!range(0, !size(list))``.
1934
1935 ``!repr(``\ *value*\ ``)``
1936 Represents *value* as a string. The string format for the value is not
1937 guaranteed to be stable. Intended for debugging purposes only.
1938
1939 ``!setdagarg(``\ *dag*\ ``,``\ *key*\ ``,``\ *arg*\ ``)``
1940 This operator produces a DAG node with the same operator and arguments as
1941 *dag*, but replacing the value of the argument specified by the *key* with
1942 *arg*. That *key* could be either an integer index or a string name.
1943
1944 ``!setdagname(``\ *dag*\ ``,``\ *key*\ ``,``\ *name*\ ``)``
1945 This operator produces a DAG node with the same operator and arguments as
1946 *dag*, but replacing the name of the argument specified by the *key* with
1947 *name*. That *key* could be either an integer index or a string name.
1948
1949 ``!setdagop(``\ *dag*\ ``,`` *op*\ ``)``
1950 This operator produces a DAG node with the same arguments as *dag*, but with its
1951 operator replaced with *op*.
1952
1953 Example: ``!setdagop((foo 1, 2), bar)`` results in ``(bar 1, 2)``.
1954
1955 ``!setdagopname(``\ *dag*\ ``,``\ *name*\ ``)``
1956 This operator produces a DAG node with the same operator and arguments as
1957 *dag*, but replacing the name of the operator with *name*.
1958
1959 ``!shl(``\ *a*\ ``,`` *count*\ ``)``
1960 This operator shifts *a* left logically by *count* bits and produces the resulting
1961 value. The operation is performed on a 64-bit integer; the result
1962 is undefined for shift counts outside 0...63.
1963
1964 ``!size(``\ *a*\ ``)``
1965 This operator produces the size of the string, list, or dag *a*.
1966 The size of a DAG is the number of arguments; the operator does not count.
1967
1968 ``!sra(``\ *a*\ ``,`` *count*\ ``)``
1969 This operator shifts *a* right arithmetically by *count* bits and produces the resulting
1970 value. The operation is performed on a 64-bit integer; the result
1971 is undefined for shift counts outside 0...63.
1972
1973 ``!srl(``\ *a*\ ``,`` *count*\ ``)``
1974 This operator shifts *a* right logically by *count* bits and produces the resulting
1975 value. The operation is performed on a 64-bit integer; the result
1976 is undefined for shift counts outside 0...63.
1977
1978 ``!strconcat(``\ *str1*\ ``,`` *str2*\ ``, ...)``
1979 This operator concatenates the string arguments *str1*, *str2*, etc., and
1980 produces the resulting string.
1981
1982 ``!sub(``\ *a*\ ``,`` *b*\ ``)``
1983 This operator subtracts *b* from *a* and produces the arithmetic difference.
1984
1985 ``!subst(``\ *target*\ ``,`` *repl*\ ``,`` *value*\ ``)``
1986 This operator replaces all occurrences of the *target* in the *value* with
1987 the *repl* and produces the resulting value. The *value* can
1988 be a string, in which case substring substitution is performed.
1989
1990 The *value* can be a record name, in which case the operator produces the *repl*
1991 record if the *target* record name equals the *value* record name; otherwise it
1992 produces the *value*.
1993
1994 ``!substr(``\ *string*\ ``,`` *start*\ [``,`` *length*]\ ``)``
1995 This operator extracts a substring of the given *string*. The starting
1996 position of the substring is specified by *start*, which can range
1997 between 0 and the length of the string. The length of the substring
1998 is specified by *length*; if not specified, the rest of the string is
1999 extracted. The *start* and *length* arguments must be integers.
2000
2001 ``!tail(``\ *a*\ ``)``
2002 This operator produces a new list with all the elements
2003 of the list *a* except for the zeroth one. (See also ``!head``.)
2004
2005 ``!tolower(``\ *a*\ ``)``
2006 This operator converts a string input *a* to lower case.
2007
2008 ``!toupper(``\ *a*\ ``)``
2009 This operator converts a string input *a* to upper case.
2010
2011 ``!xor(``\ *a*\ ``,`` *b*\ ``, ...)``
2012 This operator does a bitwise EXCLUSIVE OR on *a*, *b*, etc., and produces
2013 the result. A logical XOR can be performed if all the arguments are either
2014 0 or 1.
2015
2016 Appendix B: Paste Operator Examples
2017 ===================================
2018
2019 Here is an example illustrating the use of the paste operator in record names.
2020
2021 .. code-block:: text
2022
2023 defvar suffix = "_suffstring";
2024 defvar some_ints = [0, 1, 2, 3];
2025
2026 def name # suffix {
2027 }
2028
2029 foreach i = [1, 2] in {
2030 def rec # i {
2031 }
2032 }
2033
2034 The first ``def`` does not use the value of the ``suffix`` variable. The
2035 second def does use the value of the ``i`` iterator variable, because it is not a
2036 global name. The following records are produced.
2037
2038 .. code-block:: text
2039
2040 def namesuffix {
2041 }
2042 def rec1 {
2043 }
2044 def rec2 {
2045 }
2046
2047 Here is a second example illustrating the paste operator in field value expressions.
2048
2049 .. code-block:: text
2050
2051 def test {
2052 string strings = suffix # suffix;
2053 list<int> integers = some_ints # [4, 5, 6];
2054 }
2055
2056 The ``strings`` field expression uses ``suffix`` on both sides of the paste
2057 operator. It is evaluated normally on the left hand side, but taken verbatim
2058 on the right hand side. The ``integers`` field expression uses the value of
2059 the ``some_ints`` variable and a literal list. The following record is
2060 produced.
2061
2062 .. code-block:: text
2063
2064 def test {
2065 string strings = "_suffstringsuffix";
2066 list<int> ints = [0, 1, 2, 3, 4, 5, 6];
2067 }
2068
2069
2070 Appendix C: Sample Record
2071 =========================
2072
2073 One target machine supported by LLVM is the Intel x86. The following output
2074 from TableGen shows the record that is created to represent the 32-bit
2075 register-to-register ADD instruction.
2076
2077 .. code-block:: text
2078
2079 def ADD32rr { // InstructionEncoding Instruction X86Inst I ITy Sched BinOpRR BinOpRR_RF
2080 int Size = 0;
2081 string DecoderNamespace = "";
2082 list<Predicate> Predicates = [];
2083 string DecoderMethod = "";
2084 bit hasCompleteDecoder = 1;
2085 string Namespace = "X86";
2086 dag OutOperandList = (outs GR32:$dst);
2087 dag InOperandList = (ins GR32:$src1, GR32:$src2);
2088 string AsmString = "add{l} {$src2, $src1|$src1, $src2}";
2089 EncodingByHwMode EncodingInfos = ?;
2090 list<dag> Pattern = [(set GR32:$dst, EFLAGS, (X86add_flag GR32:$src1, GR32:$src2))];
2091 list<Register> Uses = [];
2092 list<Register> Defs = [EFLAGS];
2093 int CodeSize = 3;
2094 int AddedComplexity = 0;
2095 bit isPreISelOpcode = 0;
2096 bit isReturn = 0;
2097 bit isBranch = 0;
2098 bit isEHScopeReturn = 0;
2099 bit isIndirectBranch = 0;
2100 bit isCompare = 0;
2101 bit isMoveImm = 0;
2102 bit isMoveReg = 0;
2103 bit isBitcast = 0;
2104 bit isSelect = 0;
2105 bit isBarrier = 0;
2106 bit isCall = 0;
2107 bit isAdd = 0;
2108 bit isTrap = 0;
2109 bit canFoldAsLoad = 0;
2110 bit mayLoad = ?;
2111 bit mayStore = ?;
2112 bit mayRaiseFPException = 0;
2113 bit isConvertibleToThreeAddress = 1;
2114 bit isCommutable = 1;
2115 bit isTerminator = 0;
2116 bit isReMaterializable = 0;
2117 bit isPredicable = 0;
2118 bit isUnpredicable = 0;
2119 bit hasDelaySlot = 0;
2120 bit usesCustomInserter = 0;
2121 bit hasPostISelHook = 0;
2122 bit hasCtrlDep = 0;
2123 bit isNotDuplicable = 0;
2124 bit isConvergent = 0;
2125 bit isAuthenticated = 0;
2126 bit isAsCheapAsAMove = 0;
2127 bit hasExtraSrcRegAllocReq = 0;
2128 bit hasExtraDefRegAllocReq = 0;
2129 bit isRegSequence = 0;
2130 bit isPseudo = 0;
2131 bit isExtractSubreg = 0;
2132 bit isInsertSubreg = 0;
2133 bit variadicOpsAreDefs = 0;
2134 bit hasSideEffects = ?;
2135 bit isCodeGenOnly = 0;
2136 bit isAsmParserOnly = 0;
2137 bit hasNoSchedulingInfo = 0;
2138 InstrItinClass Itinerary = NoItinerary;
2139 list<SchedReadWrite> SchedRW = [WriteALU];
2140 string Constraints = "$src1 = $dst";
2141 string DisableEncoding = "";
2142 string PostEncoderMethod = "";
2143 bits<64> TSFlags = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 1, 0, 1, 0, 0, 0 };
2144 string AsmMatchConverter = "";
2145 string TwoOperandAliasConstraint = "";
2146 string AsmVariantName = "";
2147 bit UseNamedOperandTable = 0;
2148 bit FastISelShouldIgnore = 0;
2149 bits<8> Opcode = { 0, 0, 0, 0, 0, 0, 0, 1 };
2150 Format Form = MRMDestReg;
2151 bits<7> FormBits = { 0, 1, 0, 1, 0, 0, 0 };
2152 ImmType ImmT = NoImm;
2153 bit ForceDisassemble = 0;
2154 OperandSize OpSize = OpSize32;
2155 bits<2> OpSizeBits = { 1, 0 };
2156 AddressSize AdSize = AdSizeX;
2157 bits<2> AdSizeBits = { 0, 0 };
2158 Prefix OpPrefix = NoPrfx;
2159 bits<3> OpPrefixBits = { 0, 0, 0 };
2160 Map OpMap = OB;
2161 bits<3> OpMapBits = { 0, 0, 0 };
2162 bit hasREX_WPrefix = 0;
2163 FPFormat FPForm = NotFP;
2164 bit hasLockPrefix = 0;
2165 Domain ExeDomain = GenericDomain;
2166 bit hasREPPrefix = 0;
2167 Encoding OpEnc = EncNormal;
2168 bits<2> OpEncBits = { 0, 0 };
2169 bit HasVEX_W = 0;
2170 bit IgnoresVEX_W = 0;
2171 bit EVEX_W1_VEX_W0 = 0;
2172 bit hasVEX_4V = 0;
2173 bit hasVEX_L = 0;
2174 bit ignoresVEX_L = 0;
2175 bit hasEVEX_K = 0;
2176 bit hasEVEX_Z = 0;
2177 bit hasEVEX_L2 = 0;
2178 bit hasEVEX_B = 0;
2179 bits<3> CD8_Form = { 0, 0, 0 };
2180 int CD8_EltSize = 0;
2181 bit hasEVEX_RC = 0;
2182 bit hasNoTrackPrefix = 0;
2183 bits<7> VectSize = { 0, 0, 1, 0, 0, 0, 0 };
2184 bits<7> CD8_Scale = { 0, 0, 0, 0, 0, 0, 0 };
2185 string FoldGenRegForm = ?;
2186 string EVEX2VEXOverride = ?;
2187 bit isMemoryFoldable = 1;
2188 bit notEVEX2VEXConvertible = 0;
2189 }
2190
2191 On the first line of the record, you can see that the ``ADD32rr`` record
2192 inherited from eight classes. Although the inheritance hierarchy is complex,
2193 using parent classes is much simpler than specifying the 109 individual
2194 fields for each instruction.
2195
2196 Here is the code fragment used to define ``ADD32rr`` and multiple other
2197 ``ADD`` instructions:
2198
2199 .. code-block:: text
2200
2201 defm ADD : ArithBinOp_RF<0x00, 0x02, 0x04, "add", MRM0r, MRM0m,
2202 X86add_flag, add, 1, 1, 1>;
2203
2204 The ``defm`` statement tells TableGen that ``ArithBinOp_RF`` is a
2205 multiclass, which contains multiple concrete record definitions that inherit
2206 from ``BinOpRR_RF``. That class, in turn, inherits from ``BinOpRR``, which
2207 inherits from ``ITy`` and ``Sched``, and so forth. The fields are inherited
2208 from all the parent classes; for example, ``IsIndirectBranch`` is inherited
2209 from the ``Instruction`` class.