Documentation/driver-api/iio/triggered-buffers.rst

   1 =================
   2 Triggered Buffers
   3 =================
   4
   5 Now that we know what buffers and triggers are let's see how they work together.
   6
   7 IIO triggered buffer setup
   8 ==========================
   9
  10 * :c:func:`iio_triggered_buffer_setup` — Setup triggered buffer and pollfunc
  11 * :c:func:`iio_triggered_buffer_cleanup` — Free resources allocated by
  12   :c:func:`iio_triggered_buffer_setup`
  13 * struct :c:type:`iio_buffer_setup_ops` — buffer setup related callbacks
  14
  15 A typical triggered buffer setup looks like this::
  16
  17     const struct iio_buffer_setup_ops sensor_buffer_setup_ops = {
  18       .preenable    = sensor_buffer_preenable,
  19       .postenable   = sensor_buffer_postenable,
  20       .postdisable  = sensor_buffer_postdisable,
  21       .predisable   = sensor_buffer_predisable,
  22     };
  23
  24     irqreturn_t sensor_iio_pollfunc(int irq, void *p)
  25     {
  26         pf->timestamp = iio_get_time_ns((struct indio_dev *)p);
  27         return IRQ_WAKE_THREAD;
  28     }
  29
  30     irqreturn_t sensor_trigger_handler(int irq, void *p)
  31     {
  32         u16 buf[8];
  33         int i = 0;
  34
  35         /* read data for each active channel */
  36         for_each_set_bit(bit, active_scan_mask, masklength)
  37             buf[i++] = sensor_get_data(bit)
  38
  39         iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp);
  40
  41         iio_trigger_notify_done(trigger);
  42         return IRQ_HANDLED;
  43     }
  44
  45     /* setup triggered buffer, usually in probe function */
  46     iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc,
  47                                sensor_trigger_handler,
  48                                sensor_buffer_setup_ops);
  49
  50 The important things to notice here are:
  51
  52 * :c:type:`iio_buffer_setup_ops`, the buffer setup functions to be called at
  53   predefined points in the buffer configuration sequence (e.g. before enable,
  54   after disable). If not specified, the IIO core uses the default
  55   iio_triggered_buffer_setup_ops.
  56 * **sensor_iio_pollfunc**, the function that will be used as top half of poll
  57   function. It should do as little processing as possible, because it runs in
  58   interrupt context. The most common operation is recording of the current
  59   timestamp and for this reason one can use the IIO core defined
  60   :c:func:`iio_pollfunc_store_time` function.
  61 * **sensor_trigger_handler**, the function that will be used as bottom half of
  62   the poll function. This runs in the context of a kernel thread and all the
  63   processing takes place here. It usually reads data from the device and
  64   stores it in the internal buffer together with the timestamp recorded in the
  65   top half.
  66
  67 More details
  68 ============
  69 .. kernel-doc:: drivers/iio/buffer/industrialio-triggered-buffer.c