[v4,14/17] staging: iio: resolver: ad2s1210: add register/fault support summary
Commit Message
The ad2s1210 driver shoe-horns the register and fault support into IIO
events. The mapping between the registers/faults and the events is not
obvious. To save users from having to read the entire driver to figure
out how to use it, add a summary of the register/fault support to the
top of the file.
Signed-off-by: David Lechner <dlechner@baylibre.com>
---
v4 changes: New patch in v4.
drivers/staging/iio/resolver/ad2s1210.c | 40 +++++++++++++++++++++++++++++++++
1 file changed, 40 insertions(+)
Comments
On Thu, 5 Oct 2023 19:50:31 -0500
David Lechner <dlechner@baylibre.com> wrote:
> The ad2s1210 driver shoe-horns the register and fault support into IIO
> events. The mapping between the registers/faults and the events is not
> obvious. To save users from having to read the entire driver to figure
> out how to use it, add a summary of the register/fault support to the
> top of the file.
>
> Signed-off-by: David Lechner <dlechner@baylibre.com>
This is indeed useful to have.
Applied.
Thanks,
Jonathan
> ---
>
> v4 changes: New patch in v4.
>
> drivers/staging/iio/resolver/ad2s1210.c | 40 +++++++++++++++++++++++++++++++++
> 1 file changed, 40 insertions(+)
>
> diff --git a/drivers/staging/iio/resolver/ad2s1210.c b/drivers/staging/iio/resolver/ad2s1210.c
> index d9d51bbbade8..51490fea1647 100644
> --- a/drivers/staging/iio/resolver/ad2s1210.c
> +++ b/drivers/staging/iio/resolver/ad2s1210.c
> @@ -4,7 +4,47 @@
> *
> * Copyright (c) 2010-2010 Analog Devices Inc.
> * Copyright (c) 2023 BayLibre, SAS
> + *
> + * Device register to IIO ABI mapping:
> + *
> + * Register | Addr | IIO ABI (sysfs)
> + * ----------------------------|------|-------------------------------------------
> + * DOS Overrange Threshold | 0x89 | events/in_altvoltage0_thresh_rising_value
> + * DOS Mismatch Threshold | 0x8A | events/in_altvoltage0_mag_rising_value
> + * DOS Reset Maximum Threshold | 0x8B | events/in_altvoltage0_mag_rising_reset_max
> + * DOS Reset Minimum Threshold | 0x8C | events/in_altvoltage0_mag_rising_reset_min
> + * LOT High Threshold | 0x8D | events/in_angl1_thresh_rising_value
> + * LOT Low Threshold [1] | 0x8E | events/in_angl1_thresh_rising_hysteresis
> + * Excitation Frequency | 0x91 | out_altvoltage0_frequency
> + * Control | 0x92 | *as bit fields*
> + * Phase lock range | D5 | events/in_phase0_mag_rising_value
> + * Hysteresis | D4 | in_angl0_hysteresis
> + * Encoder resolution | D3:2 | *not implemented*
> + * Resolution | D1:0 | *device tree: assigned-resolution-bits*
> + * Soft Reset | 0xF0 | [2]
> + * Fault | 0xFF | *not implemented*
> + *
> + * [1]: The value written to the LOT low register is high value minus the
> + * hysteresis.
> + * [2]: Soft reset is performed when `out_altvoltage0_frequency` is written.
> + *
> + * Fault to event mapping:
> + *
> + * Fault | | Channel | Type | Direction
> + * ----------------------------------------|----|---------------------------------
> + * Sine/cosine inputs clipped [3] | D7 | altvoltage1 | mag | either
> + * Sine/cosine inputs below LOS | D6 | altvoltage0 | thresh | falling
> + * Sine/cosine inputs exceed DOS overrange | D5 | altvoltage0 | thresh | rising
> + * Sine/cosine inputs exceed DOS mismatch | D4 | altvoltage0 | mag | rising
> + * Tracking error exceeds LOT | D3 | angl1 | thresh | rising
> + * Velocity exceeds maximum tracking rate | D2 | anglvel0 | mag | rising
> + * Phase error exceeds phase lock range | D1 | phase0 | mag | rising
> + * Configuration parity error | D0 | *writes to kernel log*
> + *
> + * [3]: The chip does not differentiate between fault on sine vs. cosine so
> + * there will also be an event on the altvoltage2 channel.
> */
> +
> #include <linux/bitfield.h>
> #include <linux/bits.h>
> #include <linux/clk.h>
>
@@ -4,7 +4,47 @@
*
* Copyright (c) 2010-2010 Analog Devices Inc.
* Copyright (c) 2023 BayLibre, SAS
+ *
+ * Device register to IIO ABI mapping:
+ *
+ * Register | Addr | IIO ABI (sysfs)
+ * ----------------------------|------|-------------------------------------------
+ * DOS Overrange Threshold | 0x89 | events/in_altvoltage0_thresh_rising_value
+ * DOS Mismatch Threshold | 0x8A | events/in_altvoltage0_mag_rising_value
+ * DOS Reset Maximum Threshold | 0x8B | events/in_altvoltage0_mag_rising_reset_max
+ * DOS Reset Minimum Threshold | 0x8C | events/in_altvoltage0_mag_rising_reset_min
+ * LOT High Threshold | 0x8D | events/in_angl1_thresh_rising_value
+ * LOT Low Threshold [1] | 0x8E | events/in_angl1_thresh_rising_hysteresis
+ * Excitation Frequency | 0x91 | out_altvoltage0_frequency
+ * Control | 0x92 | *as bit fields*
+ * Phase lock range | D5 | events/in_phase0_mag_rising_value
+ * Hysteresis | D4 | in_angl0_hysteresis
+ * Encoder resolution | D3:2 | *not implemented*
+ * Resolution | D1:0 | *device tree: assigned-resolution-bits*
+ * Soft Reset | 0xF0 | [2]
+ * Fault | 0xFF | *not implemented*
+ *
+ * [1]: The value written to the LOT low register is high value minus the
+ * hysteresis.
+ * [2]: Soft reset is performed when `out_altvoltage0_frequency` is written.
+ *
+ * Fault to event mapping:
+ *
+ * Fault | | Channel | Type | Direction
+ * ----------------------------------------|----|---------------------------------
+ * Sine/cosine inputs clipped [3] | D7 | altvoltage1 | mag | either
+ * Sine/cosine inputs below LOS | D6 | altvoltage0 | thresh | falling
+ * Sine/cosine inputs exceed DOS overrange | D5 | altvoltage0 | thresh | rising
+ * Sine/cosine inputs exceed DOS mismatch | D4 | altvoltage0 | mag | rising
+ * Tracking error exceeds LOT | D3 | angl1 | thresh | rising
+ * Velocity exceeds maximum tracking rate | D2 | anglvel0 | mag | rising
+ * Phase error exceeds phase lock range | D1 | phase0 | mag | rising
+ * Configuration parity error | D0 | *writes to kernel log*
+ *
+ * [3]: The chip does not differentiate between fault on sine vs. cosine so
+ * there will also be an event on the altvoltage2 channel.
*/
+
#include <linux/bitfield.h>
#include <linux/bits.h>
#include <linux/clk.h>