staging: iio: events update documentation to match new abi.
authorJonathan Cameron <jic23@cam.ac.uk>
Fri, 8 Oct 2010 11:14:12 +0000 (12:14 +0100)
committerGreg Kroah-Hartman <gregkh@suse.de>
Fri, 8 Oct 2010 14:17:56 +0000 (07:17 -0700)
Signed-off-by: Jonathan Cameron <jic23@cam.ac.uk>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>
drivers/staging/iio/Documentation/sysfs-bus-iio

index 62becc0..fdb017a 100644 (file)
@@ -1,4 +1,3 @@
-
 What:          /sys/bus/iio/devices/device[n]
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
@@ -22,8 +21,8 @@ What:         /sys/bus/iio/devices/device[n]:buffer
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
-               Link to /sys/class/iio/device[n]/device[n]:buffer. n indicates the
-               device with which this buffer buffer is associated.
+               Link to /sys/class/iio/device[n]/device[n]:buffer. n indicates
+               the device with which this buffer buffer is associated.
 
 What:          /sys/.../device[n]/name
 KernelVersion: 2.6.35
@@ -52,7 +51,7 @@ Description:
                When the internal sampling clock can only take a small
                discrete set of values, this file lists those availale.
 
-What:          /sys/.../device[n]/in[_name][m]_raw
+What:          /sys/.../device[n]/in[m][_name]_raw
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
@@ -60,8 +59,11 @@ Description:
                channel m. name is used in special cases where this does
                not correspond to externally available input (e.g. supply
                voltage monitoring in which case the file is in_supply_raw).
+               If the device supports events on this channel then m must be
+               specified (even on named channels) so as to allow the source
+               of event codes to be identified.
 
-What:          /sys/.../device[n]/in[_name][m]_offset
+What:          /sys/.../device[n]/in[m][_name]_offset
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
@@ -75,7 +77,7 @@ Description:
                between different instances of the part, typically adjusted by
                using some hardware supported calibration procedure.
 
-What:          /sys/.../device[n]/in[_name][m]_offset_available
+What:          /sys/.../device[n]/in[m][_name]_offset_available
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
@@ -84,45 +86,46 @@ Description:
                options the same) for individual offsets then m should not be
                present.
 
-What:          /sys/.../device[n]/in[_name][m]_offset_[min|max]
+What:          /sys/.../device[n]/in[m][_name]_offset_[min|max]
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
-               If a more or less continuous range of voltage offsets are supported
-               then these specify the minimum and maximum.  If shared by all
-               in channels then m is not present.
+               If a more or less continuous range of voltage offsets are
+               supported then these specify the minimum and maximum.  If shared
+               by all in channels then m is not present.
 
-What:          /sys/.../device[n]/in[_name][m]_calibbias
+What:          /sys/.../device[n]/in[m][_name]_calibbias
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
                Hardware applied calibration offset. (assumed to fix production
                inaccuracies)
 
-What           /sys/.../device[n]/in[_name][m]_calibscale
+What           /sys/.../device[n]/in[m][_name]_calibscale
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
-               Hardware applied calibration scale factor. (assumed to fix production
-               inaccuracies)
+               Hardware applied calibration scale factor. (assumed to fix
+               production inaccuracies)
 
-What:          /sys/.../device[n]/in[_name][m]_scale
+What:          /sys/.../device[n]/in[m][_name]_scale
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
                If known for a device, scale to be applied to volt[m]_raw post
                addition of in[_name][m]_offset in order to obtain the measured
-               voltage in millivolts.  If shared across all in channels then                   m is not present.
+               voltage in millivolts.  If shared across all in channels then
+               m is not present.
 
 What:          /sys/.../device[n]/in[m]-in[o]_raw
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
                Raw (unscaled) differential voltage measurement equivalent to
-               channel m - channel o where these channel numbers apply to the physically
-               equivalent inputs when non differential readings are separately available.
-               In differential only parts, then all that is required is a consistent
-               labelling.
+               channel m - channel o where these channel numbers apply to the
+               physically equivalent inputs when non differential readings are
+               separately available. In differential only parts, then all that
+               is required is a consistent labelling.
 
 What:          /sys/.../device[n]/accel[_x|_y|_z][m]_raw
 KernelVersion: 2.6.35
@@ -131,17 +134,19 @@ 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 in[m].
-               Units after application of scale and offset are m/s^2.
+               this orientation). Has all of the equivalent parameters as per
+               in[m]. Units after application of scale and offset are m/s^2.
 
 What:          /sys/.../device[n]/gyro[_x|_y|_z][m]_raw
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 Description:
-               Angular velocity about axis x, y or z (may be arbitrarily assigned)
-               channel m (not present if only one gyroscope at this orientation).
+               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 in[m].
+               radians per second. Has all the equivalent parameters as
+               per in[m].
 
 What:          /sys/.../device[n]/incli[_x|_y|_z][m]_raw
 KernelVersion: 2.6.35
@@ -156,10 +161,11 @@ What:             /sys/.../device[n]/magn[_x|_y|_z][m]_raw
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 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 in[m].
+               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 in[m].
 
 What:          /sys/.../device[n]/device[n]:event[m]
 KernelVersion: 2.6.35
@@ -177,40 +183,114 @@ Description:
 
 Taking accel_x0 as an example
 
