EHLS (Elixir HLS v0.1.0)

Copy Markdown View Source

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
end

generates

  • 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_DIR is set at compile time, <kernel>.mlir there (func + arith, see EHLS.MLIR) and <kernel>.sig, which mix ehls.compile turns 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).

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.

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

__using__(opts)

(macro)

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

cpu_code()

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.

defhls(head, list)

(macro)

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 function Stream.transform/3 takes. The function itself holds nothing: on the CPU it is a plain function, called with a state. Placed with transform(init, &f/2), its second argument is the state: it sits in the circuit's registers, starts from init and 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 type s16, the same as {s16, s16, ...}), read with elem(hist, i); the next state holds the tuple rewritten with put_elem, as Elixir would. The next state replaces the state whole, so placed with transform the tuple is registers. With memory: [:hist] where it is placed, hist is the FPGA's memory (block RAM): smaller, but one element read or written per clock, and only for a next state made from it with put_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_elem writes goes in at the end of the step, as a register takes its next value: every elem of 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.

  • case and cond: a circuit gives a value for every input, so the last clause must match everything: _ -> or a variable, true -> in a cond. Patterns are integers, variables, _, ^variable and 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
    end
  • Calls: a defhls can 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. A defhls with 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)
    end
  • Table values: defhls and definstance are processed together at the end of the module, so Enum.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, k a 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
end
  • What 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}) or chunk_every makes the list shorter. So a whole chain can be tested with mix test, without a board; to compare it with the circuit, run an instance using it through mix 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 definstance placing 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
    end

    So 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(head, list)

(macro)

definstance: see EHLS.Pipeline.

definstance(head, opts, list)

(macro)

layout(arg1)

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}

pack(elements, layout)

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

packed_size(arg1)

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

placement(default \\ :cpu)

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".

run_cpu(fun, inputs, state)

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.

runtime()

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.

signed(x, n)

The low n bits of x as a two's complement signed integer.

unpack(bin, layout)

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}]

unsigned(x, n)

The low n bits of x as an unsigned integer.