diff options
Diffstat (limited to 'src/main/scala/tutorial')
| -rw-r--r-- | src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala | 97 | ||||
| -rw-r--r-- | src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala | 41 |
2 files changed, 71 insertions, 67 deletions
diff --git a/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala b/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala index 6df6733d..f3f10e72 100644 --- a/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala +++ b/src/main/scala/tutorial/lesson1-circuit-traversal/AnalyzeCircuit.scala @@ -14,11 +14,10 @@ import scala.collection.mutable /** Ledger tracks [[firrtl.ir.Circuit]] statistics * - * In this lesson, we want to count the number of muxes in each - * module in our design. + * In this lesson, we want to count the number of muxes in each module in our design. * - * This [[Ledger]] class will be passed along as we walk our - * circuit, and help us count each [[Mux]] we find. + * This [[Ledger]] class will be passed along as we walk our circuit, and help us count each [[firrtl.ir.Mux Mux]] we + * find. * * See [[lesson1.AnalyzeCircuit]] */ @@ -47,18 +46,18 @@ class Ledger { /** AnalyzeCircuit Transform * - * Walks [[firrtl.ir.Circuit]], and records the number of muxes it finds, per module. + * Walks [[firrtl.ir.Circuit Circuit]], and records the number of muxes it finds, per module. * - * While some compiler frameworks operate on graphs, we represent a Firrtl - * circuit using a tree representation: - * - A Firrtl [[Circuit]] contains a sequence of [[DefModule]]s. - * - A [[DefModule]] contains a sequence of [[Port]]s, and maybe a [[Statement]]. - * - A [[Statement]] can contain other [[Statement]]s, or [[Expression]]s. - * - A [[Expression]] can contain other [[Expression]]s. - * - * To visit all Firrtl IR nodes in a circuit, we write functions that recursively - * walk down this tree. To record statistics, we will pass along the [[Ledger]] - * class and use it when we come across a [[Mux]]. + * While some compiler frameworks operate on graphs, we represent a Firrtl circuit using a tree representation: + * - A Firrtl [[firrtl.ir.Circuit Circuit]] contains a sequence of [[firrtl.ir.DefModule DefModule]]s. + * - A [[firrtl.ir.DefModule DefModule]] contains a sequence of [[firrtl.ir.Port Port]]s, and maybe a + * [[firrtl.ir.Statement Statement]]. + * - A [[firrtl.ir.Statement Statement]] can contain other [[firrtl.ir.Statement Statement]]s, or + * [[firrtl.ir.Expression Expression]]s. + * - A [[firrtl.ir.Expression Expression]] can contain other [[firrtl.ir.Expression Expression]]s. + * + * To visit all Firrtl IR nodes in a circuit, we write functions that recursively walk down this tree. To record + * statistics, we will pass along the [[Ledger]] class and use it when we come across a [[firrtl.ir.Mux Mux]]. * * See the following links for more detailed explanations: * Firrtl's IR: @@ -69,73 +68,81 @@ class Ledger { * - https://github.com/ucb-bar/firrtl/wiki/Common-Pass-Idioms */ class AnalyzeCircuit extends Transform { - // Requires the [[Circuit]] form to be "low" + /** Requires the [[firrtl.ir.Circuit Circuit]] form to be "low" */ def inputForm = LowForm - // Indicates the output [[Circuit]] form to be "low" + /** Indicates the output [[firrtl.ir.Circuit Circuit]] form to be "low" */ def outputForm = LowForm - // Called by [[Compiler]] to run your pass. [[CircuitState]] contains - // the circuit and its form, as well as other related data. + /** Called by [[firrtl.Compiler Compiler]] to run your pass. [[firrtl.CircuitState CircuitState]] contains the circuit + * and its form, as well as other related data. + */ def execute(state: CircuitState): CircuitState = { val ledger = new Ledger() val circuit = state.circuit - // Execute the function walkModule(ledger) on every [[DefModule]] in - // circuit, returning a new [[Circuit]] with new [[Seq]] of [[DefModule]]. - // - "higher order functions" - using a function as an object - // - "function currying" - partial argument notation - // - "infix notation" - fancy function calling syntax - // - "map" - classic functional programming concept - // - discard the returned new [[Circuit]] because circuit is unmodified + /* Execute the function walkModule(ledger) on every [[firrtl.ir.DefModule DefModule]] in circuit, returning a new + * [[Circuit]] with new [[scala.collection.Seq Seq]] of [[firrtl.ir.DefModule DefModule]]. + * - "higher order functions" - using a function as an object + * - "function currying" - partial argument notation + * - "infix notation" - fancy function calling syntax + * - "map" - classic functional programming concept + * - discard the returned new [[firrtl.ir.Circuit Circuit]] because circuit is unmodified + */ circuit map walkModule(ledger) // Print our ledger println(ledger.serialize) - // Return an unchanged [[CircuitState]] + // Return an unchanged [[firrtl.CircuitState CircuitState]] state } - // Deeply visits every [[Statement]] in m. + /** Deeply visits every [[firrtl.ir.Statement Statement]] in m. */ def walkModule(ledger: Ledger)(m: DefModule): DefModule = { // Set ledger to current module name ledger.setModuleName(m.name) - // Execute the function walkStatement(ledger) on every [[Statement]] in m. - // - return the new [[DefModule]] (in this case, its identical to m) - // - if m does not contain [[Statement]], map returns m. + /* Execute the function walkStatement(ledger) on every [[firrtl.ir.Statement Statement]] in m. + * - return the new [[firrtl.ir.DefModule DefModule]] (in this case, its identical to m) + * - if m does not contain [[firrtl.ir.Statement Statement]], map returns m. + */ m map walkStatement(ledger) } - // Deeply visits every [[Statement]] and [[Expression]] in s. + /** Deeply visits every [[firrtl.ir.Statement Statement]] and [[firrtl.ir.Expression Expression]] in s. */ def walkStatement(ledger: Ledger)(s: Statement): Statement = { - // Execute the function walkExpression(ledger) on every [[Expression]] in s. - // - discard the new [[Statement]] (in this case, its identical to s) - // - if s does not contain [[Expression]], map returns s. + /* Execute the function walkExpression(ledger) on every [[firrtl.ir.Expression Expression]] in s. + * - discard the new [[firrtl.ir.Statement Statement]] (in this case, its identical to s) + * - if s does not contain [[firrtl.ir.Expression Expression]], map returns s. + */ s map walkExpression(ledger) - // Execute the function walkStatement(ledger) on every [[Statement]] in s. - // - return the new [[Statement]] (in this case, its identical to s) - // - if s does not contain [[Statement]], map returns s. + /* Execute the function walkStatement(ledger) on every [[firrtl.ir.Statement Statement]] in s. + * - return the new [[firrtl.ir.Statement Statement]] (in this case, its identical to s) + * - if s does not contain [[firrtl.ir.Statement Statement]], map returns s. + */ s map walkStatement(ledger) } - // Deeply visits every [[Expression]] in e. - // - "post-order traversal" - handle e's children [[Expression]] before e + /** Deeply visits every [[firrtl.ir.Expression Expression]] in e. + * - "post-order traversal" + * - handle e's children [[firrtl.ir.Expression Expression]] before e + */ def walkExpression(ledger: Ledger)(e: Expression): Expression = { - // Execute the function walkExpression(ledger) on every [[Expression]] in e. - // - return the new [[Expression]] (in this case, its identical to e) - // - if s does not contain [[Expression]], map returns e. + /** Execute the function walkExpression(ledger) on every [[firrtl.ir.Expression Expression]] in e. + * - return the new [[firrtl.ir.Expression Expression]] (in this case, its identical to e) + * - if s does not contain [[firrtl.ir.Expression Expression]], map returns e. + */ val visited = e map walkExpression(ledger) visited match { - // If e is a [[Mux]], increment our ledger and return e. + // If e is a [[firrtl.ir.Mux Mux]], increment our ledger and return e. case Mux(cond, tval, fval, tpe) => ledger.foundMux e - // If e is not a [[Mux]], return e. + // If e is not a [[firrtl.ir.Mux Mux]], return e. case notmux => notmux } } diff --git a/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala b/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala index 87b87004..1905aeb5 100644 --- a/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala +++ b/src/main/scala/tutorial/lesson2-working-ir/AnalyzeCircuit.scala @@ -15,12 +15,11 @@ import firrtl.Mappers._ import scala.collection.mutable /** Ledger tracks [[firrtl.ir.Circuit]] statistics - * - * In this lesson, we want to calculate the number of muxes, not just in - * a module, but also in any instances it has of other modules, etc. * - * To do this, we need to update our Ledger class to keep track of this - * module instance information + * In this lesson, we want to calculate the number of muxes, not just in a module, but also in any instances it has of + * other modules, etc. + * + * To do this, we need to update our Ledger class to keep track of this module instance information * * See [[lesson2.AnalyzeCircuit]] */ @@ -63,39 +62,37 @@ class Ledger { /** AnalyzeCircuit Transform * - * Walks [[firrtl.ir.Circuit]], and records the number of muxes and instances it - * finds, per module. + * Walks [[firrtl.ir.Circuit]], and records the number of muxes and instances it finds, per module. * - * While the Firrtl parser emits a bare form of the IR (located in firrtl.ir._), - * it is often useful to have more information in these case classes. To do this, - * the Firrtl compiler has mirror "working" classes for the following IR - * nodes (which contain additional fields): + * While the Firrtl parser emits a bare form of the IR (located in firrtl.ir._), it is often useful to have more + * information in these case classes. To do this, the Firrtl compiler has mirror "working" classes for the following IR + * nodes (which contain additional fields): * - DefInstance -> WDefInstance * - SubAccess -> WSubAccess * - SubIndex -> WSubIndex * - SubField -> WSubField * - Reference -> WRef * - * Take a look at [[ToWorkingIR]] in src/main/scala/firrtl/passes/Passes.scala - * to see how Firrtl IR nodes are replaced with working IR nodes. + * Take a look at [[firrtl.passes.ToWorkingIR ToWorkginIR]] in + * [[https://github.com/freechipsproject/firrtl/tree/master/src/main/scala/firrtl/passes + * src/main/scala/firrtl/passes/Passes.scala]] to see how Firrtl IR nodes are replaced with working IR nodes. * - * Future lessons will explain the WIR's additional fields. For now, it is - * enough to know that the transform [[ResolveAndCheck]] populates these - * fields, and checks the legality of the circuit. If your transform is - * creating new WIR nodes, use the following "unknown" values in the WIR - * node, and then call [[ResolveAndCheck]] at the end of your transform: + * Future lessons will explain the WIR's additional fields. For now, it is enough to know that the transform + * [[firrtl.ResolveAndCheck]] populates these fields, and checks the legality of the circuit. If your transform is + * creating new WIR nodes, use the following "unknown" values in the WIR node, and then call [[firrtl.ResolveAndCheck]] + * at the end of your transform: * - Kind -> ExpKind * - Gender -> UNKNOWNGENDER * - Type -> UnknownType * - * The following [[CircuitForm]]s require WIR instead of IR nodes: + * The following [[firrtl.CircuitForm]]s require WIR instead of IR nodes: * - HighForm * - MidForm * - LowForm * * See the following links for more detailed explanations: * IR vs Working IR - * - TODO(izraelevitz) + * - TODO(izraelevitz) */ class AnalyzeCircuit extends Transform { def inputForm = LowForm @@ -128,11 +125,11 @@ class AnalyzeCircuit extends Transform { // Deeply visits every [[Statement]] and [[Expression]] in s. def walkStatement(ledger: Ledger)(s: Statement): Statement = { // Map the functions walkStatement(ledger) and walkExpression(ledger) - val visited = s map walkStatement(ledger) map walkExpression(ledger) + val visited = s map walkStatement(ledger) map walkExpression(ledger) visited match { // IR node [[DefInstance]] is previously replaced by WDefInstance, a // "working" IR node - case DefInstance(info, name, module) => + case DefInstance(info, name, module) => Utils.error("All DefInstances should have been replaced by WDefInstances") // Working IR Node [[WDefInstance]] is what the compiler uses // See src/main/scala/firrtl/WIR.scala for all working IR nodes |