Re: [PATCH v2 02/19] staging: iio: Documentation: document IIO resolver AD2S1210 sysfs attributes

[Jonathan Cameron]

On Thu, 21 Sep 2023 09:43:43 -0500
David Lechner <dlechner@xxxxxxxxxxxx> wrote:

> This adds documentation for the device-specific sysfs attributes of the
> iio/resolver/ad2s1210 driver.
> 
> Signed-off-by: David Lechner <dlechner@xxxxxxxxxxxx>

Hi David,

I'm fine with carrying these docs in staging, but I think we need to resolve
mapping as many of these as possible to standard ABI if we can for
all the normal reasons about software having no idea how to deal
with custom ABI.

Anyhow, I'll use this as an opportunity to comment on the individual
files.



> ---
>  .../sysfs-bus-iio-resolver-ad2s1210           | 109 ++++++++++++++++++
>  1 file changed, 109 insertions(+)
>  create mode 100644 drivers/staging/iio/Documentation/sysfs-bus-iio-resolver-ad2s1210
> 
> diff --git a/drivers/staging/iio/Documentation/sysfs-bus-iio-resolver-ad2s1210 b/drivers/staging/iio/Documentation/sysfs-bus-iio-resolver-ad2s1210
> new file mode 100644
> index 000000000000..32890c85168e
> --- /dev/null
> +++ b/drivers/staging/iio/Documentation/sysfs-bus-iio-resolver-ad2s1210
> @@ -0,0 +1,109 @@
> +What:		/sys/bus/iio/devices/iio:deviceX/dos_mis_thrd
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Degradation of Signal Mismatch
> +		Threshold value. Writing sets the value. Valid values are 0 (0V)
> +		to 127 (4.826V). To convert the value to volts, multiply by
> +		0.038.

I mention in the cover letter, but I wonder if we can map this to a threshold
on a differential channel between the cosine and sine channels (use labels for
the channels to identify them). It's a stretch but perhaps better than
completely custom as at least we have event tooling to read it.

If nothing else we need these to have standard units and the
unit to be obvious from the name.  Voltages in IIO are mV (because
we copied hwmon a long time back)

> +
> +What:		/sys/bus/iio/devices/iio:deviceX/dos_ovr_thrd
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Degradation of Signal Overrange
> +		Threshold value. Writing sets the value. Valid values are 0 (0V)
> +		to 127 (4.826V). To convert the value to volts, multiply by
> +		0.038.
Not clear what this actually is to me, but it's a threshold on something!
Probably two channels which is always a pain as we'll have indicate two events
if they are enabled.

> +
> +What:		/sys/bus/iio/devices/iio:deviceX/dos_rst_max_thrd
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Degradation of Signal Reset Maximum
> +		Threshold value. Writing sets the value. Valid values are 0 (0V)
> +		to 127 (4.826V). To convert the value to volts, multiply by
> +		0.038.

No idea what this one is.  What does 'reset' have to do with it?
Ah I went and looked.  This is the reset value used for the running maximum / minimum
values.  They matter because they fault detection is difference between the values
and if we say init the minimum to lower than actually seen that will make the
error more likely (I think!).

So not sure what we map this to.  Maybe this just has to be custom ABI but
it should be associated with the threshold event - though I'd not registered
that's on a running minimum and maximum rather than some 'windowed' version
for recent values...

> +
> +What:		/sys/bus/iio/devices/iio:deviceX/dos_rst_min_thrd
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Degradation of Signal Reset Minimum
> +		Threshold value. Writing sets the value. Valid values are 0 (0V)
> +		to 127 (4.826V). To convert the value to volts, multiply by
> +		0.038.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/fault

This fails the sniff test for a sysfs attribute giving multiple things.
If we do use this sort of reporting rather than an event, maybe a fault
directory (sysfs group) with 8 files in it.
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns a hex value containing the fault bit flags.
> +
> +		Bit	Description
> +		---	-----------
> +		D7	Sine/cosine inputs clipped
> +		D6	Sine/cosine inputs below LOS threshold
> +		D5	Sine/cosine inputs exceed DOS overrange threshold
> +		D4	Sine/cosine inputs exceed DOS mismatch threshold
> +		D3	Tracking error exceeds LOT threshold
> +		D2	Velocity exceeds maximum tracking rate
> +		D1	Phase error exceeds phase lock range
> +		D0	Configuration parity error
> +
> +		Writing any value will clear any fault conditions.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/excitation_frequency

Hmm. I though we already had this.  Turns up in various types of device.
But nope, can't find it.  I'm fine with this one being added to the main ABI.

> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Excitation Frequency in Hz. Writing
> +		sets the Excitation Frequency and performs a software reset on
> +		the device to apply the change. Valid values are 2000 (2kHz) to
> +		20000 (20kHz).
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/los_thrd
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Loss of Signal Reset Threshold
> +		value. Writing sets the value. Valid values are 0 (0V) to
> +		127 (4.826V). To convert the value to volts, multiply by 0.038.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/lot_high_thrd
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Loss of Position Tracking Detection
> +		High Threshold value. Writing sets the value. Valid values are
> +		0 (0 deg) to 127 (9/18/45 deg). The interpretation of the value
> +		depends on the selected resolution. To convert the value to
> +		degrees, multiply by 0.35 for 10-bit resolution, multiply by
> +		0.14 for 12-bit resolution or multiply by 0.09 for 14 and 16-bit
> +		resolution.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/lot_low_thrd
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Loss of Position Tracking Detection
> +		Low Threshold value. Writing sets the value. Valid values are
> +		0 (0 deg) to 127 (9/18/45 deg). The interpretation of the value
> +		depends on the selected resolution. To convert the value to
> +		degrees, multiply by 0.35 for 10-bit resolution, multiply by
> +		0.14 for 12-bit resolution or multiply by 0.09 for 14 and 16-bit
> +		resolution.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/phase_lock_range

For what it's worth Phases in IIO (phase_raw in ABI docs) are defined
in radians so this will want to be appropriately scaled if we keep it around.

This one feels like a threshold on phase which is already in the IIO ABI
(for 3 phase power monitors IIRC)

Jonathan


> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the current Phase lock range in degrees. Writing
> +		sets the value in the configuration register.
> +
> +What:		/sys/bus/iio/devices/iio:deviceX/phase_lock_range_available
> +KernelVersion:  6.7
> +Contact:	linux-iio@xxxxxxxxxxxxxxx
> +Description:
> +		Reading returns the possible values for the phase_lock_range
> +		attribute, namely 44 and 360.