add some documentation to sema/lexer/parser and tc2halide

Author: prigoyal

tc/core/halide2isl.cc

@@ -35,7 +35,8 @@ using namespace tc::polyhedral::detail;
 
 SymbolTable makeSymbolTable(const tc2halide::HalideComponents& components) {
   // const Stmt& s) {
-  // Collect and categorize all the Variable symbols
+  // Collect and categorize all the Halide Variable symbols as reduction
+  // or index variables
   class BuildSymbolTable : public IRVisitor {
     using IRVisitor::visit;
     std::set<std::string> included;
@@ -60,7 +61,7 @@ SymbolTable makeSymbolTable(const tc2halide::HalideComponents& components) {
 
   components.stmt.accept(&builder);
   // Get params from components.params which contain everything declared in
-  // tcdef. However, the 0-D tensors are registered as both params and inputs,
+  // TC Def. However, the 0-D tensors are registered as both params and inputs,
   // filter those out.
   for (auto kvp : components.params) {
     bool skip = false;
@@ -93,7 +94,7 @@ namespace {
  * Convert Halide binary expression "op" into a list of isl affine functions by
  * converting its LHS and RHS into lists of affs and concatenating those lists.
  * This is intended to be used with Min/Max operations in upper/lower bound
- * computations, respectively.  Essentially, this allows for replacements
+ * computations, respectively. Essentially, this allows for replacements
  *   x < min(a,min(b,c)) <=> x < a AND x < b AND x < c
  *   x > max(a,max(b,c)) <=> x > a AND x > b AND x > c
  */

tc/core/tc2halide.cc

@@ -62,10 +62,13 @@ Type translateScalarType(int tcType) {
   }
 }
 
+// translate the TC def input params to corresponding Halide components.
+// params, inputs will be populated here
 void translateParam(
     const lang::Param& p,
     map<string, Parameter>* params,
     vector<ImageParam>* inputs) {
+  // check if the param is already converted to halide components
   if (params->find(p.ident().name()) != params->end()) {
     return;
   } else {
@@ -492,6 +495,8 @@ Expr reductionUpdate(Expr e) {
   return Call::make(e.type(), kReductionUpdate, {e}, Call::Intrinsic);
 }
 
+// translate a single TC comprehension/statement to Halide component.
+// funcs, bounds, reductions will be populated
 void translateComprehension(
     const lang::Comprehension& c,
     const map<string, Parameter>& params,
@@ -737,6 +742,7 @@ void translateComprehension(
   stage.reorder(loop_nest);
 }
 
+// translate a semantically checked TC def to Halide components struct
 HalideComponents translateDef(const lang::Def& def, bool throwWarnings) {
   map<string, Function> funcs;
   HalideComponents components;
@@ -956,6 +962,8 @@ translate(isl::ctx ctx, const lang::TreeRef& treeRef, bool throwWarnings) {
       lang::Def(lang::Sema().checkFunction(treeRef)), throwWarnings);
 }
 
+// NOTE: there is no guarantee here that the tc string has only one def. It
+// could have many defs. Only first def will be converted in that case.
 HalideComponents
 translate(isl::ctx ctx, const std::string& tc, bool throwWarnings) {
   LOG_IF(INFO, tc::FLAGS_debug_halide) << tc;

tc/core/tc2halide.h

@@ -27,8 +27,8 @@ namespace tc2halide {
 // of the input and output tensors. We do not explicitly enumerate the
 // scalar params.
 struct HalideComponents {
-  lang::TreeRef
-      def; // post-semantic analaysis tree, used for later error reporting
+  // post-semantic analaysis tree, used for later error reporting
+  lang::TreeRef def;
   Halide::Internal::Stmt stmt;
   std::vector<Halide::ImageParam> inputs;
   std::map<std::string, Halide::Internal::Parameter> params;

tc/lang/sema.h

@@ -339,6 +339,21 @@ struct Sema {
         throw ErrorReport(exp) << "NYI - semantic checking for " << exp;
     }
   }
+  // This is the entry function for semantic analysis. It is called by
+  // tc2halide to associate type with each node of the tree and to also make
+  // sure that the tree is sematically correct. For example: a variable
+  // may not be input two times. Parser only verifies for the syntax but does
+  // not check the semantics.
+  //
+  // It converts the TK_APPLY nodes to TK_ACCESS or TK_BUILT_IN
+  //
+  // The reduction variables are deduced and the objects are created for them
+  // and they are appended to the tree
+  //
+  // Type checking is also done but by a very small codebase
+  //
+  // withType - associates the type with a given node
+  //
   TreeRef checkFunction(TreeRef func_) {
     auto func = Def(func_);
     auto params_ =
@@ -350,6 +365,10 @@ struct Sema {
       }
     }
 
+    // everything has to be input or output. Keep track of the variables that
+    // are either input/output. We will check that the statements have variables
+    // from this list. If not, then throw error that temporaries are not yet
+    // implemented.
     for (auto p : func.params()) {
       nonTemporaries.insert(p.ident().name());
       inputParameters.insert(p.ident().name());
@@ -437,6 +456,7 @@ struct Sema {
       return checkRangeConstraint(RangeConstraint(ref));
     }
   }
+  // semantic checking for the statements/comprehensions in a TC Def
   TreeRef checkStmt(TreeRef stmt_) {
     auto stmt = Comprehension(stmt_);