v1.10.0

Release highlight:

• Clash.Class.NumConvert: Utilities for safely converting between various Clash number types #2915

Added:

• Added GHC 9.12 support

• Clash.Class.NumConvert: Utilities for safely converting between various Clash number types #2915

• Add Clash.XException.ShowX instance for Foreign.C.Types.CUShort. #2397

• Introduced various new types to Clash.Signal to more easily represent time and its relation to your clock domain. New types: Seconds, Milliseconds, Microseconds, Nanoseconds, Picoseconds, DomainToHz, HzToPeriod, PeriodToHz, PeriodToCycles, ClockDivider. #2734

• Distributive and Representable instances for Vec

• Resize functions maybeResize and maybeTruncateB to Clash.Class.Resize. Can be used to resize without loss of information. #2779

• Alongside the existing Eq-like and Ord-like signal operators like .==. and .<=. etc., there are now new functions for comparing with constants: .==, ==., ./=, /=., .<=, <=., .>=, >=., .>, >., .<, <., .&&, &&., .||, ||.. These are useful for comparing signals with constants in a more readable way. For example, a .==. pure True can now be replaced with a .== True. #2545

• instance HasField f (Signal dom r) (Signal dom a). This means record dot accesses will be passed to the underlying type. For example, this will work:

  data MyRecord = MyRecord { myField :: Int }
  
  a :: Signal dom MyRecord
  a = pure (MyRecord 3)
  
  b :: Signal dom Int
  b = a.myField

• BitPack instance for Data.Proxy.Proxy

• apEn, which is a mux that optionally applies an update function to a value. #3029

• regEnN, which is a chain of regEns. #3029

• Index 0 instances for BitPack, Bits, Counter, FiniteBits, Parity, and SaturatingNum. #2784

• Zero-sized block RAM implementations for blockRam1 and blockRamU. #2784

• Counter a => Counter (Vec 0 a) instance. #2784

• SaturatingNum and Bounded instances for Signal dom a. The sat family (satAdd, satSucc, ...) can now be used on Signals and {min,max}Bound can be used to construct them #2931

• -fclash-no-concurrent-topentity-compilation flag to disable concurrent compilation of top entities. This is mostly useful to get a consistent debug output.

• SomeBoundedSNat and Hedgehog generators #3183

• Eq, NFData, ShowX and BitPack instances for RamOp.

• smapWithBounds extending smap via offering a proof witness for the upper bound of the vector size to the mapping function. #2686

• The function Clash.Explicit.DDR.ddrForwardClock, which uses a DDR output primitive to forward a clock signal to a DDR-capable output pin. #2876

Removed:

• Support for GHC versions 9.4 and older
• Newer Verilators (> v5) can deal with delay statements, hence removing the need for Clash specific workarounds. If you relied on Clash-generated Verilator shims, consider using verilator --build --binary instead.
• Experimental feature "multiple hidden domains" #2750
• The deprecated module Clash.Prelude.DataFlow was removed. The clash-protocols package provides dataflow-based protocols and circuits. #3181
• The deprecated functions altpll and alteraPll were removed from the Clash.Intel.ClockGen module. Clash 1.8 introduced the new functions altpllSync, alteraPllSync, unsafeAltpll and unsafeAlteraPll. A name for the IP instantiation, handled by the name argument to altpll and alteraPll, can be provided with the Clash.Magic.setName function. #3181

Changed:

• dfold now offers a proof witness for the upper bound of the vector size to the folding function. Note that this change may require additional type annotations, as solutions working in the past may complain with an untouchable type error now. #2686

• You can now only create an SDomainConfiguration when the period of the domain is at least 1. Pattern matching on an SDomainConfiguration bring the 1 <= period into scope. This in turns enables the following code to typecheck:

  import Clash.Prelude
  import Data.Proxy
  
  f ::
    forall dom .
    KnownDomain dom =>
    Proxy dom ->
    SNat (PeriodToCycles dom (Milliseconds 1))
  f Proxy = case knownDomain @dom of
      SDomainConfiguration {} -> SNat
  

  where the DivRU in

  type PeriodToCycles (dom :: Domain) (period :: Nat) =  period `DivRU` DomainPeriod dom
  

  requires that the DomainPeriod dom is at least 1. #2740

