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.
  • The wizards now use the user-provided name as the name of the instance rather than the name of the IP core. This change was also done for Clash.Intel.ClockGen in Clash v1.2.0 in March 2020, when Clash started generating Intel Qsys files. Before that, the user needed to generate a Qsys component manually. Now, in Clash v1.8.0, we also generate the Tcl for Xilinx wizards. When the user is responsible for creating the IP core, it makes sense to always set the component name to the user-provided value. But when that is also generated by Clash, that is no longer needed. Allowing users to set the instance name instead makes it possible to match on the instance in SDC files and such. #2592

• The IP core generators in Clash.Intel.ClockGen now declare that their input domain needs to have asynchronous resets (HasAsynchronousReset), as the functions react asynchronously to their reset input and thus need to be glitch-free. The functions marked unsafe do not have this constraint; instead, the function documentation calls attention to the requirement. #2592

• resetGlitchFilter now uses a counter instead of shift register, allowing glitch filtering over much larger periods. #2374

• resetGlitchFilter now filters glitches symmetrically, only deasserting the reset after the incoming reset has stabilized. For more information, read #2374.

• resetGlitchFilter does not support domains with unknown initial values anymore. Its previous behavior could lead to unstable circuits. Domains not supporting initial values should consider using resetGlitchFilterWithReset or holdReset. The previous behavior can still be attained through the new unsafeResetGlitchFilter. #2544

• fromJustX now uses deepErrorX instead of errorX. This adds NFDataX constraints to blockRam like functions, asyncRam and writeToBiSignal. #2113

• All memory functions now use deepErrorX for XExceptions. This adds NFDataX constraints to asyncRom, asyncRomPow2 and asyncRom#. #2113

• Before this release, scanl1 was re-exported from the Haskell Prelude. Clash's Prelude now exports a Vec specialized version. #2172

• When generating (System)Verilog, Clash now sets the default net type to none. This means any implicitly declared signal in the design will trigger an error when elaborating the design. #2174

• Blackbox templates no longer have the outputReg key, it has been replaced with the more general outputUsage which specifies how signals are used in terms of whether writes are

  • continuous (i.e. a concurrent context)
  • procedural non-blocking (i.e. signal in a VHDL process)
  • procedural blocking (i.e. variable in a VHDL process)

  The ~OUTPUTWIREREG tag continues to work for backwards compatibility, but there is also a new ~OUTPUTUSAGE tag which is recommended. In the future, the ~OUTPUTWIREREG tag may be removed. #2230

• Clash.Explicit.Testbench.outputVerifier now takes an additional clock as an argument: the clock used by the circuit under test. If your tests use the same domain for the test circuit and design under test, consider using Clash.Explicit.Testbench.outputVerifier'. #2295

• Clash.Explicit.Signal.veryUnsafeSynchronizer now accepts either a static clock period or a dynamic one. If you don't use dynamic clocks, convert your calls to use Left. #2295

• SDomainConfiguration is now a record, easing field access. #2349

• Generalized the return types of periodToHz and hzToPeriod. Use a type application (periodToHz @(Ratio Natural), hzToPeriod @Natural) to get the old behavior back, in case type errors arise. #2436

• periodToHz and hzToPeriod now throw an ErrorCall with call stack when called with the argument 0 (zero), instead of a RatioZeroDenominator :: ArithException. #2436

• hasX now needs an NFDataX constraint, in addition to an NFData one. This API change was made to fix an issue where hasX would hide error calls in certain situations, see #2450.

• Clock generators now wait at least 100 ns before producing their first tick. This change has been implemented to account for Xilinx's GSR in clock synchronization primitives. This change does not affect Clash simulation. See #2455.

• From GHC 9.4.1 onwards the following types: BiSignalOut, Index, Signed, Unsigned, File, Ref, and SimIO are all encoded as newtype instead of data now that #2511 is merged. This means you can once again use Data.Coerce.coerce to coerce between these types and their underlying representation. #2535

