[llvm] 82687cf - Add section with details about DAGs.

[Paul C. Anagnostopoulos via llvm-commits]

Author: Paul C. Anagnostopoulos
Date: 2020-09-16T09:27:28-04:00
New Revision: 82687cf47b24a509ecd78e02fbc5666ba667ff4b

URL: https://github.com/llvm/llvm-project/commit/82687cf47b24a509ecd78e02fbc5666ba667ff4b
DIFF: https://github.com/llvm/llvm-project/commit/82687cf47b24a509ecd78e02fbc5666ba667ff4b.diff

LOG: Add section with details about DAGs.

Added: 
    

Modified: 
    llvm/docs/TableGen/ProgRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/TableGen/ProgRef.rst b/llvm/docs/TableGen/ProgRef.rst
index 07f0ba8a54dd..7bc70c8f89e6 100644
--- a/llvm/docs/TableGen/ProgRef.rst
+++ b/llvm/docs/TableGen/ProgRef.rst
@@ -285,10 +285,11 @@ wide range of records conveniently and compactly.
 
 ``dag``
     This type represents a nestable directed acyclic graph (DAG) of nodes.
-    Each node has an operator and one or more operands. A operand can be
+    Each node has an operator and zero or more operands. A operand can be
     another ``dag`` object, allowing an arbitrary tree of nodes and edges.
-    As an example, DAGs are used to represent code and patterns for use by
-    the code generator instruction selection algorithms.
+    As an example, DAGs are used to represent code patterns for use by
+    the code generator instruction selection algorithms. See `Directed
+    acyclic graphs (DAGs)`_ for more details;
 
 :token:`ClassID`
     Specifying a class name in a type context indicates
@@ -374,6 +375,7 @@ sometimes not when the value is the empty list (``[]``).
 
 This represents a DAG initializer (note the parentheses).  The first
 :token:`DagArg` is called the "operator" of the DAG and must be a record.
+See `Directed acyclic graphs (DAGs)`_ for more details.
 
 .. productionlist::
    SimpleValue6: `TokIdentifier`
@@ -582,7 +584,7 @@ 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
 become a field of the class or record being defined. Variables are provided
-to hold temporary values while processing the body. See `Defvar in Record
+to hold temporary values while processing the body. See `Defvar in a Record
 Body`_ for more details.
 
 When class ``C2`` inherits from class ``C1``, it acquires all the field
@@ -1129,7 +1131,7 @@ the next iteration.  The following ``defvar`` will not work::
   defvar i = !add(i, 1)
 
 Variables can also be defined with ``defvar`` in a record body. See
-`Defvar in Record Body`_ for more details.
+`Defvar in a Record Body`_ for more details.
 
 ``foreach`` --- iterate over a sequence of statements
 -----------------------------------------------------
@@ -1193,7 +1195,7 @@ the usual way: in a case like ``if v1 then if v2 then {...} else {...}``, the
 
 The :token:`IfBody` of the then and else arms of the ``if`` establish an
 inner scope. Any ``defvar`` variables defined in the bodies go out of scope
-when the bodies are finished (see `Defvar in Record Body`_ for more details).
+when the bodies are finished (see `Defvar in a Record Body`_ for more details).
 
 The ``if`` statement can also be used in a record :token:`Body`.
 
@@ -1201,8 +1203,41 @@ The ``if`` statement can also be used in a record :token:`Body`.
 Additional Details
 ==================
 
-Defvar in record body
----------------------
+Directed acyclic graphs (DAGs)
+------------------------------
+
+A directed acyclic graph can be represented directly in TableGen using the
+``dag`` datatype. A DAG node consists of an operator and zero or more
+operands. Each operand can be of any desired type. By using another DAG node
+as an operand, an arbitrary graph of DAG nodes can be built. 
+
+The syntax of a ``dag`` instance is:
+
+  ``(`` *operator* *operand1*\ ``,`` *operand2*\ ``,`` ... ``)``
+
+The operator must be present and must be a record. There can be zero or more
+operands, separated by commas. The operator and operands can have three
+formats. 
+
+====================== =============================================
+Format                 Meaning
+====================== =============================================
+*value*                operand value
+*value*\ ``:``\ *name* operand value and associated name
+*name*                 operand name with unset (uninitialized) value
+====================== =============================================
+
+The *value* can be any TableGen value. The *name*, if present, must be a
+:token:`TokVarName`, which starts with a dollar sign (``$``). The purpose of
+a name is to tag an operator or operand in a DAG with a particular meaning,
+or to associate an operand in one DAG with a like-named operand in another
+DAG.
+
+The following bang operators manipulate DAGs: ``!con``, ``!dag``, ``!foreach``, 
+``!getop``, ``!setop``.
+
+Defvar in a record body
+-----------------------
 
 In addition to defining global variables, the ``defvar`` statement can
 be used inside the :token:`Body` of a class or record definition to define