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

`defhls`: an Elixir function that can be synthesized, and runs on the CPU too. `definstance`
(`EHLS.Pipeline`) places it in the FPGA. A `defhls` can call others of its module; in the circuit the call is the
callee's body, and one with several arguments is only for this. `case`, `cond`, patterns and
several clauses become `if`s for the circuit. Definitions are processed at the end of the module.

    defmodule Demo do
      use EHLS

      defhls stream_kernel(x :: u32) :: u32 do
        a = signed(x &&& 0xFFFF, 16)
        b = signed(x >>> 16, 16)
        if a > b, do: a * 3 + b, else: a + b * 2
      end
    end

generates

  * `stream_kernel(integer)`: the function on the CPU, with the argument and result wrapped to
    their types (`u1`..`u64`, `s1`..`s64`, tuples), the same results as the hardware;
  * when `EHLS_OUT_DIR` is set at compile time, `<kernel>.mlir` there (func + arith, see
    `EHLS.MLIR`) and `<kernel>.sig`, which `mix ehls.compile` turns into
    SystemVerilog with CIRCT and into the SoC's kernel list. The kernel is named
    `<module>_<function>` (`kernel_demo_stream_kernel`).

# `__using__`
*macro* 

`use EHLS` imports `defhls` / `definstance`. Options:

  * `blocks: [module | {module, options}]`: packages of blocks and peripherals
    (`EHLS.Blocks`) for the SoC backend in use, besides its built-in ones
    (`EHLS.Blocks.defaults/0`); options go to the package's gateware (e.g.
    `pins: [dout: "j5:7"]` over its default pins);
  * `peripherals: [atom]`: SoC peripherals of those packages the application uses (e.g. a
    LCD).

With `EHLS_OUT_DIR` set at compile time, `<module>.packages` (the packages and their options)
and `<module>.peripherals` go there for the SoC (priv/gen_manifest.py).

# `cpu_code`

