mbox series

[v4,0/3] adis16475 driver documentation

Message ID 20240213081720.17549-1-ramona.gradinariu@analog.com
Headers
Series adis16475 driver documentation |

Message

Ramona Gradinariu Feb. 13, 2024, 8:17 a.m. UTC 
  Add documentation for:
- iio device buffers describing buffer attributes and how data is structured in
buffers using scan elements.
- adis16475 driver which describes the driver device files and shows how the
user may use the ABI for various scenarios (configuration, measurement, etc.).

This kind of documentation describes how the user can interract with the drivers
device files, showing the driver's particularities and we think all IIO drivers
need such a documentation and will benefit from it.
Having this documentation in the Linux Kernel will make it more accessible to
the user, seeing how it is in the same location as the code.
Analog Devices is prepared to add similar documentation for all new drivers (for
ADI components), and in time to also add documentation for existing drivers,
following the adis16475 documentation template.

Ramona Gradinariu (3):
  docs: iio: Refactor index.rst
  docs: iio: add documentation for device buffers
  docs: iio: add documentation for adis16475 driver

 Documentation/iio/adis16475.rst  | 406 +++++++++++++++++++++++++++++++
 Documentation/iio/iio_devbuf.rst | 125 ++++++++++
 Documentation/iio/index.rst      |   9 +-
 3 files changed, 539 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/iio/adis16475.rst
 create mode 100644 Documentation/iio/iio_devbuf.rst

--
2.34.1

Comments

Jonathan Cameron Feb. 16, 2024, 11:54 a.m. UTC | #1 
A few follow up comments on your David's review
Anything I deleted didn't need a comment as all made sense to me!

> 
> > +to 0, for devices with a single buffer.  
> 
> Is /sys/bus/iio/devices/deviceX/buffer (without the Y) for backwards
> compatibility?

Yes. For these docs I'd not mention it. New software should be aware of multiple
buffers being possible and not use it. Same is true of the scan_elements directory.
If we really want to mention it, say buffer/ and scan_elements are for backwards
compatibility and should not be used in new userspace software.

They aren't going anywhere, but better people start from a multibuffer world!

> 
> > +
> > +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.  
> 
> Could be useful here to mention that writing a non-zero value here to
> enable the buffer may result in an error, such as EINVAL, e.g. if an
> invalid configuration was selected, like choosing a combination of
> scan elements that don't match one of the valid scan masks.

Be careful to not refer to matching.  Could be a subset.  I'd refer to
"an unsupported combination of channels" or something like that.


> > +directory. 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 positive integer attribute specifying the position of the channel in  
> 
> Isn't 0 a valid scan index? So non-negative? Or unsigned?

Yes - unsigned would be my preference.

> 
> > +the buffer. Note these are not dependent on what is enabled and may not be
> > +contiguous. Thus for user-space 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.
> > +  
> 
> It would also be nice to get an example on the binary layout for
> something that has multiple channels enabled. In particular with the
> data alignment, e.g. when you have a 16-bit word followed by a 64-bit
> word.
> 

Agreed - the padding is sometimes not what people expect.

> 
> > +**_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 user space. 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-bits registers as follows:
> > +
> > +.. code-block:: bash  
> 
> Doesn't look like this should use "bash" styling.
> 
> > +
> > +          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 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.  
> 
> Is it always assumed that scan data is `raw` and needs to be
> multiplied by `scale` for that channel to convert it to SI (or IIO
> standard) units?

Definitely by far the most common case but there are a few exceptions where
there isn't a _raw attribute but only an _input one where the assumption is
processed data.  Tricky to mention that here without adding complexity.
Maybe just add some weasel words to hint there are corners not covered by
this doc.

> 
> > +
> > +Please see Documentation/ABI/testing/sysfs-bus-iio for a complete description of
> > +the attributes.  
> 
> Is it also worth mentioning
> ``Documentation/ABI/testing/sysfs-bus-iio-dma-buffer`` here?

I'd not do that until we have a section for these docs on dma buffers which
are different in a bunch of ways. Would just be a potential source of
confusion.

Jonathan