Re: [RFC PATCH 0/4] IIO: Out of staging step 1. The core.

[Jonathan Cameron <jic23@cam.ac.uk>]

Bump. Anyone had a chance to look at the text in this cover letter?

I'm planning ideally to send this first series out shortly.

Jonathan
On 08/30/11 17:18, Jonathan Cameron wrote:
> Hi All,
> 
> I'd like to make a good impression when posting this more widely,
> hence I'm posting it here first. Please comment on both the code
> and the text of this explanatory email!  Are there other things
> I should put in here?  Clearly the set is currently missing
> documentation which will need doing before this goes to lkml etc.
> 
> Also note that the code has to sit on a couple of namespace moves
> to avoid a clash with the staging tree.  These are in the
> outofstaging branch of iio-blue.git.
> 
> Dear All,
> 
> This is our first attempt to propose moving 'some' of the
> Industrial I/O subsystem out of staging.  This cover letter
> attempts to explain what IIO is and why it is needed.
> All comments welcome on this as well as the code!
> 
> So the big question is 'Why is there a need for a new subsystem?'
> 
> To answer this we need two things, a list or requirements and analysis
> of why current subystems (hwmon and input) do not meet them. Focused
> subsytems targetting just one type of sensor have been rejected as
> a concept (see ALS proposal).
> 
> Requirements of IIO.
> 
> 1) Simple interface for simple use cases.
> 2) High performance data route.
> 3) Generic and consistent 'event' handling.
> 4) Wide device type coverage with consistent interface.
> 5) Complex triggering setups - multiple devices capture 'simultaneously'.
> 6) Support output devices.
> 
> Lets take these in turn:
> 
> 1 - Simple interface for simple use cases:
> 
> The requirement boils down to an easy way to get a reading from a device or set
> an output without much overhead.
> 
> This is an area in which hwmon excels. Everything is available via sysfs
> and thats exactly what we allow drivers to provide.
> 
> 2 - High performance data route:
> 
> We want a path via which data can get to userspace without much overhead,
> thus allowing high speed data capture. (Note I'm not arguing we have this
> right yet - but the potential is there).
> 
> Input comes closest to this, but its approach of treating all data as events
> and providing significant filtering options (obvously tailored to human input)
> means that it isn't light weight.
> 
> The approach taken in IIO is to provide a 'buffered' interface.
> 
> The buffer may be in hardware or in software. The 'data' outputs of the
> devices being considered can be mapped onto the concept of 'scans'.  In ADCs it
> is common to have a single actually convertor connected via a multiplexer to a
> much larger set of inputs. The multiplexer will select the channels in turn in a
> repeating sequence.  Each repeat is termed a scan.  The whole scan clearly
> doesn't always occur simultaneously, but can be considered as a single set
> of associated data none the less.  Thus we have repeating sequences of data.
> This means that the meta data about what we are reading can be read
> 'out of band' from the data stream itself.
> 
> In IIO the buffers consist of a sequence of scans. The contents of each scan
> data set (laid out however a driver wants to do it) is provided via a set of
> sysfs attributes in the scan_elements directory.
> 
> The reason we can do it this way is that unlike input we pass our 'unusual'
> events via a different path.
> (see point 3).
> 
> We also allow for the minimum amount of processing of data to occur in the
> kernel possible. Its often best to leave this to userspace and in a number
> of important use cases doesn't need doing at all, either because it can be
> done offline (logging) or because the reverse transform can be applied
> to a much smaller set of data (e.g. software threshold comparison).  Note
> that the raw value off the sensor is often considerably more compact to store
> than a value in some set of consistent units.
> 
> 3 - Generic and consistent 'event' handling.
> 
> Numerous sensing devices provide threshold type detectors designed to do
> simple comparisons on the data without involving the host device.
> 
> In input, these are passed within the main event stream (we don't as that
> would mean all data would need to carry identifying metadata along).  Where
> these events map to typical human input device elements (double click etc)
> these are well handled. Hwmon supports a small set of such events via its alarm
> attributes.
> 
> For IIO we have decided to try and create an event code (litterally one number)
> to describe all types of events that these devices can detect and pass on to
> the host device. This is coupled with appropriate sysfs controls to configure
> the event.  The event code consists of:
> 
> 1) What type of channel
> 
> 2) Which channel (either axis / index or just index) Note this can be compound
> if modified. (e.g. freefall is typically X&Y&Z all less than alpha)
> 
> 3) What type of processed data it is applied to (raw value, abs value,
> rate of change, average shifted value)
> 
> 4) Which direction the threshold is crossed in.
> 
> 4 - Device coverage with a consistent interface
> 
> Hwmon and input have consistent interfaces that cover their chosen target well.
> When considering a wider range of sensors they simply don't generalize well
> enough. Afterall why should they?
> 
> Initially we matched hwmon where ever possible. In the end we broke away for a
> number of reasons. The in / out naming for voltage is a nasty bit of legacy for
> them which we don't want to carry. There is no general way of specifying whether
> a channel is an input or an output.  Having said that there is an easy mapping
> from IIO to hwmon (see possible future work).
> 
> Input is only interested in a narrow set of devices (those for human input).
> 
> 5) Complex triggering setups
> 
> This is probably more of a niche requirement but the generalizations required
> for it do simplify simple cases as well.
> 
> In a traditional data capturing environment (picture oscilloscopes / data
> loggers), the concept of a trigger is vital.  That is, some event on which
> data is captured.
> 
> In IIO this point is stretched somewhat.  For some devices it is indeed the
> point of capture (those with explicit 'capture now' pins, or those that
> capture when asked to by a bus transaction).  For other devices that run on
> their own internal clocks this is actualy a 'data has been captured now'
> signal (dataready).
> 
> What we want to allow (where possible) is for any device to be triggered by
> any other and crucially for any number of devices to be triggered by a single
> source.  As Thomas Gleixner observed, this is pretty much an irq cascade
> (and hence that's how it is now implemented - a very tidy approach!).
> 
> Some of the types of trigger we have are:
> 
> a) Data ready signals
>    These usually need to be used to trigger reading from the device producing
>    them but can be used to get only 'slightly' late readings from other devices.
> b) Software triggers
>    These allow userspace to trigger simultaneous capture from a number of
>    devices.
> c) Standalone triggers.
>    General interrupts from whereever can be used to cause a capture to occur
>    - typically a gpio.
> d) hardware timers
>    (could probably do with a more consistent interface outside of IIO for
>    these).
> 
> 6) Support output devices.
> 
> This is a relatively recent addition to IIO (despite us planning on it when
> the name was picked!).  Right now the support is very rudimentary -
> corresponding to the most basic sysfs only device interfaces.
> 
> It becomes more interesting when buffered outputs are considered, but that
> has not yet been implemented.
> 
> There is rudimentary support for output in hwmon (as is appropriate for its
> use domain) and indeed some of this could map to the regulator api, but
> neither is adaptable or suitable for more complex data flows.
> 
> 
> 
> 
> To get an appreciation for the whole subsystem it is necessary to look at
> what is still in staging as we aren't attempting to move the whole core
> out in one go.  Naturally if anyone fancies diving deeper into that tree
> and commenting on stuff in there it would also be welcomed.
> 
> Note however that being in staging some of the drivers are in 'interesting'
> shape.
> 
> 'Good' drivers include (and this is far from a complete list)
> 
> adc/
> 	ad7192
> 	ad7780
> 	ad7792
> 	ad799x
> 	max1363
> accel/
> 	lis3l02dq
> gyro/
> 	adis16260
> imu/
> 	adis16400
> light/
> 	tsl2563
> 
> 
> So what do we have here?
> 
> Our merge plan (order may change) has the following elements
> 
> 1) Registration core and sysfs interface
> 2) Some stripped down drivers using the above.
> 
> 3) Event interface
> 4) Extend drivers in 2 to provide event interfaces.
> 
> 5) Buffered reading interface
> 6) Extend drivers from 4 to provide buffered reading.
> 7) Pull in hardware ring buffer device examples
> 
> 8) Futher sets pulling across a few drivers at time (keeping review
> manageable!)
> 
> Drivers may be added to the subsystem at any stage (once support for
> what they use is available).
> 
> This patchset (1-2) only covers the simplest type of driver supported
> by IIO, that with only a sysfs based interface.  Please review it
> with that in mind!
> 
> Acknowledgements
> 
> A lot of thanks is due to various people during the IIO development.
> Most of it is born out by commit messages but I'd particularly like to
> thank Michael Hennerich for massive contributions and Arnd Bergmann for
> taking the time to not only suggest what we should do differently but
> to explain it to me and look at the results as they occured.
> 
> Jonathan Cameron (4):
>   IIO: Core sysfs only support.
>   IIO:ADC: max1363 initial import.
>   IIO:light:tsl2563 initial move out of staging.
>   IIO:imu:adis16400 partial move from staging.
> 
>  drivers/Kconfig                  |    2 +
>  drivers/Makefile                 |    2 +
>  drivers/iio/Kconfig              |   19 +
>  drivers/iio/Makefile             |   10 +
>  drivers/iio/adc/Kconfig          |   17 +
>  drivers/iio/adc/Makefile         |    6 +
>  drivers/iio/adc/max1363.h        |  148 ++++++
>  drivers/iio/adc/max1363_core.c   | 1000 ++++++++++++++++++++++++++++++++++++
>  drivers/iio/iio.c                |  593 +++++++++++++++++++++
>  drivers/iio/imu/Kconfig          |   10 +
>  drivers/iio/imu/Makefile         |    6 +
>  drivers/iio/imu/adis16400.h      |  180 +++++++
>  drivers/iio/imu/adis16400_core.c | 1057 ++++++++++++++++++++++++++++++++++++++
>  drivers/iio/light/Kconfig        |   14 +
>  drivers/iio/light/Makefile       |    6 +
>  drivers/iio/light/tsl2563.c      |  653 +++++++++++++++++++++++
>  include/linux/iio/iio.h          |  243 +++++++++
>  include/linux/iio/sysfs.h        |   68 +++
>  include/linux/iio/tsl2563.h      |    9 +
>  19 files changed, 4043 insertions(+), 0 deletions(-)
>  create mode 100644 drivers/iio/Kconfig
>  create mode 100644 drivers/iio/Makefile
>  create mode 100644 drivers/iio/adc/Kconfig
>  create mode 100644 drivers/iio/adc/Makefile
>  create mode 100644 drivers/iio/adc/max1363.h
>  create mode 100644 drivers/iio/adc/max1363_core.c
>  create mode 100644 drivers/iio/iio.c
>  create mode 100644 drivers/iio/imu/Kconfig
>  create mode 100644 drivers/iio/imu/Makefile
>  create mode 100644 drivers/iio/imu/adis16400.h
>  create mode 100644 drivers/iio/imu/adis16400_core.c
>  create mode 100644 drivers/iio/light/Kconfig
>  create mode 100644 drivers/iio/light/Makefile
>  create mode 100644 drivers/iio/light/tsl2563.c
>  create mode 100644 include/linux/iio/iio.h
>  create mode 100644 include/linux/iio/sysfs.h
>  create mode 100644 include/linux/iio/tsl2563.h
>