drivers/staging/iio/Documentation/device.txt

   1 IIO Device drivers
   2
   3 This is not intended to provide a comprehensive guide to writing an
   4 IIO device driver.  For further information see the drivers within the
   5 subsystem.
   6
   7 The crucial structure for device drivers in iio is iio_dev.
   8
   9 First allocate one using:
  10
  11 struct iio_dev *indio_dev = iio_device_alloc(sizeof(struct chip_state));
  12 where chip_state is a structure of local state data for this instance of
  13 the chip.
  14
  15 That data can be accessed using iio_priv(struct iio_dev *)
  16
  17 Then fill in the following:
  18
  19 - indio_dev->dev.parent
  20         Struct device associated with the underlying hardware.
  21 - indio_dev->name
  22         Name of the device being driven - made available as the name
  23         attribute in sysfs.
  24
  25 - indio_dev->info
  26         pointer to a structure with elements that tend to be fixed for
  27         large sets of different parts supported by a given driver.
  28         This contains:
  29         * info->driver_module:
  30                 Set to THIS_MODULE. Used to ensure correct ownership
  31                 of various resources allocate by the core.
  32         * info->event_attrs:
  33                 Attributes used to enable / disable hardware events.
  34         * info->attrs:
  35                 General device attributes. Typically used for the weird
  36                 and the wonderful bits not covered by the channel specification.
  37         * info->read_raw:
  38                 Raw data reading function. Used for both raw channel access
  39                 and for associate parameters such as offsets and scales.
  40         * info->write_raw:
  41                 Raw value writing function. Used for writable device values such
  42                 as DAC values and caliboffset.
  43         * info->read_event_config:
  44                 Typically only set if there are some interrupt lines.  This
  45                 is used to read if an on sensor event detector is enabled.
  46         * info->write_event_config:
  47                 Enable / disable an on sensor event detector.
  48         * info->read_event_value:
  49                 Read value associated with on sensor event detectors. Note that
  50                 the meaning of the returned value is dependent on the event
  51                 type.
  52         * info->write_event_value:
  53                 Write the value associated with on sensor event detectors. E.g.
  54                 a threshold above which an interrupt occurs.  Note that the
  55                 meaning of the value to be set is event type dependant.
  56
  57 - indio_dev->modes:
  58         Specify whether direct access and / or ring buffer access is supported.
  59 - indio_dev->ring:
  60         An optional associated buffer.
  61 - indio_dev->pollfunc:
  62         Poll function related elements. This controls what occurs when a trigger
  63         to which this device is attached sends an event.
  64 - indio_dev->channels:
  65         Specification of device channels. Most attributes etc are built
  66         form this spec.
  67 - indio_dev->num_channels:
  68         How many channels are there?
  69
  70 Once these are set up, a call to iio_device_register(indio_dev),
  71 will register the device with the iio core.
  72
  73 Worth noting here is that, if a ring buffer is to be used, it can be
  74 allocated prior to registering the device with the iio-core, but must
  75 be registered afterwards (otherwise the whole parentage of devices
  76 gets confused)
  77
  78 On remove, iio_device_unregister(indio_dev) will remove the device from
  79 the core, and iio_device_free will clean up.