clash-prelude 1.10.3 → 1.10.4
raw patch · 15 files changed
+233/−50 lines, 15 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
Files
- CHANGELOG.md +62/−0
- clash-prelude.cabal +1/−1
- src/Clash/Class/BitPack/Internal.hs +5/−0
- src/Clash/Class/NumConvert.hs +93/−2
- src/Clash/Class/Resize.hs +6/−3
- src/Clash/Explicit/Mealy.hs +6/−5
- src/Clash/Explicit/Moore.hs +4/−3
- src/Clash/Explicit/Prelude/Safe.hs +7/−7
- src/Clash/Prelude/Mealy.hs +7/−6
- src/Clash/Prelude/Moore.hs +4/−3
- src/Clash/Sized/Index.hs +3/−0
- src/Clash/Sized/Internal/BitVector.hs +14/−8
- src/Clash/Sized/Internal/Index.hs +7/−4
- src/Clash/Sized/Internal/Signed.hs +7/−4
- src/Clash/Sized/Internal/Unsigned.hs +7/−4
CHANGELOG.md view
@@ -1,5 +1,67 @@ # Changelog for the Clash project +## 1.10.4 - *17 Nov, 2026*++### Changed:++- Clash now derives more names in the generated HDL from the source code:++ * Arguments of data constructors are named after the record field they are passed to, e.g. `c$baudCount` instead of `c$app_arg` for the second field of `Tx { txState, baudCount }`.+ * Arguments of functions are named after the function and its parameter, e.g. `c$txStep_s` for the state of `mealy txStep`.+ * Case alternatives are named after the constructor they match, e.g. `c$x_case_Idle` instead of `c$x_case_alt` for the alternative `Idle -> ...` of `x = case s of ...`.+ * Pattern bindings such as `(nextState, output) = ...` are named after their variables, e.g. `nextState_output` instead of `ds`.+ * Variables made up by GHC, such as `eta`, are named after the parameter of the user-defined function they're passed to. This also names ports of top entities without a `Synthesize` annotation.+ * User-written names are kept when they are aliases of variables Clash made up. For example, `dSCL` in `let dSCL = fst _dI2C` now names the register holding that field.++ [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Fields of SystemVerilog structs for records are now named after the record fields, e.g. `baudCount` instead of `Tx_sel1` for the field `baudCount` of a record `Tx`. When a record field isn't a valid SystemVerilog identifier, such as a keyword like `input` or a name with a `'`, the struct's fields are named like `Tx_sel1_baudCount` instead. Fields of tuples and other products without field names keep names like `Tuple2_sel0`.+ [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Removing unused declarations no longer shuffles the order of the remaining declarations in the generated HDL.+ [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Comparing constructors of enumerations with derived `==`, such as `mode == Done`, no longer produces an `Int`-wide signal named `c$case_scrut` in the HDL.+ [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Alternatives of case statements in the generated HDL now mention the constructor they match in a comment, e.g. `2'b00 : busy = 1'b0; // Idle`.+ [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Signals holding a record field that the HDL matches on are now named after the record and the field, e.g. `s_mode` for the field `mode` of a signal `s`.+ [#3503](https://github.com/clash-lang/clash-compiler/pull/3503)+- Clash now reports errors in the module it compiles directly, instead of wrapping them in a message about loading the module from both precompiled and local sources.+ [#2365](https://github.com/clash-lang/clash-compiler/issues/2365) [#2680](https://github.com/clash-lang/clash-compiler/issues/2680)+- Improved the documentation on converting between number types.+ [#3537](https://github.com/clash-lang/clash-compiler/pull/3537)+- The error for an inline primitive with a mismatched name now points at the annotated function.+ [#2365](https://github.com/clash-lang/clash-compiler/issues/2365)++### Fixed:++- Clash's internal `split#` unfolding now returns zero for zero-width halves, matching its Haskell counterpart.+ [#3490](https://github.com/clash-lang/clash-compiler/pull/3490)+- `GHC.Num.Integer.integerLogBase#` and `GHC.Num.Natural.naturalLogBase#` are now constant folded accurately, even in cases where these functions return errors.+ [#3492](https://github.com/clash-lang/clash-compiler/pull/3492)+- Unhandled `error` calls are reported with their `HasCallStack` backtrace again on GHC 9.12 and later.+ [#3449](https://github.com/clash-lang/clash-compiler/pull/3449)+- Errors raised while compiling top entities concurrently now report the backtrace they were thrown with, instead of one pointing into `async`.+ [#3449](https://github.com/clash-lang/clash-compiler/pull/3449)+- Clash no longer takes quadratic or exponential time to compile designs that use `iterateI` with a function that inspects its argument more than once, e.g. `iterateI (\(Just n) -> if n == maxBound then Nothing else Just (n + 1)) (Just 0)`, when the resulting vector is consumed by functions such as `takeI` or `foldr`.+ [#3477](https://github.com/clash-lang/clash-compiler/issues/3477) [#3539](https://github.com/clash-lang/clash-compiler/pull/3539)+- Clash now reports an error when `clash-lib`'s `mkFunInput` gets called with a local variable as its function input.+ [#3499](https://github.com/clash-lang/clash-compiler/pull/3499)+- The VHDL backend now generates valid VHDL for entities without ports, such as a top entity whose ports are all zero-width. This can be helpful when creating self-contained VHDL test benches.+ [#3500](https://github.com/clash-lang/clash-compiler/pull/3500)+- Clash's evaluator no longer produces an `SNat` newtype constructor when evaluating `withSomeSNat`.+ [#3491](https://github.com/clash-lang/clash-compiler/pull/3491)+- Clash no longer crashes on `iterateI` with functions such as `map f` or `resize`.+ [#3495](https://github.com/clash-lang/clash-compiler/issues/3495)+- Constant `BitVector` indices in Verilog and SystemVerilog are now rendered as plain integers, avoiding `64'sd` prefixes that caused warnings in tools such as Verilator.+ [#3056](https://github.com/clash-lang/clash-compiler/issues/3056)+- Clash no longer duplicates components whose result is projected out of more than once.+ [#3517](https://github.com/clash-lang/clash-compiler/issues/3517) [#3519](https://github.com/clash-lang/clash-compiler/pull/3519)+- Clash no longer duplicates components when applying a primitive to another instantiation of a primitive in certain situations.+ [#3516](https://github.com/clash-lang/clash-compiler/issues/3516) [#3518](https://github.com/clash-lang/clash-compiler/pull/3518)+- Clash now reports a clear error for functions returning a non-representable type that it can't inline away.+ [#3521](https://github.com/clash-lang/clash-compiler/issues/3521)+- Generating Verilog or SystemVerilog for `BitVector` indexing now uses the built-in blackbox function directly, avoiding unnecessary interpreter sessions that slowed compilation and could crash the compiler.+ [#3522](https://github.com/clash-lang/clash-compiler/pull/3522)+ ## 1.10.3 - *14 Oct, 2026* ### Added:
clash-prelude.cabal view
@@ -1,6 +1,6 @@ Cabal-version: 2.2 Name: clash-prelude-Version: 1.10.3+Version: 1.10.4 Synopsis: Clash: a functional hardware description language - Prelude library Description: Clash is a functional hardware description language that borrows both its
src/Clash/Class/BitPack/Internal.hs view
@@ -211,6 +211,11 @@ {-# INLINE[1] bitCoerce #-} -- | Coerce a value from one type to another through its bit representation. --+-- This keeps the bit pattern, not the numeric value. To keep the value, use+-- 'Clash.Class.NumConvert.numConvert' or+-- 'Clash.Class.NumConvert.maybeNumConvert'. See "Clash.Class.NumConvert" for an+-- overview of conversions between number types.+-- -- >>> pack (-5 :: Signed 6) -- 0b11_1011 -- >>> bitCoerce (-5 :: Signed 6) :: Unsigned 6
src/Clash/Class/NumConvert.hs view
@@ -1,5 +1,6 @@ {- | Copyright : (C) 2025 , Martijn Bastiaan+ 2026 , QBayLogic B.V. License : BSD2 (see the file LICENSE) Maintainer : QBayLogic B.V. <devops@qbaylogic.com> @@ -11,9 +12,91 @@ * 'NumConvert': for conversions that, based on types, are guaranteed to succeed. * 'MaybeNumConvert': for conversions that may fail for some values. -As opposed to 'Prelude.fromIntegral', all conversions are translatable to-synthesizable HDL.+As opposed to 'Prelude.fromIntegral', no conversion silently changes the value. +== __Choosing a conversion__+Clash offers several ways to convert between number types such as+'Clash.Sized.BitVector.BitVector', 'Clash.Sized.Unsigned.Unsigned',+'Clash.Sized.Signed.Signed', 'Clash.Sized.Index.Index', 'Int' and 'Data.Word.Word8'.+Which one to use depends on what should happen to the value.++=== Keep the value, and the target type can hold every value of the source type+Use 'numConvert'. If the target type cannot represent every value of the source+type, the conversion is rejected at compile time.++>>> numConvert (3 :: Index 8) :: Unsigned 3+3+>>> numConvert (200 :: Unsigned 8) :: Signed 9+200+>>> numConvert (-3 :: Signed 4) :: Int+-3++=== Keep the value, but the target type might not hold it+Use 'maybeNumConvert'. It returns 'Nothing' for values the target type cannot+represent.++>>> maybeNumConvert (-3 :: Signed 8) :: Maybe (Unsigned 8)+Nothing+>>> maybeNumConvert (100 :: Unsigned 8) :: Maybe (Index 128)+Just 100++=== Change the width, keep the type+Use 'Clash.Class.Resize.resize', 'Clash.Class.Resize.zeroExtend',+'Clash.Class.Resize.signExtend' or 'Clash.Class.Resize.truncateB' from the+'Clash.Class.Resize.Resize' class. Making a number narrower with+'Clash.Class.Resize.truncateB' drops its most significant bits.+'Clash.Class.Resize.resize' does the same, except for signed numbers: it keeps+the sign bit and drops the bits next to it. 'Clash.Sized.Index.Index' is an+exception: a value that does not fit results in an+'Clash.XException.XException'.++>>> resize (-3 :: Signed 4) :: Signed 8+-3+>>> truncateB (300 :: Unsigned 16) :: Unsigned 8+44+>>> resize (7 :: Signed 4) :: Signed 3+3+>>> truncateB (7 :: Signed 4) :: Signed 3+-1++If you know a value fits, use 'Clash.Class.Resize.checkedResize' or+'Clash.Class.Resize.checkedTruncateB' to have simulation check that assumption.+To handle values that do not fit, use 'maybeNumConvert'.++=== Keep the bits, change the type+Use 'Clash.Class.BitPack.bitCoerce' to convert between types of the same bit+width, or 'Clash.Class.BitPack.pack' and 'Clash.Class.BitPack.unpack' to convert+to and from 'Clash.Sized.BitVector.BitVector'. These keep the bit pattern, not+the value: a negative 'Clash.Sized.Signed.Signed' number becomes a large+'Clash.Sized.Unsigned.Unsigned' one.++>>> bitCoerce (-5 :: Signed 6) :: Unsigned 6+59+>>> pack (5 :: Unsigned 4)+0b0101++Not every bit pattern represents an 'Clash.Sized.Index.Index'. Use+'Clash.Sized.Index.bv2i' to pick an 'Clash.Sized.Index.Index' that can hold all+of them:++>>> bv2i (12 :: BitVector 4)+12++=== Change the type and drop bits+Combine the conversions above. For example, to keep the 8 least significant bits+of a @Signed 16@ as an @Unsigned 8@:++>>> truncateB (bitCoerce (-1 :: Signed 16) :: Unsigned 16) :: Unsigned 8+255++=== Why not 'fromIntegral'?+'fromIntegral' converts through 'Integer', which has a fixed width in HDL (64+bits by default, see @-fclash-intwidth@). Bits above that width are lost. It+also hides what happens to values the target type cannot hold:+'Clash.Sized.Unsigned.Unsigned' and 'Clash.Sized.Signed.Signed' wrap around,+while 'Clash.Sized.Index.Index' results in an 'Clash.XException.XException'.+The functions above make that choice explicit.+ == __Relation to @convertible@__ Type classes exported here are similar to the @convertible@ package in that it aims to facilitate conversions between different types. It is different in three@@ -42,3 +125,11 @@ import Clash.Class.NumConvert.Internal.MaybeNumConvert import Clash.Class.NumConvert.Internal.NumConvert import Clash.Class.NumConvert.Internal.Canonical++{- $setup+>>> :set -fplugin GHC.TypeLits.Extra.Solver+>>> :set -fplugin GHC.TypeLits.KnownNat.Solver+>>> :set -fplugin GHC.TypeLits.Normalise+>>> import Clash.Prelude+>>> import Clash.Class.NumConvert+-}
src/Clash/Class/Resize.hs view
@@ -36,6 +36,8 @@ import GHC.TypeLits (OrderingI(EQI, GTI), cmpNat) -- | Coerce a value to be represented by a different number of bits+--+-- To convert to a different type, see "Clash.Class.NumConvert". class Resize (f :: Nat -> Type) where -- | A sign-preserving resize operation --@@ -82,9 +84,10 @@ -- -- * __NB__: Check only affects simulation. I.e., no checks will be inserted -- into the generated HDL--- * __NB__: 'fromIntegral' is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- * __NB__: 'fromIntegral' goes through 'Integer', which has a fixed width in+-- HDL. Prefer 'Clash.Class.NumConvert.numConvert' or+-- 'Clash.Class.NumConvert.maybeNumConvert'. See "Clash.Class.NumConvert" for an+-- overview of conversions between number types. checkedFromIntegral :: forall a b. HasCallStack =>
src/Clash/Explicit/Mealy.hs view
@@ -3,8 +3,9 @@ 2017 , Google Inc. 2019 , Myrtle Software Ltd 2023 , Alex Mason+ 2026 , QBayLogic B.V. License : BSD2 (see the file LICENSE)- Maintainer : Christiaan Baaij <christiaan.baaij@gmail.com>+ Maintainer : QBayLogic B.V. <devops@qbaylogic.com> Whereas the output of a Moore machine depends on the /previous state/, the output of a Mealy machine depends on /current transition/.@@ -139,7 +140,7 @@ -> Enable dom -- ^ Global enable -> (s -> i -> (s,o))- -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+ -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@ -> s -- ^ Initial state -> (Signal dom i -> Signal dom o)@@ -197,7 +198,7 @@ -> Enable dom -- ^ Global enable -> (i -> State s o)- -- ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+ -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@. -> s -- ^ Initial state -> (Signal dom i -> Signal dom o)@@ -244,7 +245,7 @@ -> Reset dom -> Enable dom -> (s -> i -> (s,o))- -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+ -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@ -> s -- ^ Initial state -> (Unbundled dom i -> Unbundled dom o)@@ -264,7 +265,7 @@ -> Reset dom -> Enable dom -> (i -> State s o)- -- ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+ -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@. -> s -- ^ Initial state -> (Unbundled dom i -> Unbundled dom o)
src/Clash/Explicit/Moore.hs view
@@ -2,8 +2,9 @@ Copyright : (C) 2013-2016, University of Twente, 2017 , Google Inc. 2019 , Myrtle Software Ltd+ 2026 , QBayLogic B.V. License : BSD2 (see the file LICENSE)- Maintainer : Christiaan Baaij <christiaan.baaij@gmail.com>+ Maintainer : QBayLogic B.V. <devops@qbaylogic.com> Whereas the output of a Mealy machine depends on /current transition/, the output of a Moore machine depends on the /previous state/.@@ -85,7 +86,7 @@ -> Reset dom -> Enable dom -> (s -> i -> s)- -- ^ Transfer function in moore machine form: @state -> input -> newstate@+ -- ^ Transition function in moore machine form: @state -> input -> newstate@ -> (s -> o) -- ^ Output function in moore machine form: @state -> output@ -> s@@ -149,7 +150,7 @@ -> Reset dom -> Enable dom -> (s -> i -> s)- -- ^ Transfer function in moore machine form:+ -- ^ Transition function in moore machine form: -- @state -> input -> newstate@ -> (s -> o) -- ^ Output function in moore machine form:
src/Clash/Explicit/Prelude/Safe.hs view
@@ -2,7 +2,7 @@ Copyright : (C) 2013-2016, University of Twente, 2017 , Google Inc. 2019 , Myrtle Software Ltd,- 2021-2022, QBayLogic B.V.+ 2021-2026, QBayLogic B.V. License : BSD2 (see the file LICENSE) Maintainer : QBayLogic B.V. <devops@qbaylogic.com> @@ -244,13 +244,13 @@ -> Enable dom -> SNat n -> Signal dom Bool-riseEvery clk rst en SNat = moore clk rst en transfer output 0 (pure ())+riseEvery clk rst en SNat = moore clk rst en trans output 0 (pure ()) where output :: Index n -> Bool output = (== maxBound) - transfer :: Index n -> () -> Index n- transfer s _ = if (s == maxBound) then 0 else s+1+ trans :: Index n -> () -> Index n+ trans s _ = if (s == maxBound) then 0 else s+1 {-# INLINEABLE riseEvery #-} -- | Oscillate a @'Bool'@ for a given number of cycles, given the starting state.@@ -264,10 +264,10 @@ -> SNat n -> Signal dom Bool oscillate clk rst en begin SNat =- moore clk rst en transfer snd (0, begin) (pure ())+ moore clk rst en trans snd (0, begin) (pure ()) where- transfer :: (Index n, Bool) -> () -> (Index n, Bool)- transfer (s, i) _ =+ trans :: (Index n, Bool) -> () -> (Index n, Bool)+ trans (s, i) _ = if s == maxBound then (0, not i) -- reset state and oscillate output else (s+1, i) -- hold current output
src/Clash/Prelude/Mealy.hs view
@@ -3,8 +3,9 @@ 2017 , Google Inc. 2019 , Myrtle Software Ltd 2023 , Alex Mason+ 2026 , QBayLogic B.V. License : BSD2 (see the file LICENSE)- Maintainer : Christiaan Baaij <christiaan.baaij@gmail.com>+ Maintainer : QBayLogic B.V. <devops@qbaylogic.com> Whereas the output of a Moore machine depends on the /previous state/, the output of a Mealy machine depends on /current transition/.@@ -123,7 +124,7 @@ :: ( HiddenClockResetEnable dom , NFDataX s ) => (s -> i -> (s,o))- -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+ -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@ -> s -- ^ Initial state -> (Signal dom i -> Signal dom o)@@ -164,7 +165,7 @@ , Bundle i , Bundle o ) => (s -> i -> (s,o))- -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+ -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@ -> s -- ^ Initial state -> (Unbundled dom i -> Unbundled dom o)@@ -212,7 +213,7 @@ :: ( HiddenClockResetEnable dom , NFDataX s ) => (i -> State s o)- -- ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+ -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@. -> s -- ^ Initial state -> (Signal dom i -> Signal dom o)@@ -228,7 +229,7 @@ , Bundle i , Bundle o ) => (i -> State s o)- -- ^ Transfer function in mealy machine handling inputs using @Control.Monad.Strict.State s@.+ -- ^ Transition function in mealy machine handling inputs using @Control.Monad.Strict.State s@. -> s -- ^ Initial state -> (Unbundled dom i -> Unbundled dom o)@@ -244,7 +245,7 @@ , Bundle i , Bundle o ) => (s -> i -> (s,o))- -- ^ Transfer function in mealy machine form: @state -> input -> (newstate,output)@+ -- ^ Transition function in mealy machine form: @state -> input -> (newstate,output)@ -> s -- ^ Initial state -> (Unbundled dom i -> Unbundled dom o)
src/Clash/Prelude/Moore.hs view
@@ -2,8 +2,9 @@ Copyright : (C) 2013-2016, University of Twente 2017 , Google Inc. 2019 , Myrtle Software Ltd+ 2026 , QBayLogic B.V. License : BSD2 (see the file LICENSE)- Maintainer : Christiaan Baaij <christiaan.baaij@gmail.com>+ Maintainer : QBayLogic B.V. <devops@qbaylogic.com> Whereas the output of a Mealy machine depends on /current transition/, the output of a Moore machine depends on the /previous state/.@@ -82,7 +83,7 @@ :: ( HiddenClockResetEnable dom , NFDataX s ) => (s -> i -> s)- -- ^ Transfer function in moore machine form: @state -> input -> newstate@+ -- ^ Transition function in moore machine form: @state -> input -> newstate@ -> (s -> o) -- ^ Output function in moore machine form: @state -> output@ -> s@@ -138,7 +139,7 @@ , Bundle i , Bundle o ) => (s -> i -> s)- -- ^ Transfer function in moore machine form: @state -> input -> newstate@+ -- ^ Transition function in moore machine form: @state -> input -> newstate@ -> (s -> o) -- ^ Output function in moore machine form: @state -> output@ -> s
src/Clash/Sized/Index.hs view
@@ -42,5 +42,8 @@ -- -- 'bv2i' on the other hand will /never/ fail at run-time, because the -- 'BitVector' argument determines the size.+--+-- See "Clash.Class.NumConvert" for an overview of conversions between number+-- types. bv2i :: KnownNat n => BitVector n -> Index (2^n) bv2i = unpack#
src/Clash/Sized/Internal/BitVector.hs view
@@ -233,10 +233,13 @@ -- * Bit indices are descending -- * 'Num' instance performs /unsigned/ arithmetic. ----- __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- -- BitVector has the <https://downloads.haskell.org/ghc/latest/docs/html/users_guide/exts/roles.html type role> --@@ -260,10 +263,13 @@ -- | A single bit ----- __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. data Bit = -- | The constructor, 'Bit', and the fields, 'unsafeMask#' and 'unsafeToInteger#', are not -- synthesizable.
src/Clash/Sized/Internal/Index.hs view
@@ -163,10 +163,13 @@ -- *** Exception: X: Clash.Sized.Index: result 8 is out of bounds: [0..7] -- ... ----- __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- -- Index has the <https://downloads.haskell.org/ghc/latest/docs/html/users_guide/exts/roles.html type role> --
src/Clash/Sized/Internal/Signed.hs view
@@ -161,10 +161,13 @@ -- a 'Signed' @n@ number has a range of: [-(2^(@n@-1)) .. 2^(@n@-1)-1] for -- @n > 0@. When @n = 0@, both the min and max bound are 0. ----- * __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- * __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- * __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want -- saturation on overflow, check out the 'SaturatingNum' class. --
src/Clash/Sized/Internal/Unsigned.hs view
@@ -165,10 +165,13 @@ -- -- Given @n@ bits, an 'Unsigned' @n@ number has a range of: [0 .. 2^@n@-1] ----- * __NB__: The usual Haskell method of converting an integral numeric type to--- another, 'fromIntegral', is not well suited for Clash as it will go through--- 'Integer' which is arbitrarily bounded in HDL. Instead use--- 'Clash.Class.BitPack.bitCoerce' and the 'Resize' class.+-- * __NB__: To convert to another number type, use+-- 'Clash.Class.NumConvert.numConvert' if the target type can hold every value,+-- 'Clash.Class.NumConvert.maybeNumConvert' if it might not, the+-- 'Clash.Class.Resize.Resize' class to change the width, and+-- 'Clash.Class.BitPack.bitCoerce' only to reinterpret the bits. Avoid+-- 'fromIntegral': it goes through 'Integer', which has a fixed width in HDL.+-- See "Clash.Class.NumConvert" for an overview with examples. -- * __NB__: The 'Num' operators perform @wrap-around@ on overflow. If you want -- saturation on overflow, check out the 'SaturatingNum' class. --