| 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. |