API Reference Elixir HLS v#0.1.0

Copy Markdown View Source

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.