Merge pull request #2540 from clash-lang/deprecate-from-polarity

Add `unsafe{From,To}Active{Low,High}`
clash-lang · Jul 14, 2023 · 897a16f · 897a16f
2 parents fadedce + 8cb9f45
commit 897a16f
Show file tree

Hide file tree

Showing 43 changed files with 206 additions and 111 deletions.
diff --git a/changelog/2022-07-26T13_16_31-05_00_reset_polarity_dsl b/changelog/2022-07-26T13_16_31-05_00_reset_polarity_dsl
@@ -1 +1 @@
-INTERNAL NEW: Added `unsafeToHighPolarity` and `unsafeToLowPolarity` to `Clash.Primitives.DSL`. [#2270](https://github.com/clash-lang/clash-compiler/pull/2270)
+INTERNAL NEW: Added `unsafeToActiveHigh` and `unsafeToActiveLow` to `Clash.Primitives.DSL`. [#2270](https://github.com/clash-lang/clash-compiler/pull/2270)
diff --git a/changelog/2023-07-13T14_49_23+02_00_rename_from_polarity b/changelog/2023-07-13T14_49_23+02_00_rename_from_polarity
@@ -0,0 +1 @@
+DEPRECATED: `unsafeFromLowPolarity`, `unsafeFromHighPolarity`, `unsafeToLowPolarity`, `unsafeToHighPolarity` have been replaced by `unsafeFromActiveLow`, `unsafeFromActiveHigh`, `unsafeToActiveLow`, `unsafeToActiveHigh`. While former ones will continue to exist, a deprecation warning has been added pointing to the latter ones.
diff --git a/clash-cores/src/Clash/Cores/Xilinx/DcFifo.hs b/clash-cores/src/Clash/Cores/Xilinx/DcFifo.hs
@@ -177,8 +177,8 @@ dcFifo DcConfig{..} wClk wRst rClk rRst writeData rEnable =
     _ -> error $ show 'dcFifo <> " only supports synchronous resets"
 
  where
-  rstSignalR = unsafeToHighPolarity rRst
-  rstSignalW = unsafeToHighPolarity wRst
+  rstSignalR = unsafeToActiveHigh rRst
+  rstSignalW = unsafeToActiveHigh wRst
 
   fifoSize = natToNum @(2 ^ depth - 1) @Int
   dataCount = fromIntegral . Seq.length

diff --git a/clash-cores/src/Clash/Cores/Xilinx/DcFifo/Internal/BlackBoxes.hs b/clash-cores/src/Clash/Cores/Xilinx/DcFifo/Internal/BlackBoxes.hs
@@ -178,7 +178,7 @@ dcFifoBBTF DcConfig{..} bbCtx
       let domty = DSL.ety knownDomainWrite
       in case stripVoid domty of
            N.KnownDomain _ _ _ Synchronous _ _ ->
-             DSL.unsafeToHighPolarity "wr_rst_high" domty wRst
+             DSL.unsafeToActiveHigh "wr_rst_high" domty wRst
            N.KnownDomain _ _ _ Asynchronous _ _ ->
              error $
                show 'dcFifoTF <> ": dcFifo only supports synchronous resets"
@@ -190,7 +190,7 @@ dcFifoBBTF DcConfig{..} bbCtx
       let domty = DSL.ety knownDomainRead
       in case stripVoid domty of
            N.KnownDomain _ _ _ Synchronous _ _ ->
-             DSL.unsafeToHighPolarity "rd_rst_high" domty rRst
+             DSL.unsafeToActiveHigh "rd_rst_high" domty rRst
            N.KnownDomain _ _ _ Asynchronous _ _ ->
              error $
                show 'dcFifoTF <> ": dcFifo only supports synchronous resets"

diff --git a/clash-cores/test/Test/Cores/Xilinx/DcFifo.hs b/clash-cores/test/Test/Cores/Xilinx/DcFifo.hs
@@ -260,7 +260,7 @@ testOverflow = testCase "Overflows appropriately" $ do
 
   fifo = dcFifo @4 defConfig{dcOverflow = True} clk noRst clk noRst
   clk = clockGen @D3
-  noRst = unsafeFromHighPolarity $ pure False
+  noRst = unsafeFromActiveHigh $ pure False
   drive15 = mealy clk noRst enableGen go 15 (pure ())
   go 0 _ = (0 :: Int, Nothing)
   go n _ = (n-1, Just (1 :: Int))
@@ -361,11 +361,11 @@ throughFifo d _ _ feed drain wrDataList rdStalls = rdDataList
   where
 
     wrClk = clockGen @write
-    noWrRst = unsafeFromHighPolarity $ pure False
+    noWrRst = unsafeFromActiveHigh $ pure False
     wrEna = enableGen @write
 
     rdClk = clockGen @read
-    noRdRst = unsafeFromHighPolarity $ pure False
+    noRdRst = unsafeFromActiveHigh $ pure False
     rdEna = enableGen @read
 
     wrData =

diff --git a/clash-lib/src/Clash/Primitives/DSL.hs b/clash-lib/src/Clash/Primitives/DSL.hs
@@ -76,8 +76,8 @@ module Clash.Primitives.DSL
   , unsignedFromBitVector
   , boolFromBits
 
-  , unsafeToHighPolarity
-  , unsafeToLowPolarity
+  , unsafeToActiveHigh
+  , unsafeToActiveLow
 
   -- ** Operations
   , andExpr
@@ -988,7 +988,7 @@ andExpr nm a b = do
   assign nm $ TExpr Bool (Identifier (Id.unsafeMake andTxt) Nothing)
 
 -- | Massage a reset to work as active-high reset.
-unsafeToHighPolarity
+unsafeToActiveHigh
   :: Backend backend
   => Text
   -- ^ Name hint
@@ -997,7 +997,7 @@ unsafeToHighPolarity
   -> TExpr
   -- ^ Reset signal
   -> State (BlockState backend) TExpr
-unsafeToHighPolarity nm dom rExpr =
+unsafeToActiveHigh nm dom rExpr =
   case extrResetPolarity dom of
     ActiveHigh -> pure rExpr
     ActiveLow -> notExpr nm rExpr
@@ -1007,7 +1007,7 @@ extrResetPolarity (Void (Just (KnownDomain _ _ _ _ _ p))) = p
 extrResetPolarity p = error ("Internal error: expected KnownDomain, got: " <> show p)
 
 -- | Massage a reset to work as active-low reset.
-unsafeToLowPolarity
+unsafeToActiveLow
   :: Backend backend
   => Text
   -- ^ Name hint
@@ -1016,7 +1016,7 @@ unsafeToLowPolarity
   -> TExpr
   -- ^ Reset signal
   -> State (BlockState backend) TExpr
-unsafeToLowPolarity nm dom rExpr =
+unsafeToActiveLow nm dom rExpr =
   case extrResetPolarity dom of
     ActiveLow -> pure rExpr
     ActiveHigh -> notExpr nm rExpr

diff --git a/clash-lib/src/Clash/Primitives/Xilinx/ClockGen.hs b/clash-lib/src/Clash/Primitives/Xilinx/ClockGen.hs
@@ -64,7 +64,7 @@ clockWizardDifferentialTemplate bbCtx
       clkWizInstName <- Id.makeBasic "clockWizardDifferential_inst"
       DSL.declarationReturn bbCtx "clockWizardDifferential" $ do
 
-        rstHigh <- DSL.unsafeToHighPolarity "reset" (DSL.ety knownDomIn) rst
+        rstHigh <- DSL.unsafeToActiveHigh "reset" (DSL.ety knownDomIn) rst
         pllOut <- DSL.declare "pllOut" Bit
         locked <- DSL.declare "locked" Bit
         pllLock <- DSL.boolFromBit "pllLock" locked

diff --git a/clash-prelude/src/Clash/Annotations/TopEntity.hs b/clash-prelude/src/Clash/Annotations/TopEntity.hs
@@ -84,8 +84,8 @@ topEntity clk20 rstBtn enaBtn modeBtn =
 
   -- Signal coming from the reset button is low when pressed, and high when
   -- not pressed. We convert this signal to the polarity of our domain with
-  -- /unsafeFromLowPolarity/.
-  rst = 'Clash.Signal.unsafeFromLowPolarity' ('Clash.Signal.unsafeFromReset' rstBtn)
+  -- /unsafeFromActiveLow/.
+  rst = 'Clash.Signal.unsafeFromActiveLow' ('Clash.Signal.unsafeFromReset' rstBtn)
 
   -- Instantiate a PLL: this stabilizes the incoming clock signal and indicates
   -- when the signal is stable. We're also using it to transform an incoming
@@ -99,11 +99,11 @@ topEntity clk20 rstBtn enaBtn modeBtn =
 
   -- Synchronize reset to clock signal coming from PLL. We want the reset to
   -- remain active while the PLL is NOT stable, hence the conversion with
-  -- /unsafeFromLowPolarity/
+  -- /unsafeFromActiveLow/
   rstSync =
     'Clash.Prelude.resetSynchronizer'
       clk50
-      ('Clash.Signal.unsafeFromLowPolarity' pllStable)
+      ('Clash.Signal.unsafeFromActiveLow' pllStable)
 
 blinkerT
   :: (BitVector 8, Bool, Index 16650001)

diff --git a/clash-prelude/src/Clash/Clocks/Deriving.hs b/clash-prelude/src/Clash/Clocks/Deriving.hs
@@ -51,7 +51,7 @@ derive' n = do
   -- Implementation of 'clocks'
   clkImpl <- [| Clock SSymbol Nothing |]
   lockImpl <- [| unsafeSynchronizer clockGen clockGen
-                   (unsafeToLowPolarity $(varE rst)) |]
+                   (unsafeToActiveLow $(varE rst)) |]
   let
     noInline  = PragmaD $ InlineP (mkName "clocks") NoInline FunLike AllPhases
     clkImpls  = replicate n clkImpl

diff --git a/clash-prelude/src/Clash/Explicit/DDR.hs b/clash-prelude/src/Clash/Explicit/DDR.hs
@@ -92,7 +92,7 @@ ddrIn#
   -> a
   -> Signal fast a
   -> Signal slow (a,a)
-ddrIn# (Clock _ Nothing) (unsafeToHighPolarity -> hRst) (fromEnable -> ena) i0 i1 i2 =
+ddrIn# (Clock _ Nothing) (unsafeToActiveHigh -> hRst) (fromEnable -> ena) i0 i1 i2 =
   case resetKind @fast of
     SAsynchronous ->
       goAsync

diff --git a/clash-prelude/src/Clash/Explicit/Reset.hs b/clash-prelude/src/Clash/Explicit/Reset.hs
@@ -30,10 +30,16 @@ module Clash.Explicit.Reset
   , systemResetGen
   , unsafeToReset
   , unsafeFromReset
-  , unsafeToHighPolarity
-  , unsafeToLowPolarity
+  , unsafeToActiveHigh
+  , unsafeToActiveLow
+  , unsafeFromActiveHigh
+  , unsafeFromActiveLow
+
+  -- * Deprecated
   , unsafeFromHighPolarity
   , unsafeFromLowPolarity
+  , unsafeToHighPolarity
+  , unsafeToLowPolarity
   ) where
 
 import           Data.Type.Equality ((:~:)(Refl))
