diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2024-03-21 13:21:31 -0700 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2024-03-21 13:21:31 -0700 |
commit | bb41fe35dce709ea8f91d313c558ee6c68f705ef (patch) | |
tree | 4a88617cf410763964342b01240e3e6f8c8a64ef /Documentation/iio/iio_devbuf.rst | |
parent | 0a59b3f42e5703a89dd6ddf5bc818a4cff975302 (diff) | |
parent | 367b3560e10bbae3660d8ba4d0a7cc92170d8398 (diff) | |
download | linux-bb41fe35dce709ea8f91d313c558ee6c68f705ef.tar.gz |
Merge tag 'char-misc-6.9-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc
Pull char/misc and other driver subsystem updates from Greg KH:
"Here is the big set of char/misc and a number of other driver
subsystem updates for 6.9-rc1. Included in here are:
- IIO driver updates, loads of new ones and evolution of existing ones
- coresight driver updates
- const cleanups for many driver subsystems
- speakup driver additions
- platform remove callback void cleanups
- mei driver updates
- mhi driver updates
- cdx driver updates for MSI interrupt handling
- nvmem driver updates
- other smaller driver updates and cleanups, full details in the
shortlog
All of these have been in linux-next for a long time with no reported
issue, other than a build warning for the speakup driver"
The build warning hits clang and is a gcc (and C23) extension, and is
fixed up in the merge.
Link: https://lore.kernel.org/all/20240321134831.GA2762840@dev-arch.thelio-3990X/
* tag 'char-misc-6.9-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc: (279 commits)
binder: remove redundant variable page_addr
uio_dmem_genirq: UIO_MEM_DMA_COHERENT conversion
uio_pruss: UIO_MEM_DMA_COHERENT conversion
cnic,bnx2,bnx2x: use UIO_MEM_DMA_COHERENT
uio: introduce UIO_MEM_DMA_COHERENT type
cdx: add MSI support for CDX bus
pps: use cflags-y instead of EXTRA_CFLAGS
speakup: Add /dev/synthu device
speakup: Fix 8bit characters from direct synth
parport: sunbpp: Convert to platform remove callback returning void
parport: amiga: Convert to platform remove callback returning void
char: xillybus: Convert to platform remove callback returning void
vmw_balloon: change maintainership
MAINTAINERS: change the maintainer for hpilo driver
char: xilinx_hwicap: Fix NULL vs IS_ERR() bug
hpet: remove hpets::hp_clocksource
platform: goldfish: move the separate 'default' propery for CONFIG_GOLDFISH
char: xilinx_hwicap: drop casting to void in dev_set_drvdata
greybus: move is_gb_* functions out of greybus.h
greybus: Remove usage of the deprecated ida_simple_xx() API
...
Diffstat (limited to 'Documentation/iio/iio_devbuf.rst')
-rw-r--r-- | Documentation/iio/iio_devbuf.rst | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/Documentation/iio/iio_devbuf.rst b/Documentation/iio/iio_devbuf.rst new file mode 100644 index 00000000000000..9919e4792d0e44 --- /dev/null +++ b/Documentation/iio/iio_devbuf.rst @@ -0,0 +1,152 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Industrial IIO device buffers +============================= + +1. Overview +=========== + +The Industrial I/O core offers a way for continuous data capture based on a +trigger source. Multiple data channels can be read at once from +``/dev/iio:deviceX`` character device node, thus reducing the CPU load. + +Devices with buffer support feature an additional sub-directory in the +``/sys/bus/iio/devices/iio:deviceX/`` directory hierarchy, called bufferY, where +Y defaults to 0, for devices with a single buffer. + +2. Buffer attributes +==================== + +An IIO buffer has an associated attributes directory under +``/sys/bus/iio/iio:deviceX/bufferY/``. The attributes are described below. + +``length`` +---------- + +Read / Write attribute which states the total number of data samples (capacity) +that can be stored by the buffer. + +``enable`` +---------- + +Read / Write attribute which starts / stops the buffer capture. This file should +be written last, after length and selection of scan elements. Writing a non-zero +value may result in an error, such as EINVAL, if, for example, an unsupported +combination of channels is given. + +``watermark`` +------------- + +Read / Write positive integer attribute specifying the maximum number of scan +elements to wait for. + +Poll will block until the watermark is reached. + +Blocking read will wait until the minimum between the requested read amount or +the low watermark is available. + +Non-blocking read will retrieve the available samples from the buffer even if +there are less samples than the watermark level. This allows the application to +block on poll with a timeout and read the available samples after the timeout +expires and thus have a maximum delay guarantee. + +Data available +-------------- + +Read-only attribute indicating the bytes of data available in the buffer. In the +case of an output buffer, this indicates the amount of empty space available to +write data to. In the case of an input buffer, this indicates the amount of data +available for reading. + +Scan elements +------------- + +The meta information associated with a channel data placed in a buffer is called +a scan element. The scan elements attributes are presented below. + +**_en** + +Read / Write attribute used for enabling a channel. If and only if its value +is non-zero, then a triggered capture will contain data samples for this +channel. + +**_index** + +Read-only unsigned integer attribute specifying the position of the channel in +the buffer. Note these are not dependent on what is enabled and may not be +contiguous. Thus for userspace to establish the full layout these must be used +in conjunction with all _en attributes to establish which channels are present, +and the relevant _type attributes to establish the data storage format. + +**_type** + +Read-only attribute containing the description of the scan element data storage +within the buffer and hence the form in which it is read from userspace. Format +is [be|le]:[s|u]bits/storagebits[Xrepeat][>>shift], where: + +- **be** or **le** specifies big or little-endian. +- **s** or **u** specifies if signed (2's complement) or unsigned. +- **bits** is the number of valid data bits. +- **storagebits** is the number of bits (after padding) that it occupies in the + buffer. +- **repeat** specifies the number of bits/storagebits repetitions. When the + repeat element is 0 or 1, then the repeat value is omitted. +- **shift** if specified, is the shift that needs to be applied prior to + masking out unused bits. + +For example, a driver for a 3-axis accelerometer with 12-bit resolution where +data is stored in two 8-bit registers is as follows:: + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06) + +---+---+---+---+---+---+---+---+ + + 7 6 5 4 3 2 1 0 + +---+---+---+---+---+---+---+---+ + |D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07) + +---+---+---+---+---+---+---+---+ + +will have the following scan element type for each axis: + +.. code-block:: bash + + $ cat /sys/bus/iio/devices/iio:device0/buffer0/in_accel_y_type + le:s12/16>>4 + +A userspace application will interpret data samples read from the buffer as +two-byte little-endian signed data, that needs a 4 bits right shift before +masking out the 12 valid bits of data. + +It is also worth mentioning that the data in the buffer will be naturally +aligned, so the userspace application has to handle the buffers accordingly. + +Take for example, a driver with four channels with the following description: +- channel0: index: 0, type: be:u16/16>>0 +- channel1: index: 1, type: be:u32/32>>0 +- channel2: index: 2, type: be:u32/32>>0 +- channel3: index: 3, type: be:u64/64>>0 + +If all channels are enabled, the data will be aligned in the buffer as follows:: + + 0-1 2 3 4-7 8-11 12 13 14 15 16-23 -> buffer byte number + +-----+---+---+-----+-----+---+---+---+---+-----+ + |CHN_0|PAD|PAD|CHN_1|CHN_2|PAD|PAD|PAD|PAD|CHN_3| -> buffer content + +-----+---+---+-----+-----+---+---+---+---+-----+ + +If only channel0 and channel3 are enabled, the data will be aligned in the +buffer as follows:: + + 0-1 2 3 4 5 6 7 8-15 -> buffer byte number + +-----+---+---+---+---+---+---+-----+ + |CHN_0|PAD|PAD|PAD|PAD|PAD|PAD|CHN_3| -> buffer content + +-----+---+---+---+---+---+---+-----+ + +Typically the buffered data is found in raw format (unscaled with no offset +applied), however there are corner cases in which the buffered data may be found +in a processed form. Please note that these corner cases are not addressed by +this documentation. + +Please see ``Documentation/ABI/testing/sysfs-bus-iio`` for a complete +description of the attributes. |