-What:          /sys/.../device[n]:event[m]/accel_x0_thresh[_high|_low]_en
-KernelVersion: 2.6.35
+What:          /sys/.../device[n]:event[m]/accel_x0_thresh[_rising|_falling]_en
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               Event generated when accel_x0 passes a threshold in the specfied
+               (_rising|_falling) direction. If the direction is not specified,
+               then either the device will report an event which ever direction
+               a single threshold value is called in (e.g.
+               accel_x0_<raw|input>_thresh_value) or
+               accel_x0_<raw|input>_thresh_rising_value and
+               accel_x0_<raw|input>_thresh_falling_value may take different
+               values, but the device can only enable both thresholds or
+               neither.
+               Note the driver will assume the last p events requested are
+               to be enabled where p is however many it supports (which may
+               vary depending on the exact set requested. So if you want to be
+               sure you have set what you think you have, check the contents of
+               these attributes after everything is configured. 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 event was previously enabled).
+
+What:          /sys/.../accel_x0_<raw|input>_thresh[_rising|_falling]_value
+KernelVersion: 2.6.37
 Contact:       linux-iio@vger.kernel.org
 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).
+               Specifies the value of threshold that the device is comparing
+               against for the events enabled by
+               accel_x0_<raw|input>_thresh[_rising|falling]_en.
+               If seperate exist for the two directions, but direction is
+               not specified for this attribute, then a single threshold value
+               applies to both directions.
+               The raw or input element of the name indicates whether the
+               value is in raw device units or in processed units (as _raw
+               and _input do on sysfs direct channel read attributes).
 
-What:          /sys/.../device[n]:event[m]/accel_x0_roc[_high|_low]_en
-KernelVersion: 2.6.35
+What:          /sys/.../accel_x0_thresh[_rising|_falling]_meanperiod
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               Period of time (in seconds) over which the raw channel value
+               is averaged before being compared with the threshold set in
+               accel_x0_thresh[_rising|_falling]_meanperiod.  If direction is
+               not specified then this mean period applies to both directions.
+
+What:          /sys/.../accel_x0_thresh[_rising|_falling]_period
+KernelVersion: 2.6.37
 Contact:       linux-iio@vger.kernel.org
 Description:
-               Same as above but based on the first differential of the value.
+               Period of time (in seconds) for which the threshold must be
+               passed before an event is generated. If direction is not
+               specified then this period applies to both directions.
 
+What:          /sys/.../device[n]:event[m]/accel_x0_mag[_rising|_falling]_en
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               Similar to accel_x0_thresh[_rising|_falling]_en, but here the
+               magnitude of the channel is compared to the threshold, not its
+               signed value.
 
-What:          /sys/.../device[n]:event[m]/accel_x0[_thresh|_roc][_high|_low]_period
-KernelVersion: 2.6.35
+What:          /sys/.../accel_x0_<raw|input>_mag[_rising|_falling]_value
+KernelVersion: 2.6.37
 Contact:       linux-iio@vger.kernel.org
 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.
+               The value to which the magnitude of the channel is compared.
 
-What:          /sys/.../device[n]:event[m]/accel_x0[_thresh|_roc][_high|_low]_value
-KernelVersion: 2.6.35
+What:          /sys/.../accel_x0_mag[_rising|_falling]_meanperiod
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               Period of time (in seconds) over which the value of the channel
+               is averaged before being compared to the threshold
+
+What:          /sys/.../accel_x0_mag[_rising|_falling]_period
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               Period of time (in seconds) for which the condition must be true
+               before an event occurs.
+
+What:          /sys/.../device[n]:event[m]/accel_x0_roc[_rising|_falling]_en
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               Similar to accel_x0_thresh[_rising|_falling]_en, but here the
+               first differential is compared with the threshold.
+
+What:          /sys/.../accel_x0_<raw|input>_roc[_rising|_falling]_value
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               The value to which the first differential of the channel is
+               compared.
+
+What:          /sys/.../accel_x0_roc[_rising|_falling]_meanperiod
+KernelVersion: 2.6.37
+Contact:       linux-iio@vger.kernel.org
+Description:
+               Period of time (in seconds) over which the value of the channel
+               is averaged before being compared to the threshold
+
+What:          /sys/.../accel_x0_roc[_rising|_falling]_period
+KernelVersion: 2.6.37
 Contact:       linux-iio@vger.kernel.org
 Description:
-               The actual value of the threshold in raw device units obtained by
-                reverse application of scale and offfset to the acceleration in m/s^2.
+               Period of time (in seconds) for which the condition must be true
+               before an event occurs.
 
 What:          /sys/.../device[n]/device[n]:buffer:event/dev
 KernelVersion: 2.6.35
@@ -255,16 +335,16 @@ What:             /sys/.../device[n]:buffer/alignment
 KernelVersion: 2.6.35
 Contact:       linux-iio@vger.kernel.org
 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 buffers that pack data well)
+               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 buffers that pack data well)
 
 What:          /sys/.../device[n]/buffer/scan_elements
 KernelVersion: 2.6.37
 Contact:       linux-iio@vger.kernel.org
 Description:
-               Directory containing interfaces for elements that will be captured
-               for a single triggered sample set in the buffer.
+               Directory containing interfaces for elements that will be
+               captured for a single triggered sample set in the buffer.
 
 What:          /sys/.../device[n]/buffer/scan_elements/accel_x0_en
 KernelVersion: 2.6.37