How the stages of an instance on the CPU run: `:beam` (the `defhls` functions as Elixir, in the VM, anywhere) or
`:nif` (their C, `mix ehls.compile --target cpu`, as machine code through the runtime's NIF). `EHLS_CPU`, else
`config :elixir_hls, cpu: ...`, else `:beam`.

# `defhls`
*macro* 

A function defined with `defhls` becomes a circuit where `definstance` places it in the FPGA; that circuit is a kernel.
It takes one element of a stream (a value up to 64 bits, or a tuple of them) and gives one result. The CPU reaches it
by calling the instance it is placed in (calling an instance from the CPU).

- **Types:** `u1`..`u64` (unsigned), `s1`..`s64` (signed) and tuples of them. A kernel's input and output are up to 64 bits:
  its ports are 32 bits, or 64 when a value of its input or output is wider. State, memories and levels are up to 32 bits,
  since the CPU reads and sets them in 32-bit words. Tuples hold
  state and values born together; on a stream they are one element, moving in one clock. On the CPU the arguments and the result are
  cut to their widths too, so the CPU computes what the circuit does.
- **Expressions:** `+ - *`, `&&& ||| ^^^`, shifts (`>>>` also by an unsigned value),
  comparisons, `and or not`, `if/else`, `case`, `cond`, tuples, `signed(x, n)` / `unsigned(x, n)` (the low n
  bits of a value as a signed / unsigned number), `Enum.at(@t, i)` (a list of integers in a
  module attribute, looked up as a table).
- **State:** a function of the element and a state, `count(x :: u8, n :: u16) :: {u8, u16}`, returns
  `{output, next_state}`: the shape of the function `Stream.transform/3` takes. The function itself holds nothing: on
  the CPU it is a plain function, called with a state. Placed with `transform(init, &f/2)`, its second argument is the
  state: it sits in the circuit's registers, starts from `init` and changes with every item.
- **A missing output:** as in `Stream.transform/3`, the output is a list, `{[y], s}` or `{[], s}` (at most one
  element), written `{[u8], u16}`: a kernel gives no output for some items, e.g. one output for every four inputs (rate
  changes).
- **Tuples in the state:** a state may hold tuples, `{pos, hist} :: {u8, tuple(s16, 8)}` (`tuple(s16, 8)`: 8
  integers of type `s16`, the same as `{s16, s16, ...}`), read with `elem(hist, i)`; the next state holds the tuple
  rewritten with `put_elem`, as Elixir would. The next state replaces the state whole, so placed with `transform` the
  tuple is registers. With `memory: [:hist]` where it is placed, `hist` is the FPGA's memory (block RAM): smaller, but
  one element read or written per clock, and only for a next state made from it with `put_elem`, from zeros:

  ```elixir
  defhls fir(x :: s16, {pos, hist} :: {u8, tuple(s16, 8)}) :: {s32, {u8, tuple(s16, 8)}} do
    acc = for k <- 1..3, reduce: x do
      acc -> acc + elem(hist, (pos - k) &&& 7)
    end
    {acc, {pos + 1, put_elem(hist, pos &&& 7, x)}}
  end

  x |> transform({0, Tuple.duplicate(0, 8)}, &fir/2, memory: [:hist])
  ```

  In a memory, what `put_elem` writes goes in at the end of the step, as a register takes its next value: every `elem`
  of the step reads the tuple as it came in, and one of a tuple rewritten in the step reads the value written there.
  On the CPU it is Elixir's tuple; an index out of range is an error, so a ring buffer writes its wrap,
  `(pos - k) &&& 7`, which costs no circuit. The circuit does not check the index: out of range it reads or writes
  something else (a memory is rounded up to a power of two), so keep the index in range, as on the CPU.
- **Levels:** after the element (and the state, for `transform`), plain arguments are levels: inputs read at each item,
  given where the function is placed, `map(&scale(&1, gain_hw(:value)))`,
  `transform(0, &volume(&1, &2, gain_hw(:value)))` (`EHLS.Pipeline`, "Instances of levels"), or integers. On the CPU
  they are plain arguments.
- **`case` and `cond`:** a circuit gives a value for every input, so the last clause must match everything: `_ ->` or a variable, `true ->` in a
  `cond`. Patterns are integers, variables, `_`, `^variable` and tuples of them, with guards (`when`). In the circuit every clause is
  computed and one selected.
- **Several clauses:** a function can have clauses with patterns and guards. Each repeats the types, which must be the same, and the last
  must match everything, as in `case`. A function with a memory has one clause.

  ```elixir
  defhls classify(0 :: u8) :: u8 do
    200
  end

  defhls classify(x :: u8) :: u8 when x < 16 do
    x * 2
  end

  defhls classify(x :: u8) :: u8 do
    x >>> 1
  end
  ```

- **Calls:** a `defhls` can call others of the same module, in any order. This adds no circuit of its own: the
  body is expanded at each call, so two calls cost two copies. Arguments and result are wrapped to the callee's types, so the CPU gives
  the same results. A `defhls` with several arguments is placed with the stream as one of them and levels or integers as
  the others (`map(&scale(&1, 3))`, `EHLS.Pipeline`). Functions with a memory or a list as the output cannot be called, and neither can a function call itself.

  ```elixir
  defhls sat16(v :: s32) :: s16 do
    if v > 32767, do: 32767, else: if(v < -32768, do: -32768, else: v)
  end

  defhls mix(a :: s16, b :: s16, k :: u4) :: s16 do
    sat16(a * k + b)
  end
  ```

- **Table values:** `defhls` and `definstance` are processed together at the end of the module, so `Enum.at(@t, i)` has the value last set in `@t`.
- **Loops:** `for k <- a..b, reduce:` is a loop in the circuit: one copy of the body, used
  again and again. `Enum.reduce(a..b, ...)` is unrolled: n copies of the body side by side,
  `k` a constant. Unroll for speed, loop for size; both nest.

What cannot become a circuit stops the compile, with a `CompileError` giving the file and the line of the expression, or
of the call in a `definstance`. Whether an expression can become a circuit shows when `mix ehls.compile` builds it.

## Stream functions

A `defhls` can take a stream as well as a single value. This gives a name to functions joined with the pipe, for using them several times.

```elixir
defhls fir(w :: tuple(s16, 32)) :: s18 do
  ...
end

defhls lowpass(x :: stream(s16)) :: stream(s18) do
  x |> chunk_every(32, 4, :discard) |> map(&fir/1)
end

lowpass([100, -200, 300, 400])    # on the CPU: a list in, a list out

definstance filtered(samples) do
  samples |> lowpass()            # placed as a circuit
end
```

- **What it holds:** the functions of `EHLS.Stream` (`map`, `transform`, `chunk_every`, ...) and other stream functions. The body starts with its argument and ends in a stream. Devices and built-in
  blocks cannot run on the CPU, so they cannot be here. One input and one output, no forks.
- **On the CPU:** a list goes through element by element. Elements stay as they are, tuples and signs included; the argument's are wrapped to the type in
  `stream(type)`. A function whose output is a list (`{[y], s}` / `{[], s}`) or `chunk_every` makes the list shorter. So a whole chain can be tested with `mix test`, without a board; to compare it with the circuit, run an instance using it through `mix ehls.sim`.
- **State:** on the CPU each call starts from the `transform`'s initial state. A circuit's state goes on, so results agree from the initial state. To go on computing on the CPU, call
  the function with state directly, giving it the state.
- **Levels:** after the stream, arguments with a type (up to 32 bits) are levels the functions in its pipe
  take, and the `definstance` placing it says where each comes from (`EHLS.Pipeline`, "Instances of levels"):

  ```elixir
  defhls louder(x :: stream(s16), k :: u9) :: stream(s16) do
    x |> map(&smooth/1) |> map(&scale(&1, k))
  end

  louder([100, 200, 300], 5)       # on the CPU: k is 5 for the whole list

  definstance player(samples) do
    louder(samples, k_hw(:value))  # in the circuit: scale reads k_hw's result at each value
  end
  ```

  So the CPU and the circuit agree while the level does not change. A level can be given on to another stream
  function, `x |> louder(k)`, or be an integer where it is placed, `louder(samples, 3)`.
- **Circuit:** a stream function is a definition too and makes no circuit. Used in an instance, it is expanded in place. Used twice, there are two circuits, with
  two states.
- **Types:** the argument's type must widen to the input of the first function in the pipe, and the end of the pipe to the result's type. The rule is that of the links.
- **Names:** what is named inside is named as if placed in the instance directly: `f(:state, :total)` (`transform(0, &sum/2, name: :total)`). A function used twice repeats the names.
  A function with a named state used twice stops the compile, as the state could not be told.

# `definstance`
*macro* 

`definstance`: see `EHLS.Pipeline`.

# `definstance`
*macro* 

# `layout`

A stream element's type as the runtime's `pack/2` and `unpack/2` take it: a scalar is its
bits, negative when signed; a tuple is a tuple of those. A block that takes any type: a word.

    iex> EHLS.layout({:tuple, [{8, false}, {16, true}]})
    {8, -16}

# `pack`

Elements to a binary in the packed format (`packed_size/1`), each value wrapped to its type:
what the runtime's `pack/2` does in C, written in Elixir to check it against.

    iex> EHLS.pack([{1, -2}, {300, 70000}], {8, -16})
    <<1, 254, 255, 44, 112, 17>>

# `packed_size`

The bytes of one element of a stream in a binary at the CPU: each scalar in 1, 2, 4 or 8, the
smallest that holds it; a tuple left to right, no padding. A block that takes any type: a word.

    iex> EHLS.packed_size({12, true})
    2
    iex> EHLS.packed_size({:tuple, [{8, false}, {32, true}]})
    5

# `placement`

Where an instance's stages run unless the stage or the instance says (`on: :cpu | :fpga`): `EHLS_PLACEMENT`, else
`config :elixir_hls, placement: ...`, else `:fpga` with a backend that makes circuits (a SoC or a device backend,
`EHLS.Backend`), else `default`: `:cpu` (an application runs without an FPGA), `:fpga` when circuits are being made
(`mix ehls.compile`). See `EHLS.Pipeline`, "Placement".

# `run_cpu`

Runs a stateful defhls function on the CPU over a list of inputs from `state`:
returns {outputs, final state}, like the FPGA does with a stream.

# `runtime`

The module the generated code calls to use the hardware: the runtime backend's
(`c:EHLS.Runtime.module/0`, `EHLS.Backend`), nil without one (CPU only: no hardware clauses).
It provides `pipe_enable(pipeline_index, on)`, `level_start(level, pipeline, words)`,
`peek(stage, words)`, `end_send/5`, `end_request/5`, `end_cancel/1`, `end_push/3`, and `pack(list, layout)`,
`unpack(binary, layout)` as `pack/2` and `unpack/2` do; the indices come from the
module `:hw_kernels` the runtime backend generates.

# `signed`

The low `n` bits of `x` as a two's complement signed integer.

# `unpack`

A binary in the packed format to its elements, signed values negative, tuples as tuples:
what the runtime's `unpack/2` does in C. A binary that is not a whole number of elements raises.

    iex> EHLS.unpack(<<1, 254, 255, 44, 112, 17>>, {8, -16})
    [{1, -2}, {44, 4464}]

# `unsigned`

The low `n` bits of `x` as an unsigned integer.

---

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