[Docs] Fix IR and TableGen grammar inconsistencies

[sebastian-ne]

Summary

IR:

• globals (and functions, ifuncs, aliases) can have a partition
• catchret has a to before the label
• the sint/int types do not exist
• signext comes after the type
• a variable was missing its type

TableGen:

• The second value after a # concatenation is optional See e.g. llvm/lib/Target/X86/X86InstrAVX512.td:L3351
• IncludeDirective and PreprocessorDirective were never referenced in the grammar
• Add some missing ;
• Parent classes of multiclasses can have generic arguments. Reuse the ParentClassList that is already used in other places.

MIR:

• liveins only allows physical registers, which start with a $

[nikic]

LangRef changes look fine with some nits. Can't comment on the rest.

llvm/docs/LangRef.rst

741–743

I'd move partition next to section here.

840–842

Duplicate section, supposed to be partition?

[sebastian-ne]

Thanks for taking a look and spotting these, I fixed your comments.

[Paul-C-Anagnostopoulos]

Thanks for making these corrections to the TableGen document. See my comments above.

llvm/docs/TableGen/ProgRef.rst

333

If we are going to specify that the right operand is optional, we should explain elsewhere what that does. I have no idea, but I'm suspicious that the example you cited above is an error.

555

Those two directives are not included in Statement because they are not actually statements. Instead, extend TableGenFile with IncludeDirective and PreprocessorDirective.

893

I'm tempted to leave this alone. It makes it clear that the ParentMultiClassList is composed of MultiClassIDs.

[sebastian-ne]

Moved include and preprocessor directive to TableGenFile. Thanks for the review Paul.

llvm/docs/TableGen/ProgRef.rst

333

Looking into the code, it looks like a feature?

// Trailing paste, concat with an empty string.
RHS = StringInit::get("");

https://github.com/llvm/llvm-project/blob/7c19fdd59939249c23384f0900d49aab4a5f0695/llvm/lib/TableGen/TGParser.cpp#L2521-L2522

893

The problem is that ParentMultiClassList is only a list of identifiers, not of identifier + optional generic arguments.
The definition of ParentClassList actually references MultiClassID (and optional generic arguments) and is also used in the defm definition. So I think ParentClassList is correct here?

[Paul-C-Anagnostopoulos]

llvm/docs/TableGen/ProgRef.rst

333

Yep, you are right. What a silly feature. I'm tempted to get rid of it and require # "".

Anyhoo, can you update the description of the paste operator to explain what this does?

893

Oh, what's there now is extraneous and incorrect. Carry on. Thanks!

[sebastian-ne]

Add a sentence about trailing # in tablegen.

[Paul-C-Anagnostopoulos]

ProgRef.rst looks good to me.

[sebastian-ne]

Thanks, it looks like all changes here should be good to go. Can one of you press the accept button please?

[foad]

+ @pcc for the partition stuff. But it all LGTM.

llvm/docs/LangRef.rst

 
 Syntax::
 
       @<GlobalVarName> = [Linkage] [PreemptionSpecifier] [Visibility]
                          [DLLStorageClass] [ThreadLocal]
                          [(unnamed_addr|local_unnamed_addr)] [AddrSpace]
                          [ExternallyInitialized]
                          <global | constant> <Type> [<InitializerConstant>]
-                         [, section "name"] [, comdat [($name)]]
-                         [, align <Alignment>] (, !name !N)*
+                         [, section "name"] [, partition "name"]
+                         [, comdat [($name)]] [, align <Alignment>]
+                         (, !name !N)*
 
 For example, the following defines a global in a numbered address space
 with an initializer, section, and alignment:
 
 .. code-block:: llvm
 
     @G = addrspace(5) constant float 1.0, section "foo", align 4
 

 address space from the :ref:`datalayout string<langref_datalayout>`.
 
 Syntax::
 
     define [linkage] [PreemptionSpecifier] [visibility] [DLLStorageClass]
            [cconv] [ret attrs]
            <ResultType> @<FunctionName> ([argument list])
            [(unnamed_addr|local_unnamed_addr)] [AddrSpace] [fn Attrs]
