Debian Codegraph @

llvm/docs/TableGen/BackGuide.rst

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