adds documentation

Author: pjots

shared/rocroller/lib/include/rocRoller/KernelGraph/ControlGraph/DataDependenceDAG.hpp

@@ -7,5 +7,22 @@
 
 namespace rocRoller::KernelGraph::DataDependenceDAG
 {
+    /**
+     * Builds the data dependence graph for the given kernel graph,
+     * specifically based on its control graph portion. It explicitly
+     * represents only the data dependences(flow, anti, and output) between
+     * the control graph nodes at the basic-block level.
+     *
+     * The data dependence graph has no cycles in it, therefore it
+     * is termed as data dependence DAG (directed acyclic graph).
+     *
+     * It describes the dependency relationship between the control graph nodes,
+     * so it makes sense to use the existing `rocRoller::KernelGraph::ControlGraph`
+     * structure for its represenatation.
+     *
+     * The dependences are indicated using `Sequence` edges at each basic-block
+     * level i.e. between the nodes sharing the same immediate body-parent
+     * in `graph.control`.
+     */
     ControlGraph::ControlGraph ConstructDataDependenceDAG(KernelGraph const& graph);
 }

shared/rocroller/lib/include/rocRoller/KernelGraph/ControlGraph/DataDependenceDAG_detail.hpp

@@ -10,12 +10,36 @@ namespace rocRoller::KernelGraph::DataDependenceDAG::Detail
     class DataDependenceDAGDetail
     {
     public:
+        /**
+         * Initializes the data dependence DAG structure (`m_dependenceDAG`)
+         * with only the control nodes from the given kernel graph.
+         */
         DataDependenceDAGDetail(KernelGraph const& graph);
 
-        int  getBodyParent(int control);
-        void addDependenceEdge(int sourceControl, int destControl);
+        /**
+         * Returns the body-parent for the given node in the control graph.
+         */
+        int getBodyParent(int control);
+        /**
+         * Adds a dependence edge(represented via `Sequence`) between the given
+         * source and destination nodes in the dependence DAG (`m_dependenceDAG),
+         * if both the nodes have the same body-parent.
+         */
+        void addDependenceEdge(int source, int dest);
+        /**
+         * Makes necessary updates to `m_latestWriteToCoord`, `m_latestReadsToCoord`
+         * and `m_dependenceDAG` structures for the given `ReadWriteRecord`.
+         */
         void processReadWriteRecord(ControlFlowRWTracer::ReadWriteRecord const& record);
+        /**
+         * Builds the data dependence DAG by populating the `m_dependenceDAG` structure
+         * with required dependence edges based on the trace generated using `ControlFlowRWTracer`
+         * for `m_graph`.
+         */
         void constructDataDependenceDAG();
+        /**
+         * Returns the data dependence DAG (`m_dependenceDAG`).
+         */
         ControlGraph::ControlGraph getDataDependenceDAG();
 
     private:

shared/rocroller/lib/include/rocRoller/KernelGraph/NodeSchedulingUtils.hpp

@@ -46,15 +46,6 @@ namespace rocRoller::KernelGraph
          * `graph.control`.
          */
         void orderNodes(KernelGraph const& graph, std::vector<int>& nodes, auto const& comp);
-
-        /**
-         * Builds the data dependence graph for the given kernel graph.
-         *
-         * The dependences are represented at each basic block level i.e. between the
-         * nodes sharing the same immediate body-parent in `graph.control`.
-         * The flow, anti, and output data dependences between such nodes are included.
-         */
-        ControlGraph::ControlGraph ConstructDataDependenceDAG(KernelGraph const& graph);
     }
 }
 

shared/rocroller/lib/source/KernelGraph/ControlGraph/DataDependenceDAG.cpp

@@ -78,21 +78,19 @@ namespace rocRoller::KernelGraph
                 return bodyParent.value();
             }
 
-            void DataDependenceDAGDetail::addDependenceEdge(int sourceControl, int destControl)
+            void DataDependenceDAGDetail::addDependenceEdge(int source, int dest)
             {
-                AssertFatal(
-                    sourceControl != destControl, ShowValue(sourceControl), ShowValue(destControl));
+                AssertFatal(source != dest, ShowValue(source), ShowValue(dest));
 
-                auto sourceBodyParent = getBodyParent(sourceControl);
-                auto destBodyParent   = getBodyParent(destControl);
+                auto sourceBodyParent = getBodyParent(source);
+                auto destBodyParent   = getBodyParent(dest);
 
                 if(sourceBodyParent != destBodyParent)
                     return;
 
-                if(!m_dependenceDAG.findEdge(sourceControl, destControl).has_value())
+                if(!m_dependenceDAG.findEdge(source, dest).has_value())
                 {
-                    m_dependenceDAG.addElement(
-                        ControlGraph::Sequence(), {sourceControl}, {destControl});
+                    m_dependenceDAG.addElement(ControlGraph::Sequence(), {source}, {dest});
                 }
             }
 

shared/rocroller/lib/source/KernelGraph/NodeSchedulingUtils.cpp

@@ -6,10 +6,6 @@
 #include <rocRoller/KernelGraph/Transforms/Simplify.hpp>
 #include <rocRoller/KernelGraph/Utils.hpp>
 
-#include <map>
-#include <unordered_map>
-#include <unordered_set>
-
 namespace rocRoller::KernelGraph::NodeScheduling
 {
     ControlGraph::ControlGraph createSubGraph(KernelGraph const&      graph,
@@ -55,4 +51,5 @@ namespace rocRoller::KernelGraph::NodeScheduling
 
         return subGraph;
     }
+
 }

shared/rocroller/lib/source/KernelGraph/Utils.cpp

@@ -1098,7 +1098,7 @@ namespace rocRoller
                 tag = *parent;
 
                 AssertFatal(graph.mapper.get<CT::Unroll>(tag) > 0,
-                            "SetCoordinate needs Unroll/ForLoop dimension");
+                            "SetCoordinate needs Unroll dimension");
 
                 result.insert(tag);
             }
@@ -1125,7 +1125,7 @@ namespace rocRoller
 
                 AssertFatal(graph.mapper.get<CT::Unroll>(tag) > 0
                                 || graph.mapper.get<CT::ForLoop>(tag) > 0,
-                            "SetCoordinate needs Unroll dimension");
+                            "SetCoordinate needs Unroll/ForLoop dimension");
             }
             return tag;
         }