Re: [PATCH] docs: IIO documentation

[Jonathan Corbet]

On Sun,  4 Dec 2016 20:49:06 +
Jonathan Cameron  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.

> Signed-off-by: Jonathan Cameron 
> ---
>  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.

> diff --git a/Documentation/driver-api/iio/buffers.rst 
> b/Documentation/driver-api/iio/buffers.rst
> new file mode 100644
> index ..559256b8e607
> --- /dev/null
> +++ b/Documentation/driver-api/iio/buffers.rst
> @@ -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:
> +
> +::

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::



Doing it that way makes the RST file a bit more readable, IMO.

Thanks for doing this,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] docs: IIO documentation

[Jonathan Cameron]

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 
---
 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(+)

diff --git a/Documentation/driver-api/iio/buffers.rst 
b/Documentation/driver-api/iio/buffers.rst
new file mode 100644
index ..559256b8e607
--- /dev/null
+++ b/Documentation/driver-api/iio/buffers.rst
@@ -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,
+