EHLS.Blocks behaviour (Elixir HLS v0.1.0)

Copy Markdown View Source

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):

defmodule MyApp do
  use EHLS, blocks: [EHLS.USBHost, {EHLS.I2S, pins: [dout: "j5:7"]}, EHLS.RPiDisplay35],
    peripherals: [:lcd]

  definstance radio do
    usb_bulk_in() |> ... |> i2s_out()
  end
end

The FPGA side of a package (gateware/0) is what its SoC backend builds, in the form that backend documents (e.g. EHLS.SoC.LiteX); the application's options to the package (use EHLS, blocks: [{Pkg, pins: [...]}]) go to it. A package used with another SoC backend than its own stops the compile.

Summary

Types

kind: :source (first stage, gives a stream), :block (stream in and out), :sink (last stage, takes a stream) or :level (last stage, takes a stream and keeps a level, e.g. hold)

Callbacks

The blocks: name => {kind, number of integer arguments}.

Problems in the application's sources that the compile cannot see, e.g. calls that cannot work: [{file, line, message}]. table is the package's table as in packages.json. They stop mix ehls.compile.

Checks a stage using one of the package's blocks, name and its literal arguments, given the package's table; raises ArgumentError on what cannot be built.

The package's gateware, as its SoC backend names it.

The application's options to the package checked and put in the form its gateware gets; raises on what cannot be built. Without it they go as they are.

The SoC peripherals an application can ask for with use EHLS, peripherals: [...].

The package's registers the CPU reads and writes: name => :r or :w. The runtime reaches them by number (:hw_kernels.reg(gateware, name), the runtime's reg_read/1, reg_write/2), so that a simple block needs no code of its own in the VM. The SoC backend says what a name is in its circuit (LiteX: the CSR <gateware>_<name>).

The SoC backend the package is for (EHLS.SoC.name/0, e.g. :litex).

What a stage using one of the package's blocks changes in the package's table: key => value. They go into packages.json, so :hw_kernels.data/2 and check_sources/2 see them.

From those options, what the package looks up on the CPU: key => value, a tuple of integers and atoms or one of them (:hw_kernels.data(gateware, key); :undefined for another key).

What the package's blocks take and give: name => {in, out}, each a type (:u8, {:s16, :s16}), :any (takes every type) or nil (nothing). A block not named here works on :u32.

The package's sources that can wait: a word stays until it is taken. A stream to the CPU from any other source needs overflow: :drop.

Functions

The packages every module gets besides its own: the SoC backend's built-in blocks (none without a SoC backend).

Types

block()

@type block() :: {:source | :block | :sink | :level, arity :: non_neg_integer()}

kind: :source (first stage, gives a stream), :block (stream in and out), :sink (last stage, takes a stream) or :level (last stage, takes a stream and keeps a level, e.g. hold)

Callbacks

blocks()

@callback blocks() :: %{required(atom()) => block()}

The blocks: name => {kind, number of integer arguments}.

check_sources(files, table)

(optional)
@callback check_sources(files :: [Path.t()], table :: map()) :: [
  {Path.t(), integer(), String.t()}
]

Problems in the application's sources that the compile cannot see, e.g. calls that cannot work: [{file, line, message}]. table is the package's table as in packages.json. They stop mix ehls.compile.

check_stage(name, args, table)

(optional)
@callback check_stage(name :: atom(), args :: list(), table :: map()) :: any()

Checks a stage using one of the package's blocks, name and its literal arguments, given the package's table; raises ArgumentError on what cannot be built.

gateware()

@callback gateware() :: String.t()

The package's gateware, as its SoC backend names it.

options(keyword)

(optional)
@callback options(keyword()) :: term()

The application's options to the package checked and put in the form its gateware gets; raises on what cannot be built. Without it they go as they are.

peripherals()

@callback peripherals() :: [atom()]

The SoC peripherals an application can ask for with use EHLS, peripherals: [...].

registers()

(optional)
@callback registers() :: %{required(atom()) => :r | :w}

The package's registers the CPU reads and writes: name => :r or :w. The runtime reaches them by number (:hw_kernels.reg(gateware, name), the runtime's reg_read/1, reg_write/2), so that a simple block needs no code of its own in the VM. The SoC backend says what a name is in its circuit (LiteX: the CSR <gateware>_<name>).

soc()

@callback soc() :: atom()

The SoC backend the package is for (EHLS.SoC.name/0, e.g. :litex).

stage_table(name, args, table)

(optional)
@callback stage_table(name :: atom(), args :: list(), table :: map()) :: map()

What a stage using one of the package's blocks changes in the package's table: key => value. They go into packages.json, so :hw_kernels.data/2 and check_sources/2 see them.

table(term)

(optional)
@callback table(term()) :: map()

From those options, what the package looks up on the CPU: key => value, a tuple of integers and atoms or one of them (:hw_kernels.data(gateware, key); :undefined for another key).

types()

(optional)
@callback types() :: %{required(atom()) => {term(), term()}}

What the package's blocks take and give: name => {in, out}, each a type (:u8, {:s16, :s16}), :any (takes every type) or nil (nothing). A block not named here works on :u32.

waits()

(optional)
@callback waits() :: [atom()]

The package's sources that can wait: a word stays until it is taken. A stream to the CPU from any other source needs overflow: :drop.

Functions

defaults()

The packages every module gets besides its own: the SoC backend's built-in blocks (none without a SoC backend).