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

v1.6.3

Fixed:

• Handle ~ISUNDEFINED hole in black boxes for BitVector and for product types. This means that with -fclash-aggressive-x-optimization-blackboxes, resets are now omitted for undefined reset values of such types as well. #2117
• The alteraPll primitive was unusable since commit d325557750 (release v1.4.0), it now works again. #2136
• Simulation/Synthesis mismatch for X-exception to undefined bitvector conversion #2154
• The VHDL blackbox for Signed.fromInteger can now handle any Netlist Expr as input #2149
• Clash no longer escapes extended identifiers when rendering SDC files. #2142
• The types defined in clash-prelude-hedgehog now come with Show instances #2133
• Extreme values are now generated from the input range instead of the type's bounds #2138

Internal change:

• Clash now always generates non-extended identifiers for port names, so that generated names play nicer with different vendor tools. #2142
• Top entity name available in netlist context. Top entity name used in generated name for include files. #2146

v1.6.2

Fixed:

• Clash now compiles for users of Clang - i.e., all macOS users.
• The trueDualPortBlockRam model did not accurately simulate concurrent active ports, thus causing a Haskell/HDL simulation mismatch for asyncFIFOSynchronizer.
• trueDualPortBlockRam Haskell/HDL simulation mismatch for port enable.
• Sometimes trueDualPortBlockRam swapped the names of the ports in exception messages. #2102
• The evaluator rule for unpack{Float,Double}# are now corrected to return boxed float and double instead of unboxed literals. #2097

Changed:

• The trueDualPortBlockRam model now only models read/write conflicts for concurrent active ports
• The trueDualPortBlockRam model now models write/write conflicts for concurrent active ports

v1.6.1

Changed:

• We accidentally released v1.6.0 with the Cabal flag multiple-hidden enabled. This is an experimental feature, supposed to be disabled by default for releases. v1.6.1 disables it again.

Added:

• Clash.Class.HasDomain.TryDomain instances for Clash sized types

v1.6.0

With each release we're trying hard to improve the usability of Clash and this release is no different: we've made many small improvements, which you can all find in the full changelog. We'd like to highlight a few of the bigger changes:

• From now on we'll be publishing clash-prelude-hedgehog containing generators for types in clash-prelude. For those unfamiliar, Hedgehog is a test framework that allows its users to quickly generate a large number of test inputs. It can often find bugs not easily found by humans alone. The new package allows Clash developers to quickly get started.
• Clash now generates a Verilator shim when compiling to Verilog or SystemVerilog. As a result, Verilator has been added to the Clash testsuite, to ensure we continue to output Verilatable HDL.
• We've added support for YAML blackboxes. Clash will now pickup on files with a .primitives.yaml extension. While we recommend upgrading your primitive files to the new format, old style primitives are still supported. We've included a utility to help you upgrade your blackboxes. See #2037 for more information.

We believe that the majority of users won't have to change anything to have their designs running on 1.6, when coming from 1.4. Any designs that use our clash-lib API need take care:

• clash-lib now uses Data.Monoid.Ap instead of Data.Semigroup.Monad.Mon. This means users defining primitives with TemplateFunction will need to replace Mon/getMon with Ap/getAp. #1835

You can find the full release notes in CHANGELOG.md.

v1.4.7

1.4.7 Jan 30th 2022

Fixed:

• Clash now shows days in time strings for compile runs which take longer than a day #1989.
• Types defined in the package head are no longer qualified in the package body when rendering VHDL #1996.
• asyncRam with different read and write clocks no longer produce the wrong results in Haskell simulation. #2031
• Clash.Explicit.RAM.asyncRam# Haskell simulation incorrectly treated an undefined write enable as asserted. It now causes an undefined value to be written instead. This problem did not propagate to the other asyncRam functions, where the same condition would simultaneously lead to an undefined write address, which would be handled correctly. This problem also only affects Haskell simulation, not the generated HDL. #2031
• Clash.Explicit.BlockRam.blockRam# and Clash.Explicit.BlockRam.File.blockRamFile# Haskell simulation incorrectly treated an undefined write enable as asserted. It now causes an undefined value to be written instead. This problem did not propagate to the other blockRam functions, where the same condition would simultaneously lead to an undefined write address, which would be handled correctly. This problem also only affects Haskell simulation, not the generated HDL.(#2054)

Internal changes:

• Removed instances of Hashable Term and Hashable Type #1986
• Added structural equality on Term (Clash.Core.Subst.eqTerm) and Type (Clash.Core.Subst.eqType)

Internal fixes:

• Enable used to be a Bool in the Blackbox DSL, so we could use boolToBit. However it now has its own type in the DSL (Enable domainName), so we've added a new conversion function in order to convert it to a Bool.