EHLS.Pipeline (Elixir HLS v0.1.0)

Copy Markdown View Source

definstance: defhls functions and blocks placed in the FPGA, running from reset, the data moving between them without the CPU.

An instance places defhls functions and blocks in the FPGA: one function alone, or, as anywhere in Elixir, several joined with the pipe (|>). The data flows through them in the pipe's order inside the FPGA without passing through the CPU. It runs from reset, so the program on the CPU only changes its levels and reads its state.

use EHLS, blocks: [EHLS.I2S]

definstance tone do
  ticks(48_000) |> tone_wave() |> i2s_out()
end

Here ticks gives an item 48,000 times a second, tone_wave (a defhls function) turns it into a sample of a waveform and i2s_out plays it over I2S.

  • What can be placed:

    • f(): a defhls function as it is; a stream function works the same. As in Elixir, a call taking the stream as its first argument is the same as the pipe: f(words) is words |> f().
    • the functions of EHLS.Stream, as Elixir's Stream has them: map(&f/1), filter(&f/1), transform(init, &f/2), zip_with(a, b, &f/2), chunk_every(n, k, :discard) |> map(&f/1) and run(), written with or without the module. Each says there what it places.
    • map(&f(&1, k_hw(:value))), or f(k_hw(:value)) in the pipe: a function of several arguments, the stream as one of them, each other argument an integer or a level (see "Instances of levels").
    • transform(init, &f/2) places a function of the element and a state; with name: n, f(:state, n) reads the state while it runs, and a state without a name has no circuit for reading it.
    • blocks (below).
  • Items: stream items can be tuples.

  • Two streams into one function: zip_with(a, b, &f/2) takes one element of each, together, as Elixir's Enum.zip_with does, and gives f(x, y); the call form f(a, b) with both arguments streams is the same, and so is a |> zip_with(b, &f/2) or a |> f(b) in a pipe. A join can be anywhere in the body, and each of a, b an argument of the instance, a pipe from one or from a source, or a join:

    defhls mix(a :: s16, b :: s16) :: s17 do
      a + b
    end
    
    definstance mixer(left, right) do
      zip_with(left, right, &mix/2) |> map(&half/1)     # or mix(left, right) |> map(&half/1)
    end
    
    mixer([1, 2, 3], [10, 20, 30])                     # two lists in, one out
    
    definstance three(a, b, c) do
      a |> mix(b) |> half() |> mix(c |> neg()) |> half()   # (a, b) joined, then with -c
    end

    The circuit is a join (it moves on when both inputs have an element) and a kernel of the pair, <f>__zip. Each input is a CPU end of its own (a DMA engine): mixer(l, r) gives them all at once, as many elements each (else :badarg), and mixer(:send, :right, data) one of them.

  • Naming a stream, and a fork: a body can have several expressions. y = ... names the stream an expression gives; a name used twice is a fork: every element goes to each branch, and the fork moves on once every branch took it (no buffer: a slow branch holds the others back). Only the last expression goes to the CPU; one before it ends in something taking the stream away (a sink):

    definstance tapped(x) do
      y = x |> map(&smooth/1)
      y |> map(&low16/1) |> hold(:last)      # one branch into a sink
      y |> map(&scale(&1, 3))               # the other, the instance's output
    end

    A fork joined again (y |> mix(y |> map(&g/1))) works as long as the branches' delays are close: a branch that gives nothing for many elements (chunk_every, a function with a list as output) would need a buffer where they meet, not there yet. An argument goes in once; to use it twice, name what it gives (y = x |> f()).

  • An instance called inside an instance: an instance exists once, so calling it in another wires to it: the stream before goes into its input, its output comes out here, and neither is a CPU end. An instance of another module is written Other.fir_hw(); it is found when the circuits are put together (mix ehls.compile), which checks that it is in the build, called once, and that the types keep their values.

    definstance fir_hw(x) do
      x |> map(&fir/1)
    end
    
    definstance player(samples) do
      samples |> map(&gain/1) |> fir_hw() |> map(&clip/1)
    end

    Called as a statement (y |> pilot_hw()), its output stays its own, read with its own calls. It can be stopped and started by itself; while it is stopped, the stream through it stands still. For now a function comes between an argument and the call, and after the call when it is the last expression (their types come from the instance called); and what comes back after a call is of a size the compile cannot tell, so a call from the CPU says it: player(samples, out: n).

  • What can be wired: an instance starts with a source or with an argument (a stream from the CPU). It ends with something that takes the stream away (i2s_out(), hold(name), ...), or with a stream, which then goes back to the CPU. A first function with nothing to read stops the compile, because it would stand still without an input. So does a level wired to a stream input: a level fires nothing, and turning one into a stream is a decision about when to read it (sample(pin)).

  • Types at the links: the output of a function in the pipe and the input of the next one must agree. A widening that keeps the value (u8 to u16, u8 to s16, s16 to s18) goes as it is; narrowing or changing the sign would change the value and stops the compile. If you mean it, put a function in between (map(&low/1)). Blocks' types are declared by their packages (usb_bulk_in() gives u8, sample(pin) u1, ticks(rate) u32; hold and run take any type).

  • Generated functions: tone(:value, name) (the level of a hold(name)), tone(:stop), tone(:start) (stop, and go on from the initial state), tone(:state, n) (read the state of transform(.., name: n); its words are taken at one clock, so they cannot tear). A value the CPU changes while it runs is an instance of levels wired into it (below).

