mix ehls.compile (Elixir HLS v0.1.0)

Copy Markdown View Source

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, 0x8000000000000000 and all ones); then --vectors N random 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 defhls function 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..b is 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/word is 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 ..., where V counts 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 as MISMATCH lines, 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.