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.
defmodule Demo do
use EHLS
defhls stream_kernel(x :: u32) :: u32 do
a = signed(x &&& 0xFFFF, 16)
b = signed(x >>> 16, 16)
if a > b, do: a * 3 + b, else: a + b * 2
end
endgenerates
stream_kernel(integer): the function on the CPU, with the argument and result wrapped to their types (u1..u64,s1..s64, tuples), the same results as the hardware;- when
EHLS_OUT_DIRis set at compile time,<kernel>.mlirthere (func + arith, seeEHLS.MLIR) and<kernel>.sig, whichmix ehls.compileturns into SystemVerilog with CIRCT and into the SoC's kernel list. The kernel is named<module>_<function>(kernel_demo_stream_kernel).
Summary
Functions
use EHLS imports defhls / definstance. Options
How the stages of an instance on the CPU run: :beam (the defhls functions as Elixir, in the VM, anywhere) or
:nif (their C, mix ehls.compile --target cpu, as machine code through the runtime's NIF). EHLS_CPU, else
config :elixir_hls, cpu: ..., else :beam.
A function defined with defhls becomes a circuit where definstance places it in the FPGA; that circuit is a kernel.
It takes one element of a stream (a value up to 64 bits, or a tuple of them) and gives one result. The CPU reaches it
by calling the instance it is placed in (calling an instance from the CPU).
definstance: see EHLS.Pipeline.
Elements to a binary in the packed format (packed_size/1), each value wrapped to its type:
what the runtime's pack/2 does in C, written in Elixir to check it against.
The bytes of one element of a stream in a binary at the CPU: each scalar in 1, 2, 4 or 8, the smallest that holds it; a tuple left to right, no padding. A block that takes any type: a word.
Where an instance's stages run unless the stage or the instance says (on: :cpu | :fpga): EHLS_PLACEMENT, else
config :elixir_hls, placement: ..., else :fpga with a backend that makes circuits (a SoC or a device backend,
EHLS.Backend), else default: :cpu (an application runs without an FPGA), :fpga when circuits are being made
(mix ehls.compile). See EHLS.Pipeline, "Placement".
Runs a stateful defhls function on the CPU over a list of inputs from state:
returns {outputs, final state}, like the FPGA does with a stream.
The module the generated code calls to use the hardware: the runtime backend's
(EHLS.Runtime.module/0, EHLS.Backend), nil without one (CPU only: no hardware clauses).
It provides pipe_enable(pipeline_index, on), level_start(level, pipeline, words),
peek(stage, words), end_send/5, end_request/5, end_cancel/1, end_push/3, and pack(list, layout),
unpack(binary, layout) as pack/2 and unpack/2 do; the indices come from the
module :hw_kernels the runtime backend generates.
The low n bits of x as a two's complement signed integer.
A binary in the packed format to its elements, signed values negative, tuples as tuples:
what the runtime's unpack/2 does in C. A binary that is not a whole number of elements raises.
The low n bits of x as an unsigned integer.
Functions
use EHLS imports defhls / definstance. Options:
blocks: [module | {module, options}]: packages of blocks and peripherals (EHLS.Blocks) for the SoC backend in use, besides its built-in ones (EHLS.Blocks.defaults/0); options go to the package's gateware (e.g.pins: [dout: "j5:7"]over its default pins);peripherals: [atom]: SoC peripherals of those packages the application uses (e.g. a LCD).
With EHLS_OUT_DIR set at compile time, <module>.packages (the packages and their options)
and <module>.peripherals go there for the SoC (priv/gen_manifest.py).
How the stages of an instance on the CPU run: :beam (the defhls functions as Elixir, in the VM, anywhere) or
:nif (their C, mix ehls.compile --target cpu, as machine code through the runtime's NIF). EHLS_CPU, else
config :elixir_hls, cpu: ..., else :beam.
A function defined with defhls becomes a circuit where definstance places it in the FPGA; that circuit is a kernel.
It takes one element of a stream (a value up to 64 bits, or a tuple of them) and gives one result. The CPU reaches it
by calling the instance it is placed in (calling an instance from the CPU).
Types:
u1..u64(unsigned),s1..s64(signed) and tuples of them. A kernel's input and output are up to 64 bits: its ports are 32 bits, or 64 when a value of its input or output is wider. State, memories and levels are up to 32 bits, since the CPU reads and sets them in 32-bit words. Tuples hold state and values born together; on a stream they are one element, moving in one clock. On the CPU the arguments and the result are cut to their widths too, so the CPU computes what the circuit does.Expressions:
+ - *,&&& ||| ^^^, shifts (>>>also by an unsigned value), comparisons,and or not,if/else,case,cond, tuples,signed(x, n)/unsigned(x, n)(the low n bits of a value as a signed / unsigned number),Enum.at(@t, i)(a list of integers in a module attribute, looked up as a table).State: a function of the element and a state,
count(x :: u8, n :: u16) :: {u8, u16}, returns{output, next_state}: the shape of the functionStream.transform/3takes. The function itself holds nothing: on the CPU it is a plain function, called with a state. Placed withtransform(init, &f/2), its second argument is the state: it sits in the circuit's registers, starts frominitand changes with every item.A missing output: as in
Stream.transform/3, the output is a list,{[y], s}or{[], s}(at most one element), written{[u8], u16}: a kernel gives no output for some items, e.g. one output for every four inputs (rate changes).Tuples in the state: a state may hold tuples,
{pos, hist} :: {u8, tuple(s16, 8)}(tuple(s16, 8): 8 integers of types16, the same as{s16, s16, ...}), read withelem(hist, i); the next state holds the tuple rewritten withput_elem, as Elixir would. The next state replaces the state whole, so placed withtransformthe tuple is registers. Withmemory: [:hist]where it is placed,histis the FPGA's memory (block RAM): smaller, but one element read or written per clock, and only for a next state made from it withput_elem, from zeros:defhls fir(x :: s16, {pos, hist} :: {u8, tuple(s16, 8)}) :: {s32, {u8, tuple(s16, 8)}} do acc = for k <- 1..3, reduce: x do acc -> acc + elem(hist, (pos - k) &&& 7) end {acc, {pos + 1, put_elem(hist, pos &&& 7, x)}} end x |> transform({0, Tuple.duplicate(0, 8)}, &fir/2, memory: [:hist])In a memory, what
put_elemwrites goes in at the end of the step, as a register takes its next value: everyelemof the step reads the tuple as it came in, and one of a tuple rewritten in the step reads the value written there. On the CPU it is Elixir's tuple; an index out of range is an error, so a ring buffer writes its wrap,(pos - k) &&& 7, which costs no circuit. The circuit does not check the index: out of range it reads or writes something else (a memory is rounded up to a power of two), so keep the index in range, as on the CPU.Levels: after the element (and the state, for
transform), plain arguments are levels: inputs read at each item, given where the function is placed,map(&scale(&1, gain_hw(:value))),transform(0, &volume(&1, &2, gain_hw(:value)))(EHLS.Pipeline, "Instances of levels"), or integers. On the CPU they are plain arguments.caseandcond: a circuit gives a value for every input, so the last clause must match everything:_ ->or a variable,true ->in acond. Patterns are integers, variables,_,^variableand tuples of them, with guards (when). In the circuit every clause is computed and one selected.Several clauses: a function can have clauses with patterns and guards. Each repeats the types, which must be the same, and the last must match everything, as in
case. A function with a memory has one clause.defhls classify(0 :: u8) :: u8 do 200 end defhls classify(x :: u8) :: u8 when x < 16 do x * 2 end defhls classify(x :: u8) :: u8 do x >>> 1 endCalls: a
defhlscan call others of the same module, in any order. This adds no circuit of its own: the body is expanded at each call, so two calls cost two copies. Arguments and result are wrapped to the callee's types, so the CPU gives the same results. Adefhlswith several arguments is placed with the stream as one of them and levels or integers as the others (map(&scale(&1, 3)),EHLS.Pipeline). Functions with a memory or a list as the output cannot be called, and neither can a function call itself.defhls sat16(v :: s32) :: s16 do if v > 32767, do: 32767, else: if(v < -32768, do: -32768, else: v) end defhls mix(a :: s16, b :: s16, k :: u4) :: s16 do sat16(a * k + b) endTable values:
defhlsanddefinstanceare processed together at the end of the module, soEnum.at(@t, i)has the value last set in@t.Loops:
for k <- a..b, reduce:is a loop in the circuit: one copy of the body, used again and again.Enum.reduce(a..b, ...)is unrolled: n copies of the body side by side,ka constant. Unroll for speed, loop for size; both nest.
What cannot become a circuit stops the compile, with a CompileError giving the file and the line of the expression, or
of the call in a definstance. Whether an expression can become a circuit shows when mix ehls.compile builds it.
Stream functions
A defhls can take a stream as well as a single value. This gives a name to functions joined with the pipe, for using them several times.
defhls fir(w :: tuple(s16, 32)) :: s18 do
...
end
defhls lowpass(x :: stream(s16)) :: stream(s18) do
x |> chunk_every(32, 4, :discard) |> map(&fir/1)
end
lowpass([100, -200, 300, 400]) # on the CPU: a list in, a list out
definstance filtered(samples) do
samples |> lowpass() # placed as a circuit
endWhat it holds: the functions of
EHLS.Stream(map,transform,chunk_every, ...) and other stream functions. The body starts with its argument and ends in a stream. Devices and built-in blocks cannot run on the CPU, so they cannot be here. One input and one output, no forks.On the CPU: a list goes through element by element. Elements stay as they are, tuples and signs included; the argument's are wrapped to the type in
stream(type). A function whose output is a list ({[y], s}/{[], s}) orchunk_everymakes the list shorter. So a whole chain can be tested withmix test, without a board; to compare it with the circuit, run an instance using it throughmix ehls.sim.State: on the CPU each call starts from the
transform's initial state. A circuit's state goes on, so results agree from the initial state. To go on computing on the CPU, call the function with state directly, giving it the state.Levels: after the stream, arguments with a type (up to 32 bits) are levels the functions in its pipe take, and the
definstanceplacing it says where each comes from (EHLS.Pipeline, "Instances of levels"):defhls louder(x :: stream(s16), k :: u9) :: stream(s16) do x |> map(&smooth/1) |> map(&scale(&1, k)) end louder([100, 200, 300], 5) # on the CPU: k is 5 for the whole list definstance player(samples) do louder(samples, k_hw(:value)) # in the circuit: scale reads k_hw's result at each value endSo the CPU and the circuit agree while the level does not change. A level can be given on to another stream function,
x |> louder(k), or be an integer where it is placed,louder(samples, 3).Circuit: a stream function is a definition too and makes no circuit. Used in an instance, it is expanded in place. Used twice, there are two circuits, with two states.
Types: the argument's type must widen to the input of the first function in the pipe, and the end of the pipe to the result's type. The rule is that of the links.
Names: what is named inside is named as if placed in the instance directly:
f(:state, :total)(transform(0, &sum/2, name: :total)). A function used twice repeats the names. A function with a named state used twice stops the compile, as the state could not be told.
definstance: see EHLS.Pipeline.
A stream element's type as the runtime's pack/2 and unpack/2 take it: a scalar is its
bits, negative when signed; a tuple is a tuple of those. A block that takes any type: a word.
iex> EHLS.layout({:tuple, [{8, false}, {16, true}]})
{8, -16}
Elements to a binary in the packed format (packed_size/1), each value wrapped to its type:
what the runtime's pack/2 does in C, written in Elixir to check it against.
iex> EHLS.pack([{1, -2}, {300, 70000}], {8, -16})
<<1, 254, 255, 44, 112, 17>>
The bytes of one element of a stream in a binary at the CPU: each scalar in 1, 2, 4 or 8, the smallest that holds it; a tuple left to right, no padding. A block that takes any type: a word.
iex> EHLS.packed_size({12, true})
2
iex> EHLS.packed_size({:tuple, [{8, false}, {32, true}]})
5
Where an instance's stages run unless the stage or the instance says (on: :cpu | :fpga): EHLS_PLACEMENT, else
config :elixir_hls, placement: ..., else :fpga with a backend that makes circuits (a SoC or a device backend,
EHLS.Backend), else default: :cpu (an application runs without an FPGA), :fpga when circuits are being made
(mix ehls.compile). See EHLS.Pipeline, "Placement".
Runs a stateful defhls function on the CPU over a list of inputs from state:
returns {outputs, final state}, like the FPGA does with a stream.
The module the generated code calls to use the hardware: the runtime backend's
(EHLS.Runtime.module/0, EHLS.Backend), nil without one (CPU only: no hardware clauses).
It provides pipe_enable(pipeline_index, on), level_start(level, pipeline, words),
peek(stage, words), end_send/5, end_request/5, end_cancel/1, end_push/3, and pack(list, layout),
unpack(binary, layout) as pack/2 and unpack/2 do; the indices come from the
module :hw_kernels the runtime backend generates.
The low n bits of x as a two's complement signed integer.
A binary in the packed format to its elements, signed values negative, tuples as tuples:
what the runtime's unpack/2 does in C. A binary that is not a whole number of elements raises.
iex> EHLS.unpack(<<1, 254, 255, 44, 112, 17>>, {8, -16})
[{1, -2}, {44, 4464}]
The low n bits of x as an unsigned integer.