Placement: the CPU or the FPGA

An instance goes to the FPGA where there is one, and runs on the CPU where there is none, so the same application works on a board and on a computer without an FPGA. Where a stage runs is the first of: the stage's on: :cpu | :fpga, the instance's (definstance radio(iq), on: :fpga do ... end), the application's config :elixir_hls, placement: ... (or EHLS_PLACEMENT), then :fpga when a backend that makes circuits is configured (a SoC or a device backend, EHLS.Backend) or circuits are being made (mix ehls.compile, mix ehls.sim), else :cpu (mix test, iex -S mix on a computer).

An instance on the CPU is a process, started at its first call, that keeps each stage's state between calls; its stages run as the defhls functions do on the CPU, or, with config :elixir_hls, cpu: :nif (EHLS_CPU=nif) and a runtime backend's NIF, as their C (mix ehls.compile --target cpu): the elements packed once per pipe and run through the kernels in chunks, the same results. It takes the same calls as one in the FPGA: radio(list) (a list out), radio(binary) (the packed format out), radio(data, as: :list | :binary, timeout: ms), radio(:start) (from the initial states) and radio(:stop) (calls answer {:error, :stopped} until the next start). So mix test runs an application's instances on the computer, without a board.

Its stream comes from its argument or from ticks(rate) (a timer in the process, from its start; then radio(:out, n) waits for the next n elements, radio(:request, :out, n) sends {radio, :out, binary}; with buffer: elements waiting the timer waits too, as overflow: :wait, or with overflow: :drop goes on and what does not fit is dropped). An instance with a source starts with radio(:start) (reading it does not start it); a stage that fails under it stops it, and what waits for it is answered {:error, :stopped}. It may end in hold(h) (radio(:value, h)) or run(); radio(:state, n) reads transform(.., name: n). An instance of levels on the CPU (definstance gain(k :: u8), initial: 3 do k end) computes its body at each call and holds the result: gain(5), gain(5, wait: false), gain(:value); a level wired into a stage (map(&scale(&1, gain(:value)))) is read once per call.

The body is what it is in the FPGA: joins (zip_with(a, b, &f/2), f(a, b), anywhere), a stream named and used twice (a fork), several expressions, the ones before the last ending in a sink. With several arguments the call takes one list or binary for each, mixer(left, right); what one side of a join has more waits for the next call, as in a circuit. Not yet on the CPU: blocks other than ticks, hold and run, instances called inside, a pin's level, and an on: :fpga stage inside; they stop the compile, saying to place the instance in the FPGA.

