Modules
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 ifs for the circuit. Definitions are processed at the end of the module.
One state for several lines of an instance, as Elixir's Agent: the functions an instance writes with this module.
The hardware abstraction layer: the backends a build uses, one of each kind.
A package of blocks for definstance (sources, sinks, fixed stream functions in
the FPGA) and of SoC peripherals, e.g. a board's I/O, for one SoC backend (soc/0). A
module of the package implements this behaviour; an application names it in
use EHLS, blocks: [...] (the SoC backend's built-in ones, EHLS.SoC.blocks/0, come
along)
A build that knows what changed: a target's steps (EHLS.Target.steps/1) run in order, each only when its inputs
changed since it last ran, or an output is missing.
A device backend: the FPGA family. It acts inside the compile: the buffers cut a kernel's combinational paths where its estimated delay exceeds the budget (priv/pipeline_buffers.py).
The generic device: the default delay model and a 12 ns budget.
Gowin GW5A (Arora V, e.g. the Tang Primer 25K's GW5A-LV25). Besides the compile settings,
priv/backend/gowin has what a build with Gowin's tools uses
The record of what a board's flash holds: for each part (:vm, :lib, ...) the hash of the file last written
there by mix ehls.flash or mix ehls.run. A board is told apart by its target and its port (the machine's
uart_port, if the target has one), so one record serves every application on the machine: an AtomVM written
for another application's SoC is seen as not matching.
Pins read and written from Elixir: generic, knowing no board; a block package of the LiteX SoC
backend (FPGA side: priv/backend/litex/ehls_gpio.py).
Translates the body of a defhls function (an Elixir AST) into MLIR (func + arith + cf +
memref) for CIRCT hlstool --dynamic-hw. Host-only: used by the defhls macro at compile
time.
The machine's settings, which differ from one computer to the next and stay out of what is committed: where
CIRCT is (CIRCT_BIN), and the target's own (on the Tang Primer 25K GOWIN_HOME, UART_PORT, ...).
A defhls function as a NIF: its C, built into the runtime and run on the CPU as machine code, outside the VM,
instead of as a circuit or as Elixir in the VM (cpu: :nif; NIF: a Native Implemented Function, as Erlang calls a
function the VM calls but does not run itself). The C is checked on the host before it becomes one.
definstance: defhls functions and blocks placed in the FPGA, running from reset, the data moving
between them without the CPU.
The application the Mix tasks build: its name, directory, start module, settings (config :elixir_hls) and
target (EHLS.Target).
Topics: what instances publish and processes or other instances receive, as Phoenix.PubSub, written with the module
as it is.
A runtime backend: what the generated functions call on the CPU to use the hardware.
The AtomVM runtime backend (priv/backend/atomvm): the generated functions call the
:hwstream NIFs, which drive the LiteX backend's CSRs and DMA.
A process that owns an instance, for an application with a supervision tree. definstance declares the circuit; this is
the runtime face a program uses to own one, where it wants one (as Ecto.Repo is beside Ecto.Schema)
A SoC backend: builds the circuits (<out>/hw: kernels.json, pipelines.json,
packages.json, peripherals.json) into a system on chip with its control bus and DMA, and
provides the blocks every SoC of its kind has. Its build code lives in
priv/backend/<name> (EHLS.Backend.priv/1).
The LiteX SoC backend (priv/backend/litex). A target's SoC script puts the circuits of
<out>/hw into its LiteX SoC with
The blocks every LiteX SoC of elixir-hls has (priv/backend/litex/hls_litex_blocks.py),
independent of the board
The functions an instance joins with the pipe, named and taking their arguments as Elixir's Stream does.
A board an application runs on, as the Mix tasks see it (mix ehls.build, mix ehls.run, mix ehls.flash,
mix ehls.console, mix ehls.doctor, mix ehls.setup): the tasks are elixir-hls', the work is the target's.
Mix Tasks
Builds the application for its target's board: the target's steps (on the Tang Primer 25K the circuits, the SoC,
AtomVM and the application's pack), each only when its inputs changed since it last ran (EHLS.Build)
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
Shows the board's console (what the application prints) until interrupted (Ctrl+C twice)
Prints one line per dependency of the current project, name directory, for a target's
scripts to find the packages, the target and elixir-hls wherever Mix put them (deps/
after mix deps.get, or the directory of a path: dependency)
Checks what a build and a run need on this machine, and says what is missing
Writes the board's flash, after mix ehls.build
Runs the application on its board
Sets up, once for the machine, what the target's builds need and the dependencies do not bring as they are (on the Tang Primer 25K the base atomvm-tang25k: its LiteX, AtomVM and host tools, some tens of minutes)
Compiles like mix ehls.compile, which checks each kernel by itself, then checks the instances:
consecutive defhls stages with what is between them, from random words into the first to
the words out of the last, in iverilog against the same stages run by Elixir, with random gaps
between the inputs given and between the outputs taken, as in a real circuit. No board and no LiteX.