maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

[TableGen] [docs] Improve description of NAME in Programmer's Reference 

Also use "parent class" consistently and add a note about the term.

Differential Revision: https://reviews.llvm.org/D100867
This commit is contained in:
Paul C. Anagnostopoulos 2021-04-20 13:05:56 -04:00
parent 59b6849012
commit 6a067cdb06
1 changed files with 56 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

105
llvm/docs/TableGen/ProgRef.rst
View File

@ -15,7 +15,7 @@ information from source files that are significantly easier to code than the
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 @@ concrete records. The distinction should be clear in context.
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 arises 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 @@ so that the abstract classes for two concepts can share a third superclass that
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 @@ See `Using Classes as Subroutines`_ for more information.
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 @@ arguments must precede any optional arguments. The template argument default
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 @@ their declarations are parsed, and thus before the class is finally defined.
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
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 @@ the value. The keyword ``code`` may be used to emphasize that the field
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<n>`` 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<n>`` 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 @@ A ``def`` statement defines a new concrete record.
.. 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 @@ the fields in the parent classes are added to the record. If two or more
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 @@ First, the abstract class ``C`` is defined. It has one field named ``V``
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 @@ records inheriting from that class can override the defaults.
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 @@ class is specified as a superclass of another class or record.
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 @@ in braces or a single statement with no braces. The bindings in the
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 @@ themselves.
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 @@ definitions in the inheriting multiclass. The body of the multiclass
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 @@ See `Examples: multiclasses and defms`_ for examples.
-----------------------------------------------------------
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 @@ regular classes included in the parent class list. This is useful for adding
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 @@ include a use of the implicit template argument ``NAME``, then ``NAME`` will
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 @@ abstract records and so go through the same steps.
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 @@ and non-0 as true.
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 @@ register-to-register ADD instruction.
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: