mirror of https://lore.kernel.org/lkml/
 help / color / mirror / Atom feed
From: David Lechner <dlechner@baylibre.com>
To: "Jorge Marques" <jorge.marques@analog.com>,
	"Jonathan Cameron" <jic23@kernel.org>,
	"Lars-Peter Clausen" <lars@metafoo.de>,
	"Michael Hennerich" <Michael.Hennerich@analog.com>,
	"Rob Herring" <robh@kernel.org>,
	"Krzysztof Kozlowski" <krzk+dt@kernel.org>,
	"Conor Dooley" <conor+dt@kernel.org>,
	"Jonathan Corbet" <corbet@lwn.net>,
	"Nuno Sá" <nuno.sa@analog.com>,
	"Andy Shevchenko" <andy@kernel.org>,
	"Uwe Kleine-König" <ukleinek@kernel.org>
Cc: linux-iio@vger.kernel.org, linux-kernel@vger.kernel.org,
	devicetree@vger.kernel.org, linux-doc@vger.kernel.org,
	linux-pwm@vger.kernel.org
Subject: Re: [PATCH v2 4/5] docs: iio: new docs for ad4052 driver
Date: Fri, 25 Apr 2025 16:44:20 -0500	[thread overview]
Message-ID: <9f5b0709-f795-44c5-aa64-aaed81a459bf@baylibre.com> (raw)
In-Reply-To: <20250422-iio-driver-ad4052-v2-4-638af47e9eb3@analog.com>

On 4/22/25 6:34 AM, Jorge Marques wrote:
> This adds a new page to document how to use the ad4052 ADC driver.
> 
> Signed-off-by: Jorge Marques <jorge.marques@analog.com>
> ---
>  Documentation/iio/ad4052.rst | 95 ++++++++++++++++++++++++++++++++++++++++++++

Also need to update the table of contents in Documentation/iio/index.rst,
otherwise this page won't be build (and will cause a build error).

You can run `make htmldocs SPHINXDIRS=iio` to speed things up and only build
the iio directory to make sure you have it right.

More info: https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html

>  MAINTAINERS                  |  1 +
>  2 files changed, 96 insertions(+)
> 
> diff --git a/Documentation/iio/ad4052.rst b/Documentation/iio/ad4052.rst
> new file mode 100644
> index 0000000000000000000000000000000000000000..410aaa437ed5fea6a2924d374fa5f816f5754e22
> --- /dev/null
> +++ b/Documentation/iio/ad4052.rst
> @@ -0,0 +1,95 @@
> +.. SPDX-License-Identifier: GPL-2.0-only
> +
> +=============
> +AD4052 driver
> +=============
> +
> +ADC driver for Analog Devices Inc. AD4052 and similar devices.

Please don't put newline after every period. Here and throughout the document.
It makes it harder to read.

> +The module name is ``ad4052``.
> +
> +Supported devices
> +=================
> +
> +The following chips are supported by this driver:
> +
> +* `AD4050 <https://www.analog.com/AD4050>`_
> +* `AD4052 <https://www.analog.com/AD4052>`_
> +* `AD4056 <https://www.analog.com/AD4056>`_
> +* `AD4058 <https://www.analog.com/AD4058>`_
> +
> +Wiring modes
> +============
> +
> +The ADC uses SPI 4-wire mode, and contain two programmable GPIOs and
> +a CNV pin.
> +
> +The CNV pin is exposed as the ``cnv-gpios`` and triggers a ADC conversion.
> +GP1 is ADC conversion ready signal and GP0 Threshold event interrupt, both
> +exposed as interrupts.
> +
> +Omit ``cnv-gpios`` and tie CNV and CS together to use the rising edge
> +of the CS as the CNV signal.
> +
> +Device attributes
> +=================
> +
> +The ADC contain only one channels, and the following attributes:
> +
> +.. list-table:: Driver attributes
> +   :header-rows: 1
> +
> +   * - Attribute
> +     - Description
> +   * - ``in_voltage0_raw``
> +     - Raw ADC voltage value

No scale attribute? How do we convert raw to millivolts?

> +   * - ``in_voltage0_oversampling_ratio``
> +     - Enable the device's burst averaging mode to over sample using
> +       the internal sample rate.
> +   * - ``in_voltage0_oversampling_ratio_available``
> +     - List of available oversampling values. Value 0 disable the burst
> +       averaging mode.

Typically 1 means no oversampling, not zero. (It is a ratio, divide by 1 is the
same as doing nothing, but divide by 0 is undefined.)

> +   * - ``conversion_frequency``

Needs to be updated to ``oversampling_frequency``.

> +     - Device internal sample rate used in the burst averaging mode.
> +   * - ``conversion_frequency_available``
> +     - List of available sample rates.
> +
> +Threshold events
> +================
> +
> +The ADC supports a monitoring mode to raise threshold events.
> +The driver supports a single interrupt for both rising and falling
> +readings.
> +
> +The feature is enabled/disabled by setting ``thresh_either_en``.
> +During monitor mode, the device continuously operates in autonomous mode until
> +put back in configuration mode, due to this, the device returns busy until the
> +feature is disabled.

Probably worth mentioning the ``events/sampling_frequency`` and
``sampling_frequency_available`` attributes since we've mentioned all of the
other attributes.

