mirror of https://gitee.com/openkylin/linux.git
staging:iio:documentation: Drop most generic docs
These docs are both suffering from being out of date, and from being superceeded by the documentation in Documentation/driver-api/iio Note the inkern.txt drop is left for now as this is an area not well covered by the more recent documentation outside staging. Signed-off-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> Link: https://lore.kernel.org/r/20200905174721.216452-5-jic23@kernel.org
This commit is contained in:
Jonathan Cameron
parent
d4ca7f94ce
commit
7b9dc60ebd
|
|
@ -1,74 +0,0 @@
|
|||
IIO Device drivers
|
||||
|
||||
This is not intended to provide a comprehensive guide to writing an
|
||||
IIO device driver. For further information see the drivers within the
|
||||
subsystem.
|
||||
|
||||
The crucial structure for device drivers in iio is iio_dev.
|
||||
|
||||
First allocate one using:
|
||||
|
||||
struct iio_dev *indio_dev = iio_device_alloc(parent, 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->name
|
||||
Name of the device being driven - made available as the name
|
||||
attribute in sysfs.
|
||||
|
||||
- indio_dev->info
|
||||
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->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 calibbias.
|
||||
* 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 dependent.
|
||||
|
||||
- indio_dev->modes:
|
||||
Specify whether direct access and / or ring buffer access is supported.
|
||||
- indio_dev->buffer:
|
||||
An optional associated buffer.
|
||||
- indio_dev->pollfunc:
|
||||
Poll function related elements. This controls what occurs when a trigger
|
||||
to which this device is attached sends an event.
|
||||
- indio_dev->channels:
|
||||
Specification of device channels. Most attributes etc. are built
|
||||
from this spec.
|
||||
- indio_dev->num_channels:
|
||||
How many channels are there?
|
||||
|
||||
Once these are set up, a call to iio_device_register(indio_dev)
|
||||
will register the device with the iio core.
|
||||
|
||||
Worth noting here is that, if a ring buffer is to be used, it can be
|
||||
allocated prior to registering the device with the iio-core, but must
|
||||
be registered afterwards (otherwise the whole parentage of devices
|
||||
gets confused)
|
||||
|
||||
On remove, iio_device_unregister(indio_dev) will remove the device from
|
||||
the core, and iio_device_free(indio_dev) will clean up.
|
||||
|
|
@ -1,57 +0,0 @@
|
|||
Overview of IIO
|
||||
|
||||
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) that functionality is also supported.
|
||||
|
||||
The aim is to fill the gap between the somewhat similar hwmon and
|
||||
input subsystems. Hwmon is very much directed at low sample rate
|
||||
sensors used in applications such as fan speed control and temperature
|
||||
measurement. Input is, as its name suggests focused on input
|
||||
devices. In some cases, there is considerable overlap between these and
|
||||
IIO.
|
||||
|
||||
A typical device falling into this category would be connected via SPI
|
||||
or I2C.
|
||||
|
||||
Functionality of IIO
|
||||
|
||||
* Basic device registration and handling. This is very similar to
|
||||
hwmon with simple polled access to device channels via sysfs.
|
||||
|
||||
* Event chrdevs. These are similar to input in that they provide a
|
||||
route to user space for hardware triggered events. Such events include
|
||||
threshold detectors, free-fall detectors and more complex action
|
||||
detection. The events themselves are currently very simple with
|
||||
merely an event code and a timestamp. Any data associated with the
|
||||
event must be accessed via polling.
|
||||
|
||||
Note: A given device may have one or more event channel. These events are
|
||||
turned on or off (if possible) via sysfs interfaces.
|
||||
|
||||
* 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 Devices ADXL345 accelerometers. Each buffer supports
|
||||
polling to establish when data is available.
|
||||
|
||||
* Trigger and software buffer support. In many data analysis
|
||||
applications it is 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 buffers acting in a very similar
|
||||
fashion to the hardware buffers described above.
|
||||
|
||||
Other documentation:
|
||||
|
||||
device.txt - elements of a typical device driver.
|
||||
|
||||
trigger.txt - elements of a typical trigger driver.
|
||||
|
||||
ring.txt - additional elements required for buffer support.
|
||||
|
||||
sysfs-bus-iio - abi documentation file.
|
||||
|
|
@ -1,47 +0,0 @@
|
|||
Buffer support within IIO
|
||||
|
||||
This document is intended as a general overview of the functionality
|
||||
a buffer may supply and how it is specified within IIO. For more
|
||||
specific information on a given buffer implementation, see the
|
||||
comments in the source code. Note that some drivers allow buffer
|
||||
implementation to be selected at compile time via Kconfig options.
|
||||
|
||||
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 a struct iio_ring_setup_ops *setup_ops
|
||||
which in turn contains the 4 function pointers
|
||||
(preenable, postenable, predisable and postdisable).
|
||||
These are used to perform device specific steps on either side
|
||||
of the core changing its 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 buffer functionality as possible. Note almost all of these
|
||||
are optional.
|
||||
|
||||
store_to
|
||||
If possible, push data to the buffer.
|
||||
|
||||
read_last
|
||||
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_first_n
|
||||
The primary buffer reading function. Note that it may well not return
|
||||
as much data as requested.
|
||||
|
||||
request_update
|
||||
If parameters have changed that require reinitialization or configuration of
|
||||
the buffer this will trigger it.
|
||||
|
||||
set_bytes_per_datum
|
||||
Set the number of bytes for a complete scan. (All samples + timestamp)
|
||||
|
||||
set_length
|
||||
Set the number of complete scans that may be held by the buffer.
|
||||
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
IIO trigger drivers.
|
||||
|
||||
Many triggers are provided by hardware that will also be registered as
|
||||
an IIO device. Whilst this can create device specific complexities
|
||||
such triggers are registered with the core in the same way as
|
||||
stand-alone triggers.
|
||||
|
||||
struct iio_trig *trig = iio_trigger_alloc("<trigger format string>", ...);
|
||||
|
||||
allocates a trigger structure. The key elements to then fill in within
|
||||
a driver are:
|
||||
|
||||
trig->set_trigger_state:
|
||||
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:
|
||||
|
||||
iio_trigger_register(trig);
|
||||
|
||||
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
|
||||
buffers and as such any device supporting INDIO_BUFFER_TRIGGERED has the
|
||||
consumer interface automatically created.
|
||||
Loading…
Reference in New Issue