Documentation/driver-api/iio/triggers.rst

   1 ========
   2 Triggers
   3 ========
   4
   5 * struct :c:type:`iio_trigger` — industrial I/O trigger device
   6 * :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc
   7 * :c:func:`devm_iio_trigger_free` — Resource-managed iio_trigger_free
   8 * :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register
   9 * :c:func:`devm_iio_trigger_unregister` — Resource-managed
  10   iio_trigger_unregister
  11 * :c:func:`iio_trigger_validate_own_device` — Check if a trigger and IIO
  12   device belong to the same device
  13
  14 In many situations it is useful for a driver to be able to capture data based
  15 on some external event (trigger) as opposed to periodically polling for data.
  16 An IIO trigger can be provided by a device driver that also has an IIO device
  17 based on hardware generated events (e.g. data ready or threshold exceeded) or
  18 provided by a separate driver from an independent interrupt source (e.g. GPIO
  19 line connected to some external system, timer interrupt or user space writing
  20 a specific file in sysfs). A trigger may initiate data capture for a number of
  21 sensors and also it may be completely unrelated to the sensor itself.
  22
  23 IIO trigger sysfs interface
  24 ===========================
  25
  26 There are two locations in sysfs related to triggers:
  27
  28 * :file:`/sys/bus/iio/devices/trigger{Y}/*`, this file is created once an
  29   IIO trigger is registered with the IIO core and corresponds to trigger
  30   with index Y.
  31   Because triggers can be very different depending on type there are few
  32   standard attributes that we can describe here:
  33
  34   * :file:`name`, trigger name that can be later used for association with a
  35     device.
  36   * :file:`sampling_frequency`, some timer based triggers use this attribute to
  37     specify the frequency for trigger calls.
  38
  39 * :file:`/sys/bus/iio/devices/iio:device{X}/trigger/*`, this directory is
  40   created once the device supports a triggered buffer. We can associate a
  41   trigger with our device by writing the trigger's name in the
  42   :file:`current_trigger` file.
  43
  44 IIO trigger setup
  45 =================
  46
  47 Let's see a simple example of how to setup a trigger to be used by a driver::
  48
  49       struct iio_trigger_ops trigger_ops = {
  50           .set_trigger_state = sample_trigger_state,
  51           .validate_device = sample_validate_device,
  52       }
  53
  54       struct iio_trigger *trig;
  55
  56       /* first, allocate memory for our trigger */
  57       trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx);
  58
  59       /* setup trigger operations field */
  60       trig->ops = &trigger_ops;
  61
  62       /* now register the trigger with the IIO core */
  63       iio_trigger_register(trig);
  64
  65 IIO trigger ops
  66 ===============
  67
  68 * struct :c:type:`iio_trigger_ops` — operations structure for an iio_trigger.
  69
  70 Notice that a trigger has a set of operations attached:
  71
  72 * :file:`set_trigger_state`, switch the trigger on/off on demand.
  73 * :file:`validate_device`, function to validate the device when the current
  74   trigger gets changed.
  75
  76 More details
  77 ============
  78 .. kernel-doc:: include/linux/iio/trigger.h
  79 .. kernel-doc:: drivers/iio/industrialio-trigger.c
  80    :export: