Changelog for clash-prelude-1.2.0

Changelog for the Clash project

1.3.0

See changelog/README.md

New features (API):
- Added basic support for writing PSL/SVA assertions in Clash.Verification
New features (Compiler):
- No new features yet!
Fixes issues:
- No fixes yet!
Fixes without issue reports:
- Use ByteArray instead of Vector Word8 in the ByteArrayLiteral type. See #1151

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 as InlinePrimitive [VHDL] "..".
Use the Enum instance for BitVector, Index, Signed, or Unsigned, as they now respect their maxBound. 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 Prelude odd and even functions due to assumptions that don't hold for Clash specific numerical types, see #970.
- NFDataX.ensureSpine, see #748
- makeTopEntity 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 empty PortProduct. 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 Signals 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 and CmpSymbol
- Added Clash.Magic.suffixNameFromNat: can be used in cases where suffixName 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 a KnownNat (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 with Clash.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 in clash --show-options
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 an Int.
- #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 and resetGen 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: inlineCleanupwill 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
Fixes without issue reports:
- Fix bug in rnfX defined for Down (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 with gshow (#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
Deprecations & removals:
- Removed support for GHC 8.2 (#842)
- Removed support for older cabal versions, only Cabal >=2.2 supported (#851)
- Reset and Enable constructors are now only exported from Clash.Signal.Internal
- #986 Remove -fclash-allow-zero-width flag

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
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
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 for TopEntity and PortName
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 to Clash
  - Implicit/Hidden clock and reset arguments using a combination of reflection and ImplicitParams.
  - Large overhaul of TopEntity annotations
  - PLL and other clock sources can now be instantiated using regular functions: Clash.Intel.ClockGen and Clash.Xilinx.ClockGen.
  - DDR registers:
    - Generic/ASIC: Clash.Explicit.DDR
    - Intel: Clash.Intel.DDR
    - Xilinx: Clash.Intel.Xilinx
- Bit is now a newtype instead of a type synonym and will be mapped to a HDL scalar instead of an array of one (e.g std_logic instead of std_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
- 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
Many bug fixes

Older versions

Check out: