Replace topEntity and enable extra extensions

[lmbollen]

This Pull requests makes the following changes:

• Export all functions. a new topEntity of function might not get picked up if the user doesn't know that it should explicitly export it, too.
• Add top entity featuring sequential logic that better represents what a digital designer would create.
• Synthesize annotation to make sure the inputs and output of the HDL are named.
• Enabling FlexibleContexts, NamedFieldPuns and RecordWildCards extensions, which are commonly used when writing Clash code.
• Add Contribution section with building instructions.

[DigitalBrains1]

Our current recommendation is that people start out with the implicit interface, and at a later point learn to work with the explicit interface.

If you want to reverse this recommendation, I think we need to discuss that with everyone who works on clash-prelude and maybe involve a few community members as well to hear what they think is best. I do not consider this a "small fix"!

I don't think I've scrutinised this file before. I think those top entities are bad. This is a template for people to extend to build their own project. And the top entity in that template is combinatorial. I think a fully combinatorial project is very exceptional and it seems like a poor basis.

Instead, I think the top entity should be nothing but an exposeClockResetEnable, with the actual basic project being implicit.

Something like this seems a much better start for somebody's project:

-- @createDomain@ below generates a warning about orphan instances, but we like
-- our code to be warning-free.
{-# OPTIONS_GHC -Wno-orphans #-}

module Example.Project where

import Clash.Prelude

-- Create a domain with the frequency of your input clock
createDomain vSystem{vName="MyDom", vPeriod=hzToPeriod 50e6}

-- | 'topEntity' is Clash's equivalent of 'main' in other programming languages.
-- Clash will look for it when compiling 'Example.Project' and translate it to
-- HDL. While polymorphism can be used freely in Clash projects, a 'topEntity'
-- must be monomorphic and must use non- recursive types. Or, to put it
-- hand-wavily, a 'topEntity' must be translatable to a static number of wires.
--
-- The inputs need to be declared as parameters in order to be able to give them
-- custom names. In other words, @topEntity = exposeClockResetEnable acc@ would
-- prevent naming the inputs.
topEntity ::
  Clock MyDom ->
  Reset MyDom ->
  Enable MyDom ->
  Signal MyDom (Unsigned 8) ->
  Signal MyDom (Unsigned 8)
topEntity clk rst en inp = (exposeClockResetEnable accum) clk rst en inp
-- Give names to the top entity parts
{-# ANN topEntity
  (Synthesize
    { t_name = "accum"
    , t_inputs = [ PortName "CLK"
                 , PortName "RST"
                 , PortName "EN"
                 , PortName "DIN"
                 ]
    , t_output = PortName "DOUT"
    }) #-}

-- | A simple accumulator: it accumulates the inputs, resets to 0, and outputs
-- the current state
accum ::
  HiddenClockResetEnable MyDom =>
  Signal MyDom (Unsigned 8) ->
  Signal MyDom (Unsigned 8)
accum = mealy accumT 0
 where
  accumT s i = (s + i, s)

Ideally, I'd lob a PLL in there but unfortunately those are platform-dependent.

[martijnbastiaan]

FWIW: I've long been a proponent for teaching the non-abstracted version (explicit prelude) first. The hidden mechanism has too many "gotchas" to recommend to beginners IMO:

• Monomorphic constraints (HiddenClockResetEnable MyDomain) generate warnings
• Can't use multiple clocks
• Yet another concept to grasp (constraints, arguments, and implicit parameters)
• Easy to use incorrectly when using a PLL/BUFG (a thing you should include for any realistic design)
• Weird error messages if you forget an IP constraint

But I agree with Peter that this is not a decision we can take on a whim. We should recommend the same in Clash.Tutorial and for this project.

[martijnbastiaan]

Could you pls change the PR title? :-)

[DigitalBrains1]

And the PR cover letter, it no longer accurately describes the PR as it will be when merged.

[DigitalBrains1]

🚀