@@ -111,7 +117,7 @@ import           GHC.TypeLits (type (+))
 --   -> Signal System (BitVector 8)
 -- topEntity clk rst key1 =
 --     let  (pllOut,pllStable) = altpll (SSymbol @"altpll50") clk rst
---          rstSync            = 'resetSynchronizer' pllOut (unsafeToHighPolarity pllStable)
+--          rstSync            = 'resetSynchronizer' pllOut (unsafeToActiveHigh pllStable)
 --     in   exposeClockResetEnable leds pllOut rstSync enableGen
 --   where
 --     key1R  = isRising 1 key1
@@ -184,8 +190,8 @@ resetSynchronizer clk rst = rstOut
 -- designed with this environment in mind.
 --
 -- === __Example 1__
--- >>> let sampleResetN n = sampleN n . unsafeToHighPolarity
--- >>> let resetFromList = unsafeFromHighPolarity . fromList
+-- >>> let sampleResetN n = sampleN n . unsafeToActiveHigh
+-- >>> let resetFromList = unsafeFromActiveHigh . fromList
 -- >>> let rst = resetFromList [True, True, False, False, True, False, False, True, True, False, True, True]
 -- >>> sampleResetN 12 (resetGlitchFilter d2 systemClockGen rst)
 -- [True,True,True,True,False,False,False,False,False,True,True,True]
