Merge pull request #237 from DFiantHDL/docsupdate8

FSM WIP + Documentation update

Author: soronpo

.gitignore

@@ -31,3 +31,5 @@ project/metals.sbt
 node_modules/
 package.json
 package-lock.json
+*.drawio.bkp
+

.scalafmt.conf

@@ -1,4 +1,4 @@
-version = 3.8.3
+version = 3.9.3
 runner.dialect = scala3
 
 maxColumn = 100

build.sbt

@@ -3,7 +3,7 @@ commands += DFHDLCommands.docExamplesRefUpdate
 
 // format: off
 val projectName = "dfhdl"
-val compilerVersion = "3.6.3"
+val compilerVersion = "3.6.4"
 
 inThisBuild(
   List(
@@ -41,7 +41,8 @@ lazy val root = (project in file("."))
     compiler_ir,
     core,
 	  compiler_stages,
-    lib
+    lib,
+    devices
   )
 
 lazy val internals = project
@@ -125,6 +126,21 @@ lazy val lib = project
     compiler_stages
   )
 
+lazy val devices = (project in file("devices"))
+  .settings(
+    name := s"$projectName-devices",
+    settings,
+    pluginUseSettings,
+    libraryDependencies ++= commonDependencies
+  )
+  .dependsOn(
+    plugin,
+    internals,
+    compiler_ir,
+    core,
+    lib
+  )
+
 // DEPENDENCIES
 
 lazy val dependencies =

compiler/ir/src/main/scala/dfhdl/compiler/analysis/DFValAnalysis.scala

@@ -12,10 +12,13 @@ import DFDesignBlock.InstMode
 import scala.util.boundary, boundary.break
 import scala.annotation.targetName
 
+object IteratorDcl:
+  def unapply(dcl: DFVal.Dcl)(using MemberGetSet): Boolean =
+    dcl.hasTagOf[DFVal.Dcl.IteratorTag.type]
+
 object Ident:
   def unapply(alias: DFVal.Alias.AsIs)(using MemberGetSet): Option[DFVal] =
-    if (alias.hasTagOf[DFVal.Alias.IdentTag.type])
-      Some(alias.relValRef.get)
+    if (alias.hasTagOf[DFVal.Alias.IdentTag.type]) Some(alias.relValRef.get)
     else None
 
 //A design parameter is an as-is alias that:

compiler/ir/src/main/scala/dfhdl/compiler/ir/Config.scala

@@ -11,16 +11,34 @@ object ConfigN:
   given [T]: CanEqual[None.type, ConfigN[T]] = CanEqual.derived
   given [L, R]: CanEqual[ConfigN[L], ConfigN[R]] = CanEqual.derived
 
+/** Sets the policy for inclusing the clock or reset signals when they are not needed
+  */
+enum ClkRstInclusionPolicy derives CanEqual:
+  /** Don't include if not needed
+    */
+  case AsNeeded
+
+  /** Always include at the top and silence with `@unused` annotation
+    */
+  case AlwaysAtTop
+
 type ClkCfg = ConfigN[ClkCfg.Explicit]
 object ClkCfg:
   enum Edge derives CanEqual:
     case Rising, Falling
 
   final case class Explicit(
       edge: Edge,
-      rate: Rate,
-      portName: String
-  ) derives CanEqual
+      rate: DFVal,
+      portName: String,
+      inclusionPolicy: ClkRstInclusionPolicy
+  ) extends HasRefCompare[Explicit] derives CanEqual:
+    override protected def prot_=~(that: Explicit)(using MemberGetSet): Boolean =
+      this.edge == that.edge && this.rate =~ that.rate && this.portName == that.portName &&
+        this.inclusionPolicy == that.inclusionPolicy
+    lazy val getRefs: List[DFRef.TwoWayAny] = rate.getRefs
+    def copyWithNewRefs: this.type = copy(rate = rate.copyWithNewRefs).asInstanceOf[this.type]
+end ClkCfg
 
 type RstCfg = ConfigN[RstCfg.Explicit]
 object RstCfg:
@@ -32,7 +50,8 @@ object RstCfg:
   final case class Explicit(
       mode: Mode,
       active: Active,
-      portName: String
+      portName: String,
+      inclusionPolicy: ClkRstInclusionPolicy
   ) derives CanEqual
 end RstCfg
 
@@ -56,15 +75,23 @@ enum RTDomainCfg extends HasRefCompare[RTDomainCfg] derives CanEqual:
   protected def `prot_=~`(that: RTDomainCfg)(using MemberGetSet): Boolean =
     (this, that) match
       case (Related(thisRef), Related(thatRef)) => thisRef =~ thatRef
-      case _                                    => this == that
+      case (
+            Explicit(thisName, thisClkCfg: ClkCfg.Explicit, thisRstCfg),
+            Explicit(thatName, thatClkCfg: ClkCfg.Explicit, thatRstCfg)
+          ) =>
+        thisName == thatName && thisClkCfg =~ thatClkCfg && thisRstCfg == thatRstCfg
+      case _ => this == that
 
   lazy val getRefs: List[DFRef.TwoWayAny] = this match
-    case Related(relatedDomainRef) => List(relatedDomainRef)
-    case _                         => Nil
+    case Related(relatedDomainRef)                    => List(relatedDomainRef)
+    case Explicit(_, clkCfg: ClkCfg.Explicit, rstCfg) => clkCfg.getRefs
+    case _                                            => Nil
 
   def copyWithNewRefs: this.type = this match
     case Related(relatedDomainRef) => Related(relatedDomainRef.copyAsNewRef).asInstanceOf[this.type]
-    case _                         => this
+    case Explicit(name, clkCfg: ClkCfg.Explicit, rstCfg) =>
+      Explicit(name, clkCfg.copyWithNewRefs, rstCfg).asInstanceOf[this.type]
+    case _ => this
 end RTDomainCfg
 
 object RTDomainCfg:

compiler/ir/src/main/scala/dfhdl/compiler/ir/DB.scala

@@ -190,10 +190,17 @@ final case class DB(
       case MemberView.Folded =>
         ownerMemberTable(owner)
       case MemberView.Flattened =>
+        def recur(owner: DFOwner, includeOwner: Boolean = true): List[DFMember] =
+          val members = ownerMemberTable(owner)
+          members.flatMap {
+            case d: DFDesignBlock => Some(d)
+            case o: DFOwner       => if (includeOwner) o :: recur(o) else recur(o)
+            case m                => Some(m)
+          }
+        end recur
         owner match
           case d: DFDesignBlock => designMemberTable(d)
-          case b: DFBlock       => blockMemberTable(b)
-          case _                => ownerMemberTable(owner)
+          case _                => recur(owner, includeOwner = false)
 
   // holds a hash table that lists members of each owner. The member list order is maintained.
   lazy val ownerMemberTable: Map[DFOwner, List[DFMember]] =