Haskell to VHDL/Verilog/SystemVerilog compiler
OTHER License
Bot releases are hidden (Show)
Published by christiaanb 11 months ago
Release highlights:
Clash.Xilinx.ClockGen
and Clash.Intel.ClockGen
, see their respective entries belowmealyS
function (and several variations) to make writing state machines using the strict State
monad easierresetGlitchFilter
, 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
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
noReset
, andReset
, orReset
plus their unsafe counterparts #2539
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
+>>.
and .<<+
, which can be used to shift in a bit into a BitVector
from the left or right respectively - similar to +>>
and <<+
for Vec
s. #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
BitPack
, NFDataX
and ShowX
instances for Ordering
#2366
timescale
pragma using -fclash-timescale-precision
. #2353
integerToFloat#
, integerToDouble#
#2342
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
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
1 <= n => Foldable1 (Vec n)
instance (base-4.18+
only) #2563
~PERIOD
, ~ISSYNC
, ~ISINITDEFINED
and ~ACTIVEEDGE
on arguments of type Clock
, Reset
, Enable
,ClockN
and DiffClock
. #2590
Removed:
Clash.Prelude.BitIndex
: functions have been moved to Clash.Class.BitPack
#2555
Clash.Prelude.BitReduction
: functions have been moved to Clash.Class.BitPack
#2555
Clash.Explicit.Signal.enable
: function has been renamed to andEnable
#2555
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
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.unsafeClockWizard
and unsafeClockWizardDifferential
for advanced use cases which directly expose the locked
output of the wizard.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.unsafe
functions, it is still necessary to synchronize the locked
output in your design.clashConnector.tcl
, which can be found in clash-lib:Clash.DataFiles
.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.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 XException
s. 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
signal
in a VHDL process)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
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
clash-manifest.json
are now (correctly) listed in reverse topological order #2334
clash-manifest.json
are now listed in reverse topological ordering #2325
-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
Annotate
#2472
Annotate
#2475
NOINLINE
of functions being specialized #2502
convertReset
was used with two domains that had a different reset polarity, the polarity of the signal was not changed.convertReset
is synchronous, a flip-flop in the source domain is inserted to filter glitches from the source reset. #2573
Internal added:
Clash.Primitives.DSL.instDecl
now accepts TExpr
s instead of LitHDL
s 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
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
unsafeToActiveHigh
and unsafeToActiveLow
to Clash.Primitives.DSL
. #2270
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
Published by DigitalBrains1 about 1 year ago
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.
Published by DigitalBrains1 over 1 year ago
Fixed:
hashable
and primitive
. #2485
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:
Wrapping
type in the Clash.Num.Wrapping
module. See #2292
Published by martijnbastiaan about 2 years ago
Fixed:
Clash.Annotations.BitRepresentation.Deriving.deriveAnnotation
no longer has quadratic complexity in the size of the constructors and fields. #2209
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:
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
RTree
(RLeaf
and RBranch
) are now exported directly in addition to the patterns LR
and BR
. #2177
~ISSCALAR
template which can be used to check if an argument is rendered to a scalar in HDL. #2184
Clash.Annotations.BitRepresentation.Deriving.deriveAnnotation
. #2191
ShowX
, NFDataX
and BitPack
on the newtypes from the Data.Functor modules (Identity
, Const
, Compose
, Product
and Sum
). #2218
Published by martijnbastiaan over 2 years ago
Fixed:
~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
alteraPll
primitive was unusable since commit d325557750
(release v1.4.0), it now works again. #2136
Signed.fromInteger
can now handle any Netlist Expr
as input #2149
clash-prelude-hedgehog
now come with Show
instances #2133
Internal change:
Published by alex-mckenna over 2 years ago
Fixed:
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.trueDualPortBlockRam
swapped the names of the ports in exception messages. #2102
Changed:
trueDualPortBlockRam
model now only models read/write conflicts for concurrent active portstrueDualPortBlockRam
model now models write/write conflicts for concurrent active portsPublished by martijnbastiaan over 2 years ago
Changed:
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 typesPublished by martijnbastiaan over 2 years ago
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:
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..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.
Published by martijnbastiaan over 2 years ago
Fixed:
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:
Hashable Term
and Hashable Type
#1986
Term
(Clash.Core.Subst.eqTerm
) and Type
(Clash.Core.Subst.eqType
)Internal fixes:
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.Published by martijnbastiaan about 3 years ago
Changed:
clash-lib
now supports prettyprinter 1.7Documentation:
Clash.Signal
.Published by martijnbastiaan over 3 years ago
Fixed:
Clash.Annotation.TopEntity
documentation #646 and #654
unconcat
cannot be used as initial/reset value for a register
#1756
showX
now doesn't crash if a spine of a Vec
is undefined~ISACTIVEENABLE
in blackboxes works again, and now acts on Signal dom Bool
in addition to Enable dom
. Since #1368, enable lines were always generated even if they were known to be always enabled. Fixes #1786.makeRecursiveGroups
now correctly identifies mutual recursion between global binders (#1796).Published by martijnbastiaan over 3 years ago
Fixed:
Clash.Sized.Vector
functions error on vectors containing Clocks
, Reset
, or Enable
#1606
Clash.Signal.Delayed.delayI
cannot be reset, the HiddenReset
constraint was unintentional. Asserting its reset has never worked. Removed the constraint #1739.Changed:
Clash.Prelude.ROM.File.romFile
now takes an Enum addr => addr
as address argument, making it actually useful. #407
Published by martijnbastiaan over 3 years ago
Although this release includes many small bug fixes and a few API changes, it mostly consists of internal changes to Clash. As promised when releasing v1.2.2 we've put a lot of effort in laying the groundwork for a partial evaluator. We believe this would make Clash an order of magnitude faster as well as more reliable when released. We've also refactored the way Clash generates unique identifiers which works around a number of issues with EDA tools our users have observed. Sadly, we haven't been able to make progress with Shake rules for Clash, promised in the same blog post.
Apart from changes to Clash itself, we've continued to build the ecosystem itself:
As said, most changes in this release have been internal to Clash - setting the stage for a faster and even more reliable Clash. Still, we expect a number of issues to impact users upgrading to 1.4:
Clash.Sized.Vector.fold
swapped: before forall a n . (a -> a -> a) -> Vec (n+1) a -> a
, after forall n a . (a -> a -> a) -> Vec (n+1) a
. This makes it easier to use fold
in a 1 <= n
context so you can "simply" do fold @(n-1)
Fixed
now obeys the laws for Enum
as set out in the Haskell Report, and it is now consistent with the documentation for the Enum
class on Hackage. As Fixed
is also Bounded
, the rule in the Report that succ maxBound
and pred minBound
should result in a runtime error is interpreted as meaning that succ
and pred
result in a runtime error whenever the result cannot be represented, not merely for minBound
and maxBound
alone.A
containing two top entities foo
and bar
will produce an HDL folder with two folders in it: A.foo
and A.bar
. Fully qualified names are not influenced by top entity annotations; instead, the Haskell name of the function is used. Files within their respective directories will be affected by names set in annotations.Thanks to all our contributors, issue reporters, and mailing list users - you make this possible.
View all the changes in the CHANGELOG.
Published by martijnbastiaan almost 4 years ago
Fixed:
flogBaseSNat
, clogBaseSNat
and logBaseSNat
primitives are now implemented correctly.Previously these primitives would be left unevaluated causing issues as demonstrated in #1479
satSucc
, satPred
correctly handle "small types" such as Index 1
.msb
no longer fails on values larger than 64 bitsundefined
can now be used as a reset value of autoReg@Maybe
#1507
fmap
is now less strict, preventing infinite loops in very specific situations. See #1521
fold
inside other HO primitives (e.g., map
) no longer fails #1524
Published by martijnbastiaan about 4 years ago
aeson
and dlist
, in preparation for the new Stack LTS.Published by christiaanb over 4 years ago
Changed:
Added:
instance Monoid a => Monoid (Vec n a)
instance Text.Printf(Index)
instance Text.Printf(Signed)
instance Text.Printf(Unsigned)
Fixed:
Clash renders incorrect VHDL when GHCs Worker/Wrapper transformation is enabled #1402
Minor faults in generated HDL when using annotations from Clash.Annotations.SynthesisAttributes
Cabal installed through Snap (clash.cabal
) can now access the internet to fetch pacakges. #1411
Generated QSys file for altpll
incompatible with Quartus CLI (did work in Quartus GUI)
Clash no longer uses component names that clash with identifiers imported
from:
when generating VHDL. See https://github.com/clash-lang/clash-compiler/issues/1439.