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);nilfor circuits only. - runtime (
EHLS.Runtime): what the generated functions call on the CPU;nilfor 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.AtomVMDefaults: the generic device, no SoC, no runtime. Each backend says what it combines with
(EHLS.Runtime.socs/0, a block package's 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).
Summary
Functions
The three backends; raises when they do not combine.
The device backend (a module implementing EHLS.Device).
The directory of a backend's files (Python, C, Erlang) in elixir-hls' priv/backend.
The runtime backend (EHLS.Runtime), or nil.
Functions
The three backends; raises when they do not combine.
The device backend (a module implementing EHLS.Device).
The directory of a backend's files (Python, C, Erlang) in elixir-hls' priv/backend.
The runtime backend (EHLS.Runtime), or nil.
The SoC backend (EHLS.SoC), or nil.