EHLS.Backend (Elixir HLS v0.1.0)

Copy Markdown View Source

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

kindactsbackends
device (EHLS.Device)inside the compile: where buffers go in a circuit, from the FPGA's estimated delays and a budgetgeneric (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, blocksnone (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 hardwarenone (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:

filecontents
<kernel>.sva 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.vthe kernel's tables and memories (one address space module)
<kernel>.sigJSON: 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.jsonthe 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.

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

Functions

check!()

The three backends; raises when they do not combine.

device()

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

priv(name)

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.