refactor resources to introduce toggle IO inversion and explcit active state

Author: Oron Port

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

@@ -186,7 +186,8 @@ object constraints:
       driveStrength: ConfigN[Int] = None,
       pullMode: ConfigN[IO.PullMode] = None,
       dualPurposeGroups: ConfigN[String] = None,
-      unusedPullMode: ConfigN[IO.PullMode] = None
+      unusedPullMode: ConfigN[IO.PullMode] = None,
+      invertActiveState: ConfigN[Boolean] = None
   ) extends SigConstraint derives CanEqual, ReadWriter:
     protected def `prot_=~`(that: HWAnnotation)(using MemberGetSet): Boolean = this == that
     lazy val getRefs: List[DFRef.TwoWayAny] = Nil
@@ -204,7 +205,8 @@ object constraints:
               driveStrength = driveStrength.merge(that.driveStrength),
               pullMode = pullMode.merge(that.pullMode),
               dualPurposeGroups = dualPurposeGroups.merge(that.dualPurposeGroups),
-              unusedPullMode = unusedPullMode.merge(that.unusedPullMode)
+              unusedPullMode = unusedPullMode.merge(that.unusedPullMode),
+              invertActiveState = invertActiveState.merge(that.invertActiveState)
             )
           )
         case _ => None
@@ -220,7 +222,8 @@ object constraints:
         csParam("driveStrength", driveStrength),
         csParam("pullMode", pullMode),
         csParam("dualPurposeGroups", dualPurposeGroups),
-        csParam("unusedPullMode", unusedPullMode)
+        csParam("unusedPullMode", unusedPullMode),
+        csParam("invertActiveState", invertActiveState)
       ).filter(_.nonEmpty).mkString(", ")
       s"""@io($params)"""
     end codeString

core/src/main/scala/dfhdl/core/DFVal.scala

@@ -1041,25 +1041,32 @@ object DFVal extends DFValLP:
     export DFTuple.Val.TCConv.given
     export DFVector.Val.TCConv.given
 
-  trait TC_Or_OPEN_Or_Resource[T <: DFTypeAny, R] extends TC[T, R]
+  trait TC_Or_OPEN_Or_Resource[T <: DFTypeAny, R] extends TC[T, R]:
+    def connect(dfVal: DFValOf[T], that: R)(using DFC): Unit
   object TC_Or_OPEN_Or_Resource:
     type Exact[T <: DFTypeAny] =
       Exact1[DFTypeAny, T, [t <: DFTypeAny] =>> t, DFC, TC_Or_OPEN_Or_Resource]
     given fromOPEN[T <: DFTypeAny]: TC_Or_OPEN_Or_Resource[T, OPEN] with
       type OutP = NOTCONST
       def conv(dfType: T, from: OPEN)(using DFC): Out = DFVal.OPEN(dfType)
+      def connect(dfVal: DFValOf[T], that: OPEN)(using DFC): Unit =
+        dfVal.connect(conv(dfVal.dfType, that))
     given fromTC[
         T <: DFTypeAny,
         R,
         TC <: DFVal.TC[T, R]
     ](using tc: TC): TC_Or_OPEN_Or_Resource[T, R] with
       type OutP = tc.OutP
       def conv(dfType: T, from: R)(using DFC): Out = tc(dfType, from)
+      def connect(dfVal: DFValOf[T], that: R)(using DFC): Unit =
+        dfVal.connect(conv(dfVal.dfType, that))
     given fromResource[T <: DFTypeAny, R <: Resource](using
-        Resource.CanConnect[R, DFValOf[T]] // just type checking
+        cc: Resource.CanConnect[R, DFValOf[T]]
     ): TC_Or_OPEN_Or_Resource[T, R] with
       type OutP = NOTCONST
       def conv(dfType: T, from: R)(using DFC): Out = ???
+      def connect(dfVal: DFValOf[T], that: R)(using DFC): Unit =
+        cc.connect(that, dfVal)
   end TC_Or_OPEN_Or_Resource
 
   trait Compare[T <: DFTypeAny, V, Op <: FuncOp, C <: Boolean] extends TCCommon[T, V, DFValAny]:
