Lines Matching full:the
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
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
20 for C++, but may be any type of file that the backend developer needs.
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.
28 This document assumes that you have read the :doc:`TableGen Programmer's
30 TableGen source files. For a description of the existing backends, see
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.
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
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.
57 In addition to the two maps, the ``RecordKeeper`` instance contains:
59 * A map that maps the names of global variables to their values.
65 The ``RecordKeeper`` class provides a few useful functions.
67 * Functions to get the complete class and record maps.
69 * Functions to get a subset of the records based on their parent classes.
73 A ``RecordKeeper`` instance can be printed to an output stream with the ``<<``
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.
85 The record name is stored as a pointer to an ``Init`` (see `Init`_), which
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
95 * A vector of source file locations that includes the record definition
96 itself, plus the locations of any multiclasses involved in its definition.
98 * For a class record, a vector of the class's template arguments.
108 The ``Record`` class provides many useful functions.
110 * Functions to get the record name, fields, source file locations,
113 * Functions to get all the record's superclasses or just its direct
120 * Boolean functions to check the various attributes of the record.
122 A ``Record`` instance can be printed to an output stream with the ``<<``
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
135 In addition to those primary members, the ``RecordVal`` has other data members.
137 * The source file location of the field definition.
139 * The type of the field, stored as an instance
140 of the ``RecTy`` class (see `RecTy`_).
142 The ``RecordVal`` class provides some useful functions.
144 * Functions to get the name of the field in various forms.
146 * A function to get the type of the field.
148 * A function to get the value of the field.
150 * A function to get the source file location.
152 Note that field values are more easily obtained directly from the ``Record``
155 A ``RecordVal`` instance can be printed to an output stream with the ``<<``
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
167 The ``RecTy`` class provides a few useful functions.
169 * A virtual function to get the type name as a string.
171 * A virtual function to check whether all the values of this type can
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.
181 The subclasses that inherit from ``RecTy`` are
191 are described in the following subsections.
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.
199 A ``RecTy`` instance can be printed to an output stream with the ``<<``
210 This class includes a data member with the size of the ``bits`` value and a
213 The ``get()`` function takes the length of the sequence, *n*, and returns the
219 This class includes a data member that specifies the type of the list's
222 The ``get()`` function takes the ``RecTy`` *type* of the list members and
223 returns the ``ListRecTy`` type corresponding to ``list<``\ *type*\ ``>``.
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.
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.
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
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.
252 The ``Init`` class provides a few useful functions.
254 * A function to get the type enumerator.
259 * Virtual functions to get the value as a string.
261 * Virtual functions to cast the value to other types, implement the bit
262 range feature of TableGen, and implement the list slice feature.
264 * A virtual function to get a particular bit of the value.
266 The subclasses that inherit directly from ``Init`` are
269 An ``Init`` instance can be printed to an output stream with the ``<<``
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``.
280 This class, a subclass of ``Init``, represents the unset (uninitialized)
281 value. The static function ``get()`` can be used to obtain the singleton
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
292 types used by the TableGen parser.)
294 This class includes a data member that specifies the ``RecTy`` type of the
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.
304 *All* of the classes derived from ``TypedInit`` provide the following functions.
307 the specified value(s). In the case of ``BitInit``, ``get(true)`` returns
313 * A function named ``GetValue()`` that returns the value of the instance
319 The ``BitsInit`` class is a subclass of ``TypedInit``. Its instances
321 data member with the length of the sequence and a vector of pointers to
324 The class provides the usual ``get()`` function. It does not provide the
327 The class provides the following additional functions.
329 * A function to get the number of bits in the sequence.
336 The ``DagInit`` class is a subclass of ``TypedInit``. Its instances
337 represent the possible direct acyclic graphs (``dag``).
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*.)
346 The class provides two forms of the usual ``get()`` function. It does not
347 provide the usual ``getValue()`` function.
349 The class provides many additional functions:
351 * Functions to get the operator in various forms and to get the
354 * Functions to determine whether there are any operands and to get the
357 * Functions to the get the operands, both individually and together.
360 get the number of names
362 * Functions to the get the names, both individually and together.
364 * Functions to get the operand iterator ``begin()`` and ``end()`` values.
366 * Functions to get the name iterator ``begin()`` and ``end()`` values.
368 The class defines two types for the return values of the operand and name
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.
384 The class provides the usual ``get()`` function. It does not provide
385 ``getValue()``. Instead, it provides ``getDef()``, which returns the
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.
395 The class provides the usual ``get()`` and ``getValue()`` functions. The
396 latter function returns the integer as an ``int64_t``.
398 The class also provides a function, ``getBit()``, to obtain a specified bit
399 of the integer value.
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
409 The class provides the usual ``get()`` and ``getValues()`` functions. The
410 latter function returns an ``ArrayRef`` of the vector of pointers to ``Init``
413 The class provides these additional functions.
415 * A function to get the element type.
417 * Functions to get the length of the vector and to determine whether
423 * Functions to get the iterator ``begin()`` and ``end()`` values. The
424 class defines a type for the return type of these two functions.
434 The ``StringInit`` class is a subclass of ``TypedInit``. Its instances
436 that contains a ``StringRef`` of the value.
438 The class provides the usual ``get()`` and ``getValue()`` functions. The
439 latter function returns the ``StringRef``.
444 The following steps are required to create a new backend for TableGen.
448 #. Write the new backend, using the file ``TableGenBackendSkeleton.cpp``
451 #. Determine which instance of TableGen requires the new backend. There is
455 #. Add your backend C++ file to the appropriate ``CMakeLists.txt`` file so
458 #. Add your C++ file to the system.
460 The Backend Skeleton
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.
466 * The list of includes is the minimal list required by most backends.
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,
474 * The constructor for the emitter class accepts a ``RecordKeeper`` reference,
475 typically named ``RK``. The ``RecordKeeper`` reference is saved in a data
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
484 * The ``run`` function should use the ``emitSourceFileHeader`` helper function
485 to include a standard header in the emitted file.
487 * Register the class or the function as the command line option
491 if the class has the constructor ``(RK)`` and
492 the method ``run(OS)``.
496 All the examples in the remainder of this document will assume the naming
497 conventions used in the skeleton file.
502 The ``RecordKeeper`` class provides two functions for getting the
503 ``Record`` instances for classes defined in the TableGen files.
505 * ``getClasses()`` returns a ``RecordMap`` reference for all the classes.
507 * ``getClass(``\ *name*\ ``)`` returns a ``Record`` reference for the named
510 If you need to iterate over all the class records:
519 ``ClassPair.second`` gets the class's ``unique_ptr``, then ``.get()`` gets the
526 The ``RecordKeeper`` class provides four functions for getting the
527 ``Record`` instances for concrete records defined in the TableGen files.
529 * ``getDefs()`` returns a ``RecordMap`` reference for all the concrete
532 * ``getDef(``\ *name*\ ``)`` returns a ``Record`` reference for the named
536 ``Record`` references for the concrete records that derive from the
540 a vector of ``Record`` references for the concrete records that derive from
541 *all* of the given classes.
543 This statement obtains all the records that derive from the ``Attribute``
557 return the name of a record. One particularly useful one is
558 ``getNameInitAsString()``, which returns the name as a ``std::string``.
560 There are also multiple functions that return the fields of a record. To
561 obtain and iterate over all the fields:
569 You will recall that ``RecordVal`` is the class whose instances contain
570 information about the fields in records.
572 The ``getValue()`` function returns the ``RecordVal`` instance for a field
575 ``RecordVal *`` and others return a ``const RecordVal *``. If the field does
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
581 ``getValueInit``, returns the value as an ``Init *``. Another function,
582 ``isValueUnset``, returns a boolean specifying whether the value is unset
585 Most of the functions return the value in some more useful form. For
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
598 null if the field does not exist.
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
613 The ``Record`` class provides a function to obtain the superclasses of a
615 array of ``std::pair`` pairs. The superclasses are in post-order: the order
616 in which the superclasses were visited while copying their fields into the
617 record. Each pair consists of a pointer to the ``Record`` instance for a
618 superclass record and an instance of the ``SMRange`` class. The range
619 indicates the source file locations of the beginning and end of the class
622 This example obtains the superclasses of the ``Prototype`` record and then
623 iterates over the pairs in the returned array.
633 The ``Record`` class also provides a function, ``getDirectSuperClasses``, to
634 append the *direct* superclasses of a record to a given vector of type
637 Emitting Text to the Output Stream
640 The ``run`` function is passed a ``raw_ostream`` to which it prints the
641 output file. By convention, this stream is saved in the emitter class member
642 named ``OS``, although some ``run`` functions are simple and just use the
643 stream without saving it. The output can be produced by writing values
644 directly to the output stream, or by using the ``std::format()`` or
653 Instances of the following classes can be printed using the ``<<`` operator:
660 The helper function ``emitSourceFileHeader()`` prints the header comment
661 that should be included at the top of every output file. A call to it is
662 included in the skeleton backend file ``TableGenBackendSkeleton.cpp``.
679 * ``PrintNote`` prints a note. It is often used after one of the previous
687 Prints the message with no source file location.
690 Prints the message followed by the specified source line,
691 along with a pointer to the item in error. The array of
695 Prints the message followed by the source line associated with the
699 Prints the message followed by the source line associated with the
702 Using these functions, the goal is to produce the most specific error report
710 The ``PrintRecords`` Backend
713 The TableGen command option ``--print-records`` invokes a simple backend
714 that prints all the classes and records defined in the source files. This is
715 the default backend option. The format of the output is guaranteed to be
716 constant over time, so that the output can be compared in tests. The output
750 The ``PrintDetailedRecords`` Backend
753 The TableGen command option ``--print-detailed-records`` invokes a backend
754 that prints all the global variables, classes, and records defined in the
755 source files. The format of the output is *not* guaranteed to be constant
756 over time. The output looks like this.
790 * The classes are shown with their source location, template arguments,
793 * The records are shown with their source location, ``defm`` sequence,
796 Superclasses are shown in the order processed, with indirect superclasses in
797 parentheses. Each field is shown with its value and the source location at
799 The ``defm`` sequence gives the locations of the ``defm`` statements that
800 were involved in generating the record, in the order they were invoked.
805 TableGen provides a phase timing feature that produces a report of the time
806 used by the various phases of parsing the source files and running the
807 selected backend. This feature is enabled with the ``--time-phases`` option
808 of the TableGen command.
810 If the backend is *not* instrumented for timing, then a report such as the
811 following is produced. This is the timing for the
812 ``--print-detailed-records`` backend run on the AMDGPU target.
827 Note that all the time for the backend is lumped under "Backend overall".
829 If the backend is instrumented for timing, then its processing is
830 divided into phases and each one timed separately. This is the timing for
831 the ``--emit-dag-isel`` backend run on the AMDGPU target.
849 The backend has been divided into four phases and timed separately.
851 If you want to instrument a backend, refer to the backend ``DAGISelEmitter.cpp``