Index: llvm/docs/TableGen/ProgRef.rst =================================================================== --- llvm/docs/TableGen/ProgRef.rst +++ llvm/docs/TableGen/ProgRef.rst @@ -15,7 +15,7 @@ output files would be, and also easier to maintain and modify over time. The information is coded in a declarative style involving classes and records, which are then processed by TableGen. The internalized records are passed on -to various backends, which extract information from a subset of the records +to various *backends*, which extract information from a subset of the records and generate one or more output files. These output files are typically ``.inc`` files for C++, but may be any type of file that the backend developer needs. @@ -62,12 +62,19 @@ Classes and concrete records have a unique *name*, either chosen by the programmer or generated by TableGen. Associated with that name -is a list of *fields* with values and an optional list of *superclasses* -(sometimes called base or parent classes). The fields are the primary data that +is a list of *fields* with values and an optional list of *parent classes* +(sometimes called base or super classes). The fields are the primary data that backends will process. Note that TableGen assigns no meanings to fields; the meanings are entirely up to the backends and the programs that incorporate the output of those backends. +.. note:: + + The term "parent class" can refer to a class that is a parent of another + class, and also to a class from which a concrete record inherits. This + nonstandard use of the term occurs because TableGen treats classes and + concrete records similarly. + A backend processes some subset of the concrete records built by the TableGen parser and emits the output files. These files are usually C++ ``.inc`` files that are included by the programs that require the data in @@ -86,10 +93,10 @@ abstracts common "sub-concepts" from the two original concepts. In order to make classes more useful, a concrete record (or another class) -can request a class as a superclass and pass *template arguments* to it. -These template arguments can be used in the fields of the superclass to +can request a class as a parent class and pass *template arguments* to it. +These template arguments can be used in the fields of the parent class to initialize them in a custom manner. That is, record or class ``A`` can -request superclass ``S`` with one set of template arguments, while record or class +request parent class ``S`` with one set of template arguments, while record or class ``B`` can request ``S`` with a different set of arguments. Without template arguments, many more classes would be required, one for each combination of the template arguments. @@ -474,12 +481,11 @@ CondClause: `Value` ":" `Value` The bang operators provide functions that are not available with the other -simple values. Except in the case of ``!cond``, a bang -operator takes a list of arguments enclosed in parentheses and performs some -function on those arguments, producing a value for that -bang operator. The ``!cond`` operator takes a list of pairs of arguments -separated by colons. See `Appendix A: Bang Operators`_ for a description of -each bang operator. +simple values. Except in the case of ``!cond``, a bang operator takes a list +of arguments enclosed in parentheses and performs some function on those +arguments, producing a value for that bang operator. The ``!cond`` operator +takes a list of pairs of arguments separated by colons. See `Appendix A: +Bang Operators`_ for a description of each bang operator. Suffixed values @@ -571,7 +577,7 @@ values are evaluated from left to right. The :token:`RecordBody` is defined below. It can include a list of -superclasses from which the current class inherits, along with field +parent classes from which the current class inherits, along with field definitions and other statements. When a class ``C`` inherits from another class ``D``, the fields of ``D`` are effectively merged into the fields of ``C``. @@ -594,8 +600,8 @@ Every class has an implicit template argument named ``NAME`` (uppercase), which is bound to the name of the :token:`Def` or :token:`Defm` inheriting -the class. The value of ``NAME`` is undefined if the class is inherited by -an anonymous record. +from the class. If the class is inherited by an anonymous record, the name +is unspecified but globally unique. See `Examples: classes and records`_ for examples. @@ -605,7 +611,7 @@ Record bodies appear in both class and record definitions. A record body can include a parent class list, which specifies the classes from which the current class or record inherits fields. Such classes are called the -superclasses or parent classes of the class or record. The record body also +parent classes of the class or record. The record body also includes the main body of the definition, which contains the specification of the fields of the class or record. @@ -633,9 +639,9 @@ has a string value that is code. The ``let`` form is used to reset a field to a new value. This can be done -for fields defined directly in the body or fields inherited from -superclasses. A :token:`RangeList` can be specified to reset certain bits -in a ``bit`` field. +for fields defined directly in the body or fields inherited from parent +classes. A :token:`RangeList` can be specified to reset certain bits in a +``bit`` field. The ``defvar`` form defines a variable whose value can be used in other value expressions within the body. The variable is not a field: it does not @@ -659,12 +665,13 @@ .. productionlist:: Def: "def" [`NameValue`] `RecordBody` - NameValue: `Value` (parsed in a special manner) + NameValue: `Value` (parsed in a special mode) The name value is optional. If specified, it is parsed in a special mode where undefined (unrecognized) identifiers are interpreted as literal strings. In particular, global identifiers are considered unrecognized. -These include global variables defined by ``defvar`` and ``defset``. +These include global variables defined by ``defvar`` and ``defset``. A +record name can be the null string. If no name value is given, the record is *anonymous*. The final name of an anonymous record is unspecified but globally unique. @@ -678,8 +685,8 @@ parent classes provide the same field, the record ends up with the field value of the last parent class. -As a special case, the name of a record can be passed in a template argument -to that record's superclasses. For example: +As a special case, the name of a record can be passed as a template argument +to that record's parent classes. For example: .. code-block:: text @@ -719,7 +726,7 @@ that is a bit initialized to true. Next, two records are defined, derived from class ``C``; that is, with ``C`` -as their superclass. Thus they both inherit the ``V`` field. Record ``Y`` +as their parent class. Thus they both inherit the ``V`` field. Record ``Y`` also defines another string field, ``Greeting``, which is initialized to ``"Hello!"``. In addition, ``Y`` overrides the inherited ``V`` field, setting it to false. @@ -731,7 +738,7 @@ TableGen supports the definition of parameterized classes as well as nonparameterized ones. Parameterized classes specify a list of variable declarations, which may optionally have defaults, that are bound when the -class is specified as a superclass of another class or record. +class is specified as a parent class of another class or record. .. code-block:: text @@ -750,8 +757,8 @@ The purpose of the ``FPFormat`` class is to act as a sort of enumerated type. It provides a single field, ``Value``, which holds a 3-bit number. Its -template argument, ``val``, is used to set the ``Value`` field. -Each of the eight records is defined with ``FPFormat`` as its superclass. The +template argument, ``val``, is used to set the ``Value`` field. Each of the +eight records is defined with ``FPFormat`` as its parent class. The enumeration value is passed in angle brackets as the template argument. Each record will inherent the ``Value`` field with the appropriate enumeration value. @@ -835,7 +842,7 @@ The field names in the :token:`LetList` must name fields in classes inherited by the classes and records defined in the statements. The field values are applied to the classes and records *after* the records inherit all the fields from -their superclasses. So the ``let`` acts to override inherited field +their parent classes. So the ``let`` acts to override inherited field values. A ``let`` cannot override the value of a template argument. Top-level ``let`` statements are often useful when a few fields need to be @@ -869,7 +876,7 @@ While classes with template arguments are a good way to factor out commonality between multiple records, multiclasses allow a convenient method for -defining multiple records at once. For example, consider a 3-address +defining many records at once. For example, consider a 3-address instruction architecture whose instructions come in two formats: ``reg = reg op reg`` and ``reg = reg op imm`` (e.g., SPARC). We would like to specify in one place that these two common formats exist, then in a separate place @@ -891,22 +898,22 @@ contains a series of statements that define records, using :token:`Def` and :token:`Defm`. In addition, :token:`Defvar`, :token:`Foreach`, and :token:`Let` statements can be used to factor out even more common elements. -The :token:`If` statement can also be used. +The :token:`If` and :token:`Assert` statements can also be used. Also as with regular classes, the multiclass has the implicit template argument ``NAME`` (see NAME_). When a named (non-anonymous) record is -defined in a multiclass and the record's name does not contain a use of the -template argument ``NAME``, such a use is automatically prepended +defined in a multiclass and the record's name does not include a use of the +template argument ``NAME``, such a use is automatically *prepended* to the name. That is, the following are equivalent inside a multiclass:: def Foo ... - def NAME#Foo ... + def NAME # Foo ... -The records defined in a multiclass are instantiated when the multiclass is +The records defined in a multiclass are created when the multiclass is "instantiated" or "invoked" by a ``defm`` statement outside the multiclass -definition. Each ``def`` statement produces a record. As with top-level -``def`` statements, these definitions can inherit from multiple -superclasses. +definition. Each ``def`` statement in the multiclass produces a record. As +with top-level ``def`` statements, these definitions can inherit from +multiple parent classes. See `Examples: multiclasses and defms`_ for examples. @@ -915,7 +922,7 @@ ----------------------------------------------------------- Once multiclasses have been defined, you use the ``defm`` statement to -"invoke" multiclasses and process the multiple record definitions in those +"invoke" them and process the multiple record definitions in those multiclasses. Those record definitions are specified by ``def`` statements in the multiclasses, and indirectly by ``defm`` statements. @@ -935,8 +942,8 @@ a common set of fields to all the records created by the ``defm``. The name is parsed in the same special mode used by ``def``. If the name is -not included, a globally unique name is provided. That is, the following -examples end up with different names:: +not included, an unspecified but globally unique name is provided. That is, +the following examples end up with different names:: defm : SomeMultiClass<...>; // A globally unique name. defm "" : SomeMultiClass<...>; // An empty name. @@ -951,8 +958,8 @@ be prepended automatically. That is, the following are equivalent inside a multiclass:: - defm Foo : SomeMultiClass<...>; - defm NAME#Foo : SomeMultiClass<...>; + defm Foo : SomeMultiClass<...>; + defm NAME # Foo : SomeMultiClass<...>; See `Examples: multiclasses and defms`_ for examples. @@ -1372,12 +1379,12 @@ 1. Build the record name (:token:`NameValue`) and create an empty record. -2. Parse the superclasses in the :token:`ParentClassList` from left to - right, visiting each superclass's ancestor classes from top to bottom. +2. Parse the parent classes in the :token:`ParentClassList` from left to + right, visiting each parent class's ancestor classes from top to bottom. - a. Add the fields from the superclass to the record. + a. Add the fields from the parent class to the record. b. Substitute the template arguments into those fields. - c. Add the superclass to the record's list of inherited classes. + c. Add the parent class to the record's list of inherited classes. 3. Apply any top-level ``let`` bindings to the record. Recall that top-level bindings only apply to inherited fields. @@ -1605,7 +1612,7 @@ Due to limitations of the type system, *arguments* must be a list of items of a common type. In practice, this means that they should either have the - same type or be records with a common superclass. Mixing ``dag`` and + same type or be records with a common parent class. Mixing ``dag`` and non-``dag`` items is not possible. However, ``?`` can be used. Example: ``!dag(op, [a1, a2, ?], ["name1", "name2", "name3"])`` results in @@ -1976,8 +1983,8 @@ On the first line of the record, you can see that the ``ADD32rr`` record inherited from eight classes. Although the inheritance hierarchy is complex, -using superclasses is much simpler than specifying the 109 individual fields for each -instruction. +using parent classes is much simpler than specifying the 109 individual +fields for each instruction. Here is the code fragment used to define ``ADD32rr`` and multiple other ``ADD`` instructions: