| 1 |
=================================== |
| 2 |
TableGen Backend Developer's Guide |
| 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 an output file. These output files are typically ``.inc`` files |
| 20 |
for C++, but they may be any type of file that the backend developer needs. |
| 21 |
|
| 22 |
This document is a guide to writing a backend for TableGen. It is not a |
| 23 |
complete reference manual, but rather a guide to using the facilities |
| 24 |
provided by TableGen for the backends. For a complete reference to the |
| 25 |
various data structures and functions involved, see the primary TableGen |
| 26 |
header file (``record.h``) and/or the Doxygen documentation. |
| 27 |
|
| 28 |
This document assumes that you have read the :doc:`TableGen Programmer's |
| 29 |
Reference <./ProgRef>`, which provides a detailed reference for coding |
| 30 |
TableGen source files. For a description of the existing backends, see |
| 31 |
:doc:`TableGen BackEnds <./BackEnds>`. |
| 32 |
|
| 33 |
Data Structures |
| 34 |
=============== |
| 35 |
|
| 36 |
The following sections describe the data structures that contain the classes |
| 37 |
and records that are collected from the TableGen source files by the |
| 38 |
TableGen parser. Note that the term *class* refers to an abstract record |
| 39 |
class, while the term *record* refers to a concrete record. |
| 40 |
|
| 41 |
Unless otherwise noted, functions associated with classes are instance |
| 42 |
functions. |
| 43 |
|
| 44 |
``RecordKeeper`` |
| 45 |
---------------- |
| 46 |
|
| 47 |
An instance of the ``RecordKeeper`` class acts as the container for all the |
| 48 |
classes and records parsed and collected by TableGen. The ``RecordKeeper`` |
| 49 |
instance is passed to the backend when it is invoked by TableGen. This class |
| 50 |
is usually abbreviated ``RK``. |
| 51 |
|
| 52 |
There are two maps in the recordkeeper, one for classes and one for records |
| 53 |
(the latter often referred to as *defs*). Each map maps the class or record |
| 54 |
name to an instance of the ``Record`` class (see `Record`_), which contains |
| 55 |
all the information about that class or record. |
| 56 |
|
| 57 |
In addition to the two maps, the ``RecordKeeper`` instance contains: |
| 58 |
|
| 59 |
* A map that maps the names of global variables to their values. |
| 60 |
Global variables are defined in TableGen files with outer |
| 61 |
``defvar`` statements. |
| 62 |
|
| 63 |
* A counter for naming anonymous records. |
| 64 |
|
| 65 |
The ``RecordKeeper`` class provides a few useful functions. |
| 66 |
|
| 67 |
* Functions to get the complete class and record maps. |
| 68 |
|
| 69 |
* Functions to get a subset of the records based on their parent classes. |
| 70 |
|
| 71 |
* Functions to get individual classes, records, and globals, by name. |
| 72 |
|
| 73 |
A ``RecordKeeper`` instance can be printed to an output stream with the ``<<`` |
| 74 |
operator. |
| 75 |
|
| 76 |
``Record`` |
| 77 |
---------- |
| 78 |
|
| 79 |
Each class or record built by TableGen is represented by an instance of |
| 80 |
the ``Record`` class. The ``RecordKeeper`` instance contains one map for the |
| 81 |
classes and one for the records. The primary data members of a record are |
| 82 |
the record name, the vector of field names and their values, and the vector of |
| 83 |
superclasses of the record. |
| 84 |
|
| 85 |
The record name is stored as a pointer to an ``Init`` (see `Init`_), which |
| 86 |
is a class whose instances hold TableGen values (sometimes referred to as |
| 87 |
*initializers*). The field names and values are stored in a vector of |
| 88 |
``RecordVal`` instances (see `RecordVal`_), each of which contains both the |
| 89 |
field name and its value. The superclass vector contains a sequence of |
| 90 |
pairs, with each pair including the superclass record and its source |
| 91 |
file location. |
| 92 |
|
| 93 |
In addition to those members, a ``Record`` instance contains: |
| 94 |
|
| 95 |
* A vector of source file locations that includes the record definition |
| 96 |
itself, plus the locations of any multiclasses involved in its definition. |
| 97 |
|
| 98 |
* For a class record, a vector of the class's template arguments. |
| 99 |
|
| 100 |
* An instance of ``DefInit`` (see `DefInit`_) corresponding to this record. |
| 101 |
|
| 102 |
* A unique record ID. |
| 103 |
|
| 104 |
* A boolean that specifies whether this is a class definition. |
| 105 |
|
| 106 |
* A boolean that specifies whether this is an anonymous record. |
| 107 |
|
| 108 |
The ``Record`` class provides many useful functions. |
| 109 |
|
| 110 |
* Functions to get the record name, fields, source file locations, |
| 111 |
template arguments, and unique ID. |
| 112 |
|
| 113 |
* Functions to get all the record's superclasses or just its direct |
| 114 |
superclasses. |
| 115 |
|
| 116 |
* Functions to get a particular field value by specifying its name in various |
| 117 |
forms and returning its value in various forms |
| 118 |
(see `Getting Record Names and Fields`_). |
| 119 |
|
| 120 |
* Boolean functions to check the various attributes of the record. |
| 121 |
|
| 122 |
A ``Record`` instance can be printed to an output stream with the ``<<`` |
| 123 |
operator. |
| 124 |
|
| 125 |
|
| 126 |
``RecordVal`` |
| 127 |
------------- |
| 128 |
|
| 129 |
Each field of a record is stored in an instance of the ``RecordVal`` class. |
| 130 |
The ``Record`` instance includes a vector of these value instances. A |
| 131 |
``RecordVal`` instance contains the name of the field, stored in an ``Init`` |
| 132 |
instance. It also contains the value of the field, likewise stored in an |
| 133 |
``Init``. (A better name for this class might be ``RecordField``.) |
| 134 |
|
| 135 |
In addition to those primary members, the ``RecordVal`` has other data members. |
| 136 |
|
| 137 |
* The source file location of the field definition. |
| 138 |
|
| 139 |
* The type of the field, stored as an instance |
| 140 |
of the ``RecTy`` class (see `RecTy`_). |
| 141 |
|
| 142 |
The ``RecordVal`` class provides some useful functions. |
| 143 |
|
| 144 |
* Functions to get the name of the field in various forms. |
| 145 |
|
| 146 |
* A function to get the type of the field. |
| 147 |
|
| 148 |
* A function to get the value of the field. |
| 149 |
|
| 150 |
* A function to get the source file location. |
| 151 |
|
| 152 |
Note that field values are more easily obtained directly from the ``Record`` |
| 153 |
instance (see `Record`_). |
| 154 |
|
| 155 |
A ``RecordVal`` instance can be printed to an output stream with the ``<<`` |
| 156 |
operator. |
| 157 |
|
| 158 |
``RecTy`` |
| 159 |
--------- |
| 160 |
|
| 161 |
The ``RecTy`` class is used to represent the types of field values. It is |
| 162 |
the base class for a series of subclasses, one for each of the |
| 163 |
available field types. The ``RecTy`` class has one data member that is an |
| 164 |
enumerated type specifying the specific type of field value. (A better |
| 165 |
name for this class might be ``FieldTy``.) |
| 166 |
|
| 167 |
The ``RecTy`` class provides a few useful functions. |
| 168 |
|
| 169 |
* A virtual function to get the type name as a string. |
| 170 |
|
| 171 |
* A virtual function to check whether all the values of this type can |
| 172 |
be converted to another given type. |
| 173 |
|
| 174 |
* A virtual function to check whether this type is a subtype of |
| 175 |
another given type. |
| 176 |
|
| 177 |
* A function to get the corresponding ``list`` |
| 178 |
type for lists with elements of this type. For example, the function |
| 179 |
returns the ``list<int>`` type when called with the ``int`` type. |
| 180 |
|
| 181 |
The subclasses that inherit from ``RecTy`` are |
| 182 |
``BitRecTy``, |
| 183 |
``BitsRecTy``, |
| 184 |
``CodeRecTy``, |
| 185 |
``DagRecTy``, |
| 186 |
``IntRecTy``, |
| 187 |
``ListRecTy``, |
| 188 |
``RecordRecTy``, and |
| 189 |
``StringRecTy``. |
| 190 |
Some of these classes have additional members that |
| 191 |
are described in the following subsections. |
| 192 |
|
| 193 |
*All* of the classes derived from ``RecTy`` provide the ``get()`` function. |
| 194 |
It returns an instance of ``RecTy`` corresponding to the derived class. |
| 195 |
Some of the ``get()`` functions require an argument to |
| 196 |
specify which particular variant of the type is desired. These arguments are |
| 197 |
described in the following subsections. |
| 198 |
|
| 199 |
A ``RecTy`` instance can be printed to an output stream with the ``<<`` |
| 200 |
operator. |
| 201 |
|
| 202 |
.. warning:: |
| 203 |
It is not specified whether there is a single ``RecTy`` instance of a |
| 204 |
particular type or multiple instances. |
| 205 |
|
| 206 |
|
| 207 |
``BitsRecTy`` |
| 208 |
~~~~~~~~~~~~~ |
| 209 |
|
| 210 |
This class includes a data member with the size of the ``bits`` value and a |
| 211 |
function to get that size. |
| 212 |
|
| 213 |
The ``get()`` function takes the length of the sequence, *n*, and returns the |
| 214 |
``BitsRecTy`` type corresponding to ``bits<``\ *n*\ ``>``. |
| 215 |
|
| 216 |
``ListRecTy`` |
| 217 |
~~~~~~~~~~~~~ |
| 218 |
|
| 219 |
This class includes a data member that specifies the type of the list's |
| 220 |
elements and a function to get that type. |
| 221 |
|
| 222 |
The ``get()`` function takes the ``RecTy`` *type* of the list members and |
| 223 |
returns the ``ListRecTy`` type corresponding to ``list<``\ *type*\ ``>``. |
| 224 |
|
| 225 |
|
| 226 |
``RecordRecTy`` |
| 227 |
~~~~~~~~~~~~~~~ |
| 228 |
|
| 229 |
This class includes data members that contain the list of parent classes of |
| 230 |
this record. It also provides a function to obtain the array of classes and |
| 231 |
two functions to get the iterator ``begin()`` and ``end()`` values. The |
| 232 |
class defines a type for the return values of the latter two functions. |
| 233 |
|
| 234 |
.. code-block:: text |
| 235 |
|
| 236 |
using const_record_iterator = Record * const *; |
| 237 |
|
| 238 |
The ``get()`` function takes an ``ArrayRef`` of pointers to the ``Record`` |
| 239 |
instances of the *direct* superclasses of the record and returns the ``RecordRecTy`` |
| 240 |
corresponding to the record inheriting from those superclasses. |
| 241 |
|
| 242 |
``Init`` |
| 243 |
-------- |
| 244 |
|
| 245 |
The ``Init`` class is used to represent TableGen values. The name derives |
| 246 |
from *initialization value*. This class should not be confused with the |
| 247 |
``RecordVal`` class, which represents record fields, both their names and |
| 248 |
values. The ``Init`` class is the base class for a series of subclasses, one |
| 249 |
for each of the available value types. The primary data member of ``Init`` |
| 250 |
is an enumerated type that represents the specific type of the value. |
| 251 |
|
| 252 |
The ``Init`` class provides a few useful functions. |
| 253 |
|
| 254 |
* A function to get the type enumerator. |
| 255 |
|
| 256 |
* A boolean virtual function to determine whether a value is completely |
| 257 |
specified; that is, has no uninitialized subvalues. |
| 258 |
|
| 259 |
* Virtual functions to get the value as a string. |
| 260 |
|
| 261 |
* Virtual functions to cast the value to other types, implement the bit |
| 262 |
range feature of TableGen, and implement the list slice feature. |
| 263 |
|
| 264 |
* A virtual function to get a particular bit of the value. |
| 265 |
|
| 266 |
The subclasses that inherit directly from ``Init`` are |
| 267 |
``UnsetInit`` and ``TypedInit``. |
| 268 |
|
| 269 |
An ``Init`` instance can be printed to an output stream with the ``<<`` |
| 270 |
operator. |
| 271 |
|
| 272 |
.. warning:: |
| 273 |
It is not specified whether two separate initialization values with |
| 274 |
the same underlying type and value (e.g., two strings with the value |
| 275 |
"Hello") are represented by two ``Init``\ s or share the same ``Init``. |
| 276 |
|
| 277 |
``UnsetInit`` |
| 278 |
~~~~~~~~~~~~~ |
| 279 |
|
| 280 |
This class, a subclass of ``Init``, represents the unset (uninitialized) |
| 281 |
value. The static function ``get()`` can be used to obtain the singleton |
| 282 |
``Init`` of this type. |
| 283 |
|
| 284 |
|
| 285 |
``TypedInit`` |
| 286 |
~~~~~~~~~~~~~ |
| 287 |
|
| 288 |
This class, a subclass of ``Init``, acts as the parent class of the classes |
| 289 |
that represent specific value types (except for the unset value). These |
| 290 |
classes include ``BitInit``, ``BitsInit``, ``DagInit``, ``DefInit``, |
| 291 |
``IntInit``, ``ListInit``, and ``StringInit``. (There are additional derived |
| 292 |
types used by the TableGen parser.) |
| 293 |
|
| 294 |
This class includes a data member that specifies the ``RecTy`` type of the |
| 295 |
value. It provides a function to get that ``RecTy`` type. |
| 296 |
|
| 297 |
``BitInit`` |
| 298 |
~~~~~~~~~~~ |
| 299 |
|
| 300 |
The ``BitInit`` class is a subclass of ``TypedInit``. Its instances |
| 301 |
represent the possible values of a bit: 0 or 1. It includes a data member |
| 302 |
that contains the bit. |
| 303 |
|
| 304 |
*All* of the classes derived from ``TypedInit`` provide the following functions: |
| 305 |
|
| 306 |
* A static function named ``get()`` that returns an ``Init`` representing |
| 307 |
the specified value(s). In the case of ``BitInit``, ``get(true)`` returns |
| 308 |
an instance of ``BitInit`` representing true, while ``get(false)`` returns |
| 309 |
an instance |
| 310 |
representing false. As noted above, it is not specified whether there |
| 311 |
is exactly one or more than one ``BitInit`` representing true (or false). |
| 312 |
|
| 313 |
* A function named ``GetValue()`` that returns the value of the instance |
| 314 |
in a more direct form, in this case as a ``bool``. |
| 315 |
|
| 316 |
``BitsInit`` |
| 317 |
~~~~~~~~~~~~ |
| 318 |
|
| 319 |
The ``BitsInit`` class is a subclass of ``TypedInit``. Its instances |
| 320 |
represent sequences of bits, from high-order to low-order. It includes a |
| 321 |
data member with the length of the sequence and a vector of pointers to |
| 322 |
``Init`` instances, one per bit. |
| 323 |
|
| 324 |
The class provides the usual ``get()`` function. It does not provide the |
| 325 |
``getValue()`` function. |
| 326 |
|
| 327 |
The class provides the following additional functions. |
| 328 |
|
| 329 |
* A function to get the number of bits in the sequence. |
| 330 |
|
| 331 |
* A function that gets a bit specified by an integer index. |
| 332 |
|
| 333 |
``DagInit`` |
| 334 |
~~~~~~~~~~~ |
| 335 |
|
| 336 |
The ``DagInit`` class is a subclass of ``TypedInit``. Its instances |
| 337 |
represent the possible directed acyclic graphs (``dag``). |
| 338 |
|
| 339 |
The class includes a pointer to an ``Init`` for the DAG operator and a |
| 340 |
pointer to a ``StringInit`` for the operator name. It includes the count of |
| 341 |
DAG operands and the count of operand names. Finally, it includes a vector of |
| 342 |
pointers to ``Init`` instances for the operands and another to |
| 343 |
``StringInit`` instances for the operand names. |
| 344 |
(The DAG operands are also referred to as *arguments*.) |
| 345 |
|
| 346 |
The class provides two forms of the usual ``get()`` function. It does not |
| 347 |
provide the usual ``getValue()`` function. |
| 348 |
|
| 349 |
The class provides many additional functions: |
| 350 |
|
| 351 |
* Functions to get the operator in various forms and to get the |
| 352 |
operator name in various forms. |
| 353 |
|
| 354 |
* Functions to determine whether there are any operands and to get the |
| 355 |
number of operands. |
| 356 |
|
| 357 |
* Functions to get the operands, both individually and together. |
| 358 |
|
| 359 |
* Functions to determine whether there are any names and to |
| 360 |
get the number of names. |
| 361 |
|
| 362 |
* Functions to get the names, both individually and together. |
| 363 |
|
| 364 |
* Functions to get the operand iterator ``begin()`` and ``end()`` values. |
| 365 |
|
| 366 |
* Functions to get the name iterator ``begin()`` and ``end()`` values. |
| 367 |
|
| 368 |
The class defines two types for the return values of the operand and name |
| 369 |
iterators. |
| 370 |
|
| 371 |
.. code-block:: text |
| 372 |
|
| 373 |
using const_arg_iterator = SmallVectorImpl<Init*>::const_iterator; |
| 374 |
using const_name_iterator = SmallVectorImpl<StringInit*>::const_iterator; |
| 375 |
|
| 376 |
|
| 377 |
``DefInit`` |
| 378 |
~~~~~~~~~~~ |
| 379 |
|
| 380 |
The ``DefInit`` class is a subclass of ``TypedInit``. Its instances |
| 381 |
represent the records that were collected by TableGen. It includes a data |
| 382 |
member that is a pointer to the record's ``Record`` instance. |
| 383 |
|
| 384 |
The class provides the usual ``get()`` function. It does not provide |
| 385 |
``getValue()``. Instead, it provides ``getDef()``, which returns the |
| 386 |
``Record`` instance. |
| 387 |
|
| 388 |
``IntInit`` |
| 389 |
~~~~~~~~~~~ |
| 390 |
|
| 391 |
The ``IntInit`` class is a subclass of ``TypedInit``. Its instances |
| 392 |
represent the possible values of a 64-bit integer. It includes a data member |
| 393 |
that contains the integer. |
| 394 |
|
| 395 |
The class provides the usual ``get()`` and ``getValue()`` functions. The |
| 396 |
latter function returns the integer as an ``int64_t``. |
| 397 |
|
| 398 |
The class also provides a function, ``getBit()``, to obtain a specified bit |
| 399 |
of the integer value. |
| 400 |
|
| 401 |
``ListInit`` |
| 402 |
~~~~~~~~~~~~ |
| 403 |
|
| 404 |
The ``ListInit`` class is a subclass of ``TypedInit``. Its instances |
| 405 |
represent lists of elements of some type. It includes a data member with the |
| 406 |
length of the list and a vector of pointers to ``Init`` instances, one per |
| 407 |
element. |
| 408 |
|
| 409 |
The class provides the usual ``get()`` and ``getValues()`` functions. The |
| 410 |
latter function returns an ``ArrayRef`` of the vector of pointers to ``Init`` |
| 411 |
instances. |
| 412 |
|
| 413 |
The class provides these additional functions: |
| 414 |
|
| 415 |
* A function to get the element type. |
| 416 |
|
| 417 |
* Functions to get the length of the vector and to determine whether |
| 418 |
it is empty. |
| 419 |
|
| 420 |
* Functions to get an element specified by an integer index and return |
| 421 |
it in various forms. |
| 422 |
|
| 423 |
* Functions to get the iterator ``begin()`` and ``end()`` values. The |
| 424 |
class defines a type for the return type of these two functions. |
| 425 |
|
| 426 |
.. code-block:: text |
| 427 |
|
| 428 |
using const_iterator = Init *const *; |
| 429 |
|
| 430 |
|
| 431 |
``StringInit`` |
| 432 |
~~~~~~~~~~~~~~ |
| 433 |
|
| 434 |
The ``StringInit`` class is a subclass of ``TypedInit``. Its instances |
| 435 |
represent arbitrary-length strings. It includes a data member |
| 436 |
that contains a ``StringRef`` of the value. |
| 437 |
|
| 438 |
The class provides the usual ``get()`` and ``getValue()`` functions. The |
| 439 |
latter function returns the ``StringRef``. |
| 440 |
|
| 441 |
Creating a New Backend |
| 442 |
====================== |
| 443 |
|
| 444 |
The following steps are required to create a new backend for TableGen. |
| 445 |
|
| 446 |
#. Invent a name for your backend C++ file, say ``GenAddressModes``. |
| 447 |
|
| 448 |
#. Write the new backend, using the file ``TableGenBackendSkeleton.cpp`` |
| 449 |
as a starting point. |
| 450 |
|
| 451 |
#. Determine which instance of TableGen requires the new backend. There is |
| 452 |
one instance for Clang and another for LLVM. Or you may be building |
| 453 |
your own instance. |
| 454 |
|
| 455 |
#. Add your backend C++ file to the appropriate ``CMakeLists.txt`` file so |
| 456 |
that it will be built. |
| 457 |
|
| 458 |
#. Add your C++ file to the system. |
| 459 |
|
| 460 |
The Backend Skeleton |
| 461 |
==================== |
| 462 |
|
| 463 |
The file ``TableGenBackendSkeleton.cpp`` provides a skeleton C++ translation |
| 464 |
unit for writing a new TableGen backend. Here are a few notes on the file: |
| 465 |
|
| 466 |
* The list of includes is the minimal list required by most backends. |
| 467 |
|
| 468 |
* As with all LLVM C++ files, it has a ``using namespace llvm;`` statement. |
| 469 |
It also has an anonymous namespace that contains all the file-specific |
| 470 |
data structure definitions, along with the class embodying the emitter |
| 471 |
data members and functions. Continuing with the ``GenAddressModes`` example, |
| 472 |
this class is named ``AddressModesEmitter``. |
| 473 |
|
| 474 |
* The constructor for the emitter class accepts a ``RecordKeeper`` reference, |
| 475 |
typically named ``RK``. The ``RecordKeeper`` reference is saved in a data |
| 476 |
member so that records can be obtained from it. This data member is usually |
| 477 |
named ``Records``. |
| 478 |
|
| 479 |
* One function is named ``run``. It is invoked by the backend's "main |
| 480 |
function" to collect records and emit the output file. It accepts an instance |
| 481 |
of the ``raw_ostream`` class, typically named ``OS``. The output file is |
| 482 |
emitted by writing to this stream. |
| 483 |
|
| 484 |
* The ``run`` function should use the ``emitSourceFileHeader`` helper function |
| 485 |
to include a standard header in the emitted file. |
| 486 |
|
| 487 |
* Register the class or the function as the command-line option |
| 488 |
with ``llvm/TableGen/TableGenBackend.h``. |
| 489 |
|
| 490 |
* Use ``llvm::TableGen::Emitter::OptClass<AddressModesEmitter>`` |
| 491 |
if the class has the constructor ``(RK)`` and |
| 492 |
the method ``run(OS)``. |
| 493 |
|
| 494 |
* Otherwise, use ``llvm::TableGen::Emitter::Opt``. |
| 495 |
|
| 496 |
All the examples in the remainder of this document will assume the naming |
| 497 |
conventions used in the skeleton file. |
| 498 |
|
| 499 |
Getting Classes |
| 500 |
=============== |
| 501 |
|
| 502 |
The ``RecordKeeper`` class provides two functions for getting the |
| 503 |
``Record`` instances for classes defined in the TableGen files. |
| 504 |
|
| 505 |
* ``getClasses()`` returns a ``RecordMap`` reference for all the classes. |
| 506 |
|
| 507 |
* ``getClass(``\ *name*\ ``)`` returns a ``Record`` reference for the named |
| 508 |
class. |
| 509 |
|
| 510 |
If you need to iterate over all the class records: |
| 511 |
|
| 512 |
.. code-block:: text |
| 513 |
|
| 514 |
for (auto ClassPair : Records.getClasses()) { |
| 515 |
Record *ClassRec = ClassPair.second.get(); |
| 516 |
... |
| 517 |
} |
| 518 |
|
| 519 |
``ClassPair.second`` gets the class's ``unique_ptr``, and then ``.get()`` gets the |
| 520 |
class ``Record`` itself. |
| 521 |
|
| 522 |
|
| 523 |
Getting Records |
| 524 |
=============== |
| 525 |
|
| 526 |
The ``RecordKeeper`` class provides four functions for getting the |
| 527 |
``Record`` instances for concrete records defined in the TableGen files. |
| 528 |
|
| 529 |
* ``getDefs()`` returns a ``RecordMap`` reference for all the concrete |
| 530 |
records. |
| 531 |
|
| 532 |
* ``getDef(``\ *name*\ ``)`` returns a ``Record`` reference for the named |
| 533 |
concrete record. |
| 534 |
|
| 535 |
* ``getAllDerivedDefinitions(``\ *classname*\ ``)`` returns a vector of |
| 536 |
``Record`` references for the concrete records that derive from the |
| 537 |
given class. |
| 538 |
|
| 539 |
* ``getAllDerivedDefinitions(``\ *classnames*\ ``)`` returns |
| 540 |
a vector of ``Record`` references for the concrete records that derive from |
| 541 |
*all* of the given classes. |
| 542 |
|
| 543 |
This statement obtains all the records that derive from the ``Attribute`` |
| 544 |
class and iterates over them. |
| 545 |
|
| 546 |
.. code-block:: text |
| 547 |
|
| 548 |
auto AttrRecords = Records.getAllDerivedDefinitions("Attribute"); |
| 549 |
for (Record *AttrRec : AttrRecords) { |
| 550 |
... |
| 551 |
} |
| 552 |
|
| 553 |
Getting Record Names and Fields |
| 554 |
=============================== |
| 555 |
|
| 556 |
As described above (see `Record`_), there are multiple functions that |
| 557 |
return the name of a record. One particularly useful one is |
| 558 |
``getNameInitAsString()``, which returns the name as a ``std::string``. |
| 559 |
|
| 560 |
There are also multiple functions that return the fields of a record. To |
| 561 |
obtain and iterate over all the fields: |
| 562 |
|
| 563 |
.. code-block:: text |
| 564 |
|
| 565 |
for (const RecordVal &Field : SomeRec->getValues()) { |
| 566 |
... |
| 567 |
} |
| 568 |
|
| 569 |
You will recall that ``RecordVal`` is the class whose instances contain |
| 570 |
information about the fields in records. |
| 571 |
|
| 572 |
The ``getValue()`` function returns the ``RecordVal`` instance for a field |
| 573 |
specified by name. There are multiple overloaded functions, some taking a |
| 574 |
``StringRef`` and others taking a ``const Init *``. Some functions return a |
| 575 |
``RecordVal *`` and others return a ``const RecordVal *``. If the field does |
| 576 |
not exist, a fatal error message is printed. |
| 577 |
|
| 578 |
More often than not, you are interested in the value of the field, not all |
| 579 |
the information in the ``RecordVal``. There is a large set of functions that |
| 580 |
take a field name in some form and return its value. One function, |
| 581 |
``getValueInit``, returns the value as an ``Init *``. Another function, |
| 582 |
``isValueUnset``, returns a boolean specifying whether the value is unset |
| 583 |
(uninitialized). |
| 584 |
|
| 585 |
Most of the functions return the value in some more useful form. For |
| 586 |
example: |
| 587 |
|
| 588 |
.. code-block:: text |
| 589 |
|
| 590 |
std::vector<int64_t> RegCosts = |
| 591 |
SomeRec->getValueAsListOfInts("RegCosts"); |
| 592 |
|
| 593 |
The field ``RegCosts`` is assumed to be a list of integers. That list is |
| 594 |
returned as a ``std::vector`` of 64-bit integers. If the field is not a list |
| 595 |
of integers, a fatal error message is printed. |
| 596 |
|
| 597 |
Here is a function that returns a field value as a ``Record``, but returns |
| 598 |
null if the field does not exist. |
| 599 |
|
| 600 |
.. code-block:: text |
| 601 |
|
| 602 |
if (Record *BaseRec = SomeRec->getValueAsOptionalDef(BaseFieldName)) { |
| 603 |
... |
| 604 |
} |
| 605 |
|
| 606 |
The field is assumed to have another record as its value. That record is returned |
| 607 |
as a pointer to a ``Record``. If the field does not exist or is unset, the |
| 608 |
function returns null. |
| 609 |
|
| 610 |
Getting Record Superclasses |
| 611 |
=========================== |
| 612 |
|
| 613 |
The ``Record`` class provides a function to obtain the direct superclasses |
| 614 |
of a record. It is named ``getDirectSuperClasses`` and returns an |
| 615 |
``ArrayRef`` of an array of ``std::pair`` instances. Each pair consists of a |
| 616 |
pointer to the ``Record`` instance for a superclass record and an instance |
| 617 |
of the ``SMRange`` class. The range indicates the source file locations of |
| 618 |
the beginning and end of the class definition. |
| 619 |
|
| 620 |
This example obtains the direct superclasses of the ``Prototype`` record and |
| 621 |
then iterates over the pairs in the returned array. |
| 622 |
|
| 623 |
.. code-block:: text |
| 624 |
|
| 625 |
ArrayRef<std::pair<const Record *, SMRange>> |
| 626 |
Superclasses = Prototype->getDirectSuperClasses(); |
| 627 |
for (const auto &[Super, Range] : Superclasses) { |
| 628 |
... |
| 629 |
} |
| 630 |
|
| 631 |
The ``Record`` class also provides a function, ``getSuperClasses``, to |
| 632 |
return a vector of *all* superclasses of a record. The superclasses are in |
| 633 |
postorder: the order in which the superclasses were visited while copying |
| 634 |
their fields into the record. |
| 635 |
|
| 636 |
Emitting Text to the Output Stream |
| 637 |
================================== |
| 638 |
|
| 639 |
The ``run`` function is passed a ``raw_ostream`` to which it prints the |
| 640 |
output file. By convention, this stream is saved in the emitter class member |
| 641 |
named ``OS``, although some ``run`` functions are simple and just use the |
| 642 |
stream without saving it. The output can be produced by writing values |
| 643 |
directly to the output stream, or by using the ``std::format()`` or |
| 644 |
``llvm::formatv()`` functions. |
| 645 |
|
| 646 |
.. code-block:: text |
| 647 |
|
| 648 |
OS << "#ifndef " << NodeName << "\n"; |
| 649 |
|
| 650 |
OS << format("0x%0*x, ", Digits, Value); |
| 651 |
|
| 652 |
Instances of the following classes can be printed using the ``<<`` operator: |
| 653 |
``RecordKeeper``, |
| 654 |
``Record``, |
| 655 |
``RecTy``, |
| 656 |
``RecordVal``, and |
| 657 |
``Init``. |
| 658 |
|
| 659 |
The helper function ``emitSourceFileHeader()`` prints the header comment |
| 660 |
that should be included at the top of every output file. A call to it is |
| 661 |
included in the skeleton backend file ``TableGenBackendSkeleton.cpp``. |
| 662 |
|
| 663 |
Printing Error Messages |
| 664 |
======================= |
| 665 |
|
| 666 |
TableGen records are often derived from multiple classes and also often |
| 667 |
defined through a sequence of multiclasses. Because of this, it can be |
| 668 |
difficult for backends to report clear error messages with accurate source |
| 669 |
file locations. To make error reporting easier, five error reporting |
| 670 |
functions are provided, each with four overloads. |
| 671 |
|
| 672 |
* ``PrintWarning`` prints a message tagged as a warning. |
| 673 |
|
| 674 |
* ``PrintError`` prints a message tagged as an error. |
| 675 |
|
| 676 |
* ``PrintFatalError`` prints a message tagged as an error and then terminates. |
| 677 |
|
| 678 |
* ``PrintNote`` prints a note. It is often used after one of the previous |
| 679 |
functions to provide more information. |
| 680 |
|
| 681 |
* ``PrintFatalNote`` prints a note and then terminates. |
| 682 |
|
| 683 |
Each of these five functions is overloaded four times. |
| 684 |
|
| 685 |
* ``PrintError(const Twine &Msg)``: |
| 686 |
Prints the message with no source file location. |
| 687 |
|
| 688 |
* ``PrintError(ArrayRef<SMLoc> ErrorLoc, const Twine &Msg)``: |
| 689 |
Prints the message followed by the specified source line, |
| 690 |
along with a pointer to the item in error. The array of |
| 691 |
source file locations is typically taken from a ``Record`` instance. |
| 692 |
|
| 693 |
* ``PrintError(const Record *Rec, const Twine &Msg)``: |
| 694 |
Prints the message followed by the source line associated with the |
| 695 |
specified record (see `Record`_). |
| 696 |
|
| 697 |
* ``PrintError(const RecordVal *RecVal, const Twine &Msg)``: |
| 698 |
Prints the message followed by the source line associated with the |
| 699 |
specified record field (see `RecordVal`_). |
| 700 |
|
| 701 |
Using these functions, the goal is to produce the most specific error report |
| 702 |
possible. |
| 703 |
|
| 704 |
Debugging Tools |
| 705 |
=============== |
| 706 |
|
| 707 |
TableGen provides some tools to aid in debugging backends. |
| 708 |
|
| 709 |
The ``PrintRecords`` Backend |
| 710 |
---------------------------- |
| 711 |
|
| 712 |
The TableGen command option ``--print-records`` invokes a simple backend |
| 713 |
that prints all the classes and records defined in the source files. This is |
| 714 |
the default backend option. The format of the output is guaranteed to be |
| 715 |
constant over time, so that the output can be compared in tests. The output |
| 716 |
looks like this: |
| 717 |
|
| 718 |
.. code-block:: text |
| 719 |
|
| 720 |
------------- Classes ----------------- |
| 721 |
... |
| 722 |
class XEntry<string XEntry:str = ?, int XEntry:val1 = ?> { // XBase |
| 723 |
string Str = XEntry:str; |
| 724 |
bits<8> Val1 = { !cast<bits<8>>(XEntry:val1){7}, ... }; |
| 725 |
bit Val3 = 1; |
| 726 |
} |
| 727 |
... |
| 728 |
------------- Defs ----------------- |
| 729 |
def ATable { // GenericTable |
| 730 |
string FilterClass = "AEntry"; |
| 731 |
string CppTypeName = "AEntry"; |
| 732 |
list<string> Fields = ["Str", "Val1", "Val2"]; |
| 733 |
list<string> PrimaryKey = ["Val1", "Val2"]; |
| 734 |
string PrimaryKeyName = "lookupATableByValues"; |
| 735 |
bit PrimaryKeyEarlyOut = 0; |
| 736 |
} |
| 737 |
... |
| 738 |
def anonymous_0 { // AEntry |
| 739 |
string Str = "Bob"; |
| 740 |
bits<8> Val1 = { 0, 0, 0, 0, 0, 1, 0, 1 }; |
| 741 |
bits<10> Val2 = { 0, 0, 0, 0, 0, 0, 0, 0, 1, 1 }; |
| 742 |
} |
| 743 |
|
| 744 |
Classes are shown with their template arguments, parent classes (following |
| 745 |
``//``), and fields. Records are shown with their parent classes and |
| 746 |
fields. Note that anonymous records are named ``anonymous_0``, |
| 747 |
``anonymous_1``, etc. |
| 748 |
|
| 749 |
The ``PrintDetailedRecords`` Backend |
| 750 |
------------------------------------ |
| 751 |
|
| 752 |
The TableGen command option ``--print-detailed-records`` invokes a backend |
| 753 |
that prints all the global variables, classes, and records defined in the |
| 754 |
source files. The format of the output is *not* guaranteed to be constant |
| 755 |
over time. The output looks like this: |
| 756 |
|
| 757 |
.. code-block:: text |
| 758 |
|
| 759 |
DETAILED RECORDS for file llvm-project\llvm\lib\target\arc\arc.td |
| 760 |
|
| 761 |
-------------------- Global Variables (5) -------------------- |
| 762 |
|
| 763 |
AMDGPUBufferIntrinsics = [int_amdgcn_s_buffer_load, ... |
| 764 |
AMDGPUImageDimAtomicIntrinsics = [int_amdgcn_image_atomic_swap_1d, ... |
| 765 |
... |
| 766 |
-------------------- Classes (758) -------------------- |
| 767 |
|
| 768 |
AMDGPUBufferLoad |IntrinsicsAMDGPU.td:879| |
| 769 |
Template args: |
| 770 |
LLVMType AMDGPUBufferLoad:data_ty = llvm_any_ty |IntrinsicsAMDGPU.td:879| |
| 771 |
Superclasses: (SDPatternOperator) Intrinsic AMDGPURsrcIntrinsic |
| 772 |
Fields: |
| 773 |
list<SDNodeProperty> Properties = [SDNPMemOperand] |Intrinsics.td:348| |
| 774 |
string LLVMName = "" |Intrinsics.td:343| |
| 775 |
... |
| 776 |
-------------------- Records (12303) -------------------- |
| 777 |
|
| 778 |
AMDGPUSample_lz_o |IntrinsicsAMDGPU.td:560| |
| 779 |
Defm sequence: |IntrinsicsAMDGPU.td:584| |IntrinsicsAMDGPU.td:566| |
| 780 |
Superclasses: AMDGPUSampleVariant |
| 781 |
Fields: |
| 782 |
string UpperCaseMod = "_LZ_O" |IntrinsicsAMDGPU.td:542| |
| 783 |
string LowerCaseMod = "_lz_o" |IntrinsicsAMDGPU.td:543| |
| 784 |
... |
| 785 |
|
| 786 |
* Global variables defined with outer ``defvar`` statements are shown with |
| 787 |
their values. |
| 788 |
|
| 789 |
* The classes are shown with their source location, template arguments, |
| 790 |
superclasses, and fields. |
| 791 |
|
| 792 |
* The records are shown with their source location, ``defm`` sequence, |
| 793 |
superclasses, and fields. |
| 794 |
|
| 795 |
Superclasses are shown in the order processed, with indirect superclasses in |
| 796 |
parentheses. Each field is shown with its value and the source location at |
| 797 |
which it was set. |
| 798 |
The ``defm`` sequence gives the locations of the ``defm`` statements that |
| 799 |
were involved in generating the record, in the order they were invoked. |
| 800 |
|
| 801 |
Timing TableGen Phases |
| 802 |
---------------------- |
| 803 |
|
| 804 |
TableGen provides a phase timing feature that produces a report of the time |
| 805 |
used by the various phases of parsing the source files and running the |
| 806 |
selected backend. This feature is enabled with the ``--time-phases`` option |
| 807 |
of the TableGen command. |
| 808 |
|
| 809 |
If the backend is *not* instrumented for timing, then a report such as the |
| 810 |
following is produced. This is the timing for the |
| 811 |
``--print-detailed-records`` backend run on the AMDGPU target. |
| 812 |
|
| 813 |
.. code-block:: text |
| 814 |
|
| 815 |
===-------------------------------------------------------------------------=== |
| 816 |
TableGen Phase Timing |
| 817 |
===-------------------------------------------------------------------------=== |
| 818 |
Total Execution Time: 101.0106 seconds (102.4819 wall clock) |
| 819 |
|
| 820 |
---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name --- |
| 821 |
85.5197 ( 84.9%) 0.1560 ( 50.0%) 85.6757 ( 84.8%) 85.7009 ( 83.6%) Backend overall |
| 822 |
15.1789 ( 15.1%) 0.0000 ( 0.0%) 15.1789 ( 15.0%) 15.1829 ( 14.8%) Parse, build records |
| 823 |
0.0000 ( 0.0%) 0.1560 ( 50.0%) 0.1560 ( 0.2%) 1.5981 ( 1.6%) Write output |
| 824 |
100.6986 (100.0%) 0.3120 (100.0%) 101.0106 (100.0%) 102.4819 (100.0%) Total |
| 825 |
|
| 826 |
Note that all the time for the backend is lumped under "Backend overall". |
| 827 |
|
| 828 |
If the backend is instrumented for timing, then its processing is |
| 829 |
divided into phases and each one timed separately. This is the timing for |
| 830 |
the ``--emit-dag-isel`` backend run on the AMDGPU target. |
| 831 |
|
| 832 |
.. code-block:: text |
| 833 |
|
| 834 |
===-------------------------------------------------------------------------=== |
| 835 |
TableGen Phase Timing |
| 836 |
===-------------------------------------------------------------------------=== |
| 837 |
Total Execution Time: 746.3868 seconds (747.1447 wall clock) |
| 838 |
|
| 839 |
---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name --- |
| 840 |
657.7938 ( 88.1%) 0.1404 ( 90.0%) 657.9342 ( 88.1%) 658.6497 ( 88.2%) Emit matcher table |
| 841 |
70.2317 ( 9.4%) 0.0000 ( 0.0%) 70.2317 ( 9.4%) 70.2700 ( 9.4%) Convert to matchers |
| 842 |
14.8825 ( 2.0%) 0.0156 ( 10.0%) 14.8981 ( 2.0%) 14.9009 ( 2.0%) Parse, build records |
| 843 |
2.1840 ( 0.3%) 0.0000 ( 0.0%) 2.1840 ( 0.3%) 2.1791 ( 0.3%) Sort patterns |
| 844 |
1.1388 ( 0.2%) 0.0000 ( 0.0%) 1.1388 ( 0.2%) 1.1401 ( 0.2%) Optimize matchers |
| 845 |
0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0050 ( 0.0%) Write output |
| 846 |
746.2308 (100.0%) 0.1560 (100.0%) 746.3868 (100.0%) 747.1447 (100.0%) Total |
| 847 |
|
| 848 |
The backend has been divided into four phases and timed separately. |
| 849 |
|
| 850 |
If you want to instrument a backend, refer to the backend ``DAGISelEmitter.cpp`` |
| 851 |
and search for ``Records.startTimer``. |