@@ -230,7 +236,7 @@ resetGlitchFilter SNat clk rst =
 --
 -- Example:
 --
--- >>> let sampleWithReset = sampleN 8 . unsafeToHighPolarity
+-- >>> let sampleWithReset = sampleN 8 . unsafeToActiveHigh
 -- >>> sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (resetGenN (SNat @3)))
 -- [True,True,True,True,True,False,False,False]
 --
@@ -239,7 +245,7 @@ resetGlitchFilter SNat clk rst =
 -- intermediate assertions of the reset signal:
 --
 -- >>> let rst = fromList [True, False, False, False, True, False, False, False]
--- >>> sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (unsafeFromHighPolarity rst))
+-- >>> sampleWithReset (holdReset @System clockGen enableGen (SNat @2) (unsafeFromActiveHigh rst))
 -- [True,True,True,False,True,True,True,False]
 --
 holdReset
@@ -255,7 +261,7 @@ holdReset
   -- ^ Reset to extend
   -> Reset dom
 holdReset clk en SNat rst =
-  unsafeFromHighPolarity ((/=maxBound) <$> counter)
+  unsafeFromActiveHigh ((/=maxBound) <$> counter)
  where
   counter :: Signal dom (Index (n+1))
   counter = register clk rst en 0 (satSucc SatBound <$> counter)

