[PATCH] D87711: Add section on DAGs to TableGen Programmer's Reference

[Paul C. Anagnostopoulos via Phabricator via llvm-commits]

Paul-C-Anagnostopoulos created this revision.
Paul-C-Anagnostopoulos added reviewers: lattner, nhaehnle.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.
Paul-C-Anagnostopoulos requested review of this revision.

This patch adds a section on DAGs to the "TableGen Programmer's Reference." The syntax of DAGs is described in detail. The new section is referenced from a couple of other places in the document.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D87711

Files:
  llvm/docs/TableGen/ProgRef.rst


Index: llvm/docs/TableGen/ProgRef.rst
===================================================================
--- llvm/docs/TableGen/ProgRef.rst
+++ llvm/docs/TableGen/ProgRef.rst
@@ -285,10 +285,11 @@
 
 ``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 @@
 
 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 @@
 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 @@
   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 :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 @@
 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


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D87711.291983.patch
Type: text/x-patch
Size: 4189 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20200915/3e4861f6/attachment-0001.bin>