From 0f2d00e0082c2ebf30f4e1230ac7feb13e92db93 Mon Sep 17 00:00:00 2001
From: Edward Wang <edward.c.wang@compdigitec.com>
Date: Mon, 31 Jul 2017 18:46:43 -0700
Subject: [PATCH] Add some documentation

---
 macros/src/main/scala/MacroCompiler.scala | 29 ++++++++++++++++-------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/macros/src/main/scala/MacroCompiler.scala b/macros/src/main/scala/MacroCompiler.scala
index a96043f2..3dc8a06b 100644
--- a/macros/src/main/scala/MacroCompiler.scala
+++ b/macros/src/main/scala/MacroCompiler.scala
@@ -320,14 +320,21 @@ class MacroCompilerPass(mems: Option[Seq[Macro]],
 
   def run(c: Circuit): Circuit = {
     val modules = (mems, libs) match {
-      case (Some(mems), Some(libs)) => (mems foldLeft c.modules){ (modules, mem) =>
+      case (Some(mems), Some(libs)) =>
+        // Try to compile each of the memories in mems.
+        // The 'state' is c.modules, which is a list of all the firrtl modules
+        // in the 'circuit'.
+        (mems foldLeft c.modules){ (modules, mem) =>
+
+        // Try to compile mem against each lib in libs, keeping track of the
+        // best compiled version, external lib used, and cost.
         val (best, cost) = (libs foldLeft (None: Option[(Module, ExtModule)], BigInt(Long.MaxValue))){
-          case ((best, area), lib) if mem.src.ports.size != lib.src.ports.size =>
+          case ((best, cost), lib) if mem.src.ports.size != lib.src.ports.size =>
             /* Palmer: FIXME: This just assumes the Chisel and vendor ports are in the same
              * order, but I'm starting with what actually gets generated. */
             System.err println s"INFO: unable to compile ${mem.src.name} using ${lib.src.name} port count must match"
-            (best, area)
-          case ((best, area), lib) =>
+            (best, cost)
+          case ((best, cost), lib) =>
             /* Palmer: A quick cost function (that must be kept in sync with
              * memory_cost()) that attempts to avoid compiling unncessary
              * memories.  This is a lower bound on the cost of compiling a
@@ -341,16 +348,20 @@ class MacroCompilerPass(mems: Option[Seq[Macro]],
               case (Some(1), Some(1)) | (None, _) => mem.src.width
               case (Some(p), _) => p // assume that the memory consists of smaller chunks
             }
-            val cost = (((mem.src.depth - 1) / lib.src.depth) + 1) *
+            val newCost = (((mem.src.depth - 1) / lib.src.depth) + 1) *
                        (((memWidth - 1) / lib.src.width) + 1) *
                        (lib.src.depth * lib.src.width + 1) // weights on # cells
-            System.err.println(s"Cost of ${lib.src.name} for ${mem.src.name}: ${cost}")
-            if (cost > area) (best, area)
+            System.err.println(s"Cost of ${lib.src.name} for ${mem.src.name}: ${newCost}")
+            if (newCost > cost) (best, cost)
             else compile(mem, lib) match {
-              case None => (best, area)
-              case Some(p) => (Some(p), cost)
+              case None => (best, cost)
+              case Some(p) => (Some(p), newCost)
             }
         }
+
+        // If we were able to compile anything, then replace the original module
+        // in the modules list with a compiled version, as well as the extmodule
+        // stub for the lib.
         best match {
           case None => modules
           case Some((mod, bb)) =>