-           [section "name"] [comdat [($name)]] [align N] [gc] [prefix Constant]
-           [prologue Constant] [personality Constant] (!name !N)* { ... }
+           [section "name"] [partition "name"] [comdat [($name)]] [align N]
+           [gc] [prefix Constant] [prologue Constant] [personality Constant]
+           (!name !N)* { ... }
 
 The argument list is a comma separated sequence of arguments where each
 argument is of the following form:
 
 Syntax::
 
    <type> [parameter Attrs] [name]
 

 Aliases may have an optional :ref:`linkage type <linkage>`, an optional
 :ref:`runtime preemption specifier <runtime_preemption_model>`, an optional
 :ref:`visibility style <visibility>`, an optional :ref:`DLL storage class
 <dllstorageclass>` and an optional :ref:`tls model <tls_model>`.
 
 Syntax::
 
     @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] [DLLStorageClass] [ThreadLocal] [(unnamed_addr|local_unnamed_addr)] alias <AliaseeTy>, <AliaseeTy>* @<Aliasee>
+              [, partition "name"]
 
 The linkage must be one of ``private``, ``internal``, ``linkonce``, ``weak``,
 ``linkonce_odr``, ``weak_odr``, ``external``. Note that some system linkers
 might not correctly handle dropping a weak symbol that is aliased.
 
 Aliases that are not ``unnamed_addr`` are guaranteed to have the same address as
 the aliasee expression. ``unnamed_addr`` ones are only guaranteed to point
 to the same content.

 that returns address of another function associated with the name.
 
 IFunc may have an optional :ref:`linkage type <linkage>` and an optional
 :ref:`visibility style <visibility>`.
 
 Syntax::
 
     @<Name> = [Linkage] [PreemptionSpecifier] [Visibility] ifunc <IFuncTy>, <ResolverTy>* @<Resolver>
+              [, partition "name"]
 
 
 .. _langref_comdats:
 
 Comdats
 -------
 
 Comdat IR provides access to object file COMDAT/section group functionality

 funclet pad (as described in the `EH documentation\ <ExceptionHandling.html#wineh-constraints>`_),
 the ``catchret``'s behavior is undefined.
 
 Example:
 """"""""
 
 .. code-block:: text
 
-      catchret from %catch label %continue
+      catchret from %catch to label %continue
 
 .. _i_cleanupret:
 
 '``cleanupret``' Instruction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""

 element zero ends up in the most significant bits for big-endian.
 
 Example:
 """"""""
 
 .. code-block:: text
 
       %X = bitcast i8 255 to i8          ; yields i8 :-1
-      %Y = bitcast i32* %x to sint*      ; yields sint*:%x
-      %Z = bitcast <2 x int> %V to i64;  ; yields i64: %V (depends on endianess)
+      %Y = bitcast i32* %x to i16*      ; yields i16*:%x
+      %Z = bitcast <2 x i32> %V to i64;  ; yields i64: %V (depends on endianess)
       %Z = bitcast <2 x i32*> %V to <2 x i64*> ; yields <2 x i64*>
 
 .. _i_addrspacecast:
 
 '``addrspacecast .. to``' Instruction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:

 """"""""
 
 .. code-block:: llvm
 
       %retval = call i32 @test(i32 %argc)
       call i32 (i8*, ...)* @printf(i8* %msg, i32 12, i8 42)        ; yields i32
       %X = tail call i32 @foo()                                    ; yields i32
       %Y = tail call fastcc i32 @foo()  ; yields i32
-      call void %foo(i8 97 signext)
+      call void %foo(i8 signext 97)
 
       %struct.A = type { i32, i8 }
       %r = call %struct.A @foo()                        ; yields { i32, i8 }
       %gr = extractvalue %struct.A %r, 0                ; yields i32
       %gr1 = extractvalue %struct.A %r, 1               ; yields i8
       %Z = call void @foo() noreturn                    ; indicates that %foo never returns normally
       %ZZ = call zeroext i32 @bar()                     ; Return value is %zero extended
 
.. code-block:: llvm
       %res = landingpad { i8*, i32 }
                catch i8** @_ZTIi
       ;; A landing pad that is a cleanup.
       %res = landingpad { i8*, i32 }
                cleanup
       ;; A landing pad which can catch an integer and can only throw a double.
       %res = landingpad { i8*, i32 }
                catch i8** @_ZTIi
-               filter [1 x i8**] [@_ZTId]
+               filter [1 x i8**] [i8** @_ZTId]
 
 .. _i_catchpad:
 
 '``catchpad``' Instruction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""

llvm/docs/TableGen/ProgRef.rst

 application.
 
 Note that all of the values have rules for converting them from one type to
 another. For example, these rules allow you to assign a value like ``7``
 to an entity of type ``bits<4>``.
 
 .. productionlist::
    Value: `SimpleValue` `ValueSuffix`*
