# Elixir HLS v0.1.0 - API Reference

## Modules

- Writing circuits
  - [EHLS](EHLS.md): `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 `if`s for the circuit. Definitions are processed at the end of the module.
  - [EHLS.Agent](EHLS.Agent.md): One state for several lines of an instance, as Elixir's `Agent`: the functions an instance writes with this module.
  - [EHLS.GPIO](EHLS.GPIO.md): 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`).
  - [EHLS.Pipeline](EHLS.Pipeline.md): `definstance`: `defhls` functions and blocks placed in the FPGA, running from reset, the data moving
between them without the CPU.
  - [EHLS.PubSub](EHLS.PubSub.md): Topics: what instances publish and processes or other instances receive, as `Phoenix.PubSub`, written with the module
as it is.
  - [EHLS.Server](EHLS.Server.md): 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`)
  - [EHLS.Stream](EHLS.Stream.md): The functions an instance joins with the pipe, named and taking their arguments as Elixir's `Stream` does.

- Blocks
  - [EHLS.Blocks](EHLS.Blocks.md): 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, `c:EHLS.SoC.blocks/0`, come
along)
  - [EHLS.SoC.LiteX.Blocks](EHLS.SoC.LiteX.Blocks.md): The blocks every LiteX SoC of elixir-hls has (`priv/backend/litex/hls_litex_blocks.py`),
independent of the board

- Building for a board
  - [EHLS.Build](EHLS.Build.md): A build that knows what changed: a target's steps (`c:EHLS.Target.steps/1`) run in order, each only when its inputs
changed since it last ran, or an output is missing.
  - [EHLS.Flash](EHLS.Flash.md): 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.
  - [EHLS.Machine](EHLS.Machine.md): 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`, ...).
  - [EHLS.Project](EHLS.Project.md): The application the Mix tasks build: its name, directory, start module, settings (`config :elixir_hls`) and
target (`EHLS.Target`).
  - [EHLS.Target](EHLS.Target.md): 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.

- Backends
  - [EHLS.Backend](EHLS.Backend.md): The hardware abstraction layer: the backends a build uses, one of each kind.
  - [EHLS.Device](EHLS.Device.md): 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).

  - [EHLS.Device.Generic](EHLS.Device.Generic.md): The generic device: the default delay model and a 12 ns budget.
  - [EHLS.Device.GowinGW5A](EHLS.Device.GowinGW5A.md): 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
  - [EHLS.Runtime](EHLS.Runtime.md): A runtime backend: what the generated functions call on the CPU to use the hardware.
  - [EHLS.Runtime.AtomVM](EHLS.Runtime.AtomVM.md): The AtomVM runtime backend (`priv/backend/atomvm`): the generated functions call the
`:hwstream` NIFs, which drive the LiteX backend's CSRs and DMA.
  - [EHLS.SoC](EHLS.SoC.md): 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`).

  - [EHLS.SoC.LiteX](EHLS.SoC.LiteX.md): The LiteX SoC backend (`priv/backend/litex`). A target's SoC script puts the circuits of
`<out>/hw` into its LiteX SoC with

- Internals
  - [EHLS.MLIR](EHLS.MLIR.md): 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.
  - [EHLS.NIF](EHLS.NIF.md): 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.

## Mix Tasks

- Mix tasks
  - [mix ehls.build](Mix.Tasks.Ehls.Build.md): 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`)
  - [mix ehls.compile](Mix.Tasks.Ehls.Compile.md): 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
  - [mix ehls.console](Mix.Tasks.Ehls.Console.md): Shows the board's console (what the application prints) until interrupted (Ctrl+C twice)
  - [mix ehls.deps](Mix.Tasks.Ehls.Deps.md): 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)
  - [mix ehls.doctor](Mix.Tasks.Ehls.Doctor.md): Checks what a build and a run need on this machine, and says what is missing
  - [mix ehls.flash](Mix.Tasks.Ehls.Flash.md): Writes the board's flash, after `mix ehls.build`
  - [mix ehls.run](Mix.Tasks.Ehls.Run.md): Runs the application on its board
  - [mix ehls.setup](Mix.Tasks.Ehls.Setup.md): 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)
  - [mix ehls.sim](Mix.Tasks.Ehls.Sim.md): 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.

