staging:iio:documenation partial update. · 44d8b3542f - evie/android_kernel_oneplus_msm8998 - Gay Catgirls Forgejo: gay catgirls having sex

evie/android_kernel_oneplus_msm8998

staging:iio:documenation partial update.

More to be added, but this brings the docs in line with
the current code. Now they are hopefully just uninformative
rather than actually incorrect.

Signed-off-by: Jonathan Cameron <jic23@cam.ac.uk>
Signed-off-by: Greg Kroah-Hartman <gregkh@suse.de>

This commit is contained in:

Jonathan Cameron

2011-05-18 14:42:40 +01:00

• committed by

Greg Kroah-Hartman

parent 0ed731d234

commit 44d8b3542f

5 changed files with 91 additions and 78 deletions

78

drivers/staging/iio/Documentation/device.txt

View file

 First allocate one using:
-struct iio_dev *indio_dev = iio_allocate_device(0);
+struct iio_dev *indio_dev = iio_allocate_device(sizeof(struct chip_state));
+where chip_state is a structure of local state data for this instance of
+the chip.
+That data can be accessed using iio_priv(struct iio_dev *)
 Then fill in the following:
-indio_dev->dev.parent
+- indio_dev->dev.parent
-  the struct device associated with the underlying hardware.
+	Struct device associated with the underlying hardware.
+- indio_dev->name
+	Name of the device being driven - made available as the name
+	attribute in sysfs.
-indio_dev->num_interrupt_lines
+- indio_dev->info
-   number of event triggering hardware lines the device has.
+	pointer to a structure with elements that tend to be fixed for
+	large sets of different parts supported by a given driver.
+	This contains:
+	* info->driver_module:
+		Set to THIS_MODULE. Used to ensure correct ownership
+		of various resources allocate by the core.
+	* info->num_interrupt_lines:
+		Number of event triggering hardware lines the device has.
+	* info->event_attrs:
+		Attributes used to enable / disable hardware events.
+	* info->attrs:
+		General device attributes. Typically used for the weird
+		and the wonderful bits not covered by the channel specification.
+	* info->read_raw:
+		Raw data reading function. Used for both raw channel access
+		and for associate parameters such as offsets and scales.
+	* info->write_raw:
+		Raw value writing function. Used for writable device values such
+		as DAC values and caliboffset.
+	* info->read_event_config:
+		Typically only set if there are some interrupt lines.  This
+		is used to read if an on sensor event detector is enabled.
+	* info->write_event_config:
+		Enable / disable an on sensor event detector.
+	* info->read_event_value:
+		Read value associated with on sensor event detectors. Note that
+		the meaning of the returned value is dependent on the event
+		type.
+	* info->write_event_value:
+		Write the value associated with on sensor event detectors. E.g.
+		a threshold above which an interrupt occurs.  Note that the
+		meaning of the value to be set is event type dependant.
-indio_dev->event_attrs
+- indio_dev->modes:
-   attributes used to enable / disable hardware events - note the
+	Specify whether direct access and / or ring buffer access is supported.
-   attributes are embedded in iio_event_attr structures with an
+- indio_dev->ring:
-   associated iio_event_handler which may or may note be shared.
+	An optional associated buffer.
-   If num_interrupt_lines = 0, then no need to fill this in.
+- indio_dev->pollfunc:
+	Poll function related elements. This controls what occurs when a trigger
-indio_dev->attrs
+	to which this device is attached sends and event.
-   general attributes such as polled access to device channels.
+- indio_dev->channels:
+	Specification of device channels. Most attributes etc are built
-indio_dev->dev_data
+	form this spec.
-   private device specific data.
+- indio_dev->num_channels:
+	How many channels are there?
-indio_dev->driver_module
-   typically set to THIS_MODULE. Used to specify ownership of some
-   iio created resources.
-indio_dev->modes
-   whether direct access and / or ring buffer access is supported.
 Once these are set up, a call to iio_device_register(indio_dev),
 will register the device with the iio core.

19

drivers/staging/iio/Documentation/overview.txt

View file

 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
+(DACs) that functionality is also supported.
-(hence the name).
 The aim is to fill the gap between the somewhat similar hwmon and
 input subsystems.  Hwmon is very much directed at low sample rate
 Note: A given device may have one or more event channel.  These events are
 turned on or off (if possible) via sysfs interfaces.
-* Hardware ring buffer support.  Some recent sensors have included
+* Hardware buffer support.  Some recent sensors have included
 fifo / ring buffers on the sensor chip.  These greatly reduce the load
 on the host CPU by buffering relatively large numbers of data samples
 based on an internal sampling clock. Examples include VTI SCA3000
-series and Analog Device ADXL345 accelerometers.  Each ring buffer
+series and Analog Device ADXL345 accelerometers.  Each buffer supports
-typically has an event chrdev (similar to the more general ones above)
+polling to establish when data is available.
-to pass on events such as buffer 50% full and an access chrdev via
-which the raw data it self may be read back.
-* Trigger and software ring buffer support. In many data analysis
+* Trigger and software buffer support. In many data analysis
 applications it it useful to be able to capture data based on some
 external signal (trigger).  These triggers might be a data ready
 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 buffers acting in a very similar
 fashion to the hardware buffers described above.
 Other documentation:
