# SPDX-FileCopyrightText: 2023 Frank Hunleth
# SPDX-FileCopyrightText: 2024 Connor Rigby
#
# SPDX-License-Identifier: Apache-2.0

defmodule Circuits.GPIO.Backend do
  @moduledoc """
  Backends provide the connection to the real or virtual GPIO controllers
  """
  alias Circuits.GPIO
  alias Circuits.GPIO.Handle

  @doc """
  Return a list of GPIOs

  See `t:GPIO.identifiers/0` for the information that is returned. The `options` contain
  backend-specific options to help with enumeration.
  """
  @callback enumerate(options :: GPIO.open_options()) :: [GPIO.identifiers()]

  @doc """
  Return identifying information about a GPIO

  See `t:gpio_spec/0` for the ways of referring to GPIOs. The `options` contain
  backend-specific options to help enumerating GPIOs.

  If the GPIO is found, this function returns identifying information about the GPIO.
  """
  @callback identifiers(
              gpio_spec :: GPIO.gpio_spec(),
              options :: GPIO.open_options()
            ) :: {:ok, GPIO.identifiers()} | {:error, atom()}

  @doc """
  Return a GPIO's current status

  This function returns how a GPIO is configured. The GPIO doesn't need to be
  opened. It's different from `gpio_identifiers/2` since it returns dynamic information
  whereas `gpio_identifiers/2` only returns information about how to refer to a GPIO
  and where it exists in the system.

  See `t:gpio_spec/0` for the ways of referring to GPIOs. The `options` contain
  backend-specific options to help enumerating GPIOs.

  If the GPIO is found, this function returns its status.
  """
  @callback status(
              gpio_spec :: GPIO.gpio_spec(),
              options :: GPIO.open_options()
            ) :: {:ok, GPIO.status()} | {:error, atom()}

  @doc """
  Open one or more GPIOs

  See `t:gpio_spec/0` for the ways of referring to GPIOs. Set `direction` to
  either `:input` or `:output`. If opening as an output, then be sure to set
  the `:initial_value` option to minimize the time the GPIO is in the default
  state.

  Passing a list of GPIO specs opens them together as a group. `read/1` then
  returns a single integer and `write/2` takes one, with the first spec as the
  least significant bit. All GPIOs in a group must be on the same controller.

  Options:

  * `:initial_value` - Set to `0` or `1` (or an integer with one bit per line for
    a group). Only used for outputs. Defaults to `0`.
  * `:pull_mode` - Set to `:not_set`, `:pullup`, `:pulldown`, or `:none` for an
    input pin. `:not_set` is the default.
  * `:drive_mode` - Set to `:push_pull`, `:open_drain`, or `:open_source`.
    `:push_pull` is the default.

  Returns `{:ok, handle}` on success.
  """
  @callback open(
              gpio_spec :: GPIO.gpio_spec() | [GPIO.gpio_spec()],
              direction :: GPIO.direction(),
              options :: GPIO.open_options()
            ) ::
              {:ok, Handle.t()} | {:error, atom()}

  @doc """
  Force all open handles that reference a GPIO spec to close
  """
  @callback force_close(
              gpio_spec :: GPIO.gpio_spec(),
              options :: GPIO.open_options()
            ) :: :ok | {:error, atom()}

  @doc """
  Return information about this backend
  """
  @callback backend_info() :: map()
end