added file doc

12 files changed, 84 insertions, 26 deletions

diff --git a/chill/include/chill_error.hh b/chill/include/chill_error.hh
index ca0936e..88e49fc 100644
--- a/chill/include/chill_error.hh
+++ b/chill/include/chill_error.hh
@@ -1,6 +1,11 @@
 #ifndef CHILL_ERROR_HH
 #define CHILL_ERROR_HH
 
+/*!
+ * \file
+ * \brief CHiLL runtime exceptions
+ */
+
 //! for loop transformation problem
 struct loop_error: public std::runtime_error {
   loop_error(const std::string &msg): std::runtime_error(msg){}
diff --git a/chill/include/chillmodule.hh b/chill/include/chillmodule.hh
index a99db0c..e83119f 100644
--- a/chill/include/chillmodule.hh
+++ b/chill/include/chillmodule.hh
@@ -1,6 +1,11 @@
 #ifndef CHILLMODULE_HH
 #define CHILLMODULE_HH
 
+/*!
+ * \file
+ * \brief chill interface to python
+ */
+
 #include <Python.h>
 
 void finalize_loop(int loop_num_start, int loop_num_end);
diff --git a/chill/include/dep.hh b/chill/include/dep.hh
index f1cc864..6c535ce 100644
--- a/chill/include/dep.hh
+++ b/chill/include/dep.hh
@@ -1,6 +1,19 @@
 #ifndef DEP_HH
 #define DEP_HH
 
+/*!
+ * \file 
+ * \brief Data dependence vector and graph.
+ *
+ * All dependence vectors are normalized, i.e., the first non-zero distance
+ * must be positve. Thus the correct dependence meaning can be given based on
+ * source/destination pair's read/write type. Suppose for a dependence vector
+ * 1, 0~5, -3), we want to permute the first and the second dimension,
+ * the result would be two dependence vectors (0, 1, -3) and (1~5, 1, -3).
+ * All operations on dependence vectors are non-destructive, i.e., new
+ * dependence vectors are returned.
+ */
+
 #include <omega.h>
 #include "graph.hh"
 #include "ir_code.hh"
diff --git a/chill/include/graph.hh b/chill/include/graph.hh
index b67183b..211444a 100644
--- a/chill/include/graph.hh
+++ b/chill/include/graph.hh
@@ -19,6 +19,14 @@
 #ifndef GRAPH_HH
 #define GRAPH_HH
 
+/*!
+ * \file
+ * \brief  Graph<VertexType, EdgeType> template class supports topological sort
+ *
+ * The result of topologically sorting a graph V={1,2,3,4} and E={1->2, 1->3,
+ * 2->3, 3->2, 3->4} is ({1}, {2,3}, {4}).
+ */
+
 #include <set>
 #include <vector>
 #include <map>
diff --git a/chill/include/ir_code.hh b/chill/include/ir_code.hh
index b6ebfcd..d695474 100644
--- a/chill/include/ir_code.hh
+++ b/chill/include/ir_code.hh
@@ -22,6 +22,18 @@
 #ifndef IR_CODE_HH
 #define IR_CODE_HH
 
+/*!
+ * \file
+ * \brief CHiLL's compiler intermediate representation interface that extends Omega's builder interface to accomodate compiler analyses and extra code generation.
+ * 
+ * Unlike CG_outputRepr, IR_Symbol,IR_Ref and IR_Control are place holders 
+ * to the underlying code, thus deleting or duplicating them does not affect
+ * the actual code.  Similar to Omega builder's memory allocation strategy,
+ * all non-const pointer parameters of CG_outputRepr/IR_Symbol/IR_Ref/IR_Control
+ * are destroyed after the call.
+ */
+
+
 #include <code_gen/CG_outputRepr.h>
 #include <code_gen/CG_outputBuilder.h>
 #include <vector>
diff --git a/chill/include/ir_rose.hh b/chill/include/ir_rose.hh
index 9e94dea..03ea50d 100644
--- a/chill/include/ir_rose.hh
+++ b/chill/include/ir_rose.hh
@@ -1,6 +1,11 @@
 #ifndef IR_ROSE_HH
 #define IR_ROSE_HH
 
+/*!
+ * \file
+ * \brief CHiLL's rose interface.
+ */
+
 #include <omega.h>
 #include "ir_code.hh"
 #include "ir_rose_utils.hh"
diff --git a/chill/include/ir_rose_utils.hh b/chill/include/ir_rose_utils.hh
index d6749de..350aa24 100644
--- a/chill/include/ir_rose_utils.hh
+++ b/chill/include/ir_rose_utils.hh
@@ -1,5 +1,10 @@
 #ifndef IR_ROSE_UTILS_HH
 #define IR_ROSE_UTILS_HH
+
+/*!
+ * \file
+ * \brief ROSE interface utilities
+ */
 #include <vector>
 #include <rose.h>
 #include <sageBuilder.h>
diff --git a/chill/include/irtools.hh b/chill/include/irtools.hh
index 205efe1..a3b552a 100644
--- a/chill/include/irtools.hh
+++ b/chill/include/irtools.hh
@@ -1,6 +1,11 @@
 #ifndef IRTOOLS_HH
 #define IRTOOLS_HH
 
+/*!
+ * \file
+ * \brief Useful tools to analyze code in compiler IR format.
+ */
+
 #include <vector>
 #include <omega.h>
 #include <code_gen/CG_outputRepr.h>
diff --git a/chill/include/loop.hh b/chill/include/loop.hh
index 2c50d6b..9620489 100644
--- a/chill/include/loop.hh
+++ b/chill/include/loop.hh
@@ -1,6 +1,25 @@
 #ifndef LOOP_HH
 #define LOOP_HH
 
+/*!
+ * \file 
+ * \brief Core loop transformation functionality.
+ *
+ * "level" (starting from 1) means loop level and it corresponds to "dim"
+ * (starting from 0) in transformed iteration space [c_1,l_1,c_2,l_2,....,
+ * c_n,l_n,c_(n+1)], e.g., l_2 is loop level 2 in generated code, dim 3
+ * in transformed iteration space, and variable 4 in Omega relation.
+ * All c's are constant numbers only and they will not show up as actual loops.
+ * 
+ * Formula:
+ *
+ * ~~~
+ *   dim = 2*level - 1
+ *   var = dim + 1
+ * ~~~
+ */
+ 
+
 #include <omega.h>
 #include <code_gen/codegen.h>
 #include <code_gen/CG.h>
diff --git a/chill/include/omegatools.hh b/chill/include/omegatools.hh
index f77a376..b51b2bd 100644
--- a/chill/include/omegatools.hh
+++ b/chill/include/omegatools.hh
@@ -1,6 +1,11 @@
 #ifndef OMEGATOOLS_HH
 #define OMEGATOOLS_HH
 
+/*!
+ * \file
+ * \brief Useful tools involving Omega manipulation.
+ */
+
 #include <string>
 #include <omega.h>
 #include "dep.hh"
diff --git a/chill/src/chillmodule.cc b/chill/src/chillmodule.cc
index b7012cc..024ac33 100644
--- a/chill/src/chillmodule.cc
+++ b/chill/src/chillmodule.cc
@@ -1,6 +1,3 @@
-
-// chill interface to python
-
 #include "chilldebug.h"
 
 #include "chill_run_util.hh"
diff --git a/chill/src/ir_rose_utils.cc b/chill/src/ir_rose_utils.cc
index fbce2f1..64b0891 100644
--- a/chill/src/ir_rose_utils.cc
+++ b/chill/src/ir_rose_utils.cc
@@ -4,7 +4,7 @@
  All Rights Reserved.
 
  Purpose:
-   SUIF interface utilities.
+   ROSE interface utilities.
 
  Notes:
 
@@ -12,27 +12,13 @@
    01/2006 created by Chun Chen
 *****************************************************************************/
 
-//#include <suif1.h>
-//#include <useful.h>
-//#include <vector>
-//#include <algorithm>
-//#include <code_gen/CG_suifRepr.h>
 #include "ir_rose_utils.hh"
 
 
 
 std::vector<SgForStatement *> find_loops(SgNode *tnl) {
   std::vector<SgForStatement *> result;
-  
-  //tree_node_list_iter iter(tnl);
-  
-  /*while (!iter.is_empty()) {
-    tree_node *tn = iter.step();
-    if (tn->kind() == TREE_FOR)
-    result.push_back(static_cast<tree_for *>(tn));
-    }
-  */
-  
+ 
   SgStatementPtrList& blockStatements = isSgBasicBlock(tnl)->get_statements();
   for(SgStatementPtrList::const_iterator j = blockStatements.begin(); j != blockStatements.end(); j++)
     if(isSgForStatement(*j))
@@ -60,13 +46,6 @@ std::vector<SgForStatement *> find_deepest_loops(SgStatementPtrList& tnl) {
   
 }
 
-
-
-
-
-
-
-
 std::vector<SgForStatement *> find_deepest_loops(SgNode *tn) {
   if (isSgForStatement(tn)) {
     std::vector<SgForStatement *> loops;