• select and selectI now use <= constraints instead of CmpNat. #2873

• ResetStrategy now contains the reset function, to avoid dummy arguments on NoClearOnReset #2849

• Clash.Explicit.DDR, Clash.Intel.DDR and Clash.Xilinx.DDR: #2833

  • The constraints for the functions have been rewritten to use DomainPeriod, which makes them more readable and relaxes unnecessary constraints on the virtual DDR domain. The type-level variables for the domains have been renamed. dom is a real domain, domDDR is the virtual DDR domain.
  • The Xilinx and Intel primitives only support domains where the rising edge is the active edge. This is now enforced at the type level by adding a constraint.
  • The Xilinx and Intel primitives now directly support any data type that has a BitPack instance.

• Order of type arguments for functions in clash-prelude-hedgehog now follows size, domain, monad. #2880

• The Clash Prelude now exports the Default class from the package data-default instead of from the now superseded data-default-class. If you import the Default class name or the def function from the data-default-class package older than version 0.2, or one of your dependencies does, you might get a bewildering error message. You might get the error "No instance for (Default T)" even though there appears to be such an instance. The best solution is to make sure all your packages and dependencies use the data-default package and not the data-default-class package. The next most obvious solution is to make sure data-default-class is of version 0.2 or higher, for instance by depending on it in your own package. If this creates a dependency conflict, another solution is to import the correct module. Default and def from Clash.Prelude or Data.Default are for the new data-default package. Data.Default.Class is for the data-default-class package. There are situations where this will still not be enough, but luckily the Default class is not used all that much. #2891

• Changed implementation of (+>>) to no longer require KnownNat

• The clash-prelude package now uses PolyKinds by default, meaning all its type class instances are now more general than before. As an example, without PolyKinds, BitPack (Proxy a) would only be defined when a :: Type, with the extension it would be defined for any a :: k. After this change, some instances in user code might now overlap. #2994

• When generating (System)Verilog, Clash now resets the default net type from none to the verilog default after the generated module. #3005

• The content from the Clash.Tutorial module and from https://clash-lang.readthedocs.io/ has been split and moved to two new locations.

  1. The actual tutorial parts has been moved to: https://docs.clash-lang.org/tutorial/
  2. Parts that fit better in the clash compiler user guide have been moved to: https://docs.clash-lang.org/compiler-user-guide/

  Moving the documentation to these locations makes it easier to update their content as it is no longer needed to release a new version of the clash-prelude package for the publication of this content.

• Vector functions in Verilog now have indices consistent with the Vec inputs/outputs (before they were reversed). This is convenient when writing design constraints, which can now be referenced consistently like imap[0],imap[1],... See #3088.

Fixed:

