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
endThe 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
@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
The blocks: name => {kind, number of integer arguments}.
@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.
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.
@callback gateware() :: String.t()
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.
@callback peripherals() :: [atom()]
The SoC peripherals an application can ask for with use EHLS, peripherals: [...].
@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>).
@callback soc() :: atom()
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.
@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.