Support setting I2C transaction timeouts

Author: fhunleth

c_src/i2c_nif.c

@@ -38,9 +38,10 @@ int test_close(int fd)
     else
         return -1;
 }
-int test_ioctl(int fd, unsigned long request, void *arg)
+int test_ioctl(int fd, unsigned long request, ...)
 {
     static int flaky = 0;
+    va_list ap;
 
     // The flaky I2C bus (0x30) works only on a retry. Reading anything besides 0x30 resets the counter.
     if (fd != 0x30)
@@ -50,11 +51,15 @@ int test_ioctl(int fd, unsigned long request, void *arg)
         return -1;
 
     if (request == I2C_FUNCS) {
-        unsigned long *funcs = (unsigned long *) arg;
+        va_start(ap, request);
+        unsigned long *funcs = va_arg(ap, unsigned long *);
+        va_end(ap);
         *funcs = 0;
         return 0;
     } else if (request == I2C_RDWR) {
-        struct i2c_rdwr_ioctl_data *data = (struct i2c_rdwr_ioctl_data *) arg;
+        va_start(ap, request);
+        struct i2c_rdwr_ioctl_data *data = va_arg(ap, struct i2c_rdwr_ioctl_data *);
+        va_end(ap);
         if (fd == 0x30) {
             // Flake out if first read or write
             if (flaky == 0) {
@@ -76,6 +81,9 @@ int test_ioctl(int fd, unsigned long request, void *arg)
             }
         }
         return data->nmsgs;
+    } else if (request == I2C_TIMEOUT) {
+        // Ignore calls to set the timeout.
+        return 0;
     } else {
         // Unknown ioctl
         return -1;
@@ -226,8 +234,10 @@ static ERL_NIF_TERM i2c_open(ErlNifEnv *env, int argc, const ERL_NIF_TERM argv[]
 {
     struct I2cNifPriv *priv = enif_priv_data(env);
     ErlNifBinary path;
+    int timeout_ms;
 
-    if (!enif_inspect_binary(env, argv[0], &path))
+    if (!enif_inspect_binary(env, argv[0], &path) ||
+            !enif_get_int(env, argv[1], &timeout_ms))
         return enif_make_badarg(env);
 
     char devpath[32];
@@ -244,6 +254,17 @@ static ERL_NIF_TERM i2c_open(ErlNifEnv *env, int argc, const ERL_NIF_TERM argv[]
         return enif_make_errno_error(env);
     }
 
+    // Change the I2C timeout
+    if (timeout_ms >= 0) {
+        int timeout_cs = (timeout_ms + 5) / 10;
+        if (timeout_cs == 0)
+            timeout_cs = 1;
+        if (do_ioctl(fd, I2C_TIMEOUT, timeout_cs) < 0) {
+            close(fd);
+            return enif_make_errno_error(env);
+        }
+    }
+
     struct I2cNifRes *i2c_nif_res = enif_alloc_resource(priv->i2c_nif_res_type, sizeof(struct I2cNifRes));
     i2c_nif_res->fd = fd;
     ERL_NIF_TERM res_term = enif_make_resource(env, i2c_nif_res);
@@ -411,7 +432,7 @@ static ERL_NIF_TERM i2c_info(ErlNifEnv *env, int argc, const ERL_NIF_TERM argv[]
 
 static ErlNifFunc nif_funcs[] =
 {
-    {"open", 1, i2c_open, ERL_NIF_DIRTY_JOB_IO_BOUND},
+    {"open", 2, i2c_open, ERL_NIF_DIRTY_JOB_IO_BOUND},
     {"read", 4, i2c_read, ERL_NIF_DIRTY_JOB_IO_BOUND},
     {"write", 4, i2c_write, ERL_NIF_DIRTY_JOB_IO_BOUND},
     {"write_read", 5, i2c_write_read, ERL_NIF_DIRTY_JOB_IO_BOUND},

lib/i2c.ex

@@ -37,7 +37,30 @@ defmodule Circuits.I2C do
   """
   @type backend() :: {module(), keyword()}
 
-  @type opt() :: {:retries, non_neg_integer()}
+  @typedoc """
+  I2C open options
+
+  See I2C backend documentation, device driver caveats, and function calls in this
+  module for notes. In general,
+
+  * `:retries` - the number of times to retry a transaction. I.e. 2 retries means
+    the transaction is attempted at most 3 times. Defaults to 0 retries.
+  * `:timeout` - the time in milliseconds to wait for a transaction to complete.
+    Any value <0 means to use the device driver or hardware default. The default
+    value is -1 to avoid setting it, but it is very common for the default to be 1000 ms.
+  """
+  @type open_options() :: keyword()
+
+  @typedoc """
+  I2C transfer options
+
+  See I2C backend documentation, device driver caveats, and function calls in this
+  module for notes. In general,
+
+  * `:retries` - override the number of times to retry a transaction from what was
+    passed to `open/3`.
+  """
+  @type transfer_options() :: keyword()
 
   @typedoc """
   Connection to a real or virtual I2C controller
@@ -79,10 +102,12 @@ defmodule Circuits.I2C do
   Options depend on the backend. The following are for the I2CDev (default)
   backend:
 
-  * `:retries` - the default number of retries to automatically do on reads
-    and writes (defaults to no retries)
+  * `:retries` - the number of times to retry a transaction. I.e. 2 retries means
+    the transaction is attempted at most 3 times. Defaults to 0 retries.
+  * `:timeout` - the time in milliseconds to wait for a transaction to complete
+    or <0 to avoid setting it. Defaults to -1.
   """
-  @spec open(String.t(), keyword()) :: {:ok, Bus.t()} | {:error, term()}
+  @spec open(String.t(), open_options()) :: {:ok, Bus.t()} | {:error, term()}
   def open(bus_name, options \\ []) when is_binary(bus_name) do
     {module, default_options} = default_backend()
     module.open(bus_name, Keyword.merge(default_options, options))
@@ -91,43 +116,38 @@ defmodule Circuits.I2C do
   @doc """
   Initiate a read transaction to the I2C device at the specified `address`
 
-  Options:
-
-  * `:retries` - number of retries before failing (defaults to no retries)
+  See `t:transfer_options/0` for options, but backend may provide more.
   """
-  @spec read(Bus.t(), address(), pos_integer(), [opt()]) :: {:ok, binary()} | {:error, term()}
+  @spec read(Bus.t(), address(), pos_integer(), transfer_options()) ::
+          {:ok, binary()} | {:error, term()}
   def read(bus, address, bytes_to_read, opts \\ []) do
     Bus.read(bus, address, bytes_to_read, opts)
   end
 
   @doc """
   Initiate a read transaction and raise on error
   """
-  @spec read!(Bus.t(), address(), pos_integer(), [opt()]) :: binary()
+  @spec read!(Bus.t(), address(), pos_integer(), transfer_options()) :: binary()
   def read!(bus, address, bytes_to_read, opts \\ []) do
     unwrap_or_raise(read(bus, address, bytes_to_read, opts))
   end
 
   @doc """
   Write `data` to the I2C device at `address`.
 
-  Options:
-
-  * `:retries` - number of retries before failing (defaults to no retries)
+  See `t:transfer_options/0` for options, but backend may provide more.
   """
-  @spec write(Bus.t(), address(), iodata(), [opt()]) :: :ok | {:error, term()}
+  @spec write(Bus.t(), address(), iodata(), transfer_options()) :: :ok | {:error, term()}
   def write(bus, address, data, opts \\ []) do
     Bus.write(bus, address, data, opts)
   end
 
   @doc """
   Write `data` to the I2C device at `address` and raise on error
 
-  Options:
-
-  * `:retries` - number of retries before failing (defaults to no retries)
+  See `t:transfer_options/0` for options, but backend may provide more.
   """
-  @spec write!(Bus.t(), address(), iodata(), [opt()]) :: :ok
+  @spec write!(Bus.t(), address(), iodata(), transfer_options()) :: :ok
   def write!(bus, address, data, opts \\ []) do
     unwrap_or_raise_ok(write(bus, address, data, opts))
   end
@@ -143,11 +163,9 @@ defmodule Circuits.I2C do
   transaction will be issued that way. On the Raspberry Pi, this can be enabled
   globally with `File.write!("/sys/module/i2c_bcm2708/parameters/combined", "1")`
 
-  Options:
-
-  * `:retries` - number of retries before failing (defaults to no retries)
+  See `t:transfer_options/0` for options, but backend may provide more.
   """
-  @spec write_read(Bus.t(), address(), iodata(), pos_integer(), [opt()]) ::
+  @spec write_read(Bus.t(), address(), iodata(), pos_integer(), transfer_options()) ::
           {:ok, binary()} | {:error, term()}
   def write_read(bus, address, write_data, bytes_to_read, opts \\ []) do
     Bus.write_read(bus, address, write_data, bytes_to_read, opts)
@@ -156,11 +174,9 @@ defmodule Circuits.I2C do
   @doc """
   Write `data` to an I2C device and then immediately issue a read. Raise on errors.
 
-  Options:
-
-  * `:retries` - number of retries before failing (defaults to no retries)
+  See `t:transfer_options/0` for options, but backend may provide more.
   """
-  @spec write_read!(Bus.t(), address(), iodata(), pos_integer(), [opt()]) :: binary()
+  @spec write_read!(Bus.t(), address(), iodata(), pos_integer(), transfer_options()) :: binary()
   def write_read!(bus, address, write_data, bytes_to_read, opts \\ []) do
     unwrap_or_raise(write_read(bus, address, write_data, bytes_to_read, opts))
   end

lib/i2c/backend.ex

@@ -14,15 +14,14 @@ defmodule Circuits.I2C.Backend do
   Support for options is backend-specific. Backends are encouraged to
   implement the following:
 
-  * `:retries` - a number of times to attempt to retry the transaction
-    before failing
+  * `:retries` - the number of retries for this transaction
   """
-  @type options() :: keyword()
+  @type transfer_options() :: keyword()
 
   @doc """
   Return the I2C bus names on this system
 
-  No supported options
+  See backend documentation for options.
   """
   @callback bus_names(options :: keyword()) :: [binary()]
 
@@ -32,10 +31,7 @@ defmodule Circuits.I2C.Backend do
   Bus names are typically of the form `"i2c-n"` and available buses may be
   found by calling `bus_names/1`.
 
-  Options:
-
-  * `:retries` - Specify a nonnegative integer for how many times to retry
-    a failed I2C operation.
+  See `t:Circuits.I2C.open_options/0` for guidance on options.
   """
   @callback open(bus_name :: String.t(), options :: keyword()) ::
               {:ok, Bus.t()} | {:error, term()}

lib/i2c/i2c_dev.ex

@@ -48,8 +48,10 @@ defmodule Circuits.I2C.I2CDev do
 
   Options:
 
-  * `:retries` - Specify a nonnegative integer for how many times to retry
-    a failed I2C operation.
+  * `:retries` - the number of times to retry a transaction. I.e. 2 retries means
+    the transaction is attempted at most 3 times. Defaults to 0 retries.
+  * `:timeout` - the time in milliseconds to wait for a transaction to complete.
+    Any value <0 means to use the device driver default which is probably 1000 ms.
   """
   @impl Backend
   def open(bus_name, options) do
@@ -59,7 +61,13 @@ defmodule Circuits.I2C.I2CDev do
       raise ArgumentError, "retries must be a non-negative integer"
     end
 
-    with {:ok, ref, flags} <- Nif.open(bus_name) do
+    timeout = Keyword.get(options, :timeout, -1)
+
+    if not is_integer(timeout) do
+      raise ArgumentError, "timeout must be an integer"
+    end
+
+    with {:ok, ref, flags} <- Nif.open(bus_name, timeout) do
       {:ok, %__MODULE__{ref: ref, flags: flags, retries: retries}}
     end
   end

lib/i2c/i2c_nif.ex

@@ -12,7 +12,7 @@ defmodule Circuits.I2C.Nif do
     :erlang.load_nif(:code.priv_dir(:circuits_i2c) ++ ~c"/i2c_nif", 0)
   end
 
-  def open(_device), do: :erlang.nif_error(:nif_not_loaded)
+  def open(_device, _timeout), do: :erlang.nif_error(:nif_not_loaded)
   def read(_ref, _address, _count, _retries), do: :erlang.nif_error(:nif_not_loaded)
   def write(_ref, _address, _data, _retries), do: :erlang.nif_error(:nif_not_loaded)
 

test/i2c/i2c_nif_test.exs

@@ -18,15 +18,15 @@ defmodule Circuits.I2CNifTest do
 
   describe "open/1" do
     test "i2c-test-0 and i2c-test-1 work" do
-      {:ok, i2c, flags} = Nif.open("i2c-test-0")
+      {:ok, i2c, flags} = Nif.open("i2c-test-0", -1)
       Nif.close(i2c)
       assert flags == []
 
-      {:ok, i2c, flags} = Nif.open("i2c-test-1")
+      {:ok, i2c, flags} = Nif.open("i2c-test-1", -1)
       Nif.close(i2c)
       assert flags == []
 
-      assert {:error, _} = Nif.open("i2c-2")
+      assert {:error, _} = Nif.open("i2c-2", -1)
     end
   end
 
@@ -37,7 +37,7 @@ defmodule Circuits.I2CNifTest do
       assert {:module, Circuits.I2C.Nif} == :code.ensure_loaded(Circuits.I2C.Nif)
 
       # Try running something to verify that it works.
-      {:ok, i2c, _} = Nif.open("i2c-test-0")
+      {:ok, i2c, _} = Nif.open("i2c-test-0", -1)
       assert is_reference(i2c)
       Nif.close(i2c)
 
@@ -75,7 +75,7 @@ defmodule Circuits.I2CNifTest do
         assert {:module, Circuits.I2C.Nif} == :code.ensure_loaded(Circuits.I2C.Nif)
 
         # Try running something to verify that it works.
-        {:ok, i2c, _} = Nif.open("i2c-test-0")
+        {:ok, i2c, _} = Nif.open("i2c-test-0", -1)
         assert is_reference(i2c)
         Nif.close(i2c)