docs: IIO documentation conversion from DocBook
Subsystems (2)
Jonathan Cameron
maintainerRFC PATCH 1/1 docs: IIO documentation conversion from DocBook
I had a long train journey today so finished off an initial cut of a conversion of the existing IIO DocBook over to Sphinx.
There are various issues with the kernel doc in some of our source files that need cleaning up, but thought I'd get this out for people to be able to take a first look.
For now I've basically left any editorial work out. This is just format conversion (with simple stuff like cross references added as I went along).
I did it by hand because I wanted to get to know the new syntax - that may well have meant I made different decisions on some of the formatting!
One thing I would love, would be cross referencing to structure members. A lot of IIO stuff is done by assigning these members of some really quite large structures.
Note whilst Daniel did a great job on these initial docs, they are far from complete - so I'd envision adding at least sections on:
1) A structural overview - probably diagrams of how the whole thing fits together.
2) in kernel interface description
3) Illustrations of 'exceptions' to the standard way of doing things (e.g. buffers without triggers)
4) DMA buffers etc.
5) Events
Jonathan
Jonathan Cameron (1):
docs: IIO documentation
Documentation/driver-api/iio/buffers.rst | 127 +++++++++++++++ Documentation/driver-api/iio/core.rst | 180 +++++++++++++++++++++ Documentation/driver-api/iio/index.rst | 15 ++ Documentation/driver-api/iio/intro.rst | 23 +++ Documentation/driver-api/iio/triggered-buffers.rst | 70 ++++++++ Documentation/driver-api/iio/triggers.rst | 78 +++++++++ Documentation/driver-api/index.rst | 1 + 7 files changed, 494 insertions(+) create mode 100644 Documentation/driver-api/iio/buffers.rst create mode 100644 Documentation/driver-api/iio/core.rst create mode 100644 Documentation/driver-api/iio/index.rst create mode 100644 Documentation/driver-api/iio/intro.rst create mode 100644 Documentation/driver-api/iio/triggered-buffers.rst create mode 100644 Documentation/driver-api/iio/triggers.rst
Signature · 1 line
2.10.2
Jonathan Cameron
maintainerPATCH 1/1 docs: IIO documentation
This is a manual conversion of the existing DocBook documentation for IIO. The intent is not to substantially change any of the content in this patch, but to give a base to build upon.
Signed-off-by Jonathan Cameron <[email protected]>
--- Documentation/driver-api/iio/buffers.rst | 127 +++++++++++++++ Documentation/driver-api/iio/core.rst | 180 +++++++++++++++++++++ Documentation/driver-api/iio/index.rst | 15 ++ Documentation/driver-api/iio/intro.rst | 23 +++ Documentation/driver-api/iio/triggered-buffers.rst | 70 ++++++++ Documentation/driver-api/iio/triggers.rst | 78 +++++++++ Documentation/driver-api/index.rst | 1 + 7 files changed, 494 insertions(+)
Documentation/driver-api/iio/buffers.rst new file +127 -0
@@ -0,0 +1,127 @@ +====================== +Industrial I/O Buffers +====================== + +* struct :c:type:`iio_buffer` — general buffer structure +* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel + is selected +* :c:func:`iio_buffer_get` — Grab a reference to the buffer +* :c:func:`iio_buffer_put` — Release the reference to the buffer + +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. + +IIO buffer sysfs interface +========================== +An IIO buffer has an associated attributes directory under +*/sys/bus/iio/iio:deviceX/buffer/*. Here are the existing attributes: + +* *length*, the total number of data samples (capacity) that can be stored by + the buffer. +* *enable*, activate buffer capture. + +IIO buffer setup +================ + +The meta information associated with a channel reading placed in a buffer is +called a scan element . The important bits configuring scan elements are +exposed to userspace applications via the +*/sys/bus/iio/iio:deviceX/scan_elements/* directory. This file contains +attributes of the following form: + +* *enable*, used for enabling a channel. If and only if its attribute is non + *zero*, then a triggered capture will contain data samples for this channel. +* *type*, description of the scan element data storage within the buffer and + hence the form in which it is read from user space. + Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] . + * *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. + * *shift*, if specified, is the shift that needs to be applied prior to + masking out unused bits. + * *repeat*, specifies the number of bits/storagebits repetitions. When the + repeat element is 0 or 1, then the repeat value is omitted. + +For example, a driver for a 3-axis accelerometer with 12 bit resolution where data is stored in two 8-bits registers 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: + +:: + + $ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type + le:s12/16>>4 + +A user space 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. + +For implementing buffer support a driver should initialize the following fields in iio_chan_spec definition: + +:: + + struct iio_chan_spec { + /* other members */ + int scan_index + struct { + char sign; + u8 realbits; + u8 storagebits; + u8 shift; + u8 repeat; + enum iio_endian endianness; + } scan_type; + }; + +The driver implementing the accelerometer described above will have the following channel definition: + +:: + + struct struct iio_chan_spec accel_channels[] = { + { + .type = IIO_ACCEL, + .modified = 1, + .channel2 = IIO_MOD_X, + /* other stuff here */ + .scan_index = 0, + .scan_type = { + .sign = 's', + .realbits = 12, + .storagebits = 16, + .shift = 4, + .endianness = IIO_LE, + }, + } + /* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1) + * and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis + */ + } + +Here **scan_index** defines the order in which the enabled channels are placed +inside the buffer. Channels with a lower **scan_index** will be placed before +channels with a higher index. Each channel needs to have a unique +**scan_index**. + +Setting **scan_index** to -1 can be used to indicate that the specific channel +does not support buffered capture. In this case no entries will be created for +the channel in the scan_elements directory. + +More details +============ +.. kernel-doc:: include/linux/iio/buffer.h +.. kernel-doc:: drivers/iio/industrialio-buffer.c + :export: + +
Documentation/driver-api/iio/core.rst new file +180 -0
180 lines not on this page · raw message
Documentation/driver-api/iio/index.rst new file +15 -0
@@ -0,0 +1,15 @@ +Industrial I/O +============== + +**Copyright** |copy| 2015 Intel Corporation + +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + core + buffers + triggers + triggered-buffers
Documentation/driver-api/iio/intro.rst new file +23 -0
@@ -0,0 +1,23 @@ +.. include:: <isonum.txt> + +================================= +Introduction to the IIO Subsystem +================================= + +The main purpose of the Industrial I/O subsystem (IIO) is to provide support for devices that in some sense perform either analog-to-digital conversion (ADC) or digital-to-analog conversion (DAC) or both. The aim is to fill the gap between the somewhat similar hwmon and input subsystems. Hwmon is directed at low sample rate sensors used to monitor and control the system itself, like fan speed control or temperature measurement. Input is, as its name suggests, focused on human interaction input devices (keyboard, mouse, touchscreen). In some cases there is considerable overlap between these and IIO. + +Devices that fall into this category include: + +* analog to digital converters (ADCs) +* accelerometers +* capacitance to digital converters (CDCs) +* digital to analog converters (DACs) +* gyroscopes +* inertial measurement units (IMUs) +* color and light sensors +* magnetometers +* pressure sensors +* proximity sensors +* temperature sensors + +Usually these sensors are connected via SPI or I2C. A common use case of the sensors devices is to have combined functionality (e.g. light plus proximity sensor).
Documentation/driver-api/iio/triggered-buffers.rst new file +70 -0
70 lines not on this page · raw message
Documentation/driver-api/iio/triggers.rst new file +78 -0
78 lines not on this page · raw message
Documentation/driver-api/index.rst +1 -0
@@ -19,6 +19,7 @@ available subsections can be seen below. message-based sound frame-buffer + iio/index input spi i2c
Signature · 1 line
2.10.2
Jonathan Corbet
maintainerRe: [PATCH] docs: IIO documentation
Quoted 3 lines · On Sun, 4 Dec 2016 20:49:06 +0000 Jonathan Cameron <[email protected]> wrote:
This is a manual conversion of the existing DocBook documentation for IIO. The intent is not to substantially change any of the content in this patch, but to give a base to build upon.
Looks mostly good, a couple of brief notes below.
Quoted 10 lines
Signed-off-by Jonathan Cameron <[email protected]>--- Documentation/driver-api/iio/buffers.rst | 127 +++++++++++++++ Documentation/driver-api/iio/core.rst | 180 +++++++++++++++++++++ Documentation/driver-api/iio/index.rst | 15 ++ Documentation/driver-api/iio/intro.rst | 23 +++ Documentation/driver-api/iio/triggered-buffers.rst | 70 ++++++++ Documentation/driver-api/iio/triggers.rst | 78 +++++++++ Documentation/driver-api/index.rst | 1 + 7 files changed, 494 insertions(+)
Please go ahead and remove iio.tmpl when you do this conversion, there's no reason to keep it around afterward.
Quoted 46 lines
Documentation/driver-api/iio/buffers.rst new file +40
-0@@ -0,0 +1,127 @@ +====================== +Industrial I/O Buffers +====================== + +* struct :c:type:`iio_buffer` — general buffer structure +* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel + is selected +* :c:func:`iio_buffer_get` — Grab a reference to the buffer +* :c:func:`iio_buffer_put` — Release the reference to the buffer + +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. + +IIO buffer sysfs interface +========================== +An IIO buffer has an associated attributes directory under +*/sys/bus/iio/iio:deviceX/buffer/*. Here are the existing attributes: + +* *length*, the total number of data samples (capacity) that can be stored by + the buffer. +* *enable*, activate buffer capture. + +IIO buffer setup +================ + +The meta information associated with a channel reading placed in a buffer is +called a scan element . The important bits configuring scan elements are +exposed to userspace applications via the +*/sys/bus/iio/iio:deviceX/scan_elements/* directory. This file contains +attributes of the following form: + +* *enable*, used for enabling a channel. If and only if its attribute is non + *zero*, then a triggered capture will contain data samples for this channel. +* *type*, description of the scan element data storage within the buffer and + hence the form in which it is read from user space. + Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] . + * *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.
Documentation/driver-api/iio/buffers.rst line 50
Quoted 10 lines
Documentation/driver-api/iio/buffers.rst new file +10
-0+ * *storagebits*, is the number of bits (after padding) that it occupies in the + buffer. + * *shift*, if specified, is the shift that needs to be applied prior to + masking out unused bits. + * *repeat*, specifies the number of bits/storagebits repetitions. When the + repeat element is 0 or 1, then the repeat value is omitted. + +For example, a driver for a 3-axis accelerometer with 12 bit resolution where data is stored in two 8-bits registers as follows: + +::
It would be nice to break the really long lines for future editing comfort.
Also worth noting: you can put the double colon at the end of the leading line, i.e.:
data is stored in two 8-bit registers as follows::
<ascii art here>
Doing it that way makes the RST file a bit more readable, IMO.
Thanks for doing this,
jon