Stages on the CPU

A stage that does not fit in the FPGA runs on the CPU, as C (mix ehls.compile --target cpu, EHLS.NIF), and the instance is cut there:

definstance radio(iq) do
  iq |> map(&channel/1) |> map(&big_filter/1, on: :cpu) |> map(&post/1)
end

This is two instances of the FPGA, radio__pre (up to the stage; its stream goes to the CPU) and radio__post (from the stage on; its stream comes from the CPU), with CPU ends like any instance, and a process on the CPU between them. radio(:cpu_start, opts) starts it (the pid is returned) and radio(:cpu_stop, pid) stops it. The process asks radio__pre for a batch, runs it through the NIF in chunks (so that the VM's other processes keep running) and gives the result to radio__post; it asks for the next batch while it works on this one. opts: batch: (elements per request, 256), chunk: (elements per call of the NIF), levels: (a function of the kernel giving its level arguments), to: (a pid: where the results go when the stage is the last one, as {radio, :out, binary}), timeout: (ms, 5000).

A stage with state is transform(init, &f/2, on: :cpu): the NIF starts from init (a literal, as anywhere) and the driver keeps the state between batches; it takes no name:, since no circuit holds the state to read.

Several stages can be on: :cpu. Those that follow each other run in one process, one after the other on each batch; an FPGA stage between two of them is an instance of its own (radio__1, radio__2, ..., the last one radio__post) with a process on each side. radio(:cpu_start, opts) then returns a list of pids, one for each run of CPU stages, and radio(:cpu_stop, pids) takes it. There has to be an FPGA stage before the first (the argument alone is not enough: call EHLS.NIFRun from the CPU then). A function's other arguments are given where it is placed, as in the FPGA: map(&volume(&1, gain(:value)), on: :cpu), transform(init, &f(&1, &2, 3), on: :cpu), each an integer or an instance of levels (Other.gain(:value) for another module's); an integer goes into the kernel made for it, and the driver reads a level before each batch, as the CPU reads it. Not yet: an instance of levels that is itself on the CPU, and a pin's level. levels: (a function of the kernel, :"Module.function", giving its level arguments) says otherwise. Across the cut the stream is packed bytes, so the types must be the same, not just widening as inside the FPGA (u8 into u16 changes the size of an element): the compile stops where a defhls function on each side says otherwise, and a map between them changes a type. A source that cannot wait for the CPU (a pin's changes, usb_bulk_in) needs overflow: :drop on the definstance, as for any stream to the CPU: a CPU stage slower than the source loses elements instead of stopping it. radio(:cpu_stats, pids) tells how busy each driver was, to see whether the CPU keeps up. The two instances take their definstance options (overflow:, buffer:) on radio__pre, the part that sends to the CPU.

Blocks

A block is what can be placed in a definstance without being written with defhls. A defhls must also run on the CPU, so what cannot run there can only be written in a definstance. There are two kinds.

KindWhat it isExamples
devicea block with physical pins: the real thing is behind them, and the CPU cannot run iti2s_out(), usb_bulk_in(), changes(pin, edge), sample(pin), pin_out(pin)
built-in blockno pins, but tied to the circuit's time or to the exchange with the CPUticks(rate), hold(name), run()

Built-in blocks belong to the SoC backend and come without being named. Devices come in packages: modules implementing EHLS.Blocks (soc/0, blocks/0, peripherals/0, gateware/0; if needed waits/0, types/0, registers/0, options/1, table/1), each for one SoC backend.

use EHLS, blocks: [Pkg, {Pkg2, pins: [...]}], peripherals: [:lcd]

pins: moves a package's default pins. peripherals: adds circuits the CPU uses directly (a display, say) rather than placed in an instance.

Levels, events and streams

What passes between the CPU and the FPGA is one of three kinds, and the kind decides how a program uses it. The test is whether overwriting hurts: an LED needs only its latest state, but an audio stream with a value missing clicks.

kindwhat mattersexampleson the CPU
levelonly the latestan LED, a switch's position, a gain, a kernel's statea plain function call, no process
eventeach one, and they are rarea button presseda message to each process that subscribed (below)
streamevery value, in orderaudio samples, IQinside the FPGA without the CPU, or an instance called as a function

Levels come from two owners. An instance owns its kernels' levels, a block package the levels of its device, with no instance involved:

gain_hw(32)                  # CPU -> kernel: an instance of levels wired into it, taken from the next input on
radio(:state, :level)        # kernel -> CPU: the state of the transform named :level
EHLS.GPIO.write(:led0, 1)    # CPU -> device
EHLS.GPIO.read(:button0)     # device -> CPU

A state of several words is taken at one clock, so its words always belong together, even while the instance runs.

Events

An event is something rare of which each one matters. An instance publishes events under a topic (an atom), as Phoenix.PubSub does: each element that goes into EHLS.PubSub.broadcast(topic) is one event. A process receives them with EHLS.PubSub.subscribe(topic), as messages {topic, value}:

definstance presses do
  changes(:button0, :rising) |> transform(0, &count/2) |> EHLS.PubSub.broadcast(:presses)
end

EHLS.PubSub.subscribe(:presses)                   # in a GenServer's init/1, say

def handle_info({:presses, n}, st), do: ...
  • Unlike a stream, the publisher does not know who receives, and never waits: it has a small FIFO of its own, and an event that does not fit is counted, not held back. Any number of processes can subscribe to a topic (up to 4 at once today), and each gets every event.

  • From the subscription on: events nobody subscribes to are dropped as they come, so a subscriber does not get what happened before.

  • Order: every publisher's events go into one queue in the FPGA in the order they come, with the time each came. One interrupt drains it into the driver, which sends the messages.

  • As a socket: EHLS.PubSub.subscribe(topic, active: :once) gives the next event and keeps the ones after (16 at most, the rest counted, {:ehls_lost, topic, n}) until the process subscribes again; active: n the next n. timestamps: true gives {topic, value, t}, t when the event came in the FPGA, on the clock of :erlang.monotonic_time(:microsecond). See EHLS.PubSub.subscribe/2.

  • A topic's events are one value up to 32 bits, of one type for all its publishers; topics are numbered when the circuits are put together (mix ehls.compile).

  • broadcast is a sink: before the last expression, it lets an instance publish what it also uses (y |> EHLS.PubSub.broadcast(:level) beside y |> map(...)).

  • In another instance, the same EHLS.PubSub.subscribe(topic) is a source of the topic's events: every event of each publisher, in its order. Each subscribing instance has a small FIFO per publisher; what does not fit while it stands still is counted, and the publisher is not held back. So it is a source that cannot wait: a stream from it to the CPU says overflow: :drop. Its type is the topic's, checked when the circuits are put together against what takes it.

    definstance doubler do
      EHLS.PubSub.subscribe(:presses) |> map(&dbl/1) |> EHLS.PubSub.broadcast(:doubled)
    end
  • A value made events: changes(k_hw(:value)) is a source giving the new value each time an instance of values changes (Other.k_hw(:value) for another module's); with filter(&f/1) only some of them:

    definstance watcher do
      y = changes(k_hw(:value))
      y |> EHLS.PubSub.broadcast(:k)
      y |> filter(&big?/1) |> EHLS.PubSub.broadcast(:big)
    end

    It cannot wait: a change not taken yet is replaced by the next one.

A pin's changes are events too, written in an instance: changes(:button0, :both) |> EHLS.PubSub.broadcast(:button0), each edge with its kind and time. One state updated by several kinds of events is an agent (below).

Planned: a level read at a rate as a stream, so that it can be processed in the FPGA (e.g. the average of the FM radio's audio level).

One state for several lines: an agent

A function with state placed with transform has a state of its own. When several kinds of elements must update one state (a value set from one place and counted on from another, events of two topics into one count), the state is an agent, EHLS.Agent, written as Elixir's Agent is:

defhls set_n(k :: u16, _n :: u16) :: {u16, u16} do
  {k, k}
end

defhls inc_n(_tick :: u32, n :: u16) :: {u16, u16} do
  {n + 1, n + 1}
end

definstance panel do
  {:ok, n} = EHLS.Agent.start_link(0, name: MyApp.Count)
  changes(k_hw(:value)) |> EHLS.Agent.update(n, &set_n/2)                    # the state only
  ticks(200) |> EHLS.Agent.get_and_update(n, &inc_n/2) |> EHLS.PubSub.broadcast(:count)  # an output too
end

EHLS.Agent.get(MyApp.Count, & &1)                        # the state, from the CPU (an agent with a name)
  • {:ok, n} = EHLS.Agent.start_link(initial) is one state; x |> EHLS.Agent.get_and_update(n, &f/2) takes each element through f(x, state), which gives {output, next_state} (as for transform), its output going on; x |> EHLS.Agent.update(n, &f/2) the same, ending the pipe. Called as functions they are Agent's (EHLS.Agent).
  • A name: EHLS.Agent.start_link(initial, name: MyApp.Count) (a module name, as an Agent's), and the CPU reads it with EHLS.Agent.get(MyApp.Count, & &1), as Agent.get/2.
  • One update at a time: the functions of an agent take its state in turn, one element at a time, in the order the elements come (in turn among those that come at once); each sees the state the one before left. Their states must be of one type, and the agent's initial value is theirs.
  • Placed, the state is the agent's register in the circuit, not a process, and only defhls functions update it. On the CPU (an instance placed there) the lines of an agent run one after the other within a call. Not yet: EHLS.Agent.get(n) in an instance (the state wired into other functions as a level), and an agent's functions as C (cpu: :nif).

Calling an instance from the CPU

An instance can be written as a function: its argument is a stream from the CPU, and the stream of the end of the pipe goes back to the CPU. The body runs in the FPGA.

defhls gray(x :: u32) :: u32 do
  (((x >>> 16) &&& 0xFF) * 77 + ((x >>> 8) &&& 0xFF) * 150 + (x &&& 0xFF) * 29) >>> 8
end

definstance gray_accel(pixels) do
  pixels |> map(&gray/1)
end

gray(0x123456)              # one value, computed on the CPU
gray_accel([0x123456, 0xABCDEF])   # a list in, a list out, through the circuit in the FPGA
gray_accel(pixels)          # a binary in, a binary out

The name tells where it runs: gray is a function, gray_accel a circuit. mix ehls.compile checks each kernel against its function, so the results are the same. To keep this visible, an instance cannot have the name of a defhls of the same module.

A circuit is always running. A call hands data to it and takes what comes out. An instance with an argument just waits for its input until it is called.

An instance that ends in a stream gets the circuit for the CPU to read it, as a function's last expression is its result. One that ends in something taking the stream does not. The CPU can be at one end only.

definstance player(samples) do          # the CPU only gives
  samples |> map(&volume/2) |> i2s_out()
end

definstance iq, overflow: :drop do      # the CPU only takes
  usb_bulk_in()
end

player(samples)      # :ok
iq(:out, 16384)      # 16384 elements: bytes, usb_bulk_in gives u8
InstanceCallReturns whenReturns
an argument, ends in a streamf(data)the output of data has arrivedwhat data is: list or binary
f(data, out: n)n elements have arrivedwhat data is
an argument, ends in something taking the streamf(data)the DMA has read data:ok
an argumentf(:in, data)the DMA has read data:ok
ends in a streamf(:out, n)n elements have arrivedbinary
f(:out, n, as: :list)n elements have arrivedlist
  • A list or a binary: data is a list of elements or a binary of them packed. A list gives a list back, a binary a binary; as: :list or as: :binary says otherwise. The circuit is the same: a list is packed on the CPU before the DMA reads it, and the output unpacked after it has arrived, in C (hwstream:pack/2, unpack/2). In a list a tuple is a tuple and a signed value is negative, as with a stream function on the CPU, so a test can compare the two directly; values going in are wrapped to the input's type. A binary costs no conversion, and holds more in less memory: 16384 u8 are 16 KB as a binary and 128 KB as a list on AtomVM.

  • Sizes count elements: f(:out, n), out:, buffer: and :request are numbers of elements of the stream, whatever its type.

  • In a binary elements are packed by one rule: each scalar in 1, 2, 4 or 8 bytes, the smallest that holds it, little-endian; a tuple left to right, no padding. A binary that is not a whole number of elements raises.

    ElementBytesIn Elixir
    u81<<b>>
    s162<<x::little-signed-16>>
    s184<<x::little-signed-32>>
    {s16, s16}4<<l::little-signed-16, r::little-signed-16>>
    {u8, s16}3<<b, x::little-signed-16>>
    {s18, s20}8<<a::little-signed-32, b::little-signed-32>>

    Going in, a kernel takes the low bits its type has. Coming out, a value is widened to its bytes as its type says (s18 by sign, u12 by zeros). A block that declares no type works on u32.

  • The size of the output: f(bin) takes the size the functions in the pipe tell: map and transform as many elements as the input has, chunk_every(n, k, :discard) with k >= n 1/k; overlapping chunks (chunk_every(n, k, :discard), k < n) begin after the first n, which they cannot tell across calls. Through a function whose output is a list ({[y], s}) or a block they cannot tell, so out: is needed; without it the call raises :out_size_needed at once.

  • Waiting: only the calling process waits. It is a receive, so the other Erlang processes keep running. :ok says the input has been read from memory, not that they have gone through the instance: sound still has to come out of the speaker.

  • Call from a process that holds little: on AtomVM a call costs the calling process a few collections, each copying its whole heap. 64 KB took about 400 ms from a process holding a list of 16,384 integers, against 7 ms from one holding only the binary. Keep large data in binaries, which live outside the heap, or make the call from another process.

  • Calling in sequence: f(:in, bin) and then f(:out, n) in one process stand still with an input larger than what the circuit can hold, as nobody reads the output, and time out. Use f(bin), which moves both at once, or the messages below.

  • State: the state goes on across calls, so one signal can go through a filter as several binaries. f(:stop) and then f(:start) start again from the initial state, dropping what the links and the buffer hold. An application replaced without resetting the FPGA finds the previous state, and calls them first if that matters.

  • Errors: three exceptions. :busy when a transfer is in progress on that end, :stopped when the instance is stopped, :timeout after 5 seconds, which timeout: ms changes; a transfer that timed out is cancelled. Slow sources take their time: 1024 elements from ticks(10) take about 100 s.

  • Size of the circuit: each end towards the CPU adds a DMA engine. mix ehls.compile lists them. The engines share one port to the memory for reading and one for writing, taking turns: an end standing still holds up no other, and ends moving at once share the memory's bandwidth.

Instances of levels

An instance whose arguments have types takes levels and gives a level: values of which only the latest matters, not streams. A call writes the arguments; the circuit computes once and holds the result until the next call.

defhls gain_of(volume :: u4) :: u9 do
  volume * 32
end

definstance gain_hw(volume :: u4), initial: 96 do
  gain_of(volume)
end

definstance k_hw(v :: u9), initial: 3 do     # a value the CPU writes, given back as it is
  v
end

gain_hw(:value)              # 96: the result held now, initial: until the first call
gain_hw(5)                   # 160: writes 5, waits for that write's result
gain_hw(5, wait: false)      # :ok: writes only
  • The body is one of the arguments, a tuple of them, or a call of a defhls function of the module without state (gain_of(volume), mix(a, b)): a function of several arguments can be placed this way. It becomes one kernel, <name>__level, checked by mix ehls.compile as any other.
  • initial: is the result before the first call and after a :start: a literal of the result's type, cut to it; 0 (a tuple of zeros) when not given.
  • What the circuit does: the arguments' words are written one by one, then a start write takes them all in the same clock, so a call never computes with half of them. A call made while the circuit computes waits for it to end; only the latest one is computed, as only the latest value of a level counts. The result and the number of the call it is for are read together, so gain_hw(5) gives the result of its own write, whatever another process writes meanwhile. A call takes a few milliseconds on AtomVM, almost all of it in the CPU.
  • Errors: :stopped when the instance is stopped (gain_hw(:stop); the result stays the last one meanwhile), :timeout after 5 seconds without the result (timeout: ms).
  • Widths: each argument and the result up to 64 bits, tuples too.
  • mix ehls.sim checks an instance of levels as the CPU calls it.

A level wired into a function placed in a stream. Inside a definstance, the same expression the CPU reads a level with is the wire to it:

defhls scale(x :: s16, k :: u9) :: s16 do
  x * k
end

definstance scaler(words) do
  words |> map(&scale(&1, k_hw(:value)))     # or scale(words, k_hw(:value)), the stream first
end

k_hw(5)            # scaler multiplies by 5 from the next value on

The kernel reads the level when it takes a value, and a level changing fires nothing. On the CPU scale(x, 5) is a plain function, so the CPU and the circuit agree while the level does not change. An argument can also be an integer, map(&scale(&1, 3)), or a pin's level, map(&scale(&1, EHLS.GPIO.read(:switch0))) (u1; an out pin gives what is written to it). An instance of another module, Other.k_hw(:value), is found when the circuits are put together (mix ehls.compile): it must be in the same build. The level's type must keep its values in the argument's (u8 into u9, not u16), and it is one value, up to 32 bits. What is placed is a kernel of one argument, <f>__<argument>_<l or c..>, one per way of placing it, checked by mix ehls.compile at the level's initial: value.

A stream function can take levels too, given where it is placed: louder(samples, k_hw(:value)) (EHLS.defhls/2, "Stream functions").

Not there yet: levels and a stream in one instance; a level wired into a function with a state.

Until it is read

A circuit runs from reset, so data flows before the CPU reads. A read gives what has gathered, oldest first, not what comes after the call. For fresh data, call f(:stop) and f(:start) first.

buffer: says how much gathers: a FIFO in block RAM before the output, in elements. Without it, only the few elements in the links. SDRAM is not used for this, since it only works once the CPU has initialized it.

definstance logger, buffer: 4096 do
  ticks(1000) |> sample(:button0) |> transform({0, 0}, &debounce/2)
end

logger(:out, 4096)

overflow: says what happens when nobody takes a value and no room is left.

overflow:DoesFor
:wait (default)the stream stands still, no value is lost; the functions before it in the pipe wait toosources that can wait, like ticks
:dropthe stream goes on, new values are lostsources that cannot, like usb_bulk_in(), changes(...)

A stream from a source that cannot wait needs overflow: :drop written out when it goes to the CPU, or the compile stops. With overflow: :drop, values between two reads that do not fit in the buffer are lost; the values of one read are consecutive.

Saying there is no output

Since an instance ending in a stream gets a circuit to read it, a forgotten sink is no error: the list from mix ehls.compile shows it. To read only state with f(:state, ...), end with run(), a block that takes the stream and does nothing with it.

definstance counter do
  changes(:button0, :rising) |> transform(0, &count/2) |> run()
end

Calling with messages

To keep the stream going while doing something else, or to have the next input ready while the output is on its way, ask for the same transfers with messages. An end is named by the argument's name, or :out.

gray_accel(:request, :out, 4096)    # {:gray_accel, :out, binary} once 4096 elements have arrived
gray_accel(:send, :pixels, input)   # {:gray_accel, :pixels, :sent} once input has been read

def handle_info({:gray_accel, :out, chunk}, st) do
  gray_accel(:request, :out, 4096)
  {:noreply, handle(chunk, st)}
end

As with an active: :once socket, messages go to the process that asked. An end takes one more transfer while one is in flight (a :request while one is being written, a :send while one is being read), started the moment the first is done, so that the stream goes on without waiting for the program; beyond that {:error, :busy}. Each answers with its own message, in order. A stopped instance answers {:error, :stopped}. f(:stop) cancels what is in flight, and no message follows. The output's name is :out, so an argument cannot be called out.

One element at a time, as a value comes (a key pressed, a reading taken), goes in without DMA: f(:send, :x, 5), with an integer, or a tuple for a tuple type, puts it into the input's small FIFO (8 elements) and returns :ok, or {:error, :full} when the FIFO has no room ({:error, :stopped} for a stopped instance); no message follows. These elements go into the stream in turn with what the DMA brings, each one whole. They are not counted by a call that waits for its own results, f(data): a value sent while one runs goes among its elements, and the call gets back results of the wrong elements. Read what one by one gives with f(:out, n) or f(:request, :out, n).

An application with a supervision tree can give an instance a process that owns it, EHLS.Server: started from the initial state with the application, callers waiting their turn instead of {:error, :busy}, its topics' events handed on to any number of processes, the drivers of a function on the CPU started with it.

Not yet (planned): a read returning at once with what has gathered.

The functions generated for an instance

Generates, with a runtime backend (EHLS.runtime/0), for a module's instance of levels f(a, b) (above): f(a, b), f(a, b, opts) (wait: false, timeout: ms), f(:value), f(:start), f(:stop). For a module's instance f of streams:

  • f(:stop), f(:start): stops it; starts it, from the initial state and clean links;
  • f(:value, h): the latest value that reached a hold(h);
  • f(:state, k): the state of transform(init, &g/2, name: k), its words taken at one clock;
  • with two arguments a, b (a join): f(data_a, data_b), f(data_a, data_b, opts), and f(:send, :a, data) per input, answered by {:f, :a, :sent}, and f(:send, :a, value) (one element);
  • with an argument x: f(data), f(data, opts), f(:in, data), f(:in, data, opts), and f(:send, :x, data), answered by {:f, :x, :sent}, and f(:send, :x, value) (one element, :ok or {:error, :full});
  • with an output: f(:out, n), f(:out, n, opts), and f(:request, :out, n), answered by {:f, :out, binary}.

data is a list of elements or a binary of them packed (EHLS.packed_size/1). f(data) gives back what it was given, a list for a list and a binary for a binary; f(:out, n) gives a binary. A list is packed and the output unpacked by the runtime (EHLS.pack/2, EHLS.unpack/2): tuples stay tuples, signed values negative, values going in are wrapped to the input's type. Sizes count elements of the stream. opts: out: n (when f(data) is to take another size than the stages' rates give, or they are not known), as: :list | :binary (the form of the output) and timeout: ms (5000).

With EHLS_OUT_DIR set at compile time, <pipeline>.pipeline (JSON) goes there for the SoC.

Without a runtime backend (on a computer) the calls of an instance exist too and raise an ArgumentError: an instance runs on a board; on a computer, check it with mix ehls.sim.

Summary

Functions

Fuses chunk_every(n, k, :discard) |> map(&f/1) with f a function of a chunk (defhls f(w :: tuple(t, n)) :: r, in windows) into one generated defhls: a ring buffer of the last n words in a memory, a counter of the elements, and f's body with elem(w, i) read from the buffer (i 0 the oldest, n - 1 the word just in). Returns {chain, [defhls AST], [generated names]}.

Functions

fuse(chain, windows)

Fuses chunk_every(n, k, :discard) |> map(&f/1) with f a function of a chunk (defhls f(w :: tuple(t, n)) :: r, in windows) into one generated defhls: a ring buffer of the last n words in a memory, a counter of the elements, and f's body with elem(w, i) read from the buffer (i 0 the oldest, n - 1 the word just in). Returns {chain, [defhls AST], [generated names]}.