-userspace.txt - overview of ring buffer reading from userspace.
 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 buffer support.
 sysfs-bus-iio - abi documentation file.

44

drivers/staging/iio/Documentation/ring.txt

View file

-Ring buffer support within IIO
+Buffer support within IIO
 This document is intended as a general overview of the functionality
-a ring buffer may supply and how it is specified within IIO.  For more
+a buffer may supply and how it is specified within IIO.  For more
-specific information on a given ring buffer implementation, see the
+specific information on a given buffer implementation, see the
-comments in the source code.  Note that the intention is to allow
+comments in the source code.  Note that some drivers allow buffer
-some drivers to specify ring buffers choice at probe or runtime, but
+implementation to be selected at compile time via Kconfig options.
-for now the selection is hard coded within a given driver.
-A given ring buffer implementation typically embedded a struct
+A given buffer implementation typically embeds a struct
 iio_ring_buffer and it is a pointer to this that is provided to the
 IIO core. Access to the embedding structure is typically done via
 container_of functions.
-struct iio_ring_buffer contains 4 function pointers
+struct iio_ring_buffer contains a struct iio_ring_setup_ops *setup_ops
-(preenable, postenable, predisable, postdisable).
+which in turn contains the 4 function pointers
-These are used to perform implementation specific steps on either side
+(preenable, postenable, predisable and postdisable).
-of the core changing it's current mode to indicate that the ring buffer
+These are used to perform device specific steps on either side
+of the core changing it's current mode to indicate that the buffer
 is enabled or disabled (along with enabling triggering etc as appropriate).
 Also in struct iio_ring_buffer is a struct iio_ring_access_funcs.
 The function pointers within here are used to allow the core to handle
-as much ring buffer functionality as possible. Note almost all of these
+as much buffer functionality as possible. Note almost all of these
 are optional.
 mark_in_use, unmark_in_use
-  Basically indicate that not changes should be made to the ring
+  Basically indicate that not changes should be made to the buffer state that
-  buffer state that will effect the form of the data being captures
+  will effect the form of the data being captures (e.g. scan elements or length)
-  (e.g. scan elements or length)
 store_to
-  If possible, push data to ring buffer.
+  If possible, push data to the buffer.
 read_last
-  If possible get the most recent entry from the buffer (without removal).
+  If possible, get the most recent scan from the buffer (without removal).
   This provides polling like functionality whilst the ring buffering is in
   use without a separate read from the device.
-rip_lots
+rip_first_n
-  The primary ring buffer reading function. Note that it may well not return
+  The primary buffer reading function. Note that it may well not return
-  as much data as requested.  The deadoffset is used to indicate that some
+  as much data as requested.
-  initial data in the data array is not guaranteed to be valid.
 mark_param_changed
   Used to indicate that something has changed. Used in conjunction with
 request_update
   If parameters have changed that require reinitialization or configuration of
-  the ring buffer this will trigger it.
+  the buffer this will trigger it.
 get_bytes_per_datum, set_bytes_per_datum
   Get/set the number of bytes for a complete scan. (All samples + timestamp)
 get_length / set_length
-  Get/set the number of sample sets that may be held by the buffer.
+  Get/set the number of complete scans that may be held by the buffer.
 is_enabled
   Query if ring buffer is in use

16

drivers/staging/iio/Documentation/trigger.txt

View file

 such triggers are registered with the core in the same way as
 stand-alone triggers.
-struct iio_trig *trig = iio_allocate_trigger();
+struct iio_trig *trig = iio_allocate_trigger("<trigger format string>", ...);
 allocates a trigger structure.  The key elements to then fill in within
 a driver are:
-trig->control_attrs
-	Any sysfs attributes needed to control parameters of the trigger
 trig->private_data
 	Device specific private data.
 	Typically set to THIS_MODULE. Used to ensure correct
 	ownership of core allocated resources.
-trig->name
+trig->set_trigger_state:
-	A unique name for the trigger.
+	Function that enables / disables the underlying source of the trigger.
+There is also a
+trig->alloc_list which is useful for drivers that allocate multiple
+triggers to keep track of what they have created.
 When these have been set call:
 to register the trigger with the core, making it available to trigger
 consumers.
 Trigger Consumers
-Currently triggers are only used for the filling of software ring
+Currently triggers are only used for the filling of software
 buffers and as such any device supporting INDIO_RING_TRIGGERED has the
 consumer interface automatically created.

12

drivers/staging/iio/Documentation/userspace.txt

View file

-Userspace access to IIO
-The sysfs attributes are documented in sysfs-bus-iio.
-Udev will create the following entries under /dev by default:
-device0:buffer0:access0 - ring access chrdev
-device0:buffer0:event0 - ring event chrdev
-device0:event0 - general event chrdev.
-The files, lis3l02dqbuffersimple.c and iio_utils.h in this directory provide an example
-of how to use the ring buffer and event interfaces.