Doc updates and some code consistency updates

Author: fhunleth

CHANGELOG.md

@@ -6,7 +6,7 @@
   * `t:gpio_info/0` now only contains static information so that it's easier to
     cache. Caching reduces open time from 2-3ms to 100us on an RPi Zero, so it's
     a decent improvement for apps that set a lot of GPIOs on boot.
-  * Add `t:gpio_status/0` and `gpio_status/1` to get runtime information about
+  * Add `t:status/0` and `status/1` to get runtime information about
     GPIOs. It's currently populated with GPIO consumer info, direction and pull
     mode. It could certainly have more added in the future.
   * Add `write_one/3` and `read_one/2` convenience methods to simplify one-off

c_src/gpio_nif.c

@@ -327,7 +327,7 @@ static ERL_NIF_TERM set_pull_mode(ErlNifEnv *env, int argc, const ERL_NIF_TERM a
     return atom_ok;
 }
 
-static ERL_NIF_TERM get_gpio_status(ErlNifEnv *env, int argc, const ERL_NIF_TERM argv[])
+static ERL_NIF_TERM get_status(ErlNifEnv *env, int argc, const ERL_NIF_TERM argv[])
 {
     struct gpio_priv *priv = enif_priv_data(env);
     char gpiochip_path[MAX_GPIOCHIP_PATH_LEN];
@@ -337,7 +337,7 @@ static ERL_NIF_TERM get_gpio_status(ErlNifEnv *env, int argc, const ERL_NIF_TERM
         return enif_make_badarg(env);
 
     ERL_NIF_TERM result;
-    int rc = hal_get_gpio_status(priv->hal_priv, env, gpiochip_path, offset, &result);
+    int rc = hal_get_status(priv->hal_priv, env, gpiochip_path, offset, &result);
     if (rc >= 0)
         return make_ok_tuple(env, result);
     else
@@ -434,7 +434,7 @@ static ErlNifFunc nif_funcs[] = {
     {"set_interrupts", 4, set_interrupts, 0},
     {"set_direction", 2, set_direction, 0},
     {"set_pull_mode", 2, set_pull_mode, 0},
-    {"status", 1, get_gpio_status, 0},
+    {"status", 1, get_status, 0},
     {"backend_info", 0, backend_info, 0},
     {"enumerate", 0, gpio_enumerate, 0}
 };

c_src/gpio_nif.h

@@ -96,7 +96,7 @@ ERL_NIF_TERM hal_info(ErlNifEnv *env, void *hal_priv, ERL_NIF_TERM info);
 /**
  * Enumerate all GPIO pins
  *
- * Returns a list of Circuits.GPIO.gpio_info maps
+ * Returns a list of Circuits.GPIO.identifiers maps
  */
 ERL_NIF_TERM hal_enumerate(ErlNifEnv *env, void *hal_priv);
 
@@ -195,7 +195,7 @@ int hal_apply_pull_mode(struct gpio_pin *pin);
  * @param result where to store the result when successful
  * @return 0 on success, -errno on failure
  */
-int hal_get_gpio_status(void *hal_priv, ErlNifEnv *env, const char *gpiochip, int offset, ERL_NIF_TERM *result);
+int hal_get_status(void *hal_priv, ErlNifEnv *env, const char *gpiochip, int offset, ERL_NIF_TERM *result);
 
 // nif_utils.c
 ERL_NIF_TERM make_ok_tuple(ErlNifEnv *env, ERL_NIF_TERM value);

c_src/hal_cdev_gpio.c

@@ -345,7 +345,7 @@ ERL_NIF_TERM hal_enumerate(ErlNifEnv *env, void *hal_priv)
     return gpio_list;
 }
 
-int hal_get_gpio_status(void *hal_priv, ErlNifEnv *env, const char *gpiochip, int offset, ERL_NIF_TERM *result)
+int hal_get_status(void *hal_priv, ErlNifEnv *env, const char *gpiochip, int offset, ERL_NIF_TERM *result)
 {
     int gpiochip_fd = open(gpiochip, O_RDWR|O_CLOEXEC);
     if (gpiochip_fd < 0)

c_src/hal_stub.c

@@ -225,7 +225,7 @@ ERL_NIF_TERM hal_enumerate(ErlNifEnv *env, void *hal_priv)
     return gpio_list;
 }
 
-int hal_get_gpio_status(void *hal_priv, ErlNifEnv *env, const char *gpiochip, int offset, ERL_NIF_TERM *result)
+int hal_get_status(void *hal_priv, ErlNifEnv *env, const char *gpiochip, int offset, ERL_NIF_TERM *result)
 {
     struct stub_priv *stub_priv = hal_priv;
     int pin_base;

lib/gpio.ex

@@ -102,14 +102,20 @@ defmodule Circuits.GPIO do
   @type pull_mode() :: :not_set | :none | :pullup | :pulldown
 
   @typedoc """
-  Static GPIO information
+  Ways of referring to a GPIO
 
-  Location and other static information about a GPIO that is returned by
-  `enumerate/1`.  Backends must provide `:location` which is an unambiguous
-  `t:gpio_spec/0` for use with `open/3`.  As described in `open/3`, there are
-  many ways to refer to GPIOs and those may be exposed here as well. Since GPIO
-  information can be cached, this map does not contain mode settings or current
-  values. See other functions for getting that information.
+  It's possible to refer to a GPIOs in many ways and this map contains
+  information for doing that.  See `enumerate/1` and `identifiers/1` for
+  querying `Circuits.GPIO` for these maps.
+
+  The information in this map is backend specific. At a minimum, all backends
+  provide the `:location` field which is an unambiguous `t:gpio_spec/0` for use
+  with `open/3`.
+
+  When provided, the `:label` field is a string name for the GPIO that should
+  be unique to the system but this isn't guaranteed. A common convention is to
+  label GPIOs by their pin names in documentation or net names in schematics.
+  The Linux cdev backend uses labels from the device tree file.
 
   Fields:
 
@@ -181,7 +187,7 @@ defmodule Circuits.GPIO do
   def gpio_spec?(x), do: is_gpio_spec(x)
 
   @doc """
-  Return static information about a GPIO
+  Return indentifying information about a GPIO
 
   See `t:gpio_spec/0` for the ways of referring to GPIOs. If the GPIO is found,
   this function returns information about the GPIO.
@@ -190,7 +196,7 @@ defmodule Circuits.GPIO do
   def identifiers(gpio_spec) do
     {backend, backend_defaults} = default_backend()
 
-    backend.gpio_identifiers(gpio_spec, backend_defaults)
+    backend.identifiers(gpio_spec, backend_defaults)
   end
 
   @doc """
@@ -203,7 +209,7 @@ defmodule Circuits.GPIO do
   def status(gpio_spec) do
     {backend, backend_defaults} = default_backend()
 
-    backend.gpio_status(gpio_spec, backend_defaults)
+    backend.status(gpio_spec, backend_defaults)
   end
 
   @doc """
@@ -391,12 +397,12 @@ defmodule Circuits.GPIO do
   def backend_info(backend \\ nil)
 
   def backend_info(nil), do: backend_info(default_backend())
-  def backend_info({backend, _options}), do: backend.info()
+  def backend_info({backend, _options}), do: backend.backend_info()
 
   @doc """
   Return a list of accessible GPIOs
 
-  Each GPIO is described in a `t:gpio_info/0` map. Some fields in the map like
+  Each GPIO is described in a `t:identifiers/0` map. Some fields in the map like
   `:location` and `:label` may be passed to `open/3` to use the GPIO. The map
   itself can also be passed to `open/3` and the function will figure out how to
   access the GPIO.

lib/gpio/backend.ex

@@ -23,9 +23,9 @@ defmodule Circuits.GPIO.Backend do
   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 information about the GPIO.
+  If the GPIO is found, this function returns identifying information about the GPIO.
   """
-  @callback gpio_identifiers(
+  @callback identifiers(
               gpio_spec :: GPIO.gpio_spec(),
               options :: GPIO.open_options()
             ) :: {:ok, GPIO.identifiers()} | {:error, atom()}
@@ -43,7 +43,7 @@ defmodule Circuits.GPIO.Backend do
 
   If the GPIO is found, this function returns its status.
   """
-  @callback gpio_status(
+  @callback status(
               gpio_spec :: GPIO.gpio_spec(),
               options :: GPIO.open_options()
             ) :: {:ok, GPIO.status()} | {:error, atom()}
@@ -74,5 +74,5 @@ defmodule Circuits.GPIO.Backend do
   @doc """
   Return information about this backend
   """
-  @callback info() :: map()
+  @callback backend_info() :: map()
 end

lib/gpio/cdev.ex

@@ -70,25 +70,25 @@ defmodule Circuits.GPIO.CDev do
   end
 
   @impl Backend
-  def gpio_identifiers(number, options) when is_integer(number) and number >= 0 do
+  def identifiers(number, options) when is_integer(number) and number >= 0 do
     retry_find(options, &find_by_index(&1, number))
   end
 
-  def gpio_identifiers(line_label, options) when is_binary(line_label) do
+  def identifiers(line_label, options) when is_binary(line_label) do
     retry_find(options, &find_by_label(&1, line_label))
   end
 
-  def gpio_identifiers(tuple_spec, options)
+  def identifiers(tuple_spec, options)
       when is_tuple(tuple_spec) and tuple_size(tuple_spec) == 2 do
     retry_find(options, &find_by_tuple(&1, tuple_spec))
   end
 
-  def gpio_identifiers(_gpio_spec, _options) do
+  def identifiers(_gpio_spec, _options) do
     {:error, :not_found}
   end
 
   @impl Backend
-  def gpio_status(gpio_spec, options \\ []) do
+  def status(gpio_spec, options \\ []) do
     with {:ok, location} <- find_location(gpio_spec, options) do
       resolved_location = resolve_gpiochip(location)
       Nif.status(resolved_location)
@@ -101,8 +101,8 @@ defmodule Circuits.GPIO.CDev do
   end
 
   defp find_location(gpio_spec, options) do
-    with {:ok, identifiers} <- gpio_identifiers(gpio_spec, options) do
-      {:ok, identifiers.location}
+    with {:ok, ids} <- identifiers(gpio_spec, options) do
+      {:ok, ids.location}
     end
   end
 
@@ -127,7 +127,7 @@ defmodule Circuits.GPIO.CDev do
   end
 
   @impl Backend
-  def info() do
+  def backend_info() do
     Nif.backend_info() |> Map.put(:name, __MODULE__)
   end
 

lib/gpio/diagnostics.ex

@@ -37,8 +37,8 @@ defmodule Circuits.GPIO.Diagnostics do
   """
   @spec report(GPIO.gpio_spec(), GPIO.gpio_spec()) :: boolean
   def report(out_gpio_spec, in_gpio_spec) do
-    {:ok, out_gpio_identifiers} = GPIO.identifiers(out_gpio_spec)
-    {:ok, in_gpio_identifiers} = GPIO.identifiers(in_gpio_spec)
+    {:ok, out_identifiers} = GPIO.identifiers(out_gpio_spec)
+    {:ok, in_identifiers} = GPIO.identifiers(in_gpio_spec)
     results = run(out_gpio_spec, in_gpio_spec)
     passed = Enum.all?(results, fn {_, result} -> result == :ok end)
     check_connections? = hd(results) != {"Simple writes and reads work", :ok}
@@ -51,8 +51,8 @@ defmodule Circuits.GPIO.Diagnostics do
       Output GPIO: #{inspect(out_gpio_spec)}
       Input GPIO:  #{inspect(in_gpio_spec)}
 
-      Output info: #{inspect(out_gpio_identifiers)}
-      Input info:  #{inspect(in_gpio_identifiers)}
+      Output ids:  #{inspect(out_identifiers)}
+      Input ids:   #{inspect(in_identifiers)}
       Backend: #{inspect(Circuits.GPIO.backend_info()[:name])}
 
       """,

lib/gpio/nil_backend.ex

@@ -16,12 +16,12 @@ defmodule Circuits.GPIO.NilBackend do
   end
 
   @impl Backend
-  def gpio_identifiers(_gpio_spec, _options) do
+  def identifiers(_gpio_spec, _options) do
     {:error, :not_found}
   end
 
   @impl Backend
-  def gpio_status(_gpio_spec, _options) do
+  def status(_gpio_spec, _options) do
     {:error, :not_found}
   end
 
@@ -31,7 +31,7 @@ defmodule Circuits.GPIO.NilBackend do
   end
 
   @impl Backend
-  def info() do
+  def backend_info() do
     %{name: __MODULE__}
   end
 end