# `mix ehls.compile`
[🔗](https://github.com/elixir-hls/elixir-hls/blob/v0.1.0/lib/mix/tasks/ehls.compile.ex#L1)

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`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
