From 2b0bc0ecbc9c53882e2104ecd1e1387039be27f3 Mon Sep 17 00:00:00 2001
From: Jiuyang Liu
Date: Tue, 23 Nov 2021 04:17:14 +0800
Subject: add documentations to decoder. (#2254)

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>---
 .../chisel3/util/experimental/decode/EspressoMinimizer.scala | 12 +++++++++++-
 .../chisel3/util/experimental/decode/QMCMinimizer.scala      |  9 +++++++++
 2 files changed, 20 insertions(+), 1 deletion(-)

(limited to 'src')

diff --git a/src/main/scala/chisel3/util/experimental/decode/EspressoMinimizer.scala b/src/main/scala/chisel3/util/experimental/decode/EspressoMinimizer.scala
index 1d725875..6adf544c 100644
--- a/src/main/scala/chisel3/util/experimental/decode/EspressoMinimizer.scala
+++ b/src/main/scala/chisel3/util/experimental/decode/EspressoMinimizer.scala
@@ -7,11 +7,21 @@ import logger.LazyLogging
 
 case object EspressoNotFoundException extends Exception
 
+/** A [[Minimizer]] implementation to use espresso to minimize the [[TruthTable]].
+  *
+  * espresso uses heuristic algorithm providing a sub-optimized) result.
+  * For implementation details, please refer to:
+  * [[https://www.springerprofessional.de/en/logic-minimization-algorithms-for-vlsi-synthesis/13780088]]
+  *
+  * a espresso executable should be downloaded from [[https://github.com/chipsalliance/espresso]]
+  *
+  * If user want to user the this [[Minimizer]], a espresso executable should be added to system PATH environment.
+  */
 object EspressoMinimizer extends Minimizer with LazyLogging {
   def minimize(table: TruthTable): TruthTable =
     TruthTable.merge(TruthTable.split(table).map{case (table, indexes) => (espresso(table), indexes)})
 
-  def espresso(table: TruthTable): TruthTable = {
+  private def espresso(table: TruthTable): TruthTable = {
     def writeTable(table: TruthTable): String = {
       def invert(string: String) = string
         .replace('0', 't')
diff --git a/src/main/scala/chisel3/util/experimental/decode/QMCMinimizer.scala b/src/main/scala/chisel3/util/experimental/decode/QMCMinimizer.scala
index c1533f44..8bd8a03e 100644
--- a/src/main/scala/chisel3/util/experimental/decode/QMCMinimizer.scala
+++ b/src/main/scala/chisel3/util/experimental/decode/QMCMinimizer.scala
@@ -8,6 +8,15 @@ import scala.annotation.tailrec
 import scala.math.Ordered.orderingToOrdered
 import scala.language.implicitConversions
 
+/** A [[Minimizer]] implementation to use Quine-Mccluskey algorithm to minimize the [[TruthTable]].
+  *
+  * This algorithm can always find the best solution, but is a NP-Complete algorithm,
+  * which means, for large-scale [[TruthTable]] minimization task, it will be really slow,
+  * and might run out of memory of JVM stack.
+  *
+  * In this situation, users should consider switch to [[EspressoMinimizer]],
+  * which uses heuristic algorithm providing a sub-optimized result.
+  */
 object QMCMinimizer extends Minimizer {
   private implicit def toImplicant(x: BitPat): Implicant = new Implicant(x)
 
-- 
cgit v1.2.3