@@ -1443,9 +1450,7 @@ object DFPortOps:
     ): ConnectPlaceholder =
       given CTName = CTName("<>")
       trydf {
-        rhs.exactFrom match
-          case resource: Resource => resource.connect(dfPort)
-          case _                  => dfPort.connect(rhs(dfPort.dfType))
+        rhs.tc.connect(dfPort, rhs.exactFrom)
       }
       ConnectPlaceholder
   end extension

core/src/main/scala/dfhdl/hw/annotation.scala

@@ -101,12 +101,13 @@ object constraints:
       driveStrength: ir.ConfigN[Int] = None,
       pullMode: ir.ConfigN[io.PullMode] = None,
       dualPurposeGroups: ir.ConfigN[String] = None,
-      unusedPullMode: ir.ConfigN[io.PullMode] = None
+      unusedPullMode: ir.ConfigN[io.PullMode] = None,
+      invertActiveState: ir.ConfigN[Boolean] = None
   ) extends SigConstraint:
     val asIR: ir.constraints.IO =
       ir.constraints.IO(
         bitIdx, loc, levelVolt, standard, slewRate, driveStrength, pullMode, dualPurposeGroups,
-        unusedPullMode
+        unusedPullMode, invertActiveState
       )
   end io
   object io:

core/src/main/scala/dfhdl/platforms/resources/ResourceContext.scala

@@ -39,8 +39,9 @@ trait ResourceContext extends OnCreateEvents, HasDFC, HasClsMetaArgs:
   protected def __dfc: DFC =
     println("Severe error: missing DFHDL context!\nMake sure you enable the DFHDL compiler plugin.")
     sys.exit(1)
-  protected def injectConstraint(constraint: Constraint): Unit =
+  final protected[resources] def injectConstraint(constraint: Constraint): this.type =
     resourceConstraints += constraint
