clash-ghc v1.2.0 Release Notes
Release Date: 2020-03-05 // about 4 years ago-
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.
- 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: