Index: llvm/docs/TableGen/ProgRef.rst =================================================================== --- llvm/docs/TableGen/ProgRef.rst +++ llvm/docs/TableGen/ProgRef.rst @@ -62,8 +62,8 @@ 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. @@ -86,10 +86,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. @@ -571,7 +571,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 +594,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 +605,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 or superclasses 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 +633,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 +659,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 +679,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 +720,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 +732,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 +751,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 +836,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 +870,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 +892,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 +916,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 +936,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 +952,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 +1373,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 +1606,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 +1977,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: