EHLS.GPIO (Elixir HLS v0.1.0)

Copy Markdown View Source

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 running
  • Direction: decides the circuit at synthesis. Only an inout has a tristate buffer and can change direction while running. It starts as an input, driving nothing; a write meanwhile 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) and active_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 edge

    A mechanical switch bounces, so one press can bring several events: debounce in the instance (sample below), or take them with active: :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 with f(:value, name); it is 0 from reset or :start until 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 literal write to it stops mix ehls.compile.

    definstance presses do
      ticks(1000) |> sample(:button0) |> transform({0, 0}, &debounce/2) |> transform(0, &count/2) |> pin_out(:led1)
    end
  • A 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)))
    end
  • Limits: 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}.

Functions

direction(name, dir)

Turns an :inout pin into an :out or :in: :ok, or {:error, reason}.

read(name)

The pin's level, 0 or 1 (of an :out: the value written), or {:error, reason}.

write(name, value)

Sets an :out or :inout pin to 0 or 1: :ok, or {:error, reason}.