diff --git a/clash-prelude/src/Clash/Explicit/Signal.hs b/clash-prelude/src/Clash/Explicit/Signal.hs
@@ -206,10 +206,10 @@ module Clash.Explicit.Signal
   , Reset
   , unsafeToReset
   , unsafeFromReset
-  , unsafeToHighPolarity
-  , unsafeToLowPolarity
-  , unsafeFromHighPolarity
-  , unsafeFromLowPolarity
+  , unsafeToActiveHigh
+  , unsafeToActiveLow
+  , unsafeFromActiveHigh
+  , unsafeFromActiveLow
     -- * Basic circuit functions
   , andEnable
   , enable -- DEPRECATED
@@ -267,6 +267,12 @@ module Clash.Explicit.Signal
   , readFromBiSignal
   , writeToBiSignal
   , mergeBiSignalOuts
+
+  -- * Deprecated
+  , unsafeFromHighPolarity
+  , unsafeFromLowPolarity
+  , unsafeToHighPolarity
+  , unsafeToLowPolarity
   )
 where
 
@@ -813,7 +819,7 @@ simulateB_lazy f = simulate_lazy (bundle . f . unbundle)
 
 -- | Like 'fromList', but resets on reset and has a defined reset value.
 --
--- >>> let rst = unsafeFromHighPolarity (fromList [True, True, False, False, True, False])
+-- >>> let rst = unsafeFromActiveHigh (fromList [True, True, False, False, True, False])
 -- >>> let res = fromListWithReset @System rst Nothing [Just 'a', Just 'b', Just 'c']
 -- >>> sampleN 6 res
 -- [Nothing,Nothing,Just 'a',Just 'b',Nothing,Just 'a']
@@ -827,7 +833,7 @@ fromListWithReset
   -> [a]
   -> Signal dom a
 fromListWithReset rst resetValue vals =
-  go (unsafeToHighPolarity rst) vals
+  go (unsafeToActiveHigh rst) vals
  where
   go (r :- rs) _ | r = resetValue :- go rs vals
   go (_ :- rs) [] = deepErrorX "fromListWithReset: input ran out" :- go rs []

