I'll start with a short demonstration of the simulator followed by some of the internal details.
First of all we need something to simulate. To keep things simple it'll be an basic up-down counter.
To start we define the input and output interfaces to the counter using the syntax extension.
In [1]:
module Up_down_counter_in = interface
clear[1] up[1] down[1]
end
module Up_down_counter_out = interface
count[8]
end
Out[1]:
Out[1]:
Now the design itself
In [2]:
open HardCaml
open Signal.Types
open Signal.Comb
open Signal.Seq
(* basic logic for the counter.
increment when up=1, decrement when down=1 *)
let up_down_counter clear up down width =
reg_fb
{ r_sync with reg_clear = clear }
(up ^: down) width
(fun d -> mux2 up (d +:. 1) (d -:. 1))
(* wrap with interfaces *)
let up_down_counter_if i =
let width = snd Up_down_counter_out.(t.count) in
let count = Up_down_counter_in.(up_down_counter i.clear i.up i.down width) in
Up_down_counter_out.( { count } )
Out[2]:
Out[2]:
The main logic is in the up_down_counter function. This is then wrapped up with the interfaces using the up_down_counter_if. This little bit of extra work here pays dividends in the next step.
In [3]:
module B = Bits.Comb.IntbitsList
module Builder = Interface.Gen(B)(Up_down_counter_in)(Up_down_counter_out)
Out[3]:
Out[3]:
The circuit interfaces have been plugged into the interface machinery from which we can build the simulator.
In [4]:
let circ,sim,i,o,_ = Builder.make "up_down_counter" up_down_counter_if
Out[4]:
We now have the circuit, simulator and ports. Time to simulate.
In [5]:
module S = Cyclesim.Api
let test sim =
let open Up_down_counter_in in
let open Up_down_counter_out in
let cycle() =
S.cycle sim;
Printf.printf "%i\n" (B.to_int !(o.count))
in
S.reset sim;
i.clear := B.vdd;
cycle();
i.clear := B.gnd;
i.up := B.vdd;
i.down := B.gnd;
cycle();
cycle();
cycle();
i.up := B.gnd;
i.down := B.vdd;
cycle();
i.up := B.vdd;
i.down := B.vdd;
cycle();
i.up := B.gnd;
i.down := B.vdd;
cycle();
cycle();
Printf.printf "done.\n"
Out[5]:
Out[5]:
In [6]:
test sim
Out[6]:
Printing a trace is all fine and dandy. But we can do better.
In [7]:
(* theres a div in a cell below which we intend to render to *)
let div = Js.Opt.get (Dom_html.document##getElementById(Js.string "waves"))
(fun () -> raise Not_found)
let sim, wave = HardCamlJS.Wave.wrap sim
Out[7]:
Out[7]:
In [8]:
test sim
Out[8]:
In [9]:
HardCamlJS.Wave.Gui.mk_wave_table div 400 20 wave
Out[9]:
HardCaml can be used without interfaces, though it does require some extra work. The main issue is this; when I write something like
let up_down_counter clear up down = ...
in my head I know what the interface looks like, but from HardCaml's point of view those useful names don't really exist. When you need to manipulate the interface to a circuit (both in simulation and when writing our RTL) you need some way to get those names back and this is done with strings.
let up = input "up" 1 in
let down = input "down" 1 in
let count = up_down_counter ... in
let count = output "count" count in
...
the whole reason we need inputs and output is precisely to associate names to the signals.
When working with the low level simulator APIs we have a similar issue.
let sim = ....
let up = S.find_in_port sim "up" in
let count = S.find_out_port sim "down" inFor small examples it isn't too bad but after a while it becomes annoying.
For the price of defining interfaces and wrapping your circuits with them this can be done automatically.