0001 ========
0002 Triggers
0003 ========
0004
0005 * struct iio_trigger — industrial I/O trigger device
0006 * :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc
0007 * :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register
0008 iio_trigger_unregister
0009 * :c:func:`iio_trigger_validate_own_device` — Check if a trigger and IIO
0010 device belong to the same device
0011
0012 In many situations it is useful for a driver to be able to capture data based
0013 on some external event (trigger) as opposed to periodically polling for data.
0014 An IIO trigger can be provided by a device driver that also has an IIO device
0015 based on hardware generated events (e.g. data ready or threshold exceeded) or
0016 provided by a separate driver from an independent interrupt source (e.g. GPIO
0017 line connected to some external system, timer interrupt or user space writing
0018 a specific file in sysfs). A trigger may initiate data capture for a number of
0019 sensors and also it may be completely unrelated to the sensor itself.
0020
0021 IIO trigger sysfs interface
0022 ===========================
0023
0024 There are two locations in sysfs related to triggers:
0025
0026 * :file:`/sys/bus/iio/devices/trigger{Y}/*`, this file is created once an
0027 IIO trigger is registered with the IIO core and corresponds to trigger
0028 with index Y.
0029 Because triggers can be very different depending on type there are few
0030 standard attributes that we can describe here:
0031
0032 * :file:`name`, trigger name that can be later used for association with a
0033 device.
0034 * :file:`sampling_frequency`, some timer based triggers use this attribute to
0035 specify the frequency for trigger calls.
0036
0037 * :file:`/sys/bus/iio/devices/iio:device{X}/trigger/*`, this directory is
0038 created once the device supports a triggered buffer. We can associate a
0039 trigger with our device by writing the trigger's name in the
0040 :file:`current_trigger` file.
0041
0042 IIO trigger setup
0043 =================
0044
0045 Let's see a simple example of how to setup a trigger to be used by a driver::
0046
0047 struct iio_trigger_ops trigger_ops = {
0048 .set_trigger_state = sample_trigger_state,
0049 .validate_device = sample_validate_device,
0050 }
0051
0052 struct iio_trigger *trig;
0053
0054 /* first, allocate memory for our trigger */
0055 trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx);
0056
0057 /* setup trigger operations field */
0058 trig->ops = &trigger_ops;
0059
0060 /* now register the trigger with the IIO core */
0061 iio_trigger_register(trig);
0062
0063 IIO trigger ops
0064 ===============
0065
0066 * struct iio_trigger_ops — operations structure for an iio_trigger.
0067
0068 Notice that a trigger has a set of operations attached:
0069
0070 * :file:`set_trigger_state`, switch the trigger on/off on demand.
0071 * :file:`validate_device`, function to validate the device when the current
0072 trigger gets changed.
0073
0074 More details
0075 ============
0076 .. kernel-doc:: include/linux/iio/trigger.h
0077 .. kernel-doc:: drivers/iio/industrialio-trigger.c
0078 :export: