Pins read and written from Elixir: generic, knowing no board; a block package of the LiteX SoC
backend (FPGA side: priv/backend/litex/ehls_gpio.py).
Not everything between the CPU and the FPGA is a stream. An LED or a switch has only a current
value, which a later value simply overwrites, so it needs no instance and no process:
EHLS.GPIO is a package whose pins are read and written with plain function calls. What must not
be lost, such as a button press, is an event: a pin's changes published by an instance (below).
use EHLS, blocks: [{EHLS.GPIO,
out: [relay: "j5:3"],
in: [door: {"j5:4", pull: :up}],
inout: [sda: {"j5:5", pull: :up}],
board: [:led0, :button0]}]
EHLS.GPIO.write(:relay, 1)
EHLS.GPIO.read(:door)
EHLS.GPIO.direction(:sda, :out) # inout only, while runningDirection: decides the circuit at synthesis. Only an
inouthas a tristate buffer and can change direction while running. It starts as an input, driving nothing; awritemeanwhile is kept for when it turns to an output.Options per pin (
{pin, options}):pull: :up | :down | :none(a pin constraint, fixed at build time) andactive_low: true(values inverted at the pin, so that 1 means on).board:names the target's parts. Their pins, pulls and polarity come from the target (EHLS_BOARD_GPIO, a JSON file), so application code does not depend on the board.Errors: options that cannot be built stop the compile; so does a call with a literal name that cannot work (
mix ehls.compile). At run time a call returns{:error, reason}.Events: a pin's changes are published by an instance, each edge with its exact kind and the time it came (
EHLS.Pipeline, "Events"):definstance door do changes(:door, :both) |> EHLS.PubSub.broadcast(:door) end EHLS.PubSub.subscribe(:door, timestamps: true) # {:door, 1 | 0, t} for each edgeA mechanical switch bounces, so one press can bring several events: debounce in the instance (
samplebelow), or take them withactive: :once.In an instance:
changes(pin, edge)(:rising,:falling,:both) is a source: one value per edge, the pin's new level, without the CPU. An edge arriving before the next function in the pipe took the last value is not counted, and a mechanical switch's bounces are edges.hold(name), a built-in block, keeps the latest value as a level, read withf(:value, name); it is 0 from reset or:startuntil the first value. Together, a counter of button presses in the FPGA:defhls count(_press :: u1, n :: u16) :: {u16, u16} do {n + 1, n + 1} end definstance presses do changes(:button0, :rising) |> transform(0, &count/2) |> hold(:count) end presses(:value, :count)Reading a switch:
sample(pin)reads the pin's level at each value of the stream, so with a slow source the bounces are not seen, and an ordinary function decides what a press is.pin_out(pin)puts the low bit of the latest value on an:out, 0 from each start until the first value; the pin is then no more the CPU's to write, and a literalwriteto it stopsmix ehls.compile.definstance presses do ticks(1000) |> sample(:button0) |> transform({0, 0}, &debounce/2) |> transform(0, &count/2) |> pin_out(:led1) endA pin's level as an argument: in a
definstance,EHLS.GPIO.read(pin)as an argument of a function placed in the stream is the pin's level, read when the function takes a value (EHLS.Pipeline, "Instances of levels"); an out pin gives what is written to it.defhls gate(x :: s16, on :: u1) :: s16 do if on == 1, do: x, else: 0 end definstance gated(words) do words |> map(&gate(&1, EHLS.GPIO.read(:button0))) endLimits: one module declares the pins, 32 pins at most. Calls from Elixir are slow compared with the circuit: a bus at speed belongs in a block with its own circuit.
A sample application: gpio_demo.ex
in atomvm-tang25k-hls, the board's LEDs and buttons, and
button_counter.ex, a counter of button presses with debounce.
Summary
Functions
Turns an :inout pin into an :out or :in: :ok, or {:error, reason}.
The pin's level, 0 or 1 (of an :out: the value written), or {:error, reason}.
Sets an :out or :inout pin to 0 or 1: :ok, or {:error, reason}.