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

The hardware abstraction layer: the backends a build uses, one of each kind.

  * device (`EHLS.Device`): the FPGA family; acts inside the compile (buffers, delay model).
  * SoC (`EHLS.SoC`): how the circuits are built into a system on chip (control bus, DMA,
    the built-in blocks); `nil` for circuits only.
  * runtime (`EHLS.Runtime`): what the generated functions call on the CPU; `nil` for the
    CPU only (no hardware clauses are generated).

Chosen at compile time from the environment (`EHLS_DEVICE`, `EHLS_SOC`, `EHLS_RUNTIME`: a
backend's short name, `none`, or a module name) or else from the application's config:

    config :elixir_hls, device: EHLS.Device.GowinGW5A, soc: EHLS.SoC.LiteX,
      runtime: EHLS.Runtime.AtomVM

Defaults: the generic device, no SoC, no runtime. Each backend says what it combines with
(`c:EHLS.Runtime.socs/0`, a block package's `c:EHLS.Blocks.soc/0`); `check!/0` stops a
combination that does not fit.

## The backends

What depends on the hardware is in three kinds of backends; a build uses one of each.

| kind | acts | backends |
|---|---|---|
| device (`EHLS.Device`) | inside the compile: where buffers go in a circuit, from the FPGA's estimated delays and a budget | `generic` (default), `gowin_gw5a` (plus the timing check `check_timing.py` and LiteX toolchain settings) |
| SoC (`EHLS.SoC`) | builds the circuits into a SoC: control bus, DMA, blocks | none (default), `litex` (`hls_litex.add_hls(soc, hw_dir, package_dirs)`) |
| runtime (`EHLS.Runtime`) | what the generated functions call on the CPU to use the hardware | none (default: CPU only, no clauses that call the hardware), `atomvm` (`:hwstream` NIFs, needs `litex`) |

They are chosen at compile time by `EHLS_DEVICE`, `EHLS_SOC`, `EHLS_RUNTIME` (a short name,
`none` or a module name) or `config :elixir_hls, device: ..., soc: ..., runtime: ...`; a
combination that does not fit (AtomVM without LiteX, say) stops the compile. Each backend's
Python, C and Erlang files are in `priv/backend/<name>`.

## Files a target gets

For those writing a target. `mix ehls.compile --out DIR [--with FILE]... FILE...` writes to
`DIR/hw`:

| file | contents |
|---|---|
| `<kernel>.sv` | a CIRCT `--dynamic-hw` module: inputs `in0..` (the argument's values, the state's, the level arguments, the memory space, a start token), outputs `out0..` (the result's values, the next state's, a done token), each with valid / ready |
| `<kernel>_space.v` | the kernel's tables and memories (one address space module) |
| `<kernel>.sig` | JSON: types, state and its initial value, the arguments after the first (`args`, each with its `kind`), whether the output is a list (`emit`), memories; a state holding memories its parts in order (`shape`) |
| `kernels.json`, `pipelines.json`, `peripherals.json`, `packages.json` | the kernels, the instances (each stage a kernel or a block with its package's gateware), the peripherals, the packages (their options, registers with their numbers, and tables) |

and what the runtime backend generates, if there is one (AtomVM: `DIR/gen/hw_kernels.erl`,
the instance / CPU end / state / level indices, a package's registers by `reg/2` and its table by
`data/2`, the runtime's module by `runtime/0`).

A kernel module is awkward to put on a stream as it is, so `priv/verilog/` has adapters
around it: `hls_stream_adapter.v` (a kernel without state, one element in, one out) and
`hls_state_adapter.v` (state in registers, tuples, a list as the output). Both connect through valid / ready /
data streams (an element moves in a clock where valid and ready are both 1), with one clock and a
synchronous reset.

With a runtime backend the generated functions call its module (`EHLS.runtime/0`; AtomVM:
`:hwstream`): `pipe_enable(instance, on)`,
`level_start(level, pipeline, words)` (an instance of levels: its arguments' words, then the start; the count of that start or `:stopped`), `peek(stage, words)`, `mem_read(stage, addr, count)` (a named state's memory, word by word), `end_send/5`, `end_request/5`, `end_cancel/1` (a transfer on a CPU end,
ending in a message), `end_push(end, pipeline, words)` (one element without DMA: `:ok`, `:full` or `:stopped`), and a block package's
registers `reg_read(reg)`, `reg_write(reg, value)` (`registers/0` of `EHLS.Blocks`).

# `check!`

The three backends; raises when they do not combine.

# `device`

The device backend (a module implementing `EHLS.Device`).

# `priv`

The directory of a backend's files (Python, C, Erlang) in elixir-hls' `priv/backend`.

# `runtime`

The runtime backend (`EHLS.Runtime`), or nil.

# `soc`

The SoC backend (`EHLS.SoC`), or nil.

---

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