+    this
   protected def setClsNamePos(
       name: String,
       position: Position,

core/src/main/scala/dfhdl/platforms/resources/ToggleIO.scala

@@ -0,0 +1,30 @@
+package dfhdl.platforms.resources
+import dfhdl.Encoded.Toggle
+import dfhdl.core.*
+import Resource.CanConnect
+import dfhdl.internals.*
+import dfhdl.compiler.ir.constraints
+
+trait ToggleIO[T <: Toggle] extends IO:
+  val activeState: T
+
+object ToggleIO:
+  given [T <: Toggle, R <: ToggleIO[T], V <: DFValOf[DFBoolOrBit]](using
+      dfc: DFC,
+      t: ShowType[T]
+  )(using
+      expectedActiveState: GivenOrError[
+        ExpectedActiveState[T],
+        "Missing implicit expected active state for toggle resource `" +
+          t.Out +
+          "`.\nTo fix this, add:\n  `given ExpectedActiveState[" + t.Out + "] = " + t.Out + ".EXPECTED_ACTIVE_STATE`"
+      ]
+  ): CanConnect[R, V] = (resource: R, dfVal: V) =>
+    resource.injectConstraint(constraints.IO(invertActiveState =
+      resource.activeState != expectedActiveState.value
+    )).connect(dfVal)
+end ToggleIO
+
+opaque type ExpectedActiveState[T <: Toggle] <: T = T
+object ExpectedActiveState:
+  given [T <: Toggle]: Conversion[T, ExpectedActiveState[T]] = identity

internals/src/main/scala/dfhdl/internals/helpers.scala

@@ -278,6 +278,15 @@ object OptionalGiven extends OptionalGivenLP:
   given fromValue[T](using t: T): OptionalGiven[T] with
     val value: Option[T] = Some(t)
 
+trait GivenOrError[T, Msg <: String]:
+  val value: T
+protected trait GivenOrErrorLP:
+  inline given [T, Msg <: String](using ValueOf[Msg]): GivenOrError[T, Msg] =
+    compiletime.error(valueOf[Msg])
+object GivenOrError extends GivenOrErrorLP:
+  given fromValue[T, Msg <: String](using t: T): GivenOrError[T, Msg] with
+    val value: T = t
+
 trait IsGiven[T]:
   type Out <: Boolean
   val value: Out

lib/src/main/scala/dfhdl/platforms/resources/Button.scala

@@ -7,4 +7,4 @@ enum Button extends Encoded.Toggle:
 
 object Button:
   @io(standard = io.Standard.LVCMOS)
-  class Resource(val activeState: Button = Button.Pressed) extends ToggleIO
+  class Resource(val activeState: Button = Button.Pressed) extends ToggleIO[Button]

lib/src/main/scala/dfhdl/platforms/resources/IOBus.scala

@@ -9,16 +9,9 @@ import Resource.CanConnect
 class IOBus[T <: IO, L <: Int] private (val ios: List[T]) extends ResourceDeps:
   def apply(i: Int): T = ios(i)
   lazy val upstreamDeps: List[Resource] = ios
-  @dfhdl.internals.metaContextIgnore
-  override protected[dfhdl] def connect(that: DFValAny)(using dfc: DFC): Unit =
-    import dfc.getSet
-    assert(ios.length == that.asIR.width, "Width mismatch")
-    for (i <- 0 until ios.length)
-      ios(i).connect(that.bits(i))
-  end connect
 object IOBus:
-  def fill[L <: Int & Singleton](length: L)(f: => IO)(using dfc: DFC): IOBus[IO, L] =
-    forced[IO, L](List.tabulate(length)(i => f.injectID(s"${dfc.getMeta.name}($i)")))
+  def fill[T <: IO, L <: Int & Singleton](length: L)(f: => T)(using dfc: DFC): IOBus[T, L] =
+    forced[T, L](List.tabulate(length)(i => f.injectID(s"${dfc.getMeta.name}($i)")))
   private def forced[T <: IO, L <: Int](ios: List[T])(using DFC): IOBus[T, L] =
     new IOBus[T, L](ios.toList)
   transparent inline def apply[T <: IO](inline ios: T*): IOBus[T, ?] = ${ applyMacro[T]('ios) }
@@ -42,6 +35,9 @@ object IOBus:
       dfc: DFC,
       wT: Width[T]
   )(using
-      check: AssertGiven[RL =:= wT.OutI, "Width mismatch"]
-  ): CanConnect[R, V] = (resource: R, dfVal: V) => resource.connect(dfVal)
+      check: AssertGiven[RL =:= wT.OutI, "Width mismatch"],
+      cc: CanConnect[RT, DFValOf[DFBit]]
+  ): CanConnect[R, V] = (resource: R, dfVal: V) =>
+    for (i <- 0 until resource.ios.length)
+      cc.connect(resource.ios(i), dfVal.bits(i))
 end IOBus

lib/src/main/scala/dfhdl/platforms/resources/Led.scala

@@ -5,6 +5,6 @@ import dfhdl.compiler.ir.constraints.IO
 enum Led extends Encoded.Toggle:
   case Off, On
 object Led:
-  class Resource(val activeState: Led = Led.On) extends ToggleIO:
+  class Resource(val activeState: Led = Led.On) extends ToggleIO[Led]:
     private val pullMode = if (activeState == Led.On) IO.PullMode.DOWN else IO.PullMode.UP
     injectConstraint(IO(standard = IO.Standard.LVCMOS, unusedPullMode = pullMode))

lib/src/main/scala/dfhdl/platforms/resources/Switches.scala

@@ -6,22 +6,22 @@ enum SwitchUD extends Encoded.Toggle:
   case Down, Up
 object SwitchUD:
   @io(standard = io.Standard.LVCMOS)
-  class Resource(val activeState: SwitchUD = SwitchUD.Up) extends ToggleIO
+  class Resource(val activeState: SwitchUD = SwitchUD.Up) extends ToggleIO[SwitchUD]
 
 enum SwitchRL extends Encoded.Toggle:
   case Left, Right
 object SwitchRL:
   @io(standard = io.Standard.LVCMOS)
-  class Resource(val activeState: SwitchRL = SwitchRL.Right) extends ToggleIO
+  class Resource(val activeState: SwitchRL = SwitchRL.Right) extends ToggleIO[SwitchRL]
 
 enum SwitchNS extends Encoded.Toggle:
   case South, North
 object SwitchNS:
   @io(standard = io.Standard.LVCMOS)
-  class Resource(val activeState: SwitchNS = SwitchNS.North) extends ToggleIO
+  class Resource(val activeState: SwitchNS = SwitchNS.North) extends ToggleIO[SwitchNS]
 
 enum SwitchEW extends Encoded.Toggle:
   case West, East
 object SwitchEW:
   @io(standard = io.Standard.LVCMOS)
-  class Resource(val activeState: SwitchEW = SwitchEW.East) extends ToggleIO
+  class Resource(val activeState: SwitchEW = SwitchEW.East) extends ToggleIO[SwitchEW]