Received-SPF: pass (google.com: domain of linux-kernel+bounces-207076-linux.lists.archive=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99;
Date: Sat, 8 Jun 2024 15:40:53 +0100
From: Jonathan Cameron <jic23@kernel.org>
To: Kim Seer Paller <kimseer.paller@analog.com>
Cc: <linux-kernel@vger.kernel.org>, <linux-iio@vger.kernel.org>,
 <devicetree@vger.kernel.org>, David Lechner <dlechner@baylibre.com>,
 Lars-Peter Clausen <lars@metafoo.de>, Liam Girdwood <lgirdwood@gmail.com>,
 Mark Brown <broonie@kernel.org>, Dimitri Fedrau <dima.fedrau@gmail.com>,
 Krzysztof Kozlowski <krzk+dt@kernel.org>, "Rob Herring" <robh@kernel.org>,
 Conor Dooley <conor+dt@kernel.org>, "Michael Hennerich"
 <michael.hennerich@analog.com>, Nuno =?UTF-8?B?U8Oh?=
 <noname.nuno@gmail.com>
Subject: Re: [PATCH v3 1/5] iio: ABI: Generalize ABI documentation for DAC
Message-ID: <20240608154053.1cf1097e@jic23-huawei>
In-Reply-To: <20240603012200.16589-2-kimseer.paller@analog.com>
References: <20240603012200.16589-1-kimseer.paller@analog.com>
	<20240603012200.16589-2-kimseer.paller@analog.com>
Precedence: bulk
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

On Mon, 3 Jun 2024 09:21:56 +0800
Kim Seer Paller <kimseer.paller@analog.com> wrote:

> Introduces a more generalized ABI documentation for DAC. Instead of
> having separate ABI files for each DAC, we now have a single ABI file
> that covers the common sysfs interface for all DAC.
> 
> Co-developed-by: Michael Hennerich <michael.hennerich@analog.com>
> Signed-off-by: Michael Hennerich <michael.hennerich@analog.com>
> Signed-off-by: Kim Seer Paller <kimseer.paller@analog.com>

A few comments inline.

I wondered if it made sense to combine voltage and current entries of each type
in single block, but I think the docs would become too complicated with lots
of wild cards etc.  Hence I think the duplication is fine.

Jonathan

> ---
>  Documentation/ABI/testing/sysfs-bus-iio-dac   | 61 +++++++++++++++++++
>  .../ABI/testing/sysfs-bus-iio-dac-ltc2688     | 31 ----------
>  2 files changed, 61 insertions(+), 31 deletions(-)
>  create mode 100644 Documentation/ABI/testing/sysfs-bus-iio-dac
> 
> diff --git a/Documentation/ABI/testing/sysfs-bus-iio-dac b/Documentation/ABI/testing/sysfs-bus-iio-dac
> new file mode 100644
> index 000000000000..36d316bb75f6
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-bus-iio-dac
> @@ -0,0 +1,61 @@
> +What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_toggle_en
> +KernelVersion:	5.18
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +       		Toggle enable. Write 1 to enable toggle or 0 to disable it. This
Tab vs space issue - see below.

> +		is useful when one wants to change the DAC output codes. The way
> +		it should be done is:
> +
> +        	- disable toggle operation;
> +        	- change out_currentY_rawN, where N is the integer value of the symbol;
> +        	- enable toggle operation.
Same question as below on whether this is accurate - Maybe it just needs to mention
this scheme needs to be used for autonomous toggling (out of software control).
It works for software toggling but may be overkill!

> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_rawN
> +KernelVersion:	5.18
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		This attribute has the same meaning as out_currentY_raw. It is
> +		specific to toggle enabled channels and refers to the DAC output
> +		code in INPUT_N (_rawN), where N is the integer value of the symbol.
> +		The same scale and offset as in out_currentY_raw applies.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_currentY_symbol
> +KernelVersion:	5.18
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +		Performs a SW switch to a predefined output symbol. This attribute
> +		is specific to toggle enabled channels and allows switching between
> +		multiple predefined symbols. Each symbol corresponds to a different
> +		output, denoted as out_currentY_rawN, where N is the integer value
> +		of the symbol. Writing an integer value N will select out_currentY_rawN.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/out_voltageY_toggle_en
> +KernelVersion:	5.18
> +Contact:	linux-iio@vger.kernel.org
> +Description:
> +       		Toggle enable. Write 1 to enable toggle or 0 to disable it. This

Mix of spacing and tabs is inconsistent. Hence the odd indent in this reply version.

> +		is useful when one wants to change the DAC output codes. The way
> +		it should be done is:

Hmm. Is this true?  If we are doing autonomous toggling on a clock or similar than agreed.
If we are using the out_current_symbol software control it would be common to switch
to A, modify B, switch to B, modify A etc.

I think our interface has probably evolved and so this might need an update.

> +
> +        	- disable toggle operation;
> +        	- change out_voltageY_rawN, where N is the integer value of the symbol;
> +        	- enable toggle operation.