Title: [9331] trunk/drivers/staging/iio/Documentation: merge from upstream: staging: iio: documentation - partial update to make more of it true.
- Revision
- 9331
- Author
- vapier
- Date
- 2010-10-24 16:39:38 -0400 (Sun, 24 Oct 2010)
Log Message
merge from upstream: staging: iio: documentation - partial update to make more of it true.
From: Jonathan Cameron <[email protected]>
Signed-off-by: Jonathan Cameron <[email protected]>
Acked-by: Manuel Stahl <[email protected]>
Signed-off-by: Greg Kroah-Hartman <[email protected]>
Modified Paths
Added Paths
Diff
Modified: trunk/drivers/staging/iio/Documentation/overview.txt (9330 => 9331)
--- trunk/drivers/staging/iio/Documentation/overview.txt 2010-10-24 20:39:34 UTC (rev 9330)
+++ trunk/drivers/staging/iio/Documentation/overview.txt 2010-10-24 20:39:38 UTC (rev 9331)
@@ -1,8 +1,8 @@
Overview of IIO
-The Industrial I/O subsytem is intended to provide support for devices
-that in some sense are analog to digital convertors (ADCs). As many
-actual devices combine some ADCs with digital to analog convertors
+The Industrial I/O subsystem is intended to provide support for devices
+that in some sense are analog to digital converters (ADCs). As many
+actual devices combine some ADCs with digital to analog converters
(DACs) the intention is to add that functionality at a future date
(hence the name).
@@ -46,18 +46,17 @@
signal, a gpio line connected to some external system or an on
processor periodic interrupt. A single trigger may initialize data
capture or reading from a number of sensors. These triggers are
-used in iio to fill software ring buffers acting in a very similar
+used in IIO to fill software ring buffers acting in a very similar
fashion to the hardware buffers described above.
Other documentation:
-userspace.txt - overview of ring buffer reading from userspace
+userspace.txt - overview of ring buffer reading from userspace.
-device.txt - elemennts of a typical device driver.
+device.txt - elements of a typical device driver.
trigger.txt - elements of a typical trigger driver.
-ring.txt - additional elements required for ring buffer support
+ring.txt - additional elements required for ring buffer support.
-
-
+sysfs-bus-iio - abi documentation file.
Added: trunk/drivers/staging/iio/Documentation/sysfs-bus-iio (0 => 9331)
--- trunk/drivers/staging/iio/Documentation/sysfs-bus-iio (rev 0)
+++ trunk/drivers/staging/iio/Documentation/sysfs-bus-iio 2010-10-24 20:39:38 UTC (rev 9331)
@@ -0,0 +1,294 @@
+
+What: /sys/bus/iio/devices/device[n]
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Hardware chip or device accessed by on communication port.
+ Corresponds to a grouping of sensor channels.
+
+What: /sys/bus/iio/devices/trigger[n]
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ An event driven driver of data capture to an in kernel buffer.
+ May be provided by a device driver that also has an IIO device
+ based on hardware generated events (e.g. data ready) or
+ provided by a separate driver for other hardware (e.g.
+ periodic timer, gpio or high resolution timer).
+ Contains trigger type specific elements. These do not
+ generalize well and hence are not documented in this file.
+
+What: /sys/bus/iio/devices/device[n]:buffer
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ 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
+Contact: [email protected]
+Description:
+ Description of the physical chip / device. Typically a part
+ number.
+
+What: /sys/.../device[n]/sampling_frequency
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Some devices have internal clocks. This parameter sets the
+ resulting sampling frequency. In many devices this
+ parameter has an effect on input filters etc rather than
+ simply controlling when the input is sampled. As this
+ effects datardy triggers, hardware buffers and the sysfs
+ direct access interfaces, it may be found in any of the
+ relevant directories. If it effects all of the above
+ then it is to be found in the base device directory as here.
+
+What: /sys/.../device[n]/sampling_frequency_available
+KernelVersion: 2.6.35
+Contact: [email protected]
+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
+KernelVersion: 2.6.35
+Contact: [email protected]
+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 in which case the file is in_supply_raw).
+
+What: /sys/.../device[n]/in[_name][m]_offset
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ If known for a device, offset to be added to in[m]_raw prior
+ to scaling by in[_name][m]_scale in order to obtain voltage in
+ millivolts. Not present if the offset is always 0 or unknown.
+ If m is not present, then voltage offset applies to all in
+ 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, typically adjusted by
+ using some hardware supported calibration procedure.
+
+What: /sys/.../device[n]/in[_name][m]_offset_available
+KernelVersion: 2.6.35
+Contact: [email protected]
+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/.../device[n]/in[_name][m]_offset_[min|max]
+KernelVersion: 2.6.35
+Contact: [email protected]
+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.
+
+What: /sys/.../device[n]/in[_name][m]_calibbias
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Hardware applied calibration offset. (assumed to fix production
+ inaccuracies)
+
+What /sys/.../device[n]/in[_name][m]_calibscale
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Hardware applied calibration scale factor. (assumed to fix production
+ inaccuracies)
+
+What: /sys/.../device[n]/in[_name][m]_scale
+KernelVersion: 2.6.35
+Contact: [email protected]
+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.
+
+What: /sys/.../device[n]/in[m]-in[o]_raw
+KernelVersion: 2.6.35
+Contact: [email protected]
+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.
+
+What: /sys/.../device[n]/accel[_x|_y|_z][m]_raw
+KernelVersion: 2.6.35
+Contact: [email protected]
+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.
+
+What: /sys/.../device[n]/gyro[_x|_y|_z][m]_raw
+KernelVersion: 2.6.35
+Contact: [email protected]
+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 in[m].
+
+What: /sys/.../device[n]/incli[_x|_y|_z][m]_raw
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Inclination raw reading about axis x, y or z (may be arbitarily
+ assigned) channel m (not present if only one inclinometer at
+ this orientation). Data converted by application of offset
+ and scale to Degrees.
+
+What: /sys/.../device[n]/magn[_x|_y|_z][m]_raw
+KernelVersion: 2.6.35
+Contact: [email protected]
+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].
+
+What: /sys/.../device[n]/device[n]:event[m]
+KernelVersion: 2.6.35
+Contact: [email protected]
+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/.../device[n]:event[m]/dev
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ major:minor character device numbers for the event line.
+
+Taking accel_x0 as an example
+
+What: /sys/.../device[n]:event[m]/accel_x0_thresh[_high|_low]_en
+KernelVersion: 2.6.35
+Contact: [email protected]
+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/.../device[n]:event[m]/accel_x0_roc[_high|_low]_en
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Same as above but based on the first differential of the value.
+
+
+What: /sys/.../device[n]:event[m]/accel_x0[_thresh|_roc][_high|_low]_period
+KernelVersion: 2.6.35
+Contact: [email protected]
+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/.../device[n]:event[m]/accel_x0[_thresh|_roc][_high|_low]_value
+KernelVersion: 2.6.35
+Contact: [email protected]
+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.
+
+What: /sys/.../device[n]/device[n]:buffer:event/dev
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Buffer for device n event character device major:minor numbers.
+
+What: /sys/.../device[n]/device[n]:buffer:access/dev
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Buffer for device n access character device o major:minor numbers.
+
+What: /sys/.../device[n]:buffer/trigger
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ The name of the trigger source being used, as per string given
+ in /sys/class/iio/trigger[n]/name.
+
+What: /sys/.../device[n]:buffer/length
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Number of scans contained by the buffer.
+
+What: /sys/.../device[n]:buffer/bytes_per_datum
+KernelVersion: 2.6.37
+Contact: [email protected]
+Description:
+ Bytes per scan. Due to alignment fun, the scan may be larger
+ than implied directly by the scan_element parameters.
+
+What: /sys/.../device[n]:buffer/enable
+KernelVersion: 2.6.35
+Contact: [email protected]
+Description:
+ Actually start the buffer capture up. Will start trigger
+ if first device and appropriate.
+
+What: /sys/.../device[n]:buffer/alignment
+KernelVersion: 2.6.35
+Contact: [email protected]
+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)
+
+What: /sys/.../device[n]/buffer/scan_elements
+KernelVersion: 2.6.37
+Contact: [email protected]
+Description:
+ 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/[m]_accel_x0_en
+KernelVersion: 2.6.37
+Contact: [email protected]
+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/.../device[n]/buffer/scan_elements/accel[_x0]_precision
+KernelVersion: 2.6.37
+Contact: [email protected]
+Description:
+ Scan element precision within the buffer. Note that the
+ data alignment must restrictions must be read from within
+ buffer to work out full data alignment for data read
+ via buffer_access chrdev. _x0 dropped if shared across all
+ acceleration channels.
+
+What: /sys/.../device[n]/buffer/scan_elements/accel[_x0]_shift
+KernelVersion: 2.6.37
+Contact: [email protected]
+Description:
+ A bit shift (to right) that must be applied prior to
+ extracting the bits specified by accel[_x0]_precision.
+
Modified: trunk/drivers/staging/iio/Documentation/userspace.txt (9330 => 9331)
--- trunk/drivers/staging/iio/Documentation/userspace.txt 2010-10-24 20:39:34 UTC (rev 9330)
+++ trunk/drivers/staging/iio/Documentation/userspace.txt 2010-10-24 20:39:38 UTC (rev 9331)
@@ -1,62 +1,12 @@
Userspace access to IIO
-Example, ST Microelectronics LIS3L02DQ accelerometer.
+The sysfs attributes are documented in sysfs-bus-iio.
-Typical sysfs entries (pruned for clarity)
-
-/sys/class/iio
- device0 - iio_dev related elements
- name - driver specific identifier (here lis3l02dq)
- accel_x_raw - polled (or from ring) raw readout of acceleration
- accel_x_offset - offset to be applied to the raw reading
- accel_x_scale - scale to be applied to the raw reading and offset
- accel_x_calibbias - hardware offset (calibration)
- accel_x_calibscale - hardware gain (calibration)
-
- sampling_frequency_available - what options are there
- sampling_frequency - control of internal sampling frequency
- device - link to underlying hardware device
- uevent - udev related element
-
- thresh - unified threshold used for detection on all axis
- event_line0_sources - which events are enabled
- accel_x_high - enable x axis high threshold event
- accel_x_low - enable x axis low threshold event
-
- event_line0 - event interface
- dev - major:minor for the chrdev (note major allocation dynamic)
- trigger - consumer attachement
- current_trigger - name based association with a trigger
- device0:buffer0 - ring buffer interface
- bytes_per_datum - byptes per complete datum (read only),
- dependant on scan element selection
- length - (rw) specificy length fo software ring buffer (typically ro in hw case)
- enable - turn the ring on. If its the first to be enabled attached to this
- trigger will also enable the trigger.
- device0:buffer0:access0
- dev - major:minor for ring buffer access chrdev
- device0:buffer0:event0
- dev - major:minor for ring buffer event chrdev
- scan_elements - controls which channels will be stored in the ring buffer
- accel_x_en
- accel_y_en
- timestamp_en
-
- trigger0 - data ready trigger elements
- name - unqiue name of trigger
-
Udev will create the following entries under /dev by default:
device0:buffer0:access0 - ring access chrdev
device0:buffer0:event0 - ring event chrdev
-event_line0 - general event chrdev.
+device0:event0 - general event chrdev.
-For the example code we assume the following rules have been used to ensure
-unique and consistent naming of these for the lis3l02dq in question:
-
-KERNEL="ring_event_line*", ID="spi1.0", DRIVER="lis3l02dq", NAME="iio/lis3l02dq_ring_event"
-KERNEL="event_line*", ID="spi1.0", DRIVER="lis3l02dq", NAME="iio/lis3l02dq_event"
-KERNEL="ring_access*", ID="spi1.0", DRIVER="lis3l02dq", NAME="iio/lis3l02dq_ring_access"
-
The files, lis3l02dqbuffersimple.c and iio_utils.h in this directory provide an example
of how to use the ring buffer and event interfaces.
_______________________________________________
Linux-kernel-commits mailing list
[email protected]
https://blackfin.uclinux.org/mailman/listinfo/linux-kernel-commits
