|
207
|
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 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 direct 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 the 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 the 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 #. Modify the selected ``tablegen.cpp`` to include your new backend.
|
|
|
456
|
|
|
457 a. Add the name to the enumerated type ``ActionType``.
|
|
|
458
|
|
|
459 #. Add a keyword to the ``ActionType`` command option using the
|
|
|
460 ``clEnumValN()`` function.
|
|
|
461
|
|
|
462 #. Add a case to the ``switch`` statement in the *xxx*\ ``TableGenMain()``
|
|
|
463 function. It should invoke the "main function" of your backend, which
|
|
|
464 in this case, according to convention, is named ``EmitAddressModes``.
|
|
|
465
|
|
|
466 5. Add a declaration of your "main function" to the corresponding
|
|
|
467 ``TableGenBackends.h`` header file.
|
|
|
468
|
|
|
469 #. Add your backend C++ file to the appropriate ``CMakeLists.txt`` file so
|
|
|
470 that it will be built.
|
|
|
471
|
|
|
472 #. Add your C++ file to the system.
|
|
|
473
|
|
|
474 The Backend Skeleton
|
|
|
475 ====================
|
|
|
476
|
|
|
477 The file ``TableGenBackendSkeleton.cpp`` provides a skeleton C++ translation
|
|
|
478 unit for writing a new TableGen backend. Here are a few notes on the file.
|
|
|
479
|
|
|
480 * The list of includes is the minimal list required by most backends.
|
|
|
481
|
|
|
482 * As with all LLVM C++ files, it has a ``using namespace llvm;`` statement.
|
|
|
483 It also has an anonymous namespace that contains all the file-specific
|
|
|
484 data structure definitions, along with the class embodying the emitter
|
|
|
485 data members and functions. Continuing with the ``GenAddressModes`` example,
|
|
|
486 this class is named ``AddressModesEmitter``.
|
|
|
487
|
|
|
488 * The constructor for the emitter class accepts a ``RecordKeeper`` reference,
|
|
|
489 typically named ``RK``. The ``RecordKeeper`` reference is saved in a data
|
|
|
490 member so that records can be obtained from it. This data member is usually
|
|
|
491 named ``Records``.
|
|
|
492
|
|
|
493 * One function is named ``run``. It is invoked by the backend's "main
|
|
|
494 function" to collect records and emit the output file. It accepts an instance
|
|
|
495 of the ``raw_ostream`` class, typically named ``OS``. The output file is
|
|
|
496 emitted by writing to this stream.
|
|
|
497
|
|
|
498 * The ``run`` function should use the ``emitSourceFileHeader`` helper function
|
|
|
499 to include a standard header in the emitted file.
|
|
|
500
|
|
|
501 * The only function in the ``llvm`` namespace is the backend "main function."
|
|
|
502 In this example, it is named ``EmitAddressModes``. It creates an instance
|
|
|
503 of the ``AddressModesEmitter`` class, passing the ``RecordKeeper``
|
|
|
504 instance, then invokes the ``run`` function, passing the ``raw_ostream``
|
|
|
505 instance.
|
|
|
506
|
|
|
507 All the examples in the remainder of this document will assume the naming
|
|
|
508 conventions used in the skeleton file.
|
|
|
509
|
|
|
510 Getting Classes
|
|
|
511 ===============
|
|
|
512
|
|
|
513 The ``RecordKeeper`` class provides two functions for getting the
|
|
|
514 ``Record`` instances for classes defined in the TableGen files.
|
|
|
515
|
|
|
516 * ``getClasses()`` returns a ``RecordMap`` reference for all the classes.
|
|
|
517
|
|
|
518 * ``getClass(``\ *name*\ ``)`` returns a ``Record`` reference for the named
|
|
|
519 class.
|
|
|
520
|
|
|
521 If you need to iterate over all the class records:
|
|
|
522
|
|
|
523 .. code-block:: text
|
|
|
524
|
|
|
525 for (auto ClassPair : Records.getClasses()) {
|
|
|
526 Record *ClassRec = ClassPair.second.get();
|
|
|
527 ...
|
|
|
528 }
|
|
|
529
|
|
|
530 ``ClassPair.second`` gets the class's ``unique_ptr``, then ``.get()`` gets the
|
|
|
531 class ``Record`` itself.
|
|
|
532
|
|
|
533
|
|
|
534 Getting Records
|
|
|
535 ===============
|
|
|
536
|
|
|
537 The ``RecordKeeper`` class provides four functions for getting the
|
|
|
538 ``Record`` instances for concrete records defined in the TableGen files.
|
|
|
539
|
|
|
540 * ``getDefs()`` returns a ``RecordMap`` reference for all the concrete
|
|
|
541 records.
|
|
|
542
|
|
|
543 * ``getDef(``\ *name*\ ``)`` returns a ``Record`` reference for the named
|
|
|
544 concrete record.
|
|
|
545
|
|
|
546 * ``getAllDerivedDefinitions(``\ *classname*\ ``)`` returns a vector of
|
|
|
547 ``Record`` references for the concrete records that derive from the
|
|
|
548 given class.
|
|
|
549
|
|
|
550 * ``getAllDerivedDefinitions(``\ *classnames*\ ``)`` returns
|
|
|
551 a vector of ``Record`` references for the concrete records that derive from
|
|
|
552 *all* of the given classes.
|
|
|
553
|
|
|
554 This statement obtains all the records that derive from the ``Attribute``
|
|
|
555 class and iterates over them.
|
|
|
556
|
|
|
557 .. code-block:: text
|
|
|
558
|
|
|
559 auto AttrRecords = Records.getAllDerivedDefinitions("Attribute");
|
|
|
560 for (Record *AttrRec : AttrRecords) {
|
|
|
561 ...
|
|
|
562 }
|
|
|
563
|
|
|
564 Getting Record Names and Fields
|
|
|
565 ===============================
|
|
|
566
|
|
|
567 As described above (see `Record`_), there are multiple functions that
|
|
|
568 return the name of a record. One particularly useful one is
|
|
|
569 ``getNameInitAsString()``, which returns the name as a ``std::string``.
|
|
|
570
|
|
|
571 There are also multiple functions that return the fields of a record. To
|
|
|
572 obtain and iterate over all the fields:
|
|
|
573
|
|
|
574 .. code-block:: text
|
|
|
575
|
|
|
576 for (const RecordVal &Field : SomeRec->getValues()) {
|
|
|
577 ...
|
|
|
578 }
|
|
|
579
|
|
|
580 You will recall that ``RecordVal`` is the class whose instances contain
|
|
|
581 information about the fields in records.
|
|
|
582
|
|
|
583 The ``getValue()`` function returns the ``RecordVal`` instance for a field
|
|
|
584 specified by name. There are multiple overloaded functions, some taking a
|
|
|
585 ``StringRef`` and others taking a ``const Init *``. Some functions return a
|
|
|
586 ``RecordVal *`` and others return a ``const RecordVal *``. If the field does
|
|
|
587 not exist, a fatal error message is printed.
|
|
|
588
|
|
|
589 More often than not, you are interested in the value of the field, not all
|
|
|
590 the information in the ``RecordVal``. There is a large set of functions that
|
|
|
591 take a field name in some form and return its value. One function,
|
|
|
592 ``getValueInit``, returns the value as an ``Init *``. Another function,
|
|
|
593 ``isValueUnset``, returns a boolean specifying whether the value is unset
|
|
|
594 (uninitialized).
|
|
|
595
|
|
|
596 Most of the functions return the value in some more useful form. For
|
|
|
597 example:
|
|
|
598
|
|
|
599 .. code-block:: text
|
|
|
600
|
|
|
601 std::vector<int64_t> RegCosts =
|
|
|
602 SomeRec->getValueAsListOfInts("RegCosts");
|
|
|
603
|
|
|
604 The field ``RegCosts`` is assumed to be a list of integers. That list is
|
|
|
605 returned as a ``std::vector`` of 64-bit integers. If the field is not a list
|
|
|
606 of integers, a fatal error message is printed.
|
|
|
607
|
|
|
608 Here is a function that returns a field value as a ``Record``, but returns
|
|
|
609 null if the field does not exist.
|
|
|
610
|
|
|
611 .. code-block:: text
|
|
|
612
|
|
|
613 if (Record *BaseRec = SomeRec->getValueAsOptionalDef(BaseFieldName)) {
|
|
|
614 ...
|
|
|
615 }
|
|
|
616
|
|
|
617 The field is assumed to have another record as its value. That record is returned
|
|
|
618 as a pointer to a ``Record``. If the field does not exist or is unset, the
|
|
|
619 functions returns null.
|
|
|
620
|
|
|
621 Getting Record Superclasses
|
|
|
622 ===========================
|
|
|
623
|
|
|
624 The ``Record`` class provides a function to obtain the superclasses of a
|
|
|
625 record. It is named ``getSuperClasses`` and returns an ``ArrayRef`` of an
|
|
|
626 array of ``std::pair`` pairs. The superclasses are in post-order: the order
|
|
|
627 in which the superclasses were visited while copying their fields into the
|
|
|
628 record. Each pair consists of a pointer to the ``Record`` instance for a
|
|
|
629 superclass record and an instance of the ``SMRange`` class. The range
|
|
|
630 indicates the source file locations of the beginning and end of the class
|
|
|
631 definition.
|
|
|
632
|
|
|
633 This example obtains the superclasses of the ``Prototype`` record and then
|
|
|
634 iterates over the pairs in the returned array.
|
|
|
635
|
|
|
636 .. code-block:: text
|
|
|
637
|
|
|
638 ArrayRef<std::pair<Record *, SMRange>>
|
|
|
639 Superclasses = Prototype->getSuperClasses();
|
|
|
640 for (const auto &SuperPair : Superclasses) {
|
|
|
641 ...
|
|
|
642 }
|
|
|
643
|
|
|
644 The ``Record`` class also provides a function, ``getDirectSuperClasses``, to
|
|
|
645 append the *direct* superclasses of a record to a given vector of type
|
|
|
646 ``SmallVectorImpl<Record *>``.
|
|
|
647
|
|
|
648 Emitting Text to the Output Stream
|
|
|
649 ==================================
|
|
|
650
|
|
|
651 The ``run`` function is passed a ``raw_ostream`` to which it prints the
|
|
|
652 output file. By convention, this stream is saved in the emitter class member
|
|
|
653 named ``OS``, although some ``run`` functions are simple and just use the
|
|
|
654 stream without saving it. The output can be produced by writing values
|
|
|
655 directly to the output stream, or by using the ``std::format()`` or
|
|
|
656 ``llvm::formatv()`` functions.
|
|
|
657
|
|
|
658 .. code-block:: text
|
|
|
659
|
|
|
660 OS << "#ifndef " << NodeName << "\n";
|
|
|
661
|
|
|
662 OS << format("0x%0*x, ", Digits, Value);
|
|
|
663
|
|
|
664 Instances of the following classes can be printed using the ``<<`` operator:
|
|
|
665 ``RecordKeeper``,
|
|
|
666 ``Record``,
|
|
|
667 ``RecTy``,
|
|
|
668 ``RecordVal``, and
|
|
|
669 ``Init``.
|
|
|
670
|
|
|
671 The helper function ``emitSourceFileHeader()`` prints the header comment
|
|
|
672 that should be included at the top of every output file. A call to it is
|
|
|
673 included in the skeleton backend file ``TableGenBackendSkeleton.cpp``.
|
|
|
674
|
|
|
675 Printing Error Messages
|
|
|
676 =======================
|
|
|
677
|
|
|
678 TableGen records are often derived from multiple classes and also often
|
|
|
679 defined through a sequence of multiclasses. Because of this, it can be
|
|
|
680 difficult for backends to report clear error messages with accurate source
|
|
|
681 file locations. To make error reporting easier, five error reporting
|
|
|
682 functions are provided, each with four overloads.
|
|
|
683
|
|
|
684 * ``PrintWarning`` prints a message tagged as a warning.
|
|
|
685
|
|
|
686 * ``PrintError`` prints a message tagged as an error.
|
|
|
687
|
|
|
688 * ``PrintFatalError`` prints a message tagged as an error and then terminates.
|
|
|
689
|
|
|
690 * ``PrintNote`` prints a note. It is often used after one of the previous
|
|
|
691 functions to provide more information.
|
|
|
692
|
|
|
693 * ``PrintFatalNote`` prints a note and then terminates.
|
|
|
694
|
|
|
695 Each of these five functions is overloaded four times.
|
|
|
696
|
|
|
697 * ``PrintError(const Twine &Msg)``:
|
|
|
698 Prints the message with no source file location.
|
|
|
699
|
|
|
700 * ``PrintError(ArrayRef<SMLoc> ErrorLoc, const Twine &Msg)``:
|
|
|
701 Prints the message followed by the specified source line,
|
|
|
702 along with a pointer to the item in error. The array of
|
|
|
703 source file locations is typically taken from a ``Record`` instance.
|
|
|
704
|
|
|
705 * ``PrintError(const Record *Rec, const Twine &Msg)``:
|
|
|
706 Prints the message followed by the source line associated with the
|
|
|
707 specified record (see `Record`_).
|
|
|
708
|
|
|
709 * ``PrintError(const RecordVal *RecVal, const Twine &Msg)``:
|
|
|
710 Prints the message followed by the source line associated with the
|
|
|
711 specified record field (see `RecordVal`_).
|
|
|
712
|
|
|
713 Using these functions, the goal is to produce the most specific error report
|
|
|
714 possible.
|
|
|
715
|
|
|
716 Debugging Tools
|
|
|
717 ===============
|
|
|
718
|
|
|
719 TableGen provides some tools to aid in debugging backends.
|
|
|
720
|
|
|
721 The ``PrintRecords`` Backend
|
|
|
722 ----------------------------
|
|
|
723
|
|
|
724 The TableGen command option ``--print-records`` invokes a simple backend
|
|
|
725 that prints all the classes and records defined in the source files. This is
|
|
|
726 the default backend option. The format of the output is guaranteed to be
|
|
|
727 constant over time, so that the output can be compared in tests. The output
|
|
|
728 looks like this:
|
|
|
729
|
|
|
730 .. code-block:: text
|
|
|
731
|
|
|
732 ------------- Classes -----------------
|
|
|
733 ...
|
|
|
734 class XEntry<string XEntry:str = ?, int XEntry:val1 = ?> { // XBase
|
|
|
735 string Str = XEntry:str;
|
|
|
736 bits<8> Val1 = { !cast<bits<8>>(XEntry:val1){7}, ... };
|
|
|
737 bit Val3 = 1;
|
|
|
738 }
|
|
|
739 ...
|
|
|
740 ------------- Defs -----------------
|
|
|
741 def ATable { // GenericTable
|
|
|
742 string FilterClass = "AEntry";
|
|
|
743 string CppTypeName = "AEntry";
|
|
|
744 list<string> Fields = ["Str", "Val1", "Val2"];
|
|
|
745 list<string> PrimaryKey = ["Val1", "Val2"];
|
|
|
746 string PrimaryKeyName = "lookupATableByValues";
|
|
|
747 bit PrimaryKeyEarlyOut = 0;
|
|
|
748 }
|
|
|
749 ...
|
|
|
750 def anonymous_0 { // AEntry
|
|
|
751 string Str = "Bob";
|
|
|
752 bits<8> Val1 = { 0, 0, 0, 0, 0, 1, 0, 1 };
|
|
|
753 bits<10> Val2 = { 0, 0, 0, 0, 0, 0, 0, 0, 1, 1 };
|
|
|
754 }
|
|
|
755
|
|
|
756 Classes are shown with their template arguments, parent classes (following
|
|
|
757 ``//``), and fields. Records are shown with their parent classes and
|
|
|
758 fields. Note that anonymous records are named ``anonymous_0``,
|
|
|
759 ``anonymous_1``, etc.
|
|
|
760
|
|
|
761 The ``PrintDetailedRecords`` Backend
|
|
|
762 ------------------------------------
|
|
|
763
|
|
|
764 The TableGen command option ``--print-detailed-records`` invokes a backend
|
|
|
765 that prints all the global variables, classes, and records defined in the
|
|
|
766 source files. The format of the output is *not* guaranteed to be constant
|
|
|
767 over time. The output looks like this.
|
|
|
768
|
|
|
769 .. code-block:: text
|
|
|
770
|
|
|
771 DETAILED RECORDS for file llvm-project\llvm\lib\target\arc\arc.td
|
|
|
772
|
|
|
773 -------------------- Global Variables (5) --------------------
|
|
|
774
|
|
|
775 AMDGPUBufferIntrinsics = [int_amdgcn_buffer_load_format, ...
|
|
|
776 AMDGPUImageDimAtomicIntrinsics = [int_amdgcn_image_atomic_swap_1d, ...
|
|
|
777 ...
|
|
|
778 -------------------- Classes (758) --------------------
|
|
|
779
|
|
|
780 AMDGPUBufferLoad |IntrinsicsAMDGPU.td:879|
|
|
|
781 Template args:
|
|
|
782 LLVMType AMDGPUBufferLoad:data_ty = llvm_any_ty |IntrinsicsAMDGPU.td:879|
|
|
|
783 Superclasses: (SDPatternOperator) Intrinsic AMDGPURsrcIntrinsic
|
|
|
784 Fields:
|
|
|
785 list<SDNodeProperty> Properties = [SDNPMemOperand] |Intrinsics.td:348|
|
|
|
786 string LLVMName = "" |Intrinsics.td:343|
|
|
|
787 ...
|
|
|
788 -------------------- Records (12303) --------------------
|
|
|
789
|
|
|
790 AMDGPUSample_lz_o |IntrinsicsAMDGPU.td:560|
|
|
|
791 Defm sequence: |IntrinsicsAMDGPU.td:584| |IntrinsicsAMDGPU.td:566|
|
|
|
792 Superclasses: AMDGPUSampleVariant
|
|
|
793 Fields:
|
|
|
794 string UpperCaseMod = "_LZ_O" |IntrinsicsAMDGPU.td:542|
|
|
|
795 string LowerCaseMod = "_lz_o" |IntrinsicsAMDGPU.td:543|
|
|
|
796 ...
|
|
|
797
|
|
|
798 * Global variables defined with outer ``defvar`` statements are shown with
|
|
|
799 their values.
|
|
|
800
|
|
|
801 * The classes are shown with their source location, template arguments,
|
|
|
802 superclasses, and fields.
|
|
|
803
|
|
|
804 * The records are shown with their source location, ``defm`` sequence,
|
|
|
805 superclasses, and fields.
|
|
|
806
|
|
|
807 Superclasses are shown in the order processed, with indirect superclasses in
|
|
|
808 parentheses. Each field is shown with its value and the source location at
|
|
|
809 which it was set.
|
|
|
810 The ``defm`` sequence gives the locations of the ``defm`` statements that
|
|
|
811 were involved in generating the record, in the order they were invoked.
|
|
|
812
|
|
|
813 Timing TableGen Phases
|
|
|
814 ----------------------
|
|
|
815
|
|
|
816 TableGen provides a phase timing feature that produces a report of the time
|
|
|
817 used by the various phases of parsing the source files and running the
|
|
|
818 selected backend. This feature is enabled with the ``--time-phases`` option
|
|
|
819 of the TableGen command.
|
|
|
820
|
|
|
821 If the backend is *not* instrumented for timing, then a report such as the
|
|
|
822 following is produced. This is the timing for the
|
|
|
823 ``--print-detailed-records`` backend run on the AMDGPU target.
|
|
|
824
|
|
|
825 .. code-block:: text
|
|
|
826
|
|
|
827 ===-------------------------------------------------------------------------===
|
|
|
828 TableGen Phase Timing
|
|
|
829 ===-------------------------------------------------------------------------===
|
|
|
830 Total Execution Time: 101.0106 seconds (102.4819 wall clock)
|
|
|
831
|
|
|
832 ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name ---
|
|
|
833 85.5197 ( 84.9%) 0.1560 ( 50.0%) 85.6757 ( 84.8%) 85.7009 ( 83.6%) Backend overall
|
|
|
834 15.1789 ( 15.1%) 0.0000 ( 0.0%) 15.1789 ( 15.0%) 15.1829 ( 14.8%) Parse, build records
|
|
|
835 0.0000 ( 0.0%) 0.1560 ( 50.0%) 0.1560 ( 0.2%) 1.5981 ( 1.6%) Write output
|
|
|
836 100.6986 (100.0%) 0.3120 (100.0%) 101.0106 (100.0%) 102.4819 (100.0%) Total
|
|
|
837
|
|
|
838 Note that all the time for the backend is lumped under "Backend overall".
|
|
|
839
|
|
|
840 If the backend is instrumented for timing, then its processing is
|
|
|
841 divided into phases and each one timed separately. This is the timing for
|
|
|
842 the ``--emit-dag-isel`` backend run on the AMDGPU target.
|
|
|
843
|
|
|
844 .. code-block:: text
|
|
|
845
|
|
|
846 ===-------------------------------------------------------------------------===
|
|
|
847 TableGen Phase Timing
|
|
|
848 ===-------------------------------------------------------------------------===
|
|
|
849 Total Execution Time: 746.3868 seconds (747.1447 wall clock)
|
|
|
850
|
|
|
851 ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Name ---
|
|
|
852 657.7938 ( 88.1%) 0.1404 ( 90.0%) 657.9342 ( 88.1%) 658.6497 ( 88.2%) Emit matcher table
|
|
|
853 70.2317 ( 9.4%) 0.0000 ( 0.0%) 70.2317 ( 9.4%) 70.2700 ( 9.4%) Convert to matchers
|
|
|
854 14.8825 ( 2.0%) 0.0156 ( 10.0%) 14.8981 ( 2.0%) 14.9009 ( 2.0%) Parse, build records
|
|
|
855 2.1840 ( 0.3%) 0.0000 ( 0.0%) 2.1840 ( 0.3%) 2.1791 ( 0.3%) Sort patterns
|
|
|
856 1.1388 ( 0.2%) 0.0000 ( 0.0%) 1.1388 ( 0.2%) 1.1401 ( 0.2%) Optimize matchers
|
|
|
857 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0050 ( 0.0%) Write output
|
|
|
858 746.2308 (100.0%) 0.1560 (100.0%) 746.3868 (100.0%) 747.1447 (100.0%) Total
|
|
|
859
|
|
|
860 The backend has been divided into four phases and timed separately.
|
|
|
861
|
|
|
862 If you want to instrument a backend, refer to the backend ``DAGISelEmitter.cpp``
|
|
|
863 and search for ``Records.startTimer``. |