> +
> +Low-power mode
> +==============
> +
> +The device enters low-power mode on idle to save power.
> +Enabling an event puts the device out of the low-power since the ADC
> +autonomously samples to assert the event condition.
> +
> +SPI offload support
> +===================
> +
> +To be able to achieve the maximum sample rate, the driver can be used with the
> +`AXI SPI Engine`_ to provide SPI offload support.
> +
> +.. _AXI SPI Engine: http://analogdevicesinc.github.io/hdl/projects/ad4052_ardz/index.html
> +
> +When SPI offload is being used, additional attributes are present:
> +
> +.. list-table:: Additional attributes
> +   :header-rows: 1
> +
> +   * - Attribute
> +     - Description
> +   * - ``in_voltage0_sampling_frequency``
> +     - Set the sampling frequency.
> +   * - ``in_voltage0_sampling_frequency_available``
> +     - Get the sampling frequency range.

In the driver, this is currently info_mask_shared_by_type, so would be
``in_voltage_sampling_frequency``. And there currently isn't 
``in_voltage_sampling_frequency_available`` in the driver, so it needs to be
added in the driver (or removed here).

> +
> +The scan type is different when the buffer with offload support is enabled.
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 81fbe7176475c48eae03ab04115d4ef5b6299fac..04aa8db44bee418382a2e74cb6b1d03a810bd781 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1334,6 +1334,7 @@ M:	Jorge Marques <jorge.marques@analog.com>
>  S:	Supported
>  W:	https://ez.analog.com/linux-software-drivers
>  F:	Documentation/devicetree/bindings/iio/adc/adi,ad4052.yaml
> +F:	Documentation/iio/ad4052.rst
>  
>  ANALOG DEVICES INC AD4130 DRIVER
>  M:	Cosmin Tanislav <cosmin.tanislav@analog.com>
> 


  reply	other threads:[~2025-04-25 21:44 UTC|newest]

Thread overview: 38+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2025-04-22 11:34 [PATCH v2 0/5] Add support for AD4052 device family Jorge Marques
2025-04-22 11:34 ` [PATCH v2 1/5] Documentation: ABI: add oversampling frequency in sysfs-bus-iio Jorge Marques
2025-04-22 15:50   ` Andy Shevchenko
2025-04-29 13:47     ` Jorge Marques
2025-04-29 15:40       ` David Lechner
2025-04-29 22:03         ` Andy Shevchenko
2025-05-05 12:39           ` Jonathan Cameron
2025-04-25 21:16   ` David Lechner
2025-04-29 13:47     ` Jorge Marques
2025-04-22 11:34 ` [PATCH v2 2/5] iio: code: mark iio_dev as const in iio_buffer_enabled Jorge Marques
2025-04-22 15:51   ` Andy Shevchenko
2025-04-26 15:45   ` Jonathan Cameron
2025-06-02  9:48     ` Jorge Marques
2025-04-22 11:34 ` [PATCH v2 3/5] dt-bindings: iio: adc: Add adi,ad4052 Jorge Marques
2025-04-25 20:58   ` Rob Herring (Arm)
2025-04-25 22:50   ` David Lechner
2025-04-29 13:48     ` Jorge Marques
2025-04-29 15:45       ` David Lechner
2025-06-02  9:17         ` Jorge Marques
2025-06-02 15:17           ` David Lechner
2025-06-02 16:32             ` Jorge Marques
2025-06-02 17:23               ` David Lechner
2025-06-03  7:29                 ` Jorge Marques
2025-06-03 13:27                   ` David Lechner
2025-04-22 11:34 ` [PATCH v2 4/5] docs: iio: new docs for ad4052 driver Jorge Marques
2025-04-25 21:44   ` David Lechner [this message]
2025-04-29 13:49     ` Jorge Marques
2025-04-29 15:50       ` David Lechner
2025-04-22 11:34 ` [PATCH v2 5/5] iio: adc: add support for ad4052 Jorge Marques
2025-04-22 16:33   ` Andy Shevchenko
2025-04-29 13:49     ` Jorge Marques
2025-04-25 23:13   ` David Lechner
2025-06-02 11:16     ` Jorge Marques
2025-06-02 15:33       ` David Lechner
2025-04-26 16:03   ` Jonathan Cameron
2025-06-02 10:50     ` Jorge Marques
2025-05-16 10:11   ` Uwe Kleine-König
2025-06-02 10:38     ` Jorge Marques

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=9f5b0709-f795-44c5-aa64-aaed81a459bf@baylibre.com \
    --to=dlechner@baylibre.com \
    --cc=Michael.Hennerich@analog.com \
    --cc=andy@kernel.org \
    --cc=conor+dt@kernel.org \
    --cc=corbet@lwn.net \
    --cc=devicetree@vger.kernel.org \
    --cc=jic23@kernel.org \
    --cc=jorge.marques@analog.com \
    --cc=krzk+dt@kernel.org \
    --cc=lars@metafoo.de \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-iio@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-pwm@vger.kernel.org \
    --cc=nuno.sa@analog.com \
    --cc=robh@kernel.org \
    --cc=ukleinek@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox

all inboxes | Powered by JetHome®