Staging:IIO: New ABI
Dear All,
An extensive conversation with Manuel Stahl that grew out of his work on an ADIS16400 driver and the userspace IIO tools at iioutils.sourceforge.net showed that there were a number of significant short comings in the current IIO ABI. Some of these were simply things that have never been pinned down, others are down to silly issues with how the code has developed.
Hence Manuel and I have drawn up a new ABI specification. With hindsight we should probably have held the entire conversation publicly but this document will hopefully act as summary.
Please forgive the flagrant abuse of syntax in large parts of this file. This will all be cleaned up before a formal submission. At this stage what we are after is comments on the actual IIO sysfs ABI. There are doubtlessly unclear sections and elements we have forgotten completely so if you know of something that is missing (along with a concrete example of where it is needed, please do point it out!)
To avoid an insanely long ABI spec, I've suppressed fields that are not of interest to this discussion and not specified some items that are similar in purpose to those given for volt channels.
All comments welcome. One area of extreme complexity currently is that of event handling and specifically how come up with a consistent generalizable specification when there are so many different options. Comments / suggestions on this are particularly welcome!
As ever, if people could forward / cc anyone how they think may be interested that would be great. The current cc list is based on a fairly rapid dash through previous threads.
What: /sys/class/iio/device[n]
Description:
Hardware chip or device accessed by on communication port. Corresponds to a grouping of sensor channels.
What: /sys/class/iio/trigger[n]
Description:
An event driven driver of data capture to an in kernel buffer. May be provided a device driver that also has an IIO device based on hardware generated events (e.g. data ready) or provided by other hardware (e.g. periodic timer or gpio) Contains trigger type specific elements. These do not generalize well.
What: /sys/class/iio/ring_buffer[m]
Description:
Link to /sys/class/iio/device[n]/ring_buffer[m]. Ring buffer numbering may not match that of device as some devices do not have ring buffers.
What: /sys/class/iio/device[n]/name
Description:
Description of the physical chip / device. Typically a part number.
What: /sys/class/iio/device[n]/volt_[name][m]_raw
Description:
Raw (unscaled no bias removal etc) voltage measurement from channel m. name is used in special cases where this does not correspond to externally available input (e.g. supply voltage monitoring).
What: /sys/class/iio/device[n]/volt_[name][m]_offset
Description:
If known for a device, offset to be added to volt[m]_raw prior to scaling by volt[m]_scale in order to obtain voltage in Volts. Not present if the offset is always 0 or unknown. If m is not present, then voltage offset applies to all volt channels. May be writable if a variable offset is controlled by the device. Note that this is different to calibbias which is for devices that apply offsets to compensate for variation between different instances of the part.
What: /sys/class/iio/device[n]/volt_[name][m]_offset_available
Description:
If a small number of discrete offset values are available, this will be a space separated list. If these are independant (but options the same) for individual offsets then m should not be present.
What: /sys/class/iio/device[n]/volt_[name][m]_offset_[min|max]
Description:
If a more or less continuous range of voltage offsets are supported then this specifies the minimum / maximum. If shared by all volt channels then m is not present.
What: /sys/class/iio/device[n]/volt_[name][m]_calibbias
Description:
Hardware applied calibration offset. (assumed to fix production inaccuracies)
What /sys/class/iio/device[n]/volt_[name][m]_calibscale
Description:
Hardware applied calibration scale factor. (assumed to fix production inaccuracies)
What: /sys/class/iio/device[n]/volt_[name][m]_scale
Description:
If known for a device, scale to be applied to volt[m]_raw post addition of volt[m]_offset in order to obtain the measured voltage
in volts. If shared across all voltage channels the m is not present.
What: /sys/class/iio/device[n]/accel_[x|y|z][m]_raw
Description:
Acceleration in direction x, y or z (may be arbitrarily assigned but should match other such assignments on device) channel m (not present if only one accelerometer channel at this orientation). Has all of the equivalent parameters as per volt[m]. Units after application of scale and offset are m/s^2.
What: /sys/class/iio/device[n]/gyro_[x|y|z][m]_raw
Description:
Angular velocity about axis x,y or z (may be arbitrarily assigned) channel m (not present if only one gyroscope at this orientation). Data converted by application of offset then scale to radians per second. Has all the equivalent parameters as per volt[m].
What: /sys/class/iio/device[n]/mag_[x|y|z][m]_raw
Description:
Magnetic field along axis x, y or z (may be arbitrarily assigned) channel m (not present if only one magnetometer at this orientation). Data converted by application of offset then scale to Gauss Has all the equivalent modifiers as per volt[m].
What: /sys/class/iio/device[n]/pressure[m]_raw
Description:
Barometric pressure
//Lots more to add along a similar vain.
What: /sys/class/iio/device[n]/event_line[m]
Description:
Configuration of which hardware generated events are passed up to userspace. Some of these are a bit complex to generalize so this section is a work in progress.
What: /sys/class/iio/device[n]/event_line[m]/dev
Description:
major:minor character device numbers.
Again taking accel_x0 as example and serious liberties with ABI spec.
What: /sys/.../event_line[m]/accel_x0_thresh[_high|_low]
Description:
Event generated when accel_x0 passes a threshold in correction direction (or stays beyond one). If direction isn't specified, either triggers it. Note driver will assume last p events requested are enabled where p is however many it supports. So if you want to be sure you have set what you think you have, check the contents of these. Drivers may have to buffer any parameters so that they are consistent when a given event type is enabled a future point (and not those for whatever alarm was previously enabled).
What: /sys/.../event_line[m]/accel_x0_roc[_high|_low]
Description:
Same as above but based on the first differential of the value.
What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_period
Description:
A period of time (microsecs) for which the condition must be broken before an interrupt is triggered. Applies to all alarms if type is not specified.
What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_value
Description:
The actual value of the threshold either in raw device units obtained by reverse application of scale and offfset to the acceleration in m/s^2.
What: /sys/.../event_line[m]/free_fall
Description:
Common hardware event in accelerometers. Takes no parameters.
There are many other weird and wonderful event types that we'll deal with as and when.
Taking accel_x0 for example of next section.
What: /sys/class/iio/device[n]/scan_elements/[m]_accel_x0_en
Description:
Scan element control for triggered data capture. m implies the ordering within the buffer. Next the type is specified with modifier and channel number as per the sysfs single channel access above.
What: /sys/class/iio/device[n]/scan_elements/accel[_x0]_precision
Description:
Scan element precision within the ring buffer. Note that the data alignment must restrictions must be read from in ring_buffer to work out full data alignment for data read via ring_access chrdev. _x0 dropped if shared across all acceleration channels.
What: /sys/class/iio/device[n]/scan_elements/accel[_x0]_shift
Description:
A bit shift (to right) that must be applied prior to extracting the bits specified by accel[_x0]_precision.
What: /sys/class/iio/device[n]/ring_buffer[m]
Description:
Ring buffer specific parameters separate. Some are influenced by scan_elements.
What: /sys/.../ring_buffer[m]/ring_event[o]/dev
Description:
Ring buffer m event character device o major:minor numbers.
What: /sys/.../ring_buffer[m]/ring_access[o]/dev
Description:
Ring buffer m access character device o major:minor numbers.
What: /sys/.../ring_buffer[m]/trigger
Description:
The name of the trigger source being used, as per string given in /sys/class/iio/trigger[n]/name.
What: /sys/.../ring_buffer[m]/length
Description:
Number of scans contained by the buffer.
What: /sys/.../ring_buffer[m]/bps
Description:
Bytes per scan. Due to alignment fun, the scan may be larger than implied directly by the scan_element parameters.
What: /sys/.../ring_buffer[m]/enable
Description:
Actually start the ring buffer capture up. Will start trigger if first device and appropriate.
What: /sys/.../ring_buffer[m]/alignment
Description:
Minimum data alignment. Scan elements larger than this are aligned to the nearest power of 2 times this. (may not be true in weird hardware ring buffers that pack data well)
So an example, adis16350
/sys/class/iio contains
device0
accel_scale (applies to all accel channels)
accel_x_raw (the raw reading)
accel_x_calibbias (calibration value - in reg XACCEL_OFF
accel_x_raw_offset assumed to be 0 so not provided).
accel_y_raw
accel_y_calibbias
accel_z_raw
accel_z_calibbias
gyro_scale
gyro_x_raw
gyro_x_calibbias
gyro_y_raw
gyro_x_calibbias
gyro_z_raw
gyro_z_calbbias
volt_0_raw
volt_0_scale
volt_supply_raw
volt_supply_scale
temp_gyrox_raw (These are somewhat unusual!)
temp_scale
temp_offset
temp_gyroy_raw
temp_gyroz_raw
frequency (applies even when trigger not running)
//some stuff that may not generalise...
auto_bias_calib
auto_bias_calib_precision
restore_factory
gyro_compensate_accel
accel_origin_align
//associated trigger can be navigated to via device directory. Also the default //trigger will be set correctly. Not in ring_buffer as that directory may become //dependent on live configurable ring buffer types. (spurious argument?) trigger/
current_trigger
ring_buffer0/
ring_access0
dev
ring_event0
dev
length
bps
ring_enable
alignment
scan_elements
00_volt_supply_en
01_gyro_x_en
02_gyro_y_en
03_gyro_z_en
04_accel_x_en
05_accel_y_en
06_accel_z_en
07_temp_gyrox_en
08_temp_gyroy_en
09_temp_gyroz_en
10_volt_0_en
gyro_prescision
accel_precision
volt_0_precision
volt_supply_precision
temp_precision
event_line0/
dev
accel_x_thresh_high_en
accel_x_thresh_high_value
accel_x_thresh_high_period
accel_x_thresh_low_en
accel_x_thresh_low_value
accel_x_thresh_low_period
accel_x_roc_high_en
accel_x_roc_high_value
accel_x_roc_high_period
accel_x_roc_low_en
accel_x_roc_low_value
accel_x_roc_low_period
//etc. This may seem overkill but this the only option that I
//can think of that generalizes well. Other suggestions welcome!
//device specific (may generalize)
filteredtrigger0/ (adis16350 is providing a data ready trigger)
name
//there are no other parameters here as the datardy frequency is dependent //on how device is configured. (I think it makes more sense in device).
Quoted 15 lines · Jonathan Cameron
What: /sys/class/iio/device[n]
Description:
Hardware chip or device accessed by on communication port. Corresponds to a grouping of sensor channels.What: /sys/class/iio/trigger[n]
Description:
An event driven driver of data capture to an in kernel buffer. May be provided a device driver that also has an IIO device based on hardware generated events (e.g. data ready) or provided by other hardware (e.g. periodic timer or gpio) Contains trigger type specific elements. These do not generalize well.
Quoted 5 lines
What: /sys/class/iio/ring_buffer[m]
Description:
Link to /sys/class/iio/device[n]/ring_buffer[m]. Ring buffer numbering may not match that of device as some devices do not have ring buffers.
Why is this link needed? Why can't you just look in the device directory for a ring buffer? And wouldn't the ring buffer be 1..n for every device? They shouldn't be "unique" for all iio devices, that would be wierd.
Quoted 11 lines
What: /sys/class/iio/device[n]/name
Description:
Description of the physical chip / device. Typically a part number.What: /sys/class/iio/device[n]/volt_[name][m]_raw
Description:
Raw (unscaled no bias removal etc) voltage measurement from channel m. name is used in special cases where this does not correspond to externally available input (e.g. supply voltage monitoring).
So what would 'name' be?
Quoted 34 lines
What: /sys/class/iio/device[n]/volt_[name][m]_offset
Description:
If known for a device, offset to be added to volt[m]_raw prior to scaling by volt[m]_scale in order to obtain voltage in Volts. Not present if the offset is always 0 or unknown. If m is not present, then voltage offset applies to all volt channels. May be writable if a variable offset is controlled by the device. Note that this is different to calibbias which is for devices that apply offsets to compensate for variation between different instances of the part.What: /sys/class/iio/device[n]/volt_[name][m]_offset_available
Description:
If a small number of discrete offset values are available, this will be a space separated list. If these are independant (but options the same) for individual offsets then m should not be present.What: /sys/class/iio/device[n]/volt_[name][m]_offset_[min|max]
Description:
If a more or less continuous range of voltage offsets are supported then this specifies the minimum / maximum. If shared by all volt channels then m is not present.What: /sys/class/iio/device[n]/volt_[name][m]_calibbias
Description:
Hardware applied calibration offset. (assumed to fix production inaccuracies)What /sys/class/iio/device[n]/volt_[name][m]_calibscale
Description:
Hardware applied calibration scale factor. (assumed to fix production inaccuracies)
Quoted 5 lines
What: /sys/class/iio/device[n]/volt_[name][m]_scale
Description:
If known for a device, scale to be applied to volt[m]_raw post addition of volt[m]_offset in order to obtain the measured voltage
in volts. If shared across all voltage channels the m is not present.
For all of these voltage measurements, why use something different from what the kernel already supports for the existing hardware monitoring devices? There is already a well-defined api for these things.
Quoted 7 lines
What: /sys/class/iio/device[n]/accel_[x|y|z][m]_raw
Description:
Acceleration in direction x, y or z (may be arbitrarily assigned but should match other such assignments on device) channel m (not present if only one accelerometer channel at this orientation). Has all of the equivalent parameters as per volt[m]. Units after application of scale and offset are m/s^2.
Shouldn't this just use the existing input accelerometer interface so as to keep userspace sane?
Quoted 6 lines
What: /sys/class/iio/device[n]/gyro_[x|y|z][m]_raw
Description:
Angular velocity about axis x,y or z (may be arbitrarily assigned) channel m (not present if only one gyroscope at this orientation). Data converted by application of offset then scale to radians per second. Has all the equivalent parameters as per volt[m].
Same as above, I think we already have an api for this.
Quoted 7 lines
What: /sys/class/iio/device[n]/mag_[x|y|z][m]_raw
Description:
Magnetic field along axis x, y or z (may be arbitrarily assigned) channel m (not present if only one magnetometer at this orientation). Data converted by application of offset then scale to Gauss Has all the equivalent modifiers as per volt[m].
Quoted 5 lines
What: /sys/class/iio/device[n]/pressure[m]_raw
Description:
Barometric pressure//Lots more to add along a similar vain.
Again, look at the existing apis, if we don't have the exiting units and types, we can always add them, instead of making up new ones burried in the iio class stuff.
Quoted 9 lines
What: /sys/class/iio/device[n]/event_line[m]
Description:
Configuration of which hardware generated events are passed up to userspace. Some of these are a bit complex to generalize so this section is a work in progress.What: /sys/class/iio/device[n]/event_line[m]/dev
Description:
major:minor character device numbers.
No, don't bury devices down a level in sysfs, that's not ok. Actually, I think it would take you a lot of work to get this to properly work on the implementation side :)
If event_lines need device nodes, then they should be real devices.
Actually, all of this looks like it needs to be a bus, not a class, if you are having this many different types of things hanging off of them. Have you thought about that instead? It would make your code a lot easier in the end.
Quoted 24 lines
Again taking
accel_x0as example and serious liberties with ABI spec.What: /sys/.../event_line[m]/accel_x0_thresh[_high|_low]
Description:
Event generated whenaccel_x0passes a threshold in correction direction (or stays beyond one). If direction isn't specified, either triggers it. Note driver will assume last p events requested are enabled where p is however many it supports. So if you want to be sure you have set what you think you have, check the contents of these. Drivers may have to buffer any parameters so that they are consistent when a given event type is enabled a future point (and not those for whatever alarm was previously enabled).What: /sys/.../event_line[m]/accel_x0_roc[_high|_low]
Description:
Same as above but based on the first differential of the value.What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_period
Description:
A period of time (microsecs) for which the condition must be broken before an interrupt is triggered. Applies to all alarms if type is not specified.
Quoted 5 lines
What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_value
Description:
The actual value of the threshold either in raw device units obtained by reverse application of scale and offfset to the acceleration in m/s^2.
Again, look at our existing apis, I think we already cover these types of things, don't create new ones please.
Quoted 3 lines
What: /sys/.../event_line[m]/free_fall
Description:
Common hardware event in accelerometers. Takes no parameters.
I know we have this one already, please use it.
Quoted 25 lines
There are many other weird and wonderful event types that we'll deal with as and when.
Taking
accel_x0for example of next section.What: /sys/class/iio/device[n]/scan_elements/[m]_accel_x0_en
Description:
Scan element control for triggered data capture. m implies the ordering within the buffer. Next the type is specified with modifier and channel number as per the sysfs single channel access above.What: /sys/class/iio/device[n]/scan_elements/accel[_x0]_precision
Description:
Scan element precision within the ring buffer. Note that the data alignment must restrictions must be read from inring_bufferto work out full data alignment for data read viaring_accesschrdev._x0dropped if shared across all acceleration channels.What: /sys/class/iio/device[n]/scan_elements/accel[_x0]_shift
Description:
A bit shift (to right) that must be applied prior to extracting the bits specified by accel[_x0]_precision.
Quoted 8 lines
What: /sys/class/iio/device[n]/ring_buffer[m]
Description:
Ring buffer specific parameters separate. Some are influenced byscan_elements.What: /sys/.../ring_buffer[m]/ring_event[o]/dev
Description:
Ring buffer m event character device o major:minor numbers.
Again, don't bury devices. Or if you are, use a bus, not a class, that's the wrong classification.
thanks,
greg k-h
Quoted 11 lines · Greg KH
Quoted 5 lines · Jonathan Cameron
What: /sys/class/iio/ring_buffer[m]
Description:
Link to /sys/class/iio/device[n]/ring_buffer[m]. Ring buffer numbering may not match that of device as some devices do not have ring buffers.Why is this link needed? Why can't you just look in the device directory for a ring buffer? And wouldn't the ring buffer be 1..n for every device? They shouldn't be "unique" for all iio devices, that would be wierd.
I think with the hidden class kobject we successfully prevent any custom links from being created there. :) The class sysfs layout does not allow custom links added to its single directory, it confuses userspace.
Jonathan, if you need anything like this, please consider using a "bus_type", which has the proper userspace interface. The "class" interface can not be extended to make such things possible.
Thanks,
Kay
Hi Greg,
Quoted 22 lines · Jonathan Cameron
Quoted 15 lines
What: /sys/class/iio/device[n]
Description:
Hardware chip or device accessed by on communication port. Corresponds to a grouping of sensor channels.What: /sys/class/iio/trigger[n]
Description:
An event driven driver of data capture to an in kernel buffer. May be provided a device driver that also has an IIO device based on hardware generated events (e.g. data ready) or provided by other hardware (e.g. periodic timer or gpio) Contains trigger type specific elements. These do not generalize well.Quoted 5 lines
What: /sys/class/iio/ring_buffer[m]
Description:
Link to /sys/class/iio/device[n]/ring_buffer[m]. Ring buffer numbering may not match that of device as some devices do not have ring buffers.
Quoted 4 lines
Why is this link needed? Why can't you just look in the device directory for a ring buffer? And wouldn't the ring buffer be 1..n for every device? They shouldn't be "unique" for all iio devices, that would be wierd.
I'm a little unclear what you mean here (so my apologies if I'm misinterpreting!) A given IIO device will indeed have a either none or typically 1 ring buffers. They are not currently shared across devices. Aggregation if desired is done in userspace.
Curiously enough there has been some argument in favour of a buffer per channel but that is a whole different issue.
Reasons to have independent buffer per device:
1) Simplicity of handling a lot of data. Rates we are catering for go up to MSPs.
2) Low overheads. Using the interface given here userspace knows what is in the buffer so you simply store data, not headers which would be needed in shared buffers. (being able to do this is what a lot of the api below is about).
3) Applications do not desire aggregation of data from different sensors, or if they do this is better handled in user space where we can waste time figuring out data set alignment offline.
There are cases where a trigger is shared across multiple devices, where it may make sense to share a ring buffer but the management of that is rather complex so has been left for now.
e.g. How do you handle a case where a trigger is too fast for one of your two sensors so it misses a reading without every single reading requiring a header? (toy example of the fun that occurs!)
Also note that in some cases the ring buffer is very much unique to the device: It is in hardware on it. (sca3000 for example)
Quoted 6 lines
Quoted 6 lines
What: /sys/class/iio/device[n]/name
Description:
Description of the physical chip / device. Typically a part number.
Quoted 8 lines
Quoted 6 lines
What: /sys/class/iio/device[n]/volt_[name][m]_raw
Description:
Raw (unscaled no bias removal etc) voltage measurement from channel m. name is used in special cases where this does not correspond to externally available input (e.g. supply voltage monitoring).So what would 'name' be?
This is for a few device corner cases such as volt_supply_raw for the the adis16350 below. It can't really be used as a general purpose ADC so the idea was to separate it out. The vast majority of voltage channels would simply be numbered. There is an argument that, it might make sense to support this single parameter via hwmon, but then there are high end gyros where we would be grabbing the voltage, temperature and actual reading on each trigger so as to be able to compensate for the huge difference these can make to the resulting data.
Quoted 41 lines
Quoted 35 lines
What: /sys/class/iio/device[n]/volt_[name][m]_offset
Description:
If known for a device, offset to be added to volt[m]_raw prior to scaling by volt[m]_scale in order to obtain voltage in Volts. Not present if the offset is always 0 or unknown. If m is not present, then voltage offset applies to all volt channels. May be writable if a variable offset is controlled by the device. Note that this is different to calibbias which is for devices that apply offsets to compensate for variation between different instances of the part.What: /sys/class/iio/device[n]/volt_[name][m]_offset_available
Description:
If a small number of discrete offset values are available, this will be a space separated list. If these are independant (but options the same) for individual offsets then m should not be present.What: /sys/class/iio/device[n]/volt_[name][m]_offset_[min|max]
Description:
If a more or less continuous range of voltage offsets are supported then this specifies the minimum / maximum. If shared by all volt channels then m is not present.What: /sys/class/iio/device[n]/volt_[name][m]_calibbias
Description:
Hardware applied calibration offset. (assumed to fix production inaccuracies)What /sys/class/iio/device[n]/volt_[name][m]_calibscale
Description:
Hardware applied calibration scale factor. (assumed to fix production inaccuracies)Quoted 5 lines
What: /sys/class/iio/device[n]/volt_[name][m]_scale
Description:
If known for a device, scale to be applied to volt[m]_raw post addition of volt[m]_offset in order to obtain the measured voltage
in volts. If shared across all voltage channels the m is not present.
Quoted 3 lines
For all of these voltage measurements, why use something different from what the kernel already supports for the existing hardware monitoring devices? There is already a well-defined api for these things.
Agreed. We did consider using in0 etc as per hwmon but decided that we were breaking sufficiently from the approach there (where the readings are always provided in microvolts iirc) that we could change the name to something that was a little more specific. I'm not overly tied to volt but the semantics are different enough here (with offsets and gain passed to userspace) that we may actually create confusion by mirroring that api.
Quoted 11 lines
Quoted 8 lines
What: /sys/class/iio/device[n]/accel_[x|y|z][m]_raw
Description:
Acceleration in direction x, y or z (may be arbitrarily assigned but should match other such assignments on device) channel m (not present if only one accelerometer channel at this orientation). Has all of the equivalent parameters as per volt[m]. Units after application of scale and offset are m/s^2.Shouldn't this just use the existing input accelerometer interface so as to keep userspace sane?
Again, it comes down to whether we process the data or not. IIO is all about the ability to handle things fast. These sysfs interfaces are actually meant to mirror the chrdev ring buffer accesses which are the primary access point for higher end devices. A lot of the use cases are either interested in logging for later use, or algorithms that will run in the device units (sometime in integer arithmetic). Hence all conversion to sane units is left to userspace. The drivers merely provide sufficient information to do this conversion if it is desired.
Quoted 21 lines
Quoted 7 lines
What: /sys/class/iio/device[n]/gyro_[x|y|z][m]_raw
Description:
Angular velocity about axis x,y or z (may be arbitrarily assigned) channel m (not present if only one gyroscope at this orientation). Data converted by application of offset then scale to radians per second. Has all the equivalent parameters as per volt[m].Same as above, I think we already have an api for this.
Quoted 11 lines
What: /sys/class/iio/device[n]/mag_[x|y|z][m]_raw
Description:
Magnetic field along axis x, y or z (may be arbitrarily assigned) channel m (not present if only one magnetometer at this orientation). Data converted by application of offset then scale to Gauss Has all the equivalent modifiers as per volt[m].What: /sys/class/iio/device[n]/pressure[m]_raw
Description:
Barometric pressure
Quoted 5 lines
Quoted 1 line
//Lots more to add along a similar vain.
Again, look at the existing apis, if we don't have the exiting units and types, we can always add them, instead of making up new ones burried in the iio class stuff.
I'm happy matching units (post conversion) but we really really don't want to convert in kernel. When you are dealing with a few hundred Hz this is fine, here it could mean halving your maximum sample rate or worse. Just consider the loops some hwmon drivers jump through to do this in integer arithmetic (I know, I wrote one of the most hideous ;)
Quoted 7 lines
Quoted 7 lines
What: /sys/class/iio/device[n]/event_line[m]
Description:
Configuration of which hardware generated events are passed up to userspace. Some of these are a bit complex to generalize so this section is a work in progress.
Quoted 7 lines
Quoted 3 lines
What: /sys/class/iio/device[n]/event_line[m]/dev
Description:
major:minor character device numbers.No, don't bury devices down a level in sysfs, that's not ok. Actually, I think it would take you a lot of work to get this to properly work on the implementation side :)
This bit of the documentation is indeed wrong (oops). These are members of the IIO class and so this is just a link (much like the event elements in input) created by making them in class iio with the device as a a parent. Again, application wise we aren't normally interested in aggregation so there is one (or more) of these per device.
Quoted 2 lines
If
event_linesneed device nodes, then they should be real devices.
(oops) The are ;)
Quoted 5 lines
Actually, all of this looks like it needs to be a bus, not a class, if you are having this many different types of things hanging off of them. Have you thought about that instead? It would make your code a lot easier in the end.
That is definitely an option. The reason we didn't is more to do with following the most similar current case (input) than any particular preference.
Quoted 25 lines
Quoted 25 lines
Again taking
accel_x0as example and serious liberties with ABI spec.What: /sys/.../event_line[m]/accel_x0_thresh[_high|_low]
Description:
Event generated whenaccel_x0passes a threshold in correction direction (or stays beyond one). If direction isn't specified, either triggers it. Note driver will assume last p events requested are enabled where p is however many it supports. So if you want to be sure you have set what you think you have, check the contents of these. Drivers may have to buffer any parameters so that they are consistent when a given event type is enabled a future point (and not those for whatever alarm was previously enabled).What: /sys/.../event_line[m]/accel_x0_roc[_high|_low]
Description:
Same as above but based on the first differential of the value.What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_period
Description:
A period of time (microsecs) for which the condition must be broken before an interrupt is triggered. Applies to all alarms if type is not specified.
Quoted 8 lines
Quoted 5 lines
What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_value
Description:
The actual value of the threshold either in raw device units obtained by reverse application of scale and offfset to the acceleration in m/s^2.Again, look at our existing apis, I think we already cover these types of things, don't create new ones please.
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Quoted 6 lines
Quoted 4 lines
What: /sys/.../event_line[m]/free_fall
Description:
Common hardware event in accelerometers. Takes no parameters.I know we have this one already, please use it.
Again, does it make sense to match api when the result is very different? The event infrastructure in IIO is much slimmer than that in input (this was one of the original reasons for not simply adding these things to input in the first place). This particular example is a bit unusual in that the current api (hwmon/lis3lv02d.c for example) handles this via a dedicated freefall character device. This doesn't really generalize to the more complex events handled here. To be honest this one doesn't really make sense in IIO's intended applications so it might be best to drop it entirely!
We come back to an issue that turned up in the first discussions. There are cases where the possible use cases of some of these sensors differ so much that it may make sense to have completely separate drivers.
Quoted 31 lines
Quoted 31 lines
There are many other weird and wonderful event types that we'll deal with as and when.
Taking
accel_x0for example of next section.What: /sys/class/iio/device[n]/scan_elements/[m]_accel_x0_en
Description:
Scan element control for triggered data capture. m implies the ordering within the buffer. Next the type is specified with modifier and channel number as per the sysfs single channel access above.What: /sys/class/iio/device[n]/scan_elements/accel[_x0]_precision
Description:
Scan element precision within the ring buffer. Note that the data alignment must restrictions must be read from inring_bufferto work out full data alignment for data read viaring_accesschrdev._x0dropped if shared across all acceleration channels.What: /sys/class/iio/device[n]/scan_elements/accel[_x0]_shift
Description:
A bit shift (to right) that must be applied prior to extracting the bits specified by accel[_x0]_precision.What: /sys/class/iio/device[n]/ring_buffer[m]
Description:
Ring buffer specific parameters separate. Some are influenced byscan_elements.
Quoted 6 lines
Quoted 3 lines
What: /sys/.../ring_buffer[m]/ring_event[o]/dev
Description:
Ring buffer m event character device o major:minor numbers.Again, don't bury devices. Or if you are, use a bus, not a class, that's the wrong classification.
Cool, I'll look into making the change. What we really have here is a single conceptual device using a pair or character interfaces. Is a bus the right way to handle that?
How about the following under a bus (this is for a single physical chip).
device0
event0 (for physical events)
ringaccess0 (actual device from which data is read)
ringevent0 (associated event interface for the ring - ideally not aggregated with the event0)
and sometimes:
trigger0
Is that best way to go. Currently ringacces0 and ring event0 are grouped under ring_buffer0 but that was simply for the reason they are always matched.
Thanks for the quick response!
Jonathan
Quoted 9 lines · Jonathan Cameron
Quoted 6 lines
Quoted 3 lines
What: /sys/.../ring_buffer[m]/ring_event[o]/dev Description:
Ring buffer m event character device o major:minor numbers.Again, don't bury devices. Or if you are, use a bus, not a class, that's the wrong classification.
Cool, I'll look into making the change. What we really have here is a single conceptual device using a pair or character interfaces. Is a bus the right way to handle that?
"bus" and "class" are almost the same regarding the driver core, it should not make any difference for you. The "class" implementation is only a very simple case of a "bus" -- just with a pretty much broken userspace interface. :)
Today, if we would start from scratch, there would be only something like /sys/subsystem in the layout of today's /sys/bus, and /sys/class, /sys/bus and /sys/block would not event exist. Tools like udev intentionally make no difference between them, and do not allow to distinguish between "class" or "bus". It's just called "susbsystem" there from the early days on.
The "class" has only a single flat directory in /sys so it can never be extended with anything custom. No new subsystem should use the class interface anymore, all should use a "bus". I guess it's time to document that somewhere. :)
Thanks,
Kay
Quoted 24 lines · Jonathan Cameron
Hi Greg,
Quoted 22 lines · Jonathan Cameron
Quoted 20 lines
What: /sys/class/iio/device[n]
Description:
Hardware chip or device accessed by on communication port. Corresponds to a grouping of sensor channels.What: /sys/class/iio/trigger[n]
Description:
An event driven driver of data capture to an in kernel buffer. May be provided a device driver that also has an IIO device based on hardware generated events (e.g. data ready) or provided by other hardware (e.g. periodic timer or gpio) Contains trigger type specific elements. These do not generalize well.What: /sys/class/iio/ring_buffer[m]
Description:
Link to /sys/class/iio/device[n]/ring_buffer[m]. Ring buffer numbering may not match that of device as some devices do not have ring buffers.
Quoted 8 lines
Quoted 4 lines
Why is this link needed? Why can't you just look in the device directory for a ring buffer? And wouldn't the ring buffer be 1..n for every device? They shouldn't be "unique" for all iio devices, that would be wierd.
I'm a little unclear what you mean here (so my apologies if I'm misinterpreting!) A given IIO device will indeed have a either none or typically 1 ring buffers. They are not currently shared across devices. Aggregation if desired is done in userspace.
Ok, that's fine, but the name of those buffers do not have to be unique to all ring buffers in the system.
Hm, oh yeah, they do, ok, nevermind, stupid me :)
Quoted 13 lines
Quoted 5 lines
Quoted 5 lines
What: /sys/class/iio/device[n]/name
Description:
Description of the physical chip / device. Typically a part number.Quoted 8 lines
Quoted 6 lines
What: /sys/class/iio/device[n]/volt_[name][m]_raw
Description:
Raw (unscaled no bias removal etc) voltage measurement from channel m. name is used in special cases where this does not correspond to externally available input (e.g. supply voltage monitoring).So what would 'name' be?
Quoted 8 lines
This is for a few device corner cases such as
volt_supply_rawfor the the adis16350 below. It can't really be used as a general purpose ADC so the idea was to separate it out. The vast majority of voltage channels would simply be numbered. There is an argument that, it might make sense to support this single parameter via hwmon, but then there are high end gyros where we would be grabbing the voltage, temperature and actual reading on each trigger so as to be able to compensate for the huge difference these can make to the resulting data.
But again, what would 'name' be?
Quoted 9 lines
Quoted 9 lines
Quoted 5 lines
What: /sys/class/iio/device[n]/volt_[name][m]_scale
Description:
If known for a device, scale to be applied to volt[m]_raw post addition of volt[m]_offset in order to obtain the measured voltage
in volts. If shared across all voltage channels the m is not present.For all of these voltage measurements, why use something different from what the kernel already supports for the existing hardware monitoring devices? There is already a well-defined api for these things.
Quoted 6 lines
Agreed. We did consider using in0 etc as per hwmon but decided that we were breaking sufficiently from the approach there (where the readings are always provided in microvolts iirc) that we could change the name to something that was a little more specific. I'm not overly tied to volt but the semantics are different enough here (with offsets and gain passed to userspace) that we may actually create confusion by mirroring that api.
I really think you should merge with that api somehow.
I understand that you don't want to do conversions in the kernel, so perhaps there could be some way to show this like you have described, that the hwmon interface could also use.
That way userspace tools will work for all types of devices, and you don't have a custom interface just for these device. Unification is a good thing :)
Quoted 10 lines
Quoted 10 lines
Quoted 7 lines
What: /sys/class/iio/device[n]/accel_[x|y|z][m]_raw
Description:
Acceleration in direction x, y or z (may be arbitrarily assigned but should match other such assignments on device) channel m (not present if only one accelerometer channel at this orientation). Has all of the equivalent parameters as per volt[m]. Units after application of scale and offset are m/s^2.Shouldn't this just use the existing input accelerometer interface so as to keep userspace sane?
Quoted 8 lines
Again, it comes down to whether we process the data or not. IIO is all about the ability to handle things fast. These sysfs interfaces are actually meant to mirror the chrdev ring buffer accesses which are the primary access point for higher end devices. A lot of the use cases are either interested in logging for later use, or algorithms that will run in the device units (sometime in integer arithmetic). Hence all conversion to sane units is left to userspace. The drivers merely provide sufficient information to do this conversion if it is desired.
See above. I suggest working with the hwmon developers to add the "raw" type interface to their api making these able to be used there as well.
Quoted 10 lines
Quoted 10 lines
Quoted 9 lines
What: /sys/class/iio/device[n]/event_line[m]
Description:
Configuration of which hardware generated events are passed up to userspace. Some of these are a bit complex to generalize so this section is a work in progress.What: /sys/class/iio/device[n]/event_line[m]/dev
Description:
major:minor character device numbers.
Quoted 8 lines
Quoted 3 lines
No, don't bury devices down a level in sysfs, that's not ok. Actually, I think it would take you a lot of work to get this to properly work on the implementation side :)
This bit of the documentation is indeed wrong (oops). These are members of the IIO class and so this is just a link (much like the event elements in input) created by making them in class iio with the device as a a parent. Again, application wise we aren't normally interested in aggregation so there is one (or more) of these per device.
Ok.
Quoted 3 lines
Quoted 2 lines
If
event_linesneed device nodes, then they should be real devices.(oops) The are ;)
Heh, that will not work, as Kay described :)
Quoted 6 lines
Quoted 4 lines
Actually, all of this looks like it needs to be a bus, not a class, if you are having this many different types of things hanging off of them. Have you thought about that instead? It would make your code a lot easier in the end.
That is definitely an option. The reason we didn't is more to do with following the most similar current case (input) than any particular preference.
As Kay said, this should be a bus, and you should have devices attach to them, be it virtual or not. Or, you just tie into the hwmon interface which makes it much easier for you overall.
Quoted 30 lines
Quoted 30 lines
Quoted 29 lines
Again taking
accel_x0as example and serious liberties with ABI spec.What: /sys/.../event_line[m]/accel_x0_thresh[_high|_low]
Description:
Event generated whenaccel_x0passes a threshold in correction direction (or stays beyond one). If direction isn't specified, either triggers it. Note driver will assume last p events requested are enabled where p is however many it supports. So if you want to be sure you have set what you think you have, check the contents of these. Drivers may have to buffer any parameters so that they are consistent when a given event type is enabled a future point (and not those for whatever alarm was previously enabled).What: /sys/.../event_line[m]/accel_x0_roc[_high|_low]
Description:
Same as above but based on the first differential of the value.What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_period
Description:
A period of time (microsecs) for which the condition must be broken before an interrupt is triggered. Applies to all alarms if type is not specified.What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_value
Description:
The actual value of the threshold either in raw device units obtained by reverse application of scale and offfset to the acceleration in m/s^2.
Quoted 5 lines
Quoted 2 lines
Again, look at our existing apis, I think we already cover these types of things, don't create new ones please.
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Hm, I thought we had an accelerator interface somewhere...
Quoted 6 lines
Quoted 5 lines
Quoted 3 lines
What: /sys/.../event_line[m]/free_fall
Description:
Common hardware event in accelerometers. Takes no parameters.I know we have this one already, please use it.
Quoted 7 lines
Again, does it make sense to match api when the result is very different? The event infrastructure in IIO is much slimmer than that in input (this was one of the original reasons for not simply adding these things to input in the first place). This particular example is a bit unusual in that the current api (
hwmon/lis3lv02d.cfor example) handles this via a dedicated freefall character device. This doesn't really generalize to the more complex events handled here. To be honest this one doesn't really make sense in IIO's intended applications so it might be best to drop it entirely!
Yeah, a dedicated char device doesn't seem to make much sense either, but any unification you could find here would be nice. Even if it means the existing driver converts over to your new api :)
Quoted 13 lines
Quoted 2 lines
Again, don't bury devices. Or if you are, use a bus, not a class, that's the wrong classification.
Cool, I'll look into making the change. What we really have here is a single conceptual device using a pair or character interfaces. Is a bus the right way to handle that?
How about the following under a bus (this is for a single physical chip).
device0
event0 (for physical events)
ringaccess0 (actual device from which data is read)
ringevent0 (associated event interface for the ring - ideally not aggregated with the event0)
Quoted 6 lines
and sometimes:
trigger0Is that best way to go. Currently ringacces0 and ring event0 are grouped under
ring_buffer0but that was simply for the reason they are always matched.
Yes, that would work, and make sense.
thanks,
greg k-h
Quoted 7 lines · Greg KH
Quoted 3 lines · Jonathan Cameron
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a bunch of accelerometers, magnetometers, etc drivers that are trying to plug into input sysbsystem and quite unsure what to do with them.
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use input devnts as primary API and I am unsure if it is the best solution. Accelerometer might be used as an input device but not always an input device.
Signature · 1 line
Dmitry
Quoted 13 lines · Dmitry Torokhov
Quoted 7 lines · Greg KH
Quoted 3 lines · Jonathan Cameron
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a bunch of accelerometers, magnetometers, etc drivers that are trying to plug into input sysbsystem and quite unsure what to do with them.
Quoted 5 lines
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use input devnts as primary API and I am unsure if it is the best solution. Accelerometer might be used as an input device but not always an input device.
Yeah, I see it using a joystick interface, which might be acceptable for "toy" devices like you say.
But for "real" ones, we should do something else.
Maybe, for devices that are going to be used by x.org, like the "toy" ones, we stick with the current input interface, but for others, we use a "real" interface, probably through hwmon, so that users can get the real data out in a consistant manner.
thanks,
greg k-h
Hi Greg,
Quoted 58 lines
Quoted 22 lines
Quoted 22 lines · Jonathan Cameron
Quoted 20 lines
What: /sys/class/iio/device[n]
Description:
Hardware chip or device accessed by on communication port. Corresponds to a grouping of sensor channels.What: /sys/class/iio/trigger[n]
Description:
An event driven driver of data capture to an in kernel buffer. May be provided a device driver that also has an IIO device based on hardware generated events (e.g. data ready) or provided by other hardware (e.g. periodic timer or gpio) Contains trigger type specific elements. These do not generalize well.What: /sys/class/iio/ring_buffer[m]
Description:
Link to /sys/class/iio/device[n]/ring_buffer[m]. Ring buffer numbering may not match that of device as some devices do not have ring buffers.Quoted 8 lines
Quoted 4 lines
Why is this link needed? Why can't you just look in the device directory for a ring buffer? And wouldn't the ring buffer be 1..n for every device? They shouldn't be "unique" for all iio devices, that would be wierd.
I'm a little unclear what you mean here (so my apologies if I'm misinterpreting!) A given IIO device will indeed have a either none or typically 1 ring buffers. They are not currently shared across devices. Aggregation if desired is done in userspace.
Ok, that's fine, but the name of those buffers do not have to be unique to all ring buffers in the system.
Hm, oh yeah, they do, ok, nevermind, stupid me :)
Quoted 13 lines
Quoted 5 lines
Quoted 5 lines
What: /sys/class/iio/device[n]/name
Description:
Description of the physical chip / device. Typically a part number.Quoted 8 lines
Quoted 6 lines
What: /sys/class/iio/device[n]/volt_[name][m]_raw
Description:
Raw (unscaled no bias removal etc) voltage measurement from channel m. name is used in special cases where this does not correspond to externally available input (e.g. supply voltage monitoring).So what would 'name' be?
Quoted 8 lines
This is for a few device corner cases such as
volt_supply_rawfor the the adis16350 below. It can't really be used as a general purpose ADC so the idea was to separate it out. The vast majority of voltage channels would simply be numbered. There is an argument that, it might make sense to support this single parameter via hwmon, but then there are high end gyros where we would be grabbing the voltage, temperature and actual reading on each trigger so as to be able to compensate for the huge difference these can make to the resulting data.
Quoted 1 line
But again, what would 'name' be?
Probably an option from a small list. (supply being the only element right now!) Actually, whilst the list is small we might as well put it straight in the abi description line.
Quoted 19 lines
Quoted 10 lines
Quoted 10 lines
Quoted 6 lines
What: /sys/class/iio/device[n]/volt_[name][m]_scale
Description:
If known for a device, scale to be applied to volt[m]_raw post addition of volt[m]_offset in order to obtain the measured voltage
in volts. If shared across all voltage channels the m is not present.For all of these voltage measurements, why use something different from what the kernel already supports for the existing hardware monitoring devices? There is already a well-defined api for these things.
Quoted 6 lines
Agreed. We did consider using in0 etc as per hwmon but decided that we were breaking sufficiently from the approach there (where the readings are always provided in microvolts iirc) that we could change the name to something that was a little more specific. I'm not overly tied to volt but the semantics are different enough here (with offsets and gain passed to userspace) that we may actually create confusion by mirroring that api.
I really think you should merge with that api somehow.
Quoted 7 lines
I understand that you don't want to do conversions in the kernel, so perhaps there could be some way to show this like you have described, that the hwmon interface could also use.
That way userspace tools will work for all types of devices, and you don't have a custom interface just for these device. Unification is a good thing :)
A good point. I'll have a think about how to do this then post an update including the hwmon list to see if we can work out what needs adding to their current interface.
Quoted 54 lines
Quoted 11 lines
Quoted 11 lines
Quoted 8 lines
What: /sys/class/iio/device[n]/accel_[x|y|z][m]_raw
Description:
Acceleration in direction x, y or z (may be arbitrarily assigned but should match other such assignments on device) channel m (not present if only one accelerometer channel at this orientation). Has all of the equivalent parameters as per volt[m]. Units after application of scale and offset are m/s^2.Shouldn't this just use the existing input accelerometer interface so as to keep userspace sane?
Quoted 8 lines
Again, it comes down to whether we process the data or not. IIO is all about the ability to handle things fast. These sysfs interfaces are actually meant to mirror the chrdev ring buffer accesses which are the primary access point for higher end devices. A lot of the use cases are either interested in logging for later use, or algorithms that will run in the device units (sometime in integer arithmetic). Hence all conversion to sane units is left to userspace. The drivers merely provide sufficient information to do this conversion if it is desired.
See above. I suggest working with the hwmon developers to add the "raw" type interface to their api making these able to be used there as well.
Quoted 10 lines
Quoted 10 lines
Quoted 9 lines
What: /sys/class/iio/device[n]/event_line[m]
Description:
Configuration of which hardware generated events are passed up to userspace. Some of these are a bit complex to generalize so this section is a work in progress.What: /sys/class/iio/device[n]/event_line[m]/dev
Description:
major:minor character device numbers.Quoted 8 lines
Quoted 3 lines
No, don't bury devices down a level in sysfs, that's not ok. Actually, I think it would take you a lot of work to get this to properly work on the implementation side :)
This bit of the documentation is indeed wrong (oops). These are members of the IIO class and so this is just a link (much like the event elements in input) created by making them in class iio with the device as a a parent. Again, application wise we aren't normally interested in aggregation so there is one (or more) of these per device.
Ok.
Quoted 3 lines
Quoted 2 lines
If
event_linesneed device nodes, then they should be real devices.(oops) The are ;)
Heh, that will not work, as Kay described :)
Quoted 4 lines
Quoted 4 lines
Actually, all of this looks like it needs to be a bus, not a class, if you are having this many different types of things hanging off of them. Have you thought about that instead? It would make your code a lot easier in the end.
Quoted 6 lines
Quoted 2 lines
That is definitely an option. The reason we didn't is more to do with following the most similar current case (input) than any particular preference.
As Kay said, this should be a bus, and you should have devices attach to them, be it virtual or not. Or, you just tie into the hwmon interface which makes it much easier for you overall.
We'll definitely move over to a bus. I'd fallen for the naming and never really considered it as an option! As for tying into hwmon, I'll take another look as I can see it may be simpler with the bus structure separating the different 'devices'.
Quoted 31 lines
Quoted 31 lines
Quoted 31 lines
Quoted 30 lines
Again taking
accel_x0as example and serious liberties with ABI spec.What: /sys/.../event_line[m]/accel_x0_thresh[_high|_low]
Description:
Event generated whenaccel_x0passes a threshold in correction direction (or stays beyond one). If direction isn't specified, either triggers it. Note driver will assume last p events requested are enabled where p is however many it supports. So if you want to be sure you have set what you think you have, check the contents of these. Drivers may have to buffer any parameters so that they are consistent when a given event type is enabled a future point (and not those for whatever alarm was previously enabled).What: /sys/.../event_line[m]/accel_x0_roc[_high|_low]
Description:
Same as above but based on the first differential of the value.What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_period
Description:
A period of time (microsecs) for which the condition must be broken before an interrupt is triggered. Applies to all alarms if type is not specified.What: /sys/.../event_line[m]/accel_x0[_thresh|_roc][_high|_low]_value
Description:
The actual value of the threshold either in raw device units obtained by reverse application of scale and offfset to the acceleration in m/s^2.
Quoted 7 lines
Quoted 5 lines
Quoted 2 lines
Again, look at our existing apis, I think we already cover these types of things, don't create new ones please.
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Hm, I thought we had an accelerator interface somewhere...
(cleared up by Dmitry further down the thread)
Quoted 15 lines
Quoted 7 lines
Quoted 6 lines
Quoted 4 lines
What: /sys/.../event_line[m]/free_fall
Description:
Common hardware event in accelerometers. Takes no parameters.I know we have this one already, please use it.
Quoted 7 lines
Again, does it make sense to match api when the result is very different? The event infrastructure in IIO is much slimmer than that in input (this was one of the original reasons for not simply adding these things to input in the first place). This particular example is a bit unusual in that the current api (
hwmon/lis3lv02d.cfor example) handles this via a dedicated freefall character device. This doesn't really generalize to the more complex events handled here. To be honest this one doesn't really make sense in IIO's intended applications so it might be best to drop it entirely!
Quoted 3 lines
Yeah, a dedicated char device doesn't seem to make much sense either, but any unification you could find here would be nice. Even if it means the existing driver converts over to your new api :)
Fair point.
Quoted 14 lines
Quoted 14 lines
Quoted 3 lines
Again, don't bury devices. Or if you are, use a bus, not a class, that's the wrong classification.
Cool, I'll look into making the change. What we really have here is a single conceptual device using a pair or character interfaces. Is a bus the right way to handle that?
How about the following under a bus (this is for a single physical chip).
device0
event0 (for physical events)
ringaccess0 (actual device from which data is read)
ringevent0 (associated event interface for the ring - ideally not aggregated with the event0)
Quoted 8 lines
Quoted 6 lines
and sometimes:
trigger0Is that best way to go. Currently ringacces0 and ring event0 are grouped under
ring_buffer0but that was simply for the reason they are always matched.Yes, that would work, and make sense.
Excellent,
Thanks for taking a look at this!
Jonathan
Hi Kay,
Quoted 24 lines · Kay Sievers
Quoted 9 lines · Jonathan Cameron
Quoted 6 lines
Quoted 3 lines
What: /sys/.../ring_buffer[m]/ring_event[o]/dev
Description:
Ring buffer m event character device o major:minor numbers.Again, don't bury devices. Or if you are, use a bus, not a class, that's the wrong classification.
Cool, I'll look into making the change. What we really have here is a single conceptual device using a pair or character interfaces. Is a bus the right way to handle that?
"bus" and "class" are almost the same regarding the driver core, it should not make any difference for you. The "class" implementation is only a very simple case of a "bus" -- just with a pretty much broken userspace interface. :)
Today, if we would start from scratch, there would be only something like
/sys/subsystemin the layout of today's/sys/bus, and/sys/class,/sys/busand/sys/blockwould not event exist. Tools like udev intentionally make no difference between them, and do not allow to distinguish between "class" or "bus". It's just called "susbsystem" there from the early days on.
Quoted 5 lines
The "class" has only a single flat directory in /sys so it can never be extended with anything custom. No new subsystem should use the class interface anymore, all should use a "bus". I guess it's time to document that somewhere. :)
Thanks for clearing that up. IIO is now a bus, as you said the changes needed were very minor. I'll post the patch in a series with the ABI changes once the rest have settled down.
The move to a bus has, in a sense (by looking at how others, particularly usb handle things), suggested that the 'bus element' naming could usefully provide more information about where things have come from.
Perhaps the contents of /sys/bus/iio should be something like
dev0
dev0:event0
[dev0:event1 etc]
dev0:ring
dev0:ring:access
dev0:ring:event
Note that dev0:ring only exists as a device to allow it to be used as a common parent for dev0:ring:access and dev0:ring:event, making the internal navigation a little more obvious along with providing a site for attributes that aren't specific to the ring access or event devices.
This does lead to some slightly clunky naming inside directories, complicating user space access marginally
dev0/dev0:ring/dev0:ring:access etc
Is this added clarity something people feel is worth doing?
Jonathan
Quoted 23 lines · Greg KH
Quoted 13 lines · Dmitry Torokhov
Quoted 7 lines · Greg KH
Quoted 3 lines · Jonathan Cameron
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a bunch of accelerometers, magnetometers, etc drivers that are trying to plug into input sysbsystem and quite unsure what to do with them.
Quoted 5 lines
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use input devnts as primary API and I am unsure if it is the best solution. Accelerometer might be used as an input device but not always an input device.
Yeah, I see it using a joystick interface, which might be acceptable for "toy" devices like you say.
Quoted 7 lines
But for "real" ones, we should do something else.
Maybe, for devices that are going to be used by x.org, like the "toy" ones, we stick with the current input interface, but for others, we use a "real" interface, probably through hwmon, so that users can get the real data out in a consistant manner.
I'd rather have all of them use real interface and then have a bridge to input module to enable toyish mode (unless the device in question is really truly an input device).
Signature · 1 line
Dmitry
Quoted 36 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 23 lines · Greg KH
Quoted 13 lines · Dmitry Torokhov
Quoted 7 lines · Greg KH
Quoted 3 lines · Jonathan Cameron
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a bunch of accelerometers, magnetometers, etc drivers that are trying to plug into input sysbsystem and quite unsure what to do with them.
Quoted 5 lines
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use input devnts as primary API and I am unsure if it is the best solution. Accelerometer might be used as an input device but not always an input device.
Yeah, I see it using a joystick interface, which might be acceptable for "toy" devices like you say.
Quoted 7 lines
But for "real" ones, we should do something else.
Maybe, for devices that are going to be used by x.org, like the "toy" ones, we stick with the current input interface, but for others, we use a "real" interface, probably through hwmon, so that users can get the real data out in a consistant manner.
Quoted 6 lines
I'd rather have all of them use real interface and then have a bridge to input module to enable toyish mode (unless the device in question is really truly an input device).
--
Dmitry
I really don't see that hwmon provides facilities like input/evdev does.
Queuing of events with time stamping and multiple reader support.
The adxl34x accelerometer driver for example is really intended to be a input device. Send EV_KEY for x,y,z_TAP detections, send EV_KEY for 3D orientation sensing, and EV_ABS for acceleration. With very minor platform data customization you can use this device for game controls or GUI interaction. A few examples include digital picture frames, ebook readers, etc.
-Michael
------------------------------------------------------------------
********* Analog Devices GmbH Open Platform Solutions
** *****
** ** Wilhelm-Wagenfeld-Strasse 6
** ***** D-80807 Munich
********* Germany
Registergericht München HRB 40368, Geschäftsführer: Thomas Wessel, William A. Martin, Margaret K. Seif
Quoted 40 lines · Michael
Quoted 40 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 23 lines · Greg KH
Quoted 13 lines · Dmitry Torokhov
Quoted 7 lines · Greg KH
Quoted 3 lines · Jonathan Cameron
I am not aware of these. Could you direct me to the current api? Also note that these aren't the actual alarms, merely a means of enabling the relevant event on the related event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a bunch of accelerometers, magnetometers, etc drivers that are trying to plug into input sysbsystem and quite unsure what to do with them.
Quoted 5 lines
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use input devnts as primary API and I am unsure if it is the best solution. Accelerometer might be used as an input device but not always an input device.
Yeah, I see it using a joystick interface, which might be acceptable for "toy" devices like you say.
Quoted 7 lines
But for "real" ones, we should do something else.
Maybe, for devices that are going to be used by x.org, like the "toy" ones, we stick with the current input interface, but for others, we use a "real" interface, probably through hwmon, so that users can get the real data out in a consistant manner.
I'd rather have all of them use real interface and then have a bridge to input module to enable toyish mode (unless the device in question is really truly an input device).
Quoted 7 lines
Quoted 2 lines
--
DmitryI really don't see that hwmon provides facilities like input/evdev does. Queuing of events with time stamping and multiple reader support.
I understand that using evdev might be very convenient but I still believe that input should be used for human interfaces, not for generic data acquisition. The idea is that userpsace consumers should be able to query device's capabilities and based on those capabilities be able to classify and properly handle the device. Now it all breaks when we get random hardware using EV_ABS/ABS_* for delivering some datastream that has nothing to do with coordinates.
Quoted 7 lines
The adxl34x accelerometer driver for example is really
intended to be a input device. SendEV_KEYfor x,y,z_TAP detections, sendEV_KEYfor 3D orientation sensing, andEV_ABSfor acceleration. With very minor platform data customization you can use this device for game controls or GUI interaction. A few examples include digital picture frames, ebook readers, etc.
I see. However, can it be reasonably used for other purposes? If yes than maybe input is not the best primary subsystem the driver should belong to. Having said that I need to look at the driver again...
Signature · 1 line
Dmitry
Quoted 10 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 8 lines · Michael
Quoted 8 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 3 lines · Greg KH
Quoted 2 lines · Dmitry Torokhov
Quoted 1 line · Greg KH
On Wed, Jan 20, 2010 at 04:53:21PM +0000, Jonathan Cameron
Quoted 1 line · wrote:
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
I am not aware of these. Could you direct me to the current
api? Also note that these
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
aren't the actual alarms, merely a means of enabling the
relevant event on the related
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line
event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a
bunch of
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
accelerometers, magnetometers, etc drivers that are trying to
plug into
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
input sysbsystem and quite unsure what to do with them.
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use
input
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
devnts as primary API and I am unsure if it is the best
solution.
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Accelerometer might be used as an input device but not always an
input
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 1 line
device.
Yeah, I see it using a joystick interface, which might be
acceptable for
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
"toy" devices like you say.
But for "real" ones, we should do something else.
Maybe, for devices that are going to be used by x.org, like the
"toy"
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
ones, we stick with the current input interface, but for others,
we use
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
a "real" interface, probably through hwmon, so that users can get
the
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 2 lines
real data out in a consistant manner.
I'd rather have all of them use real interface and then have a
bridge
Quoted 7 lines
Quoted 6 lines
Quoted 5 lines
to input module to enable toyish mode (unless the device in question is really truly an input device).
--
Dmitry
Quoted 7 lines
Quoted 3 lines
I really don't see that hwmon provides facilities like input/evdev does. Queuing of events with time stamping and multiple reader support.
I understand that using evdev might be very convenient but I still believe that input should be used for human interfaces, not for generic data acquisition. The idea is that userpsace consumers should be able
to
Quoted 4 lines
query device's capabilities and based on those capabilities be able to classify and properly handle the device. Now it all breaks when we get random hardware using EV_ABS/ABS_* for delivering some datastream that has nothing to do with coordinates.
Acceleration in X,Y,Z translates pretty well in what joysticks deliver.
Quoted 10 lines
Quoted 8 lines
The adxl34x accelerometer driver for example is really
intended to be a input device. SendEV_KEYfor x,y,z_TAP detections, sendEV_KEYfor 3D orientation sensing, andEV_ABSfor acceleration. With very minor platform data customization you can use this device for game controls or GUI interaction. A few examples include digital picture frames, ebook readers, etc.I see. However, can it be reasonably used for other purposes?
Well - it depends. Some applications for Accelerometers also include:
Personal navigation devices
Hard disk drive (HDD) protection
Safety
I agree with you that for these three mentioned above - Input is the wrong place.
Quoted 6 lines
If yes
than maybe input is not the best primary subsystem the driver should belong to. Having said that I need to look at the driver again...--
Dmitry
Am 26.01.2010 11:25, schrieb Hennerich, Michael:
Quoted 66 lines
Quoted 10 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 8 lines · Michael
Quoted 8 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 3 lines · Greg KH
Quoted 2 lines · Dmitry Torokhov
Quoted 1 line · Greg KH
On Wed, Jan 20, 2010 at 04:53:21PM +0000, Jonathan Cameron
Quoted 1 line · wrote:
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
I am not aware of these. Could you direct me to the current
api? Also note that these
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
aren't the actual alarms, merely a means of enabling the
relevant event on the related
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line
event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a
bunch of
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
accelerometers, magnetometers, etc drivers that are trying to
plug into
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
input sysbsystem and quite unsure what to do with them.
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use
input
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
devnts as primary API and I am unsure if it is the best
solution.
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Accelerometer might be used as an input device but not always an
input
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 1 line
device.
Yeah, I see it using a joystick interface, which might be
acceptable for
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
"toy" devices like you say.
But for "real" ones, we should do something else.
Maybe, for devices that are going to be used by x.org, like the
"toy"
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
ones, we stick with the current input interface, but for others,
we use
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
a "real" interface, probably through hwmon, so that users can get
the
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 2 lines
real data out in a consistant manner.
I'd rather have all of them use real interface and then have a
bridge
Quoted 7 lines
Quoted 6 lines
Quoted 5 lines
to input module to enable toyish mode (unless the device in question is really truly an input device).
--
DmitryQuoted 7 lines
Quoted 3 lines
I really don't see that hwmon provides facilities like input/evdev does. Queuing of events with time stamping and multiple reader support.
I understand that using evdev might be very convenient but I still believe that input should be used for human interfaces, not for generic data acquisition. The idea is that userpsace consumers should be able
Quoted 7 lines
to
Quoted 4 lines
query device's capabilities and based on those capabilities be able to classify and properly handle the device. Now it all breaks when we get random hardware using EV_ABS/ABS_* for delivering some datastream that has nothing to do with coordinates.
Acceleration in X,Y,Z translates pretty well in what joysticks deliver.
But it's not only about accelerometers here. We also have gyros, magnetometers, pressure sensors and generic ADCs.
Quoted 8 lines
Quoted 8 lines
Quoted 7 lines
The adxl34x accelerometer driver for example is really
intended to be a input device. SendEV_KEYfor x,y,z_TAP detections, sendEV_KEYfor 3D orientation sensing, andEV_ABSfor acceleration. With very minor platform data customization you can use this device for game controls or GUI interaction. A few examples include digital picture frames, ebook readers, etc.
Quoted 5 lines
Quoted 1 line
I see. However, can it be reasonably used for other purposes?
Well - it depends. Some applications for Accelerometers also include:
Personal navigation devices
(low to mid data rate)
Quoted 1 line
Hard disk drive (HDD) protection
(only alerts)
Quoted 1 line
Safety
(probably low data rate)
What we want with IIO is a common high performance interface to these devices. That's why we have ring buffers in the kernel. Possible applications are robotics, precise navigation, data aquisition, etc.
Regards,
Signature · 6 lines
Dipl.-Inf. Manuel Stahl Fraunhofer-Institut für Integrierte Schaltungen IIS - Leistungsoptimierte Systeme - Nordostpark 93 Telefon +49 (0)911/58061-6419 90411 Nürnberg Fax +49 (0)911/58061-6398 http://www.iis.fraunhofer.de [email protected]
begin:vcard
fn:Manuel Stahl
n:Stahl;Manuel
email;internet:[email protected]
tel;work:+49 911 58061-6419
x-mozilla-html:FALSE
version:2.1
end:vcard
Quoted 83 lines · Michael
Quoted 10 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 8 lines · Michael
Quoted 8 lines
From: Dmitry Torokhov [mailto:[email protected]]
Quoted 3 lines · Greg KH
Quoted 2 lines · Dmitry Torokhov
Quoted 1 line · Greg KH
On Wed, Jan 20, 2010 at 04:53:21PM +0000, Jonathan Cameron
Quoted 1 line · wrote:
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
I am not aware of these. Could you direct me to the current
api? Also note that these
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
aren't the actual alarms, merely a means of enabling the
relevant event on the related
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line
event character device.
Hm, I thought we had an accelerator interface somewhere...
Nope. And I am also interested in this since I am sittign on a
bunch of
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
accelerometers, magnetometers, etc drivers that are trying to
plug into
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
input sysbsystem and quite unsure what to do with them.
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use
input
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
devnts as primary API and I am unsure if it is the best
solution.
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Accelerometer might be used as an input device but not always an
input
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 1 line
device.
Yeah, I see it using a joystick interface, which might be
acceptable for
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
Quoted 5 lines
"toy" devices like you say.
But for "real" ones, we should do something else.
Maybe, for devices that are going to be used by x.org, like the
"toy"
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
ones, we stick with the current input interface, but for others,
we use
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
a "real" interface, probably through hwmon, so that users can get
the
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 2 lines
real data out in a consistant manner.
I'd rather have all of them use real interface and then have a
bridge
Quoted 7 lines
Quoted 6 lines
Quoted 5 lines
to input module to enable toyish mode (unless the device in question is really truly an input device).
--
DmitryQuoted 7 lines
Quoted 3 lines
I really don't see that hwmon provides facilities like input/evdev does. Queuing of events with time stamping and multiple reader support.
I understand that using evdev might be very convenient but I still believe that input should be used for human interfaces, not for generic data acquisition. The idea is that userpsace consumers should be able
to
Quoted 4 lines
query device's capabilities and based on those capabilities be able to classify and properly handle the device. Now it all breaks when we get random hardware using EV_ABS/ABS_* for delivering some datastream that has nothing to do with coordinates.
Acceleration in X,Y,Z translates pretty well in what joysticks deliver.
Quoted 9 lines
Quoted 8 lines
The adxl34x accelerometer driver for example is really
intended to be a input device. SendEV_KEYfor x,y,z_TAP detections, sendEV_KEYfor 3D orientation sensing, andEV_ABSfor acceleration. With very minor platform data customization you can use this device for game controls or GUI interaction. A few examples include digital picture frames, ebook readers, etc.
Quoted 6 lines
Quoted 1 line
I see. However, can it be reasonably used for other purposes?
Well - it depends. Some applications for Accelerometers also include:
Personal navigation devices
Hard disk drive (HDD) protection
Safety
Just to add the apps I tend see these in (including that particular chip). Sports performance monitoring (including live feedback and logging situations), equine gait and I know at least one group who use these cheap 'input' sensors for UAV navigation and packages instrumenting birds in flight (not sure exactly which chip they are using right now but I know they were trying to obtain samples of the adxl345 a while back.)
Obviously not all of the above are under Linux, but given the ease of development and increasingly good low power and crucially small embedded boards it is becoming more common.
Round here the smallest end is still bare metal code, but a lot of the initial prototypes are Linux based.
Jonathan
Quoted 16 lines
Quoted 16 lines
Quoted 10 lines
Nope. And I am also interested in this since I am sittign on a bunch of accelerometers, magnetometers, etc drivers that are trying to plug into input sysbsystem and quite unsure what to do with them.
It was OK whch HDAPS and friends when they were using input for secondary, toyish purposes, but these new drivers trying to use input devnts as primary API and I am unsure if it is the best solution. Accelerometer might be used as an input device but not always an input device.
Yeah, I see it using a joystick interface, which might be acceptable for "toy" devices like you say.
But for "real" ones, we should do something else.
Quoted 8 lines
Quoted 4 lines
Maybe, for devices that are going to be used by x.org, like the "toy" ones, we stick with the current input interface, but for others, we use a "real" interface, probably through hwmon, so that users can get the real data out in a consistant manner.
I'd rather have all of them use real interface and then have a bridge to input module to enable toyish mode (unless the device in question is really truly an input device).
Well, if you look at the PDA class devices, they really use magnetometers and accelerometers for input. I guess we should look at better support in input...
Pavel
Signature · 2 lines
(english) http://www.livejournal.com/~pavelmachek (cesky, pictures) http://atrey.karlin.mff.cuni.cz/~pavel/picture/horses/blog.html