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 > -- To unsubscribe from this list: send the line "unsubscribe linux-iio" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