• Clash no longer gives Dubious primitive instantiation warning when using unpack #2386.
• Clash now generates more intuitive names for specialized binders. See #2508.
• foldl on Vec is now strict. See [this GitHub discussion](https://github.com/hasura/graphql-engine/pu...

v1.8.5

Added:

• Clash.Annotation.SynthesisAtrributes.annotateReg, a function to add synthesis attributes (e.g. ASYNC_REG) to register declarations in the HDL generated by the Clash compiler.
  #3093
• registerSyncReset #3115

Fixed:

• The Clash.Explicit.Verification.check blackbox now correctly uses the given clock line, not assuming any longer that it is already bound to an identifier in the first place. #2907
• The type of string literals passed to the Clash.Explicit.Verification.check blackbox now matches with the input provided via Clash.Explicit.Verification.name. #2908
• toInteger, toEnum, and fromEnum now correctly sign extend when using Verilog backend. #2729
• dumpVCD now properly aligns the first clock edges in multi-domain designs. #3075
• Removed the limit on the number of traces in dumpVCD. Also removed unnecessary double newlines after 1-bit signals. #3082
• In Clash simulation, pack for Vec and RTree had all bits undefined when the spine of the value had an XException. Now, those elements with defined bits will output those defined bits. In HDL, this was already the case. Example: consider xs = 1 :> undefined :> Nil :: Vec 2 (Unsigned 4) and ys = 1 :> undefined :: Vec 2 (Unsigned 4). xs merely has an undefined element, but ys has an undefined spine: it is a :> constructor that is undefined. pack ys used to be 0b...._.... but is now 0b0001_...., just as pack xs already was.
  #3114
• Clash drops cached normalization result. #3109
• Fix holdReset glitch behavior for asynchronous resets and wrong hold cycles for sync resets. #3115
• Do not emit source locations if -g is not passed to clash. #3132
• clash-ghc: Remove Opt_LlvmTBAA from unwanted flags. #2508

v1.8.4

Changed:

• Nix flake updated to make it more suitable for use in downstream projects. #2987 #3060

Fixed:

• collapseRHSNoops now runs after constant folding, making Clash able to constant fold more expressions than before. See #3036.
• The unzip family no longer retains a reference to the original input for every (unevaluated) part of the output tuple. Similarly, mapAccumL and mapAccumR are now also more eager to drop references. This can help to prevent space leaks. See #3038.
• Individual items of iterateI no longer retain a reference to the whole list, preventing space leaks. See #3042.
• The compiler now tracks assignment types in more places, which can prevent "clash error call" errors in some specific cases. See #3045.
• Test bench primitives now assign the string they want to pass to Verilog's $display to a variable before printing. This works around a limitation in IVerilog. See #3046.

v1.8.3

Added:

• Counter instances for Bool, Bit, Int, Int8, Int16, Int32, Int64, Word, Word8, Word16, Word32, Word64, Identity and Maybe. #2692
• The Vec type now has a COMPLETE pragma to avoid incomplete pattern matches when using the (:>) pattern. #3020
• RamOp now has an AutoReg instance. #2792
• Added instance NFDataX (SimOnly a) #2900
• Support for GHC 9.10 on Windows (macOS and Linux were already supported) #2945
• Added a BitPack instance for Char #2957
• Support for GHC 9.10.2 #3003

Changed:

• Functions defined on Clash.Class.Counter are now public #2692

Fixed:

• Clash hanging when rendering Index n literals, for large values of n #2813
• Render overflowed Index literals as don't-cares in HDL #2970
• Clash errors out when Clash.Sized.Vector.splitAt is compile-time evaluated in an illegal context [#2831]#2831
• Clash.Explicit.DDR: #2911
  • ddrIn: VHDL: Remove data input from sensitivity list of ddrIn_neg_latch register as it is superfluous. This should not affect functionality.
  • ddrOut: VHDL: Fix incorrect usage of Enable input when the domain is set to asynchronous resets. Deasserting the Enable exhibited wrong behavior before this fix.
• Clash.Xilinx.DDR: #2911
  • These primitives only support clocks where the rising edge is the active edge. Using them in a domain with falling active edges now causes an error.
  • oddr: Fix VHDL and SystemVerilog erroring out during HDL generation
  • Symbols in HDL for both iddr and oddr were renamed to match their function.
• Clash.Intel.DDR: #2911
  • These primitives only support clocks where the rising edge is the active edge. Using them in a domain with falling active edges now causes an error.
  • Fix rendering HDL. It variously errored out or generated non-working HDL.
  • Rendering HDL no longer causes Clash to issue a warning about an argument unused in Haskell but used in the primitive black box.
• makeTopEntity now accounts for SimOnly constructs. This can prevent warnings in situtations where the SimOnly type would contain types makeTopEntity cannot handle. #2897
• Clash did not build on GHC 9.6.7 (but did on 9.6.6) #2916
• Ignore Ticks in TermLiteral Integer, TermLiteral Char, TermLiteral Natural, and TermLiteral (SNat n) #2925
• Fixed laziness issue in internal black box imap_go #2542
• Clash's evaluator now uses TemplateHaskell names to detect renamed symbols in GHC.* and Clash.*. Fixes errors similar to No blackbox found for: GHC.Internal.Base.eqString #2972
• No blackbox found for: GHC.Internal.Control.Exception.Base.recSelError on GHC 9.10 #2966
• Verilog and System Verilog code gen bug for map head #2809
• Error parsing blackbox: Clash.Sized.Vector.head #2988
• Clash no longer duplicates included datafiles when component is instantiated multiple times #3008
• Clash will no longer emit "no blackbox found for" GHC.Real's exponentiation function if it is applied to constants #3010
• Clash will no longer error out when converting ensureSpine on Clash number types to HDL #3021
• Clash will no longer ignore Synthesize annotations when the function is used in an argument position #3024

v1.8.2

Added:

• Support for GHC 9.10 #2758
• Support for GHC 9.8.4 #2852
• Add ShowX, NFDataX instances for Proxy #2637
• Added Clash.Sized.Vector.ToTuple.vecToTuple: a way to safely work around incomplete patterns warnings on patterns involving Vectors. #2862
• Added operator precedences for infix usage of functions exported from Clash.Class.Num: mul, add, sub, satMul, satAdd, satSub, boundedMul, boundedAdd, and boundedSub. This means that expressions such as a `add` b `mul` c now get parsed as a `add` (b `mul` c) instead of (a `add` b) `mul` c. #2719

Changed:

• BitVector n now has an implementation for ensureSpine which ensures the constructor is present. #2702
• xToBV is now located in Clash.Sized.Internal.BitVector to avoid circular dependencies. #2702
• The error messages that mention the valid ranges for out-of-range inputs have been improved to be more intuitive: one of <empty range>, [n] or [n..m]. All n..m ranges are now ordered with the lower bound on the left. #2733

Fixed:

• cabal: Make workaround-ghc-mmap-crash a noop on non-x86_64. Fixes #2656
• Clash no longer hides error messages if it fails to load external (precompiled) modules. Note: this fix only works from GHC 9.0 on. See #2365
• HDL generation fails when using multiple-hidden feature in combination with synthesis attributes #2593
• Clash no longer errors out in the netlist generation stage when a polymorphic function is applied to type X in one alternative of a case-statement and applied to a newtype wrapper of type X in a different alternative. See #2828
• various issues with black boxes and evaluator rules for number-related primitives #2689
• genBitVector no longer contains off-by-one error on for generated Naturals #2704
• (+>>.) and (.<<+) such that they are compliant with (+>>) and (<<+) for vectors of zero length in the sense that the input vector is kept unchanged. #2730
• Removed stringsearch dependency from v16-upgrade-primitives. See #2726
• Bug in the compile-time evaluator #2781
• Exponentiation (Clash.Class.Exp) is now right-associative with a precedence level of 8 (infixr 8). By accident, it used to lack a fixity declaration, meaning it was implicitly left-associative at level 9. #2818
• Unused argument warnings on writeToBiSignal# #2822
• Clash errored saying it cannot translate a globally recursive function in code that originally only contains let-bound (local) recursion #2839
• Clash generates illegal Verilog names #2845

v1.8.1

• Bump package dependencies to allow inclusion in stackage-nightly
• Bump package dependencies to allow building on GHC 9.8.1

v1.8.0

Release highlights:

• Support for GHC 9.2, 9.4, 9.6 and 9.8. While GHC 9.2 is supported, we recommend users to skip this version as there is a severe degradation of error message quality. With this change, Clash now supports GHC versions 8.6 through 9.8.
• Major overhaul of the clocking functionality in Clash.Xilinx.ClockGen and Clash.Intel.ClockGen, see their respective entries below
• mealyS function (and several variations) to make writing state machines using the strict State monad easier
• Overhaul of resetGlitchFilter, see its respective entries below.

Added:

• altpllSync and alteraPllSync in Clash.Intel.ClockGen. These replace the deprecated functions without the Sync suffix. Unlike the old functions, these functions are safe to use and have a reset signal for each output domain that can be used to keep the domain in reset while the clock output stabilizes. All PLL functions now also support multiple clock outputs like the old alteraPll did. #2592
• A new clock type DiffClock is introduced to signify a differential clock signal that is passed to the design on two ports in antiphase. This is used by the differential Xilinx clock wizards in Clash.Xilinx.ClockGen. #2592
• Clash.Explicit.Testbench.clockToDiffClock, to create a differential clock signal in a test bench. It is not suitable for synthesizing a differential output in hardware. #2592
• resetGlitchFilterWithReset, which accomplishes the same task as resetGlitchFilter in domains with unknown initial values by adding a power-on reset input to reset the glitch filter itself. #2544
• Convenience functions: noReset, andReset, orReset plus their unsafe counterparts #2539
• Convenience constraint aliases: HasSynchronousReset, HasAsynchronousReset, and HasDefinedInitialValues #2539
• Clash.Prelude.Mealy.mealyS and Clash.Explicit.Mealy.mealyS and their bundled equivalents mealySB which make writing state machines using the strict State monad easier. The tutorial has also been simplified by using this change. #2484
• An experimental feature allowing clocks to vary their periods over time, called "dynamic clocks". Given that this is an experimental feature, it is not part of the public API. #2295
• The prelude now exports +>>. and .<<+, which can be used to shift in a bit into a BitVector from the left or right respectively - similar to +>> and <<+ for Vecs. #2307
• Clash.DataFiles.tclConnector and the executable static-files in clash-lib. They provide the Tcl Connector, a Tcl script that allows Vivado to interact with the metadata generated by Clash (Quartus support will be added later). See Clash.DataFiles.tclConnector for further information. More documentation about the Tcl Connector and the Clash<->Tcl API will be made available later. #2335
• Add BitPack, NFDataX and ShowX instances for Ordering #2366
• Verilog users can now influence the "precision" part of the generated timescale pragma using -fclash-timescale-precision. #2353
• Clash now includes blackboxes for integerToFloat#, integerToDouble# #2342
• Instances Arbitrary (Erroring a), Arbitrary (Saturating a), Arbitrary (Saturating a), and Arbitrary (Zeroing a) #2356
• Clash.Magic.clashSimulation, a way to differentiate between Clash simulation and generating HDL. #2473
• Clash.Magic.clashCompileError: make HDL generation error out with a custom error message. Simulation in Clash will also error when the function is evaluated, including a call stack. HDL generation unfortunately does not include a call stack. #2399
• Added Clash.XException.MaybeX, a data structure with smart constructors that can help programmers deal with XException values in their blackbox model implementations #2442
• Clash.Magic.SimOnly, A container for data you only want to have around during simulation and is ignored during synthesis. Useful for carrying around things such as: a map of simulation/vcd traces, co-simulation state or meta-data, etc. #2464
• KnownNat (DomainPeriod dom) as an implied constraint to KnownDomain dom. This reduces the amount of code needed to write - for example - clock speed dependent code. #2541
• Clash.Annotations.SynthesisAttributes.annotate: a term level way of annotating signals with synthesis attributes #2547
• Clash.Annotations.SynthesisAttributes.markDebug: a way of marking a signals "debug", instructing synthesizers to leave the signal alone and offer debug features #2547
• Add hex and octal BitVector parsing. #1772
• 1 <= n => Foldable1 (Vec n) instance (base-4.18+ only) #2563
• You can now use ~PERIOD, ~ISSYNC, ~ISINITDEFINED and ~ACTIVEEDGE on arguments of type Clock, Reset, Enable,ClockN and DiffClock. #2590

Removed:

• Deprecated module Clash.Prelude.BitIndex: functions have been moved to Clash.Class.BitPack #2555
• Deprecated module Clash.Prelude.BitReduction: functions have been moved to Clash.Class.BitPack #2555
• Deprecated function Clash.Explicit.Signal.enable: function has been renamed to andEnable #2555
• The module Clash.Clocks.Deriving has been removed. #2592

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. #2540
• The functions altpll and alteraPll in Clash.Intel.ClockGen have been deprecated because they are unsafe to use while this is not apparent from the name. The locked output signal of these functions is an asynchronous signal which needs to be synchronized before it can be used (something the examples did in fact demonstrate). For the common use case, new functions are available, named altpllSync and alteraPllSync. These functions are safe. For advanced use cases, the old functionality can be obtained through unsafeAltpll and unsafeAlteraPll. #2592

Changed:

• The wizards in Clash.Xilinx.ClockGen have been completely overhauled. The original functions were unsafe and broken in several ways. See the documentation in Clash.Xilinx.ClockGen for how to use the new functions. Significant changes are:
  • clockWizard and clockWizardDifferential now output a Clock and a Reset which can be directly used by logic. Previously, it outputted a clock and an asynchronous locked signal which first needed to be synchronized before it could be used (hence the old function being unsafe). Additionally, the original locked signal was strange: it mistakenly was an Enable instead of a Signal dom Bool and there was a polarity mismatch between Clash simulation and HDL. The locked signal was also not resampled to the output domain in Clash simulation.
  • There are new functions unsafeClockWizard and unsafeClockWizardDifferential for advanced use cases which directly expose the locked output of the wizard.
  • All clock generators now have the option to output multiple clocks from a single instance.
  • clockWizardDifferential now gets its input clock as a DiffClock type; use clockToDiffClock to generate this in your test bench if needed. Previously, the function received two clock inputs, but this generated create_clock statements in the top-level SDC file for both phases which is incorrect.
  • A constraint was removed: The output clock domain no longer requires asynchronous resets. This was originally intended to signal that the outgoing lock signal is an asynchronous signal. The constraint does not convey this information at all and is wrong; it also prevents using synchronous resets in the circuit as recommended by Xilinx. Note that if you use the unsafe functions, it is still necessary to synchronize the locked output in your design.
  • The port names of the primitives in HDL are now correctly lower case.
  • Add Tcl generation. This moves the responsibility of MMCM component generation from the user to clashConnector.tcl, which can be found in [clash-lib:Clash.DataFiles](https://hackage.haskell.org/package/clash-lib-1.8.0/docs/Cl...

v1.6.6

• Support Aeson 2.2 #2578

• Drop the snap package #2439

  The Clash snap package has not been a recommended way to use Clash for quite some time, and it is a hassle to support.

  In order to build a snap package, we build .deb packages for Clash with Ubuntu 20.04 LTS. But the interaction between the Debian build system and GHC is problematic, requiring significant effort to support and to upgrade to a more recent Ubuntu release.

  Additionally, snap packages have their own issues on distributions other than Ubuntu. Given that we no longer recommend people use our snap package and given the effort required to keep supporting them, we have decided to drop the snap package.

v1.6.5

Fixed:

• Support building with all combinations of specific versions of our dependencies hashable and primitive. #2485
• The Haskell simulation of the PLL lock signal in Clash.Clocks (used by Clash.Intel.ClockGen) is fixed: the signal is now unasserted for the time the reset input is asserted and vice versa, and no longer crashes the simulation. HDL generation is unchanged. The PLL functions now have an additional constraint: KnownDomain pllLock. #2420

Changed:

• Export the constructor for the Wrapping type in the Clash.Num.Wrapping module. See #2292

v1.6.4

Fixed:

• Input validation of the used arguments in blackboxes is now complete. #2184
• Clash.Annotations.BitRepresentation.Deriving.deriveAnnotation no longer has quadratic complexity in the size of the constructors and fields. #2209
• Fully resolve type synonyms when deriving bit representations. #2209
• Disregard ticks when determining whether terms are shared. Fixes #2233.
• The blackbox parser will make sure it fully parses its input, and report an error when it can't. #2237
• Wrap ~ARG[n] in parentheses. Fixes #2213
• The VHDL shift primitives no longer generate bound check failures. Fixes #2215
• Evaluator fails impredicative type instantiation of error values #2272
• Fix out of bound errors in toEnum/fromSLV for sum types #2220
• Netlist generation fails for certain uses of GADTs #2289
• The documentation for ANN TestBench had it backwards; it now correctly indicates the annotation is on the test bench, not the device under test. #1750

Fixes with minor changes:

• reduceXor now produces a result if the argument has undefined bits instead of throwing an XException (the result is an undefined bit). reduceAnd and reduceOr already always produced a result. #2244

Added:

• Support for symbols in types while deriving bit representations. #2209
• Support for promoted data types while deriving bit representations. #2209
• scanlPar and scanrPar in Clash's Prelude, as well as the RTree versions tscanl and tscanr. These variants of scanl1 and scanr1 compile to a binary tree of operations, with a depth of O(log(n)) (n being the length of the vector) rather than a depth of n for scanl1 and scanr1. #2177
• The GADT constructors for RTree (RLeaf and RBranch) are now exported directly in addition to the patterns LR and BR. #2177
• Added the ~ISSCALAR template which can be used to check if an argument is rendered to a scalar in HDL. #2184
• Added support for records and infix constructors when using Clash.Annotations.BitRepresentation.Deriving.deriveAnnotation. #2191
• Clash now contains instances for ShowX, NFDataX and BitPack on the newtypes from the Data.Functor modules (Identity, Const, Compose, Product and Sum). #2218