TableGen: Streamline the semantics of NAME

Summary:
The new rules are straightforward. The main rules to keep in mind
are:

1. NAME is an implicit template argument of class and multiclass,
   and will be substituted by the name of the instantiating def/defm.

2. The name of a def/defm in a multiclass must contain a reference
   to NAME. If such a reference is not present, it is automatically
   prepended.

And for some additional subtleties, consider these:

3. defm with no name generates a unique name but has no special
   behavior otherwise.

4. def with no name generates an anonymous record, whose name is
   unique but undefined. In particular, the name won't contain a
   reference to NAME.

Keeping rules 1&2 in mind should allow a predictable behavior of
name resolution that is simple to follow.

The old "rules" were rather surprising: sometimes (but not always),
NAME would correspond to the name of the toplevel defm. They were
also plain bonkers when you pushed them to their limits, as the old
version of the TableGen test case shows.

Having NAME correspond to the name of the toplevel defm introduces
"spooky action at a distance" and breaks composability:
refactoring the upper layers of a hierarchy of nested multiclass
instantiations can cause unexpected breakage by changing the value
of NAME at a lower level of the hierarchy. The new rules don't
suffer from this problem.

Some existing .td files have to be adjusted because they ended up
depending on the details of the old implementation.

Change-Id: I694095231565b30f563e6fd0417b41ee01a12589

Reviewers: tra, simon_tatham, craig.topper, MartinO, arsenm, javed.absar

Subscribers: wdng, llvm-commits

Differential Revision: https://reviews.llvm.org/D47430

llvm-svn: 333900

2 files changed, 45 insertions, 23 deletions

diff --git a/llvm/docs/TableGen/LangRef.rst b/llvm/docs/TableGen/LangRef.rst
index 9e492410b16..d31f7f36c80 100644
--- a/llvm/docs/TableGen/LangRef.rst
+++ b/llvm/docs/TableGen/LangRef.rst
@@ -125,6 +125,7 @@ TableGen's top-level production consists of "objects".
 
 .. productionlist::
    Class: "class" `TokIdentifier` [`TemplateArgList`] `ObjectBody`
+   TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
 
 A ``class`` declaration creates a record which other records can inherit
 from. A class can be parametrized by a list of "template arguments", whose
@@ -145,8 +146,9 @@ forward declaration: note that records deriving from the forward-declared
 class will inherit no fields from it since the record expansion is done
 when the record is parsed.
 
-.. productionlist::
-   TemplateArgList: "<" `Declaration` ("," `Declaration`)* ">"
+Every class has an implicit template argument called ``NAME``, which is set
+to the name of the instantiating ``def`` or ``defm``. The result is undefined
+if the class is instantiated by an anonymous record.
 
 Declarations
 ------------
@@ -246,6 +248,8 @@ of:
        int Baz = Bar;
      }
 
+* the implicit template argument ``NAME`` in a ``class`` or ``multiclass``
+
 .. productionlist::
    SimpleValue: `TokInteger`
 
@@ -332,31 +336,56 @@ The ``let`` form allows overriding the value of an inherited field.
 ``def``
 -------
 
-.. TODO::
-   There can be pastes in the names here, like ``#NAME#``. Look into that
-   and document it (it boils down to ParseIDValue with IDParseMode ==
-   ParseNameMode). ParseObjectName calls into the general ParseValue, with
-   the only different from "arbitrary expression parsing" being IDParseMode
-   == Mode.
-
 .. productionlist::
-   Def: "def" `TokIdentifier` `ObjectBody`
+   Def: "def" [`Value`] `ObjectBody`
+
+Defines a record whose name is given by the optional :token:`Value`. The value
+is parsed in a special mode where global identifiers (records and variables
+defined by ``defset``) are not recognized, and all unrecognized identifiers
+are interpreted as strings.
 
-Defines a record whose name is given by the :token:`TokIdentifier`. The
-fields of the record are inherited from the base classes and defined in the
-body.
+If no name is given, the record is anonymous. The final name of anonymous
+records is undefined, but globally unique.
 
 Special handling occurs if this ``def`` appears inside a ``multiclass`` or
 a ``foreach``.
 
+When a non-anonymous record is defined in a multiclass and the given name
+does not contain a reference to the implicit template argument ``NAME``, such
+a reference will automatically be prepended. That is, the following are
+equivalent inside a multiclass::
+
+    def Foo;
+    def NAME#Foo;
+
 ``defm``
 --------
 
 .. productionlist::
-   Defm: "defm" [`TokIdentifier`] ":" `BaseClassListNE` ";"
+   Defm: "defm" [`Value`] ":" `BaseClassListNE` ";"
+
+The :token:`BaseClassList` is a list of at least one ``multiclass`` and any
+number of ``class``'s. The ``multiclass``'s must occur before any ``class``'s.
+
+Instantiates all records defined in all given ``multiclass``'s and adds the
+given ``class``'s as superclasses.
+
+The name is parsed in the same special mode used by ``def``. If the name is
+missing, a globally unique string is used instead (but instantiated records
+are not considered to be anonymous, unless they were originally defined by an
+anonymous ``def``) That is, the following have different semantics::
+
+    defm : SomeMultiClass<...>;    // some globally unique name
+    defm "" : SomeMultiClass<...>; // empty name string
+
+When it occurs inside a multiclass, the second variant is equivalent to
+``defm NAME : ...``. More generally, when ``defm`` occurs in a multiclass and
+its name does not contain a reference to the implicit template argument
+``NAME``, such a reference will automatically be prepended. That is, the
+following are equivalent inside a multiclass::
 
-Note that in the :token:`BaseClassList`, all of the ``multiclass``'s must
-precede any ``class``'s that appear.
+    defm Foo : SomeMultiClass<...>;
+    defm NAME#Foo : SomeMultiClass<...>;
 
 ``defset``
 ----------
diff --git a/llvm/docs/TableGen/index.rst b/llvm/docs/TableGen/index.rst
index e6800fac64e..a19b4f82b63 100644
--- a/llvm/docs/TableGen/index.rst
+++ b/llvm/docs/TableGen/index.rst
@@ -171,13 +171,6 @@ factor out the common features that instructions of its class share.  A key
 feature of TableGen is that it allows the end-user to define the abstractions
 they prefer to use when describing their information.
 
-Each ``def`` record has a special entry called "NAME".  This is the name of the
-record ("``ADD32rr``" above).  In the general case ``def`` names can be formed
-from various kinds of string processing expressions and ``NAME`` resolves to the
-final value obtained after resolving all of those expressions.  The user may
-refer to ``NAME`` anywhere she desires to use the ultimate name of the ``def``.
-``NAME`` should not be defined anywhere else in user code to avoid conflicts.
-
 Syntax
 ======