clash-lib
Clash: a functional hardware description language - As a library
LTS Haskell 19.33: | 1.6.4 |
Stackage Nightly 2024-10-31: | 1.8.1@rev:3 |
Latest on Hackage: | 1.8.1@rev:3 |
clash-lib-1.8.1@sha256:2e1ee92587985da6b1e348778591ebe9f720a6b836fa54a0ffe8b9a090c79272,16148
Module documentation for 1.8.1
- Clash
- Clash.Annotations
- Clash.Annotations.BitRepresentation
- Clash.Backend
- Clash.Core
- Clash.Core.DataCon
- Clash.Core.EqSolver
- Clash.Core.Evaluator
- Clash.Core.FreeVars
- Clash.Core.HasFreeVars
- Clash.Core.HasType
- Clash.Core.Literal
- Clash.Core.Name
- Clash.Core.PartialEval
- Clash.Core.Pretty
- Clash.Core.Subst
- Clash.Core.Term
- Clash.Core.TermInfo
- Clash.Core.TermLiteral
- Clash.Core.TyCon
- Clash.Core.Type
- Clash.Core.TysPrim
- Clash.Core.Util
- Clash.Core.Var
- Clash.Core.VarEnv
- Clash.Data
- Clash.DataFiles
- Clash.Debug
- Clash.Driver
- Clash.Edalize
- Clash.Netlist
- Clash.Normalize
- Clash.Normalize.PrimitiveReductions
- Clash.Normalize.Primitives
- Clash.Normalize.Strategy
- Clash.Normalize.Transformations
- Clash.Normalize.Transformations.ANF
- Clash.Normalize.Transformations.Case
- Clash.Normalize.Transformations.Cast
- Clash.Normalize.Transformations.DEC
- Clash.Normalize.Transformations.EtaExpand
- Clash.Normalize.Transformations.Inline
- Clash.Normalize.Transformations.Letrec
- Clash.Normalize.Transformations.MultiPrim
- Clash.Normalize.Transformations.Reduce
- Clash.Normalize.Transformations.SeparateArgs
- Clash.Normalize.Transformations.Specialize
- Clash.Normalize.Transformations.XOptimize
- Clash.Normalize.Types
- Clash.Normalize.Util
- Clash.Pretty
- Clash.Primitives
- Clash.Primitives.Annotations
- Clash.Primitives.DSL
- Clash.Primitives.GHC
- Clash.Primitives.Intel
- Clash.Primitives.Magic
- Clash.Primitives.Sized
- Clash.Primitives.Types
- Clash.Primitives.Util
- Clash.Primitives.Verification
- Clash.Primitives.Xilinx
- Clash.Rewrite
- Clash.Unique
- Clash.Util
- Clash.Verification
- Clash.Annotations
- Data
- Data.Aeson
- Data.Aeson.Extra
- Data.Text
- Data.Text.Prettyprint
- Data.Text.Prettyprint.Doc
- Data.Text.Prettyprint
- Data.Aeson
- GHC
- GHC.BasicTypes
clash-lib
- Clash compiler, as a library
- See the LICENSE file for license and copyright details
Clash - A functional hardware description language
Clash is a functional hardware description language that borrows both its syntax and semantics from the functional programming language Haskell. The Clash compiler transforms these high-level descriptions to low-level synthesizable VHDL, Verilog, or SystemVerilog.
Features of Clash:
-
Strongly typed, but with a very high degree of type inference, enabling both safe and fast prototyping using concise descriptions.
-
Interactive REPL: load your designs in an interpreter and easily test all your component without needing to setup a test bench.
-
Higher-order functions, with type inference, result in designs that are fully parametric by default.
-
Synchronous sequential circuit design based on streams of values, called
Signal
s, lead to natural descriptions of feedback loops. -
Support for multiple clock domains, with type safe clock domain crossing.
Support
For updates and questions join the mailing list [email protected] or read the forum
Changes
Changelog for the Clash project
1.8.1 Nov 10th 2023
- Bump package dependencies to allow inclusion in stackage-nightly
- Bump package dependencies to allow building on GHC 9.8.1
1.8.0 Nov 10th 2023
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
andClash.Intel.ClockGen
, see their respective entries below mealyS
function (and several variations) to make writing state machines using the strictState
monad easier- Overhaul of
resetGlitchFilter
, see its respective entries below.
Added:
altpllSync
andalteraPllSync
inClash.Intel.ClockGen
. These replace the deprecated functions without theSync
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 oldalteraPll
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 inClash.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. #2592resetGlitchFilterWithReset
, which accomplishes the same task asresetGlitchFilter
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
, andHasDefinedInitialValues
#2539 Clash.Prelude.Mealy.mealyS
andClash.Explicit.Mealy.mealyS
and their bundled equivalentsmealySB
which make writing state machines using the strictState
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 aBitVector
from the left or right respectively - similar to+>>
and<<+
forVec
s. #2307 Clash.DataFiles.tclConnector
and the executablestatic-files
inclash-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). SeeClash.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
andShowX
instances forOrdering
#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)
, andArbitrary (Zeroing a)
#2356 Clash.Magic.clashSimulation
, a way to differentiate between Clash simulation and generating HDL. #2473Clash.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 withXException
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. #2464KnownNat (DomainPeriod dom)
as an implied constraint toKnownDomain dom
. This reduces the amount of code needed to write - for example - clock speed dependent code. #2541Clash.Annotations.SynthesisAttributes.annotate
: a term level way of annotating signals with synthesis attributes #2547Clash.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 typeClock
,Reset
,Enable
,ClockN
andDiffClock
. #2590
Removed:
- Deprecated module
Clash.Prelude.BitIndex
: functions have been moved toClash.Class.BitPack
#2555 - Deprecated module
Clash.Prelude.BitReduction
: functions have been moved toClash.Class.BitPack
#2555 - Deprecated function
Clash.Explicit.Signal.enable
: function has been renamed toandEnable
#2555 - The module
Clash.Clocks.Deriving
has been removed. #2592
Deprecated:
unsafeFromLowPolarity
,unsafeFromHighPolarity
,unsafeToLowPolarity
,unsafeToHighPolarity
have been replaced byunsafeFromActiveLow
,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
andalteraPll
inClash.Intel.ClockGen
have been deprecated because they are unsafe to use while this is not apparent from the name. Thelocked
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, namedaltpllSync
andalteraPllSync
. These functions are safe. For advanced use cases, the old functionality can be obtained throughunsafeAltpll
andunsafeAlteraPll
. #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 inClash.Xilinx.ClockGen
for how to use the new functions. Significant changes are:clockWizard
andclockWizardDifferential
now output aClock
and aReset
which can be directly used by logic. Previously, it outputted a clock and an asynchronouslocked
signal which first needed to be synchronized before it could be used (hence the old function being unsafe). Additionally, the originallocked
signal was strange: it mistakenly was anEnable
instead of aSignal dom Bool
and there was a polarity mismatch between Clash simulation and HDL. Thelocked
signal was also not resampled to the output domain in Clash simulation.- There are new functions
unsafeClockWizard
andunsafeClockWizardDifferential
for advanced use cases which directly expose thelocked
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 aDiffClock
type; useclockToDiffClock
to generate this in your test bench if needed. Previously, the function received two clock inputs, but this generatedcreate_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 thelocked
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 inclash-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 markedunsafe
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 usingresetGlitchFilterWithReset
orholdReset
. The previous behavior can still be attained through the newunsafeResetGlitchFilter
. #2544 -
fromJustX
now usesdeepErrorX
instead oferrorX
. This addsNFDataX
constraints toblockRam
like functions,asyncRam
andwriteToBiSignal
. #2113 -
All memory functions now use
deepErrorX
forXException
s. This addsNFDataX
constraints toasyncRom
,asyncRomPow2
andasyncRom#
. #2113 -
Before this release,
scanl1
was re-exported from the Haskell Prelude. Clash’s Prelude now exports aVec
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 generaloutputUsage
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 usingClash.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 useLeft
. #2295 -
SDomainConfiguration
is now a record, easing field access. #2349 -
Generalized the return types of
periodToHz
andhzToPeriod
. Use a type application (periodToHz @(Ratio Natural)
,hzToPeriod @Natural
) to get the old behavior back, in case type errors arise. #2436 -
periodToHz
andhzToPeriod
now throw anErrorCall
with call stack when called with the argument 0 (zero), instead of aRatioZeroDenominator :: ArithException
. #2436 -
hasX
now needs anNFDataX
constraint, in addition to anNFData
one. This API change was made to fix an issue wherehasX
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
, andSimIO
are all encoded asnewtype
instead ofdata
now that #2511 is merged. This means you can once again useData.Coerce.coerce
to coerce between these types and their underlying representation. #2535 -
The
Foldable (Vec n)
instance andTraversable (Vec n)
instance no longer have the1 <= 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
andminimum
functions exported byClash.Prelude
work on non-empty vectors, instead of the more generic version fromData.Foldable
. #2563 -
unsafeToReset
andinvertReset
now have a KnownDomain constraint This was done in preparation for Remove KnownDomain #2589
Fixed:
altpll
andalteraPll
inClash.Intel.ClockGen
now account for the input domain’sResetPolarity
. 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 theqsys
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 #2350trueDualPortBlockRam
now correctly handles port enables when clock edges coincide #2351Clash.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 acceptsTExpr
s instead ofLitHDL
s as generics/parameters. This allows for VHDL black boxes to use all possible generic types. To ease transition,litTExpr
has been added toClash.Primitives.DSL
. #2471Clash.Core.TermLiteral.deriveTermToData
now works on records #2270Clash.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 aMaybe
into its constructor bit and data. This is often useful for primitives taking ‘enable’ and ‘data’ signals. #2202 - Added
unsafeToActiveHigh
andunsafeToActiveLow
toClash.Primitives.DSL
. #2270 - Added
TermLiteral
instance forEither
#2329 Clash.Primitives.DSL.declareN
, a companion todeclare
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 someBitVector
expression into some type. #2202 -
Add
CompDecl
toClash.Netlist.Types.Declaration
to accomodate VHDL’scomponent
declarations. -
Black box functions declare their usage, necessary for implicit netlist usage analysis implemented in #2230
-
Added
showsTypePrec
toTermLiteral
to makeTermLiteral 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
1.6.6 Oct 2nd 2023
-
Support Aeson 2.2
-
Dropped the snap package
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.
1.6.5 Jun 27th 2023
Fixed:
- Support building with all combinations of specific versions of our dependencies
hashable
andprimitive
. #2485 - The Haskell simulation of the PLL lock signal in
Clash.Clocks
(used byClash.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 theClash.Num.Wrapping
module. See #2292
1.6.4 Aug 30th 2022
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 anXException
(the result is an undefined bit).reduceAnd
andreduceOr
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
andscanrPar
in Clash’s Prelude, as well as theRTree
versionstscanl
andtscanr
. These variants ofscanl1
andscanr1
compile to a binary tree of operations, with a depth ofO(log(n))
(n
being the length of the vector) rather than a depth ofn
forscanl1
andscanr1
. #2177- The GADT constructors for
RTree
(RLeaf
andRBranch
) are now exported directly in addition to the patternsLR
andBR
. #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
andBitPack
on the newtypes from the Data.Functor modules (Identity
,Const
,Compose
,Product
andSum
). #2218
1.6.3 Apr 7th 2022
Fixed:
- Handle
~ISUNDEFINED
hole in black boxes forBitVector
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 commitd325557750
(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 anyNetlist Expr
as input #2149 - Clash no longer escapes extended identifiers when rendering SDC files. #2142
- The types defined in
clash-prelude-hedgehog
now come withShow
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
1.6.2 Feb 25th 2022
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 forasyncFIFOSynchronizer
. 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
1.6.1 Feb 11th 2022
Changed:
- We accidentally released
v1.6.0
with the Cabal flagmultiple-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
1.6.0 Feb 10th 2022
Added:
Clash.Class.Counter
: a class that defines a odometer-style supercounter. #1763isLike
function for BitPack types. #1774- ‘seqErrorX’ for catching both
XException
andErrorCall
. #1774 Clash.Explicit.BlockRam.File.memFile
, a function for creating the contents of the data files this blockRAM uses. Can also be imported fromClash.Prelude.BlockRam.File
,Clash.Prelude.ROM.File
andClash.Explicit.ROM.File
. #1840- Support for Yosys compatible SVA to
Clash.Verification
. This enables formal verification using SymbiYosis for Verilog and SystemVerilog. #1798 Clash.Explicit.Signal.Delayed.forward
, a function that can be used to retime aDSignal
into the future without applying any logic. #1882Clash.Signal.andEnable
is theHiddenEnable
version ofClash.Explicit.Signal.andEnable
(formerly known asenable
) #1849runUntil
, a function to sample a signal until it returns a value that satisfies the user-given test. It is a convenience function that, among others, allow easy running of atestBench
style function in Haskell simulation, logging assertion failures to stderr. #1940- Support for true dual ported block ram through
Clash.Prelude.BlockRam.trueDualPortBlockRam
andClash.Explicit.BlockRam.trueDualPortBlockRam
. #1726 #1975 clash-{prelude,lib}-hedgehog
packages which provide generators for types inclash-prelude
andclash-lib
. The former is published on Hackage. #1976- Clash now contains black boxes which are verilator compatible. When running with
--verilog
or--systemverilog
a C++ shim is automatically produced which can be used to quickly generate a verilated executable. Users who wish to interact with verilator simulations are recommended to use clashilator. #2019 - 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 tool to automatically upgrade your JSON files, see #2037 MemBlob
: a datastructure for efficient constants, typically used for initializing memories. #2041
Fixed:
- BlockRam simulation is now less strict. #1458
- Don’t overflow VHDL’s integer type when addressing RAM/ROM in simulation.Addresses are masked to 32 bits to be sure to keep it within the simulator’s range. #1875
show
onBitVector 0
no longer results in an empty string. #1785- Clash now preserves transfinite floating numbers (NaN, Infinity) when packing/unpacking #1803
SynthesisAnnotation
s can now be defined in type synoynms without being excluded from the generated HDL #1771- Manifest files now correctly list bidirectional ports as “inout” rather than “in” #1843
div
/rem
/mod
now avoid division by zero during VHDL simulation. Due to the use of concurrent statements, even unreachable code would previously result in simulation error #1873- Don’t overflow the range of VHDL’s natural type in shift/rotate, leading to simulation issues. Shift now saturates to a 31-bit shift amount. For rotate, in simulation only, the rotate amount is modulo the word width of the rotated value #1874
shiftL
for Clash datatypes does not cause a crash anymore when running Clash code with a really large shift amount #1874- VHDL generated for
Signed.fromInteger
now truncates, like the Clash simulation, when the result is smaller than the argument #1874 - Clash now preserves boolean combinatorial logic better when generating HDL #1881
valid
field ofTemplateFunction
is now checked for includes #1945- Clash now generates clock generators that ensure that the amount of time between simulation start and the first active edge of the clock is equal to (/or longer than/) the period of the clock. The first active edges of the clocks do still occur simultaneously. #2001
- Expected values in assert become undefined when using
-fclash-compile-ultra
#2040 toEnum
/fromEnum
on sized types is now less eager to report warnings about integer functions being used #2046
Changed:
Clash.Verification.PrettyPrinters
has been moved from clash-prelude to toClash.Verification.Pretty
inclash-lib
. #1798- RAM/ROM functions: They now throw
XExeception
for out-of-bounds address inputs, so this condition no longer aborts simulation. #1875 Vec
’s show instance now generates valid Haskell. #1776ShowX
and its functions now produce valid Haskell #1782bLit
now infers the size of the generated BitVector from the string given to it. This means you don’t have to give it an explicit type signature anymore. This does slightly modify the syntax needed to invokebLit
. E.g.,$$(bLit "00..1") :: BitVector 5
should be rewritten as$(bLit "00..1")
. If you relied on the size inference, wrap the new invocation inresize
. For example:resize $(bLit "00..1")
. #1784NumericUnderscores
is now enabled by default inclash
,clashi
, and starter projects using Clash >=1.6. #1785Show
instance ofBitVector
now includes a0b
prefix, making it a copyable expression for fully defined vectors. #1785blockRam
usesSTArray
as the underlying representation to improve simulation performance #1878asyncRom
now throwsXException
for out-of-bounds addressing, no longer aborting simulation #1878- Clash now renders ADTs with all zero-width fields as enumerations in VHDL #1879
- A warning about possible hard-to-debug issues has been added to the
Clash.Signal
documentation on hidden clocks, resets, and enables, in the form of the section named “Monomorphism restriction leads to surprising behavior” #1960 Clash.Explicit.Testbench.outputVerifier
andoutputVerifierBitVector
now emit a warning if they are used improperly. This situation only arises when they are used in synthesized code rather than a test bench context. When the clock domainscircuitDom
andtestDom
are two different domains, the clock crossing insideoutputVerifier
is only suitable inside a test bench, not inside a synthesized circuit. Clash now emits a warning for this case. #1931resetSynchronizer
now no longer takes anEnable
argument. The argument was already marked for removal and was ignored. #1964- Clash can now compile multiple entities concurrently, providing speedups to designs with multiple entities to build #2034
- All
asyncRam
variants andasyncFIFOSynchronizer
now require that the data has anNFDataX
instance. #2055 - Clash now respects the
-Werror
option from GHC #2066 asyncFIFOSynchronizer
now uses the synchronous dual-ported RAMtrueDualPortBlockRam
, where it previously used a dual-ported RAM with an asynchronous read portasyncRam
. With this change it’s nearly guaranteed thatasyncFIFOSynchronizer
actually synthesizes to a circuit that uses the dual-ported RAMs found on most FPGAs. #2083
Deprecated:
- The function
Clash.Explicit.Signal.enable
is renamed toandEnable
and the existing name deprecated #1849 - ‘-fclash-float-support’: it is now on by default and can’t be turned off. #2048
Removed:
- GHC 8.4 is no longer supported. Users should upgrade to at least GHC 8.6. #1762
Internal changes:
clash-lib
now usesData.Monoid.Ap
instead ofData.Semigroup.Monad.Mon
. This means users defining primitives withTemplateFunction
will need to replaceMon
/getMon
withAp
/getAp
. #1835- Clash now supports more expressive debug options at the command line #1800.
- Added
zeroWidthSpec
transformation #1891 - Added
collapseRHSNoops
inlining stage andWorkIdentity
constructor #1896 - Added
HasType
andInferType
classes for getting / inferring core types from data representing some typed “thing” #1915 - Added
HasFreeVars
class for getting free variables from data “containing” variables #1917 - Added the primitive equality type (
~#
) toClash.Core.TysPrim
. In order to make this change,undefinedTy
andunsafeCoerceTy
were moved fromClash.Core.Type
toClash.Core.Util
. #1955 - Clash now keeps information about which let bindings are recursive from GHC core. This can be used to avoid performing free variable calculations, or sorting bindings in normalization. #1980 #2000
- Manifest files now use SHA256 for a cache invalidation digest #1985
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. #2031Clash.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 otherasyncRam
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. #2031Clash.Explicit.BlockRam.blockRam#
andClash.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 otherblockRam
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
andHashable Type
#1986 - Added structural equality on
Term
(Clash.Core.Subst.eqTerm
) andType
(Clash.Core.Subst.eqType
)
Internal fixes:
- Enable used to be a
Bool
in the Blackbox DSL, so we could useboolToBit
. 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.
1.4.6 Oct 26th 2021
Fixed:
- Clash tries to cast-specialize non-“global binders” resulting in “specialisation of non-work-free cast” warning #1933
- More consistently render bare untyped and unsized literals for
~LIT
tags. This fixes #1934
1.4.5 Oct 13th 2021
Changed:
clash-lib
now supports prettyprinter 1.7
Documentation:
- The documentation on hidden clocks, resets, and enables has been corrected and extended in
Clash.Signal
.
1.4.4 Oct 11th 2021
Changed:
clash-lib
now supports aeson >= 2.0
Fixed:
- Dont’ loop on recursive data types hiding behind type families #1921
- Recognize
enableGen
as workfree and don’t duplicate registers #1935
1.4.3 Aug 8th 2021
Fixed:
- Clash no longer generates calls to
{shift,rotate}_{left,right}
in VHDL where the count is a negative number #1810. - Clash no longer incurs unnecessary compile-time complexity while compiling Vector indexing operator #1557
1.4.2 May 18th 2021
Fixed:
- Erroneous examples in
Clash.Annotation.TopEntity
documentation #646 and #654 unconcat
cannot be used as initial/reset value for aregister
#1756showX
now doesn’t crash if a spine of aVec
is undefined~ISACTIVEENABLE
in blackboxes works again, and now acts onSignal dom Bool
in addition toEnable dom
. Since #1368, enable lines were always generated even if they were known to be always enabled. Fixes #1786.- clash –show-options now shows -fclash-* options in GHC 9.0 #1787
makeRecursiveGroups
now correctly identifies mutual recursion between global binders (#1796).
1.4.1 April 6th 2021
Fixed:
- Broken VHDL primitive template for setSlice# #1715
- Unable to reduce nested type families #1721
- DEC transformation fails for functions applied to more than 62 arguments #1669
- Erroneous examples in BlockRam.File and ROM.File documentation #1608
- Blackboxes of
Clash.Sized.Vector
functions error on vectors containingClocks
,Reset
, orEnable
#1606 Clash.Signal.Delayed.delayI
cannot be reset, theHiddenReset
constraint was unintentional. Asserting its reset has never worked. Removed the constraint #1739.- Annotate attributes cannot use type families #1742
Changed:
Clash.Prelude.ROM.File.romFile
now takes anEnum addr => addr
as address argument, making it actually useful. #407
1.4.0 March 12th 2021
Highlighted changes (repeated in other categories):
- Clash no longer disables the monomorphism restriction. See #1270, and mentioned issues, as to why. This can cause, among other things, certain eta-reduced descriptions of sequential circuits to no longer type-check. See #1349 for code hints on what kind of changes to make to your own code in case it no longer type-checks due to this change.
- Type arguments of
Clash.Sized.Vector.fold
swapped: beforeforall a n . (a -> a -> a) -> Vec (n+1) a -> a
, afterforall n a . (a -> a -> a) -> Vec (n+1) a
. This makes it easier to usefold
in a1 <= n
context so you can “simply” dofold @(n-1)
Fixed
now obeys the laws forEnum
as set out in the Haskell Report, and it is now consistent with the documentation for theEnum
class on Hackage. AsFixed
is alsoBounded
, the rule in the Report thatsucc maxBound
andpred minBound
should result in a runtime error is interpreted as meaning thatsucc
andpred
result in a runtime error whenever the result cannot be represented, not merely forminBound
andmaxBound
alone.- Primitives should now be stored in
*.primitives
files instead of*.json
. While primitive files very much look like JSON files, they’re not actually spec complaint as they use newlines in strings. This has recently been brought to our attention by Aeson fixing an oversight in their parser implementation. We’ve therefore decided to rename the extension to prevent confusion.
Fixed:
- Result of
Clash.Class.Exp.(^)
has enough bits in order to deal withx^0
. - Resizes to
Signed 0
(e.g.,resize @(Signed n) @(Signed 0)
) don’t throw an error anymore satMul
now correctly handles arguments of typeIndex 2
Clash.Explicit.Reset.resetSynchronizer
now synchronizes on synchronous domains too #1567.Clash.Explicit.Reset.convertReset
: now converts synchronous domains too, if necessary #1567.inlineWorkFree
now never inlines a topentity. It previously only respected this invariant in one of the two cases #1587.- Clash now reduces recursive type families #1591
- Primitive template warning is now retained when a
PrimitiveGuard
annotation is present #1625 signum
andRealFrac
forFixed
now give the correct results.- Fixed a memory leak in register when used on asynchronous domains. Although the memory leak has always been there, it was only triggered on asserted resets. These periods are typically short, hence typically unnoticable.
createDomain
will not override user definitions of types, helping users who strive for complete documentation coverage [#1674] https://github.com/clash-lang/clash-compiler/issues/1674fromSNat
is now properly constrained #1692- As part of an internal overhaul on netlist identifier generation #1265:
- Clash no longer produces “name conflicts” between basic and extended identifiers. I.e.,
\x\
andx
are now considered the same variable in VHDL (likewise for other HDLs). Although the VHDL spec considers them distinct variables, some HDL tools - like Quartus - don’t. - Capitalization of Haskell names are now preserved in VHDL. Note that VHDL is a case insensitive languages, so there are measures in place to prevent Clash from generating both
Foo
andfOO
. This used to be handled by promoting every capitalized identifier to an extended one and wasn’t handled for basic ones. - Names generated for testbenches can no longer cause collisions with previously generated entities.
- Names generated for components can no longer cause collisions with user specified top entity names.
- For (System)Verilog, variables can no longer cause collisions with (to be) generated entity names.
- HO blackboxes can no longer cause collisions with identifiers declared in their surrounding architecture block.
- Clash no longer produces “name conflicts” between basic and extended identifiers. I.e.,
Changed:
- Treat enable lines specially in generated HDL #1171
Signed
,Unsigned
,SFixed
, andUFixed
now correctly implement theEnum
law specifying that the predecessor ofminBound
and the successor ofmaxBound
should result in an error #1495.Fixed
now obeys the laws forEnum
as set out in the Haskell Report, and it is now consistent with the documentation for theEnum
class on Hackage. AsFixed
is alsoBounded
, the rule in the Report thatsucc maxBound
andpred minBound
should result in a runtime error is interpreted as meaning thatsucc
andpred
result in a runtime error whenever the result cannot be represented, not merely forminBound
andmaxBound
alone.- Type arguments of
Clash.Sized.Vector.fold
swapped: beforeforall a n . (a -> a -> a) -> Vec (n+1) a -> a
, afterforall n a . (a -> a -> a) -> Vec (n+1) a
. This makes it easier to usefold
in a1 <= n
context so you can “simply” dofold @(n-1)
- Moved
Clash.Core.Evaluator
intoClash.GHC
and provided generic interface inClash.Core.Evalautor.Types
. This removes all GHC specific code from the evaluator in clash-lib. - Clash no longer disables the monomorphism restriction. See #1270, and mentioned issues, as to why. This can cause, among other things, certain eta-reduced descriptions of sequential circuits to no longer type-check. See #1349 for code hints on what kind of changes to make to your own code in case it no longer type-checks due to this change.
- Clash now generates SDC files for each topentity with clock inputs
deepErrorX
is now equal toundefined#
, which means that instead of the whole BitVector being undefined, its individual bits are. This makes sure bit operations are possible on it. #1532- From GHC 9.0.1 onwards the following types:
BiSignalOut
,Index
,Signed
,Unsigned
,File
,Ref
, andSimIO
are all encoded asdata
instead ofnewtype
to work around an issue where the Clash compiler can no longer recognize primitives over these types. This means you can no longer useData.Coerce.coerce
to coerce between these types and their underlying representation. - Signals on different domains used to be coercable because the domain had a type role “phantom”. This has been changed to “nominal” to prevent accidental, unsafe coercions. #1640
- Size parameters on types in Clash.Sized.Internal.* are now nominal to prevent unsafe coercions. #1640
hzToPeriod
now takes aRatio Natural
rather than aDouble
. It rounds slightly differently, leading to more intuitive results and satisfying the requested change in #1253. Clash expresses clock rate as the clock period in picoseconds. If picosecond precision is required for your design, please use the exact method of specifying a clock period rather than a clock frequency.periodToHz
now results in aRatio Natural
createDomain
doesn’t override existing definitions anymore, fixing #1674- Manifest files are now stored as
clash-manifest.json
- Manifest files now store hashes of the files Clash generated. This allows Clash to detect user changes on a next run, preventing accidental data loss.
- Primitives should now be stored in
*.primitives
files. While primitive files very much look like JSON files, they’re not actually spec complaint as they use newlines in strings. This has recently been brought to our attention by Aeson fixing an oversight in their parser implementation. We’ve therefore decided to rename the extension to prevent confusion. - Each binder marked with a
Synthesize
orTestBench
pragma will be put in its own directory under their fully qualified Haskell name. For example, two bindersfoo
andbar
in moduleA
will be synthesized inA.foo
andA.bar
. - Clash will no longer generate vhdl, verilog, or systemverilog subdirectories when using
-fclash-hdldir
. Data.Kind.Type
is now exported fromClash.Prelude
#1700
Added:
- Support for GHC 9.0.1
Clash.Signal.sameDomain
: Allows user obtain evidence whether two domains are equal.xToErrorCtx
: makes it easier to track the origin ofXException
wherepack
would hide them #1461- Additional field with synthesis attributes added to
InstDecl
inClash.Netlist.Types
#1482 Data.Ix.Ix
instances forSigned
,Unsigned
, andIndex
#1481 #1631- Added
nameHint
to allow explicitly naming terms, e.g.Signal
s. - Checked versions of
resize
,truncateB
, andfromIntegral
. Depending on the typeresize
,truncateB
, andfromIntegral
either yield anXException
or silently perform wrap-around if its argument does not fit in the resulting type’s bounds. The added functions check the bound condition and fail with an error call if the condition is violated. They do not affect HDL generation. #1491 HasBiSignalDefault
: constraint to Clash.Signal.BiSignal,pullUpMode
gives access to the pull-up mode. #1498- Match patterns to bitPattern #1545
- Non TH
fromList
andunsafeFromList
for Vec. These functions allow Vectors to be created from a list without needing to use template haskell, which is not always desirable. The unsafe version of the function does not compare the length of the list to the desired length of the vector, either truncating or padding with undefined if the lengths differ. Clash.Explicit.Reset.resetGlitchFilter
: filters glitchy reset signals. Useful when your reset signal is connected to sensitive actuators.- Clash can now generate EDAM for using Edalize. This generates edam.py files in all top entities with the configuration for building that entity. Users still need to edit this file to specify the EDA tool to use, and if necessary the device to target (for Quartus, Vivado etc.). #1386
-fclash-aggressive-x-optimization-blackboxes
: when enabled primitives can detect undefined values and change their behavior accordingly. For example, ifregister
is used in combination with an undefined reset value, it will leave out the reset logic entirely. Related issue: #1506.- Automaton-based interface to simulation, to allow interleaving of cyle-by-cycle simulation and external effects #1261
New internal features:
constructProduct
anddeconstructProduct
inClash.Primitives.DSL
. Liketuple
anduntuple
, but on arbitrary product types.- Support for multi result primitives. Primitives can now assign their results to multiple variables. This can help to work around synthesis tools limits in some cases. See #1560.
- Added a rule for missing
Int
comparisons inGHC.Classes
in the compile time evaluator. #1648 - Clash now creates a mapping from domain names to configurations in
LoadModules
. #1405 - The convenience functions in
Clash.Primitives.DSL
now take a list of HDLs, instead of just one. Clash.Netlist.Id
overhauls the way identifiers are generated in the Netlist part of Clash.- Added
defaultWithAction
to Clash-as-a-library API to work around/fix issues such as #1686 - Manifest files now list files and components in an reverse topological order. This means it can be used when calling EDA tooling without causing compilation issues.
Deprecated:
Clash.Prelude.DataFlow
: see #1490. In time, its functionality will be replaced by clash-protocols.
Removed:
- The deprecated function
freqCalc
has been removed.
1.2.5 November 9th 2020
Fixed:
- The normalizeType function now fully normalizes types which require calls to reduceTypeFamily #1469
flogBaseSNat
,clogBaseSNat
andlogBaseSNat
primitives are now implemented correctly.Previously these primitives would be left unevaluated causing issues as demonstrated in #1479- Specializing on functions with type family arguments no longer fails #1477
satSucc
,satPred
correctly handle “small types” such asIndex 1
.msb
no longer fails on values larger than 64 bitsundefined
can now be used as a reset value ofautoReg@Maybe
#1507- Signal’s
fmap
is now less strict, preventing infinite loops in very specific situations. See #1521 - Clash now uses correct function names in manifest and sdc files #1533
- Clash no longer produces erroneous HDL in very specific cases #1536
- Usage of
fold
inside other HO primitives (e.g.,map
) no longer fails #1524
Changed:
- Due to difficulties using
resetSynchronizer
we’ve decided to make this function always insert a synchronizer. See: #1528.
1.2.4 July 28th 2020
- Changed:
- Relaxed upper bound versions of
aeson
anddlist
, in preparation for the new Stack LTS. - Reverted changes to primitive definitions for ‘zipWith’, ‘map’, ‘foldr’, and ‘init’ introduced in 1.2.2. They have shown to cause problems in very specific circumstances.
- Relaxed upper bound versions of
1.2.3 July 11th 2020
-
Changed:
- Upgrade to nixos 20.03. Nix and snap users will now use packages present in 20.03.
-
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]https://github.com/clash-lang/clash-compiler/issues/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:
- IEEE.STD_LOGIC_1164.all
- IEEE.NUMERIC_STD.all
- IEEE.MATH_REAL.all
- std.textio.all when generating VHDL. See https://github.com/clash-lang/clash-compiler/issues/1439.
1.2.2 June 12th 2020
-
Changed:
- The hardwired functions to unroll primitive definitions for ‘zipWith’, ‘map’, ‘foldr’, and ‘init’ have been changed to only unroll a single step, whereas they would previously unroll the whole definition in one step. This allows Clash to take advantage of the lazy nature of these functions, in turn speeding up compilation speeds significantly in some cases. Part of PR 1354.
-
Added:
- Support for GHC 8.10
- Ability to load designs from precompiled modules (i.e., stored in a package database). See #1172
- Support for ‘-main-is’ when used with
--vhdl
,--verilog
, or--systemverilog
- A partial instance for
NFDataX (Signal domain a)
-
Fixed:
- Clash’s evaluator now inlines work free definitions, preventing situations where it would otherwise get stuck in an infinite loop
caseCon
doesn’t apply type-substitution correctly #1340- Clash generates illegal SystemVerilog slice #1313
- Fix result type of head and tail Verilog blackboxes #1351
- Certain recursive let-expressions in side a alternatives of a case-expression throw the Clash compiler into an infinite loop #1316
- Fixes issue with one of Clash’s transformations,
inlineCleanup
, introducing free variables #1337 - Fails to propagate type information of existential type #1310
- Certain case-expressions throw the Clash compiler into an infinite loop #1320
- Added blackbox implementation for ‘Clash.Sized.Vector.iterateI’, hence making it usable as a register reset value #1240
iterate
anditerateI
can now be used in reset values #1240- Prim evaluation fails on undefined arguments #1297
- Missing re-indexing in (Un)Signed fromSLV conversion #1292
- VHDL: generate a type qualification inside ~TOBV, fixes #1360
1.2.1 April 23rd 2020
-
Changed:
- Treat
Signed 0
,Unsigned 0
,Index 1
,BitVector 0
as unit. In effect this means that ‘minBound’ and ‘maxBound’ return 0, whereas previously they might crash #1183 - Infix use of
deepseqX
is now right-associative
- Treat
-
Added:
- Add ‘natToInteger’, ‘natToNatural’, and ‘natToNum’. Similar to ‘snatTo*’, but works solely on a type argument instead of an SNat.
Clash.Sized.Vector.unfoldr
andClash.Sized.Vector.unfoldrI
to construct vectors from a seed value- Added NFDataX instances for
Data.Monoid.{First,Last}
-
Fixed:
- The Verilog backend can now deal with non-contiguous ranges in custom bit-representations.
- Synthesizing BitPack instances for type with phantom parameter fails #1242
- Synthesis of
fromBNat (toBNat d5)
failed due tounsafeCoerce
coercing fromAny
- Memory leak in register primitives #1256
- Illegal VHDL slice when projecting nested SOP type #1254
- Vivado VHDL code path (
-fclash-hdlsyn Vivado
) generates illegal VHDL #1264
1.2.0 March 5th 2020
As promised when releasing 1.0, we’ve tried our best to keep the API stable. We think most designs will continue to compile with this new version, although special care needs to be taken when using:
-
Use inline blackboxes. Instead of taking a single HDL, inline primitives now take multiple. For example,
InlinePrimitive VHDL ".."
must now be written asInlinePrimitive [VHDL] ".."
. -
Use the
Enum
instance forBitVector
,Index
,Signed
, orUnsigned
, as they now respect theirmaxBound
. See #1089.
On top of that, we’ve added a number of new features:
-
makeTopEntity
: Template Haskell function for generating TopEntity annotations. See the documentation on Haddock for more information. -
Clash.Explicit.SimIO
: ((System)Verilog only) I/O actions that can be translated to HDL I/O. See the documentation on Haddock for more information. -
Clash.Class.AutoReg
: A smart register that improves the chances of synthesis tools inferring clock-gated registers, when used. See the documentation on Haddock for more information.
The full list of changes follows. Happy hacking!
-
New features (API):
Clash.Class.Parity
type class replaces Preludeodd
andeven
functions due to assumptions that don’t hold for Clash specific numerical types, see #970.NFDataX.ensureSpine
, see #748makeTopEntity
Template Haskell function for generating TopEntity annotations intended to cover the majority of use cases. Generation failures should either result in an explicit error, or a valid annotation of an emptyPortProduct
. Any discrepancy between the shape of generated annotations and the shape of the Clash compiler is a bug. See #795. Known limitations:- Type application (excluding
Signal
s and:::
) is best effort: - Data types with type parameters will work if the generator can discover a single relevant constructor after attempting type application.
- Arbitrary explicit clock/reset/enables are supported, but only a single
HiddenClockResetEnable
constraint is supported. - Data/type family support is best effort.
- Type application (excluding
- Added
Bundle ((f :*: g) a)
instance - Added
NFDataX CUShort
instance - Clash’s internal type family solver now recognizes
AppendSymbol
andCmpSymbol
- Added
Clash.Magic.suffixNameFromNat
: can be used in cases wheresuffixName
is too slow - Added
Clash.Class.AutoReg
. Improves the chances of synthesis tools inferring clock-gated registers, when used. See #873. Clash.Magic.suffixNameP
,Clash.Magic.suffixNameFromNatP
: enable prefixing of name suffixes- Added
Clash.Magic.noDeDup
: can be used to instruct Clash to /not/ share a function between multiple branches - A
BitPack a
constraint now implies aKnownNat (BitSize a)
constraint, so you won’t have to add it manually anymore. See #942. Clash.Explicit.SimIO
: ((System)Verilog only) I/O actions that can be translated to HDL I/O; useful for generated test benches.- Export
Clash.Explicit.Testbench.assertBitVector
#888 - Add
Clash.Prelude.Testbench.assertBitVector
to achieve feature parity withClash.Explicit.Testbench
. #891 - Add
Clash.XException.NFDataX.ensureSpine
#803 - Add
Clash.Class.BitPack.bitCoerceMap
#798 - Add
Clash.Magic.deDup
: instruct Clash to force sharing an operator between multiple branches of a case-expression InlinePrimitive
can now support multiple backends simultaneously #425- Add
Clash.XException.hwSeqX
: render declarations of an argument, but don’t assign it to a result signal - Add
Clash.Signal.Bundle.TaggedEmptyTuple
: allows users to emulate the pre-1.0 behavior of “Bundle ()”. See #1100
-
New features (Compiler):
- #961: Show
-fclash-*
Options inclash --show-options
- #961: Show
-
New internal features:
- #918: Add X-Optimization to normalization passes (-fclash-aggressive-x-optimization)
- #821: Add
DebugTry
: print name of all tried transformations, even if they didn’t succeed - #856: Add
-fclash-debug-transformations
: only print debug info for specific transformations - #911: Add ‘RenderVoid’ option to blackboxes
- #958: Prefix names of inlined functions
- #947: Add “Clash.Core.TermLiteral”
- #887: Show nicer error messages when failing in TH code
- #884: Teach reduceTypeFamily about AppendSymbol and CmpSymbol
- #784: Print whether
Id
is global or local in ppr output - #781: Use naming contexts in register names
- #1061: Add ‘usedArguments’ to BlackBoxHaskell blackboxes
-
Fixes issues:
- #974: Fix indirect shadowing in
reduceNonRepPrim
- #964: SaturatingNum instance of
Index
now behaves correctly when the size of the index overflows anInt
. - #810: Verilog backend now correctly specifies type of
BitVector 1
- #811: Improve module load behavior in clashi
- #439: Template Haskell splices and TopEntity annotations can now be used in clashi
- #662: Clash will now constant specialize partially constant constructs
- #700: Check work content of expression in cast before warning users. Should eliminate a lot of (superfluous) warnings about “specializing on non work-free cast”s.
- #837: Blackboxes will now report clearer error messages if they’re given unexpected arguments.
- #869: PLL is no longer duplicated in Blinker.hs example
- #749: Clash’s dependencies now all work with GHC 8.8, allowing
clash-{prelude,lib,ghc}
to be compiled from Hackage soon. - #871: RTree Bundle instance is now properly lazy
- #895: VHDL type error when generating
Maybe (Vec 2 (Signed 8), Index 1)
- #880: Custom bit representations can now be used on product types too
- #976: Prevent shadowing in Clash’s core evaluator
- #1007: Can’t translate domain tagType.Errors.IfStuck…
- #967: Naming registers disconnects their output
- #990: Internal shadowing bug results in incorrect HDL
- #945: Rewrite rules for Vec Applicative Functor
- #919: Clash generating invalid Verilog after Vec operations #919
- #996: Ambiguous clock when using
ClearOnReset
andresetGen
together - #701: Unexpected behaviour with the
Synthesize
annotation - #694: Custom bit representation error only with VHDL
- #347: topEntity synthesis fails due to insufficient type-level normalisation
- #626: Missing Clash.Explicit.Prelude definitions
- #960: Blackbox Error Caused by Simple map
- #1012: Case-let doesn’t look through ticks
- #430: Issue warning when not compiled with
executable-dynamic: True
- #374: Clash.Sized.Fixed: fromInteger and fromRational don’t saturate correctly
- #836: Generate warning when
toInteger
blackbox drops MSBs - #1019: Clash breaks on constants defined in terms of
GHC.Natural.gcdNatural
- #1025:
inlineCleanup
will not produce empty letrecs anymore - #1030:
bindConstantVar
will bind (workfree) constructs - #1034: Error (10137): object “pllLock” on lhs must have a variable data type
- #1046: Don’t confuse term/type namespaces in ‘lookupIdSubst’
- #1041: Nested product types incorrectly decomposed into ports
- #1058: Prevent substitution warning when using type equalities in top entities
- #1033: Fix issue where Clash breaks when using Clock/Reset/Enable in product types in combination with Synthesize annotations
- #1075: Removed superfluous constraints on ‘maybeX’ and ‘maybeIsX’
- #1085: Suggest exporting topentities if they can’t be found in a module
- #1065: Report polymorphic topEntities as errors
- #1089: Respect maxBound in Enum instances for BitVector,Index,Signed,Unsigned
- #974: Fix indirect shadowing in
-
Fixes without issue reports:
- Fix bug in
rnfX
defined forDown
(baef30e) - Render numbers inside gensym (bc76f0f)
- Report blackbox name when encountering an error in ‘setSym’ (#858)
- Fix blackbox issues causing Clash to generate invalid HDL (#865)
- Treat types with a zero-width custom bit representation like other zero-width constructs (#874)
- TH code for auto deriving bit representations now produces nicer error messages (7190793)
- Adds ‘–enable-shared-executables’ for nix builds; this should make Clash run much faster (#894)
- Custom bit representations can now mark fields as zero-width without crashing the compiler (#898)
- Throw an error if there’s data left to parse after successfully parsing a valid JSON construct (#904)
Data.gfoldl
is now manually implemented, in turn fixing issues withgshow
(#933)- Fix a number of issues with blackbox implementations (#934)
- Don’t inline registers with non-constant clock and reset (#998)
- Inline let-binders called [dsN | N <- [1..]] (#992)
- ClockGens use their name at the Haskell level #827
- Render numbers inside gensym #809
- Don’t overwrite existing binders when specializing #790
- Deshadow in ‘caseCase’ #1067
- Deshadow in ‘caseLet’ and ‘nonRepANF’ #1071
- Fix bug in
-
Deprecations & removals:
1.0.0 September 3rd 2019
-
10x - 50x faster compile times
-
New features:
- API changes: check the migration guide at the end of
Clash.Tutorial
- All memory elements now have an (implicit) enable line; “Gated” clocks have been removed as the clock wasn’t actually gated, but implemented as an enable line.
- Circuit domains are now configurable in:
-
(old) The clock period
-
(new) Clock edge on which memory elements latch their inputs (rising edge or falling edge)
-
(new) Whether the reset port of a memory element is level sensitive asynchronous reset) or edge sensitive (synchronous reset)
-
(new) Whether the reset port of a memory element is active-high or active-low (negated reset)
-
(new) Whether memory element power on in a configurable/defined state (common on FPGAs) or in an undefined state (ASICs)
-
See the blog post on this new feature
-
- Data types can now be given custom bit-representations: http://hackage.haskell.org/package/clash-prelude/docs/Clash-Annotations-BitRepresentation.html
- Annotate expressions with attributes that persist in the generated HDL, e.g. synthesis directives: http://hackage.haskell.org/package/clash-prelude/docs/Clash-Annotations-SynthesisAttributes.html
- Control (System)Verilog module instance, and VHDL entity instantiation names in generated code: http://hackage.haskell.org/package/clash-prelude/docs/Clash-Magic.html
- Much improved infrastructure for handling of unknown values: defined spine, but unknown leafs: http://hackage.haskell.org/package/clash-prelude/docs/Clash-XException.html#t:NFDataX
- Experimental: Multiple hidden clocks. Can be enabled by compiling
clash-prelude
with-fmultiple-hidden
- Experimental: Limited GADT support (pattern matching on vectors, or custom GADTs as longs as their usage can be statically removed; no support of recursive GADTs)
- Experimental: Use regular Haskell functions to generate HDL black boxes for primitives (in an addition to existing string templates for HDL black boxes) See for example: http://hackage.haskell.org/package/clash-lib/docs/Clash-Primitives-Intel-ClockGen.html
- API changes: check the migration guide at the end of
-
Fixes issues:
- #316
- #319
- #323
- #324
- #329
- #331
- #332
- #335
- #348
- #349
- #350
- #351
- #352
- #353
- #358
- #359
- #363
- #364
- #365
- #371
- #372
- #373
- #378
- #380
- #381
- #382
- #383
- #387
- #393
- #396
- #398
- #399
- #401
- #403
- #407
- #412
- #413
- #420
- #422
- #423
- #424
- #438
- #450
- #452
- #455
- #460
- #461
- #463
- #468
- #475
- #476
- #500
- #507
- #512
- #516
- #517
- #526
- #556
- #560
- #566
- #567
- #569
- #573
- #575
- #581
- #582
- #586
- #588
- #591
- #596
- #601
- #607
- #629
- #637
- #644
- #647
- #661
- #668
- #677
- #678
- #682
- #691
- #703
- #713
- #715
- #727
- #730
- #736
- #738
0.99.3 July 28th 2018
-
Fixes bugs:
- Evaluator recognizes
Bit
literals #329 - Use existential type-variables in context of GADT pattern match
- Do not create zero-bit temporary variables in generated HDL
- Use correct arguments in nested primitives #323
- Zero-constructor data type needs 0 bits #238
- Create empty component when result needs 0 bits
- Evaluator performs BigNat arithmetic
- Evaluator recognizes
-
Features:
- Bundle and BitPack instances up to and including 62-tuples
- Handle undefined writes to RAM properly
- Handle undefined clock enables properly
0.99.1 May 12th 2018
- Allow
~NAME[N]
tag inside~GENSYM[X]
- Support HDL record selector generation #313
InlinePrimitive
support: specify HDL primitives inline with Haskell code- Support for
ghc-typelits-natnormalise-0.6.1
Lift
instances forTopEntity
andPortName
InlinePrimitive
support: specify HDL primitives inline with Haskell code
0.99 March 31st 2018
- New features:
- Major API overhaul: check the migration guide at the end of
Clash.Tutorial
- New features:
- Explicit clock and reset arguments
- Rename
CLaSH
toClash
- Implicit/
Hidden
clock and reset arguments using a combination ofreflection
andImplicitParams
. - Large overhaul of
TopEntity
annotations - PLL and other clock sources can now be instantiated using regular functions:
Clash.Intel.ClockGen
andClash.Xilinx.ClockGen
. - DDR registers:
- Generic/ASIC:
Clash.Explicit.DDR
- Intel:
Clash.Intel.DDR
- Xilinx:
Clash.Intel.Xilinx
- Generic/ASIC:
Bit
is now anewtype
instead of atype
synonym and will be mapped to a HDL scalar instead of an array of one (e.gstd_logic
instead ofstd_logic_vector(0 downto 0)
)- Hierarchies with multiple synthesisable boundaries by allowing more than one
function in scope to have a
Synthesize
annotation.- Local caching of functions with a
Synthesize
annotation
- Local caching of functions with a
Bit
type is mapped to a HDL scalar type (e.g.std_logic
in VHDL)- Improved name preservation
- Zero-bit values are filtered out of the generated HDL
- Improved compile-time computation
- Major API overhaul: check the migration guide at the end of
- Many bug fixes
Older versions
Check out:
- https://github.com/clash-lang/clash-compiler/blob/3649a2962415ea8ca2d6f7f5e673b4c14de26b4f/clash-prelude/CHANGELOG.md
- https://github.com/clash-lang/clash-compiler/blob/3649a2962415ea8ca2d6f7f5e673b4c14de26b4f/clash-lib/CHANGELOG.md
- https://github.com/clash-lang/clash-compiler/blob/3649a2962415ea8ca2d6f7f5e673b4c14de26b4f/clash-ghc/CHANGELOG.md