diff --git a/clash-prelude/src/Clash/Intel/ClockGen.hs b/clash-prelude/src/Clash/Intel/ClockGen.hs
@@ -77,13 +77,13 @@ import Clash.Signal.Internal
 --  where
 --   (clk, pllStable) =
 --     'altpll' \@'Clash.Signal.System' ('SSymbol' \@\"altpll50to100\") clkInp
---            ('Clash.Signal.unsafeFromLowPolarity' rstInp)
---   rst = 'Clash.Signal.resetSynchronizer' clk ('Clash.Signal.unsafeFromLowPolarity' pllStable)
+--            ('Clash.Signal.unsafeFromActiveLow' rstInp)
+--   rst = 'Clash.Signal.resetSynchronizer' clk ('Clash.Signal.unsafeFromActiveLow' pllStable)
 -- @
 --
 -- 'Clash.Signal.resetSynchronizer' will keep the reset asserted when
 -- @pllStable@ is 'False', hence the use of
--- @'Clash.Signal.unsafeFromLowPolarity' pllStable@. Your circuit will have
+-- @'Clash.Signal.unsafeFromActiveLow' pllStable@. Your circuit will have
 -- signals of type @'Signal' 'Clash.Signal.System'@ and all the clocks and
 -- resets of your components will be the @clk@ and @rst@ signals generated here
 -- (modulo local resets, which will be based on @rst@ or never asserted at all
@@ -179,13 +179,13 @@ altpll !_ = knownDomain @domIn `seq` knownDomain @domOut `seq` clocks
 --  where
 --   (clk :: 'Clock' 'Clash.Signal.System', pllStable :: 'Signal' 'Clash.Signal.System' 'Bool')
 --     'alteraPll' ('SSymbol' \@\"alterapll50to100\") clkInp
---               ('Clash.Signal.unsafeFromLowPolarity' rstInp)
---   rst = 'Clash.Signal.resetSynchronizer' clk ('Clash.Signal.unsafeFromLowPolarity' pllStable)
+--               ('Clash.Signal.unsafeFromActiveLow' rstInp)
+--   rst = 'Clash.Signal.resetSynchronizer' clk ('Clash.Signal.unsafeFromActiveLow' pllStable)
 -- @
 --
 -- 'Clash.Signal.resetSynchronizer' will keep the reset asserted when
 -- @pllStable@ is 'False', hence the use of
--- @'Clash.Signal.unsafeFromLowPolarity' pllStable@. Your circuit will have
+-- @'Clash.Signal.unsafeFromActiveLow' pllStable@. Your circuit will have
 -- signals of type @'Signal' 'Clash.Signal.System'@ and all the clocks and
 -- resets of your components will be the @clk@ and @rst@ signals generated here
 -- (modulo local resets, which will be based on @rst@ or never asserted at all

diff --git a/clash-prelude/src/Clash/Signal.hs b/clash-prelude/src/Clash/Signal.hs
@@ -136,10 +136,10 @@ module Clash.Signal
   , Reset
   , unsafeToReset
   , unsafeFromReset
-  , unsafeToHighPolarity
-  , unsafeToLowPolarity
-  , unsafeFromHighPolarity
-  , unsafeFromLowPolarity
+  , unsafeToActiveHigh
+  , unsafeToActiveLow
+  , unsafeFromActiveHigh
+  , unsafeFromActiveLow
 #ifdef CLASH_MULTIPLE_HIDDEN
   , convertReset
 #endif
@@ -262,6 +262,12 @@ module Clash.Signal
   , HiddenClockName
   , HiddenResetName
   , HiddenEnableName
+
+    -- * Deprecated
+  , unsafeFromHighPolarity
+  , unsafeFromLowPolarity
+  , unsafeToHighPolarity
+  , unsafeToLowPolarity
   )
 where
 
@@ -417,7 +423,7 @@ topEntity
   -> Signal System (BitVector 8)
 topEntity clk rst key1 =
     let  (pllOut,pllStable) = 'Clash.Intel.ClockGen.altpll' (SSymbol \@\"altpll50\") clk rst
-         rstSync            = 'resetSynchronizer' pllOut (unsafeToHighPolarity pllStable)
+         rstSync            = 'resetSynchronizer' pllOut (unsafeToActiveHigh pllStable)
     in   'exposeClockResetEnable' leds pllOut rstSync enableGen
   where
     key1R  = isRising 1 key1
@@ -434,7 +440,7 @@ topEntity
   -> Signal System (BitVector 8)
 topEntity clk rst key1 =
     let  (pllOut,pllStable) = 'Clash.Intel.ClockGen.altpll' (SSymbol \@\"altpll50\") clk rst
-         rstSync            = 'resetSynchronizer' pllOut (unsafeToHighPolarity pllStable)
+         rstSync            = 'resetSynchronizer' pllOut (unsafeToActiveHigh pllStable)
     in   'withClockResetEnable' pllOut rstSync enableGen leds
   where
     key1R  = isRising 1 key1
@@ -2234,7 +2240,7 @@ unsafeSynchronizer =
 --
 -- Example:
 --
--- >>> sampleN @System 8 (unsafeToHighPolarity (holdReset (SNat @2)))
+-- >>> sampleN @System 8 (unsafeToActiveHigh (holdReset (SNat @2)))
 -- [True,True,True,False,False,False,False,False]
 --
 -- 'holdReset' holds the reset for an additional 2 clock cycles for a total
@@ -2252,7 +2258,7 @@ holdReset m =
 
 -- | Like 'fromList', but resets on reset and has a defined reset value.
 --
--- >>> let rst = unsafeFromHighPolarity (fromList [True, True, False, False, True, False])
+-- >>> let rst = unsafeFromActiveHigh (fromList [True, True, False, False, True, False])
 -- >>> let res = withReset rst (fromListWithReset Nothing [Just 'a', Just 'b', Just 'c'])
 -- >>> sampleN @System 6 res
 -- [Nothing,Nothing,Just 'a',Just 'b',Nothing,Just 'a']