Compiles the defhls functions and pipelines of Elixir files to SystemVerilog with CIRCT and checks every kernel in simulation (iverilog) against the same function run by Elixir:
mix ehls.compile --out build file.ex...
mix ehls.compile --out build --with blocks.ex app.ex # --with: compiled along (e.g.
# EHLS.Blocks modules of packages)Writes to <out>/hw: per kernel <kernel>.sv (a CIRCT handshake module; with tables /
memories also <kernel>_space.v), <kernel>.sig (JSON: types, state, the arguments after the first, memories),
the simulation files; for the SoC backend kernels.json, pipelines.json,
peripherals.json, packages.json; and, with a runtime backend, what it generates (e.g.
<out>/gen/hw_kernels.erl: the indices for the generated runtime calls).
--target cpu writes C for the CPU instead (<out>/cpu/<kernel>.c, see EHLS.NIF) and checks it
against the Elixir functions with the host's C compiler; it needs no CIRCT, python3 or iverilog.
Options: --target (circuit, default, or cpu), --out (default build), --with FILE (repeatable), --vectors N (random
vectors per kernel, default 2000). Environment: CIRCT_BIN (required: the directory of the
CIRCT 1.160 release binaries, hlstool + mlir-opt), EHLS_DEVICE / EHLS_SOC / EHLS_RUNTIME
(the backends, EHLS.Backend), PIPE_BUDGET (ns; default: the device's). Needs python3
and iverilog.
The check in simulation
No test is written by hand: for each kernel the inputs, the expected results and the testbench are made here, and the circuit runs in iverilog against them.
- Inputs: edge values first,
0,1,0x7FFF,0x8000,0xFFFF,0x10000,0x7FFFFFFF,0x80000000,0xFFFFFFFF,0x80008000,0x7FFF7FFF(and, for a kernel with 64-bit ports,0x100000000,0x7FFFFFFFFFFF,0x800000000000,0xFFFFFFFFFFFF,0x7FFFFFFFFFFFFFFF,0x8000000000000000and all ones); then--vectors Nrandom ones. A random input covers the whole port, 32 or 64 bits, so bits beyond the argument's type come too: the circuit and the function both cut them, which is checked as well. A tuple gets the edge values at each of its values in turn, the others random, then random tuples. The seed is fixed, so every run has the same inputs. - Expected results: the same
defhlsfunction run by Elixir, on the BEAM, over the same inputs. The function is the specification. - A kernel without state: one input at a time, its result compared;
latency=a..bis the fewest and the most clocks an input took. - A kernel with state: behind its state adapter, as in the SoC. The inputs go in two
halves, each from the initial state, so a restart is checked too. The testbench leaves
random gaps between the inputs it gives and between the outputs it takes, as data does not
come every clock in a real circuit and whoever takes the output can make it wait. With a list as the output (
{[y], s}/{[], s}), an input that gives nothing must give nothing.clocks/wordis clocks per element. - Levels (a function's arguments besides the stream) are 0, or the integer they are placed with; tables and memories are in the simulation with their kernel.
- The verdict: a line per kernel,
RESULT <kernel>: vectors=V errors=E ..., whereVcounts the edge values and the random ones (11 + 2000 = 2011 by default; 2018 with 64-bit ports; for a tuple of k values, k times the edge values, e.g. 2 * 11 + 2000 = 2022). The first five differences are printed asMISMATCHlines, with what came and what was expected. A kernel with errors, or one that stops answering (TIMEOUT), stops the command there.
Not checked here: a level changed while running, and the CPU ends (their DMA, in
test/sim_cpu_ends.py). What a definstance places, its functions joined with the pipe,
is checked by mix ehls.sim.