-        :| `Value` "#" `Value`
+        :| `Value` "#" [`Value`]
    ValueSuffix: "{" `RangeList` "}"
               :| "[" `RangeList` "]"
               :| "." `TokIdentifier`
    RangeList: `RangePiece` ("," `RangePiece`)*
    RangePiece: `TokInteger`
              :| `TokInteger` "..." `TokInteger`
              :| `TokInteger` "-" `TokInteger`
              :| `TokInteger` `TokInteger`

 verbatim string of characters. The value of a global name is not used.
 
 The paste operator can be used in all other value expressions, in which case
 it can construct a string or a list. Rather oddly, but consistent with the
 previous case, if the *right-hand-side* operand is an undefined name or a
 global name, it is treated as a verbatim string of characters. The
 left-hand-side operand is treated normally.
 
+Values can have a trailing paste operator, in which case the left-hand-side 
+operand is concatenated to an empty string.
+
 `Appendix B: Paste Operator Examples`_ presents examples of the behavior of
 the paste operator.
 
 Statements
 ==========
 
 The following statements may appear at the top level of TableGen source
 files.
 
 .. productionlist::
-   TableGenFile: `Statement`*
+   TableGenFile: (`Statement` | `IncludeDirective`
+            :| `PreprocessorDirective`)*
    Statement: `Assert` | `Class` | `Def` | `Defm` | `Defset` | `Defvar`
             :| `Foreach` | `If` | `Let` | `MultiClass`
 
 The following sections describe each of these top-level statements.
 
 
 ``class`` --- define an abstract record class
 ---------------------------------------------
 
 A ``class`` statement defines an abstract record class from which other

 to that record's parent classes. For example:
 
 .. code-block:: text
 
   class A <dag d> {
     dag the_dag = d;
   }
 
-  def rec1 : A<(ops rec1)>
+  def rec1 : A<(ops rec1)>;
 
 The DAG ``(ops rec1)`` is passed as a template argument to class ``A``. Notice
 that the DAG includes ``rec1``, the record being defined.
 
 The steps taken to create a new record are somewhat complex. See `How
 records are built`_.
 
 See `Examples: classes and records`_ for examples.

 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
 specify what all the operations are. The ``multiclass`` and ``defm``
 statements accomplish this goal. You can think of a multiclass as a macro or
 template that expands into multiple records.
 
 .. productionlist::
    MultiClass: "multiclass" `TokIdentifier` [`TemplateArgList`]
-             : [":" `ParentMultiClassList`]
+             : `ParentClassList`
              : "{" `MultiClassStatement`+ "}"
-   ParentMultiClassList: `MultiClassID` ("," `MultiClassID`)*
    MultiClassID: `TokIdentifier`
    MultiClassStatement: `Assert` | `Def` | `Defm` | `Defvar` | `Foreach` | `If` | `Let`
 
 As with regular classes, the multiclass has a name and can accept template
 arguments. A multiclass can inherit from other multiclasses, which causes
 the other multiclasses to be expanded and contribute to the record
 definitions in the inheriting multiclass. The body of the multiclass
 contains a series of statements that define records, using :token:`Def` and

 type of the variable is automatically inferred.
 
 Once a variable has been defined, it cannot be set to another value.
 
 Variables defined in a top-level ``foreach`` go out of scope at the end of
 each loop iteration, so their value in one iteration is not available in
 the next iteration.  The following ``defvar`` will not work::
 
-  defvar i = !add(i, 1)
+  defvar i = !add(i, 1);
 
 Variables can also be defined with ``defvar`` in a record body. See
 `Defvar in a Record Body`_ for more details.
 
 ``foreach`` --- iterate over a sequence of statements
 -----------------------------------------------------
 
 The ``foreach`` statement iterates over a series of statements, varying a

llvm/lib/CodeGen/MIRParser/MIParser.cpp

if (consumeIfPresent(MIToken::lparen)) {
     consumeIfPresent(MIToken::rparen);
   }
   consumeIfPresent(MIToken::colon);
 
   // Parse the liveins and successors.
   // N.B: Multiple lists of successors and liveins are allowed and they're
   // merged into one.
   // Example:
-  //   liveins: %edi
-  //   liveins: %esi
+  //   liveins: $edi
+  //   liveins: $esi
   //
   // is equivalent to
-  //   liveins: %edi, %esi
+  //   liveins: $edi, $esi
   bool ExplicitSuccessors = false;
   while (true) {
     if (Token.is(MIToken::kw_successors)) {
       if (parseBasicBlockSuccessors(MBB))
         return true;
       ExplicitSuccessors = true;
     } else if (Token.is(MIToken::kw_liveins)) {
       if (parseBasicBlockLiveins(MBB))