Need tutorial: naming inputs/outputs?

[mgajda]

How to name inputs and outputs, so they can be immediately mapped to chip pins?

[christiaanb]

At the moment, you have to write a thin wrapper in VHDL yourself. See for example: https://github.com/christiaanb/DE1-Cyclone-II-FPGA-Board-Support-Package/blob/master/DE1Top/CII_Starter_TOP.vhd

There are plans to add a feature by which you can generate the pin-mappings automatically.

[mgajda]

A similar question is: how to name an IP component which has a simulation code, but when instantiated to VHDL it should be just mapped to an externally defined VHDL component? (For example provider-specific FPGA slice, like multiplier-accumulator, or netlist FFT implementation.)

[mgajda]

Do I correctly expect, that adding a few signals may require redefining names in this thin wrapper?
So far the key to name generation is rather opaque for me.

[christiaanb]

At the moment, yes, you might need to update the wrapper. I do plan to generate consistently named top-level entities. It's on the big to-do list...

[mgajda]

Sounds like you might want to add a comment (CONTRIBUTING.md in the main dir of the repo) on how to start hacking and contributing to the project then...
Clash is definitely very interesting approach!

[masterdezign]

That would be very practical to have such a wrapper generator. But do you already have some development documentation/guides for contributors?

[christiaanb]

At the moment, all there is, is: https://github.com/clash-lang/clash-compiler/blob/master/HACKING.MD

Could somebody point me to a guide for another project after which I should model a development guide for CLaSH?

[masterdezign]

Sure,

here is a guide for another project related to hardware design (the one I am currently using):

http://dev.myhdl.org/guide.html
http://dev.myhdl.org/meps/
http://dev.myhdl.org/ideas/

[christiaanb]

I just released version 0.5.4 of the clash compiler which features topEntity wrapper. This feature is described at: http://christiaanb.github.io/posts/clash-fpga-starter/

Please indicate if this feature is enough for this issue to be closed.

[masterdezign]

Really useful feature. Congratulations!
I guess, the issue may be closed now.

[mgajda]

Thank you very much. Now time to try to add topentity generator to my Xilinx file.

That said, I'd recommend considering YAML as more lightweight option over JSON.

[ggreif]

Just a side comment. Did you consider annotations for adding such metainformation to haskell values? The folks at skedge.me do it for their JS APIs that they generate from GHC. There is a video https://www.youtube.com/watch?v=fTNEDhMjevQ

[christiaanb]

@ggreif Yeah... we've actually used GHC annotations in an older version of the clash compiler, back in the GHC 6.12 era I believe. Anyhow, no, I hadn't considered them. It actually makes more sense to use annotations because then you don't need this extra file that you might put in the wrong place, and, you don't have to write JSON or YAML or whatever markup language.

I guess version 0.5.5 might already use annotations instead of external files. Unless somebody objects.

[mgajda]

+1 on annotations.

[mgajda]

Unless there is a way to add {-# NOINLINE #-} blackbox a -> a function that does the same job.

[Ericson2314]

Yeah I like annotations too. It would be cool too if the PLL was just another black box, rather than needing special support, though I am not sure how that would work.

[Ericson2314]

One thing I once thought about is making every register explicitly take the clock line (which I guess would be the clock singleton?), but making it an implicit paramter. Then we wouldn't need implicit/explicit variants, and CLaSH wouldn't have to infer the extra wires. Best of both worlds!

The PLL primitive would have the type of a clock singleton then (or SClock -> SClock for the crystal)

[christiaanb]

Alright, I implemented GHC annotation based topEntity annotations. Following the example of the tutorial, you will be able to write:

{-# ANN topEntity
  (defTop
    { t_name     = "blinker"
    , t_inputs   = ["KEY1"]
    , t_outputs  = ["LED"]
    , t_extraIn  = [ ("CLOCK_50", 1)
                   , ("KEY0"    , 1)
                   ]
    , t_clocks   = [ defClkAltera "altpll50" "CLOCK_50(0)" "not KEY0(0)" ]
    }) #-}
topEntity :: Signal Bit -> Signal (BitVector 8)
topEntity key1 = leds
  where
    key1R = isRising 1 key1
    leds  = mealy blinkerT (1,False,0) key1R

blinkerT (leds,mode,cntr) key1R = ((leds',mode',cntr'),leds)
  where
    -- clock frequency = 50e6  (50 MHz)
    -- led update rate = 333e-3 (every 333ms)
    cnt_max = 16650000 -- 50e6 * 333e-3

    cntr' | cntr == cnt_max = 0
          | otherwise       = cntr + 1

    mode' | key1R     = not mode
          | otherwise = mode

    leds' | cntr == 0 = if mode then complement leds
                                else rotateL leds 1
          | otherwise = leds

It's time to go home now, so I'll make a release tomorrow.

[christiaanb]

I've just released version 0.5.5 which implements the wrapper specifications as annotations: https://hackage.haskell.org/package/clash-prelude-0.7.4/docs/CLaSH-Annotations-TopEntity.html

Also, I've updated the tutorial accordingly: http://christiaanb.github.io/posts/clash-fpga-starter/

I think I'll close the issue now.

[Ericson2314]

Just because you closed this, did you see my proposal in this comment? It's somewhat orthogonal to the stuff here so I'd be happy to open another issue if you are interested.

[christiaanb]

@Ericson2341: yes I did see it. The problem is that the implicit parameters approach might make clash even harder to grok than it already is for those that come to use clash but are not Haskell natives. Please open a another issue so we can have that discussion there.