• The Foldable (Vec n) instance and Traversable (Vec n) instance no longer have the 1 <= n constraint. Foldable.{foldr1,foldl1,maximum,minimum} functions now throw an error at run-/simulation-time, and also at HDL-generation time, for vectors of length zero. #2563

• The maximum and minimum functions exported by Clash.Prelude work on non-empty vectors, instead of the more generic version from Data.Foldable. #2563

• unsafeToReset and invertReset now have a KnownDomain constraint This was done in preparation for Remove KnownDomain #2589

Fixed:

• altpll and alteraPll in Clash.Intel.ClockGen now account for the input domain's ResetPolarity. Before this fix, the reset was always interpreted as an active-high signal. #2592
• Fix alteraPll qsys generation. PR #2417 (included in Clash v1.6.5) caused a bug in the generation of the qsys file: it generated a spurious extra output clock which was completely unused otherwise. #2587
• Files in clash-manifest.json are now (correctly) listed in reverse topological order #2334
• Dependencies in clash-manifest.json are now listed in reverse topological ordering #2325
• Clash now renders undefined bits set via -fclash-force-undefined correctly #2360
• resetGen's documentation now mentions it is non-synthesizable (#2375)
• trueDualPortBlockRam now handles undefined values in its input correctly #2350
• trueDualPortBlockRam now correctly handles port enables when clock edges coincide #2351
• Clash.Primitives.DSL.deconstructProduct now projects fields out of a product #2469
• BiSignal test does not look through Annotate #2472
• Port size not rendered when type has more than one Annotate #2475
• Clash now preserves NOINLINE of functions being specialized #2502
• When convertReset was used with two domains that had a different reset polarity, the polarity of the signal was not changed.
• Functional arguments of primitives cannot have 0-bit results #2549
• If the source reset of convertReset is synchronous, a flip-flop in the source domain is inserted to filter glitches from the source reset. #2573
• SystemVerilog backend: Assignment patterns for unpacked arrays now have an index for every element; improves QuestaSim compatibility. #2595
• Name duplication in generated Verilog involving reset synchronizer #2598

Internal added:

• Clash.Primitives.DSL.instDecl now accepts TExprs instead of LitHDLs as generics/parameters. This allows for VHDL black boxes to use all possible generic types. To ease transition, litTExpr has been added to Clash.Primitives.DSL. #2471
• Clash.Core.TermLiteral.deriveTermToData now works on records #2270
• Clash.Primitives.getVec tries to get all elements in a Vector from an expression #2483
• Added Clash.Primitives.DSL.deconstructMaybe. This DSL function makes it easy to deconstruct a Maybe into its constructor bit and data. This is often useful for primitives taking 'enable' and 'data' signals. #2202
• Added unsafeToActiveHigh and unsafeToActiveLow to Clash.Primitives.DSL. #2270
• Added TermLiteral instance for Either #2329
• Clash.Primitives.DSL.declareN, a companion to declare which declares multiple signals in one go. #2592

Internal changes:

• Clash.Primitives.DSL.boolFromBit is now polymorphic in its HDL backend. #2202

• Clash.Primitives.DSL.unsignedFromBitVector is now polymorphic in its HDL backend. #2202

• Clash.Primitives.DSL.fromBV now converts some BitVector expression into some type. #2202

• Add CompDecl to Clash.Netlist.Types.Declaration to accomodate VHDL's component declarations.

• Black box functions declare their usage, necessary for implicit netlist usage analysis implemented in #2230

• Added showsTypePrec to TermLiteral to make TermLiteral SNat work as expected. Deriving an instance is now a bit simpler. Instances which previously had to be defined as:

  instance TermLiteral Bool where
    termToData = $(deriveTermToData ''Bool)
  

  can now be defined using:

  deriveTermLiteral ''Bool
  

  #2329