Currently, there are 3 helper macros in iio/events.h to create event
identifiers:
- IIO_EVENT_CODE : create generic event identifier for differential and non
  differential channels
- IIO_MOD_EVENT_CODE : create event identifier for modified (non
  differential) channels
- IIO_UNMOD_EVENT_CODE : create event identifier for unmodified (non
  differential) channels

For differential channels, drivers are expected to use IIO_EVENT_CODE.
However, only one driver in drivers/iio currently uses it correctly,
leading to inconsistent event identifiers for differential channels that
don’t match the intended attributes (such as max1363.c that supports
differential channels, but only uses IIO_UNMOD_EVENT_CODE).

To prevent such issues in future drivers, a new helper macro,
IIO_DIFF_EVENT_CODE, is introduced to specifically create event identifiers
for differential channels. Only one helper is needed for differential
channels since they cannot have modifiers.

Additionally, the descriptions for IIO_MOD_EVENT_CODE and
IIO_UNMOD_EVENT_CODE have been updated to clarify that they are intended
for non-differential channels,

Signed-off-by: Julien Stephan <jstephan@baylibre.com>
---
 include/linux/iio/events.h | 18 ++++++++++++++++--
 1 file changed, 16 insertions(+), 2 deletions(-)

diff --git a/include/linux/iio/events.h b/include/linux/iio/events.h
index a4558c45a548834e33702927609ca9ad447c67de..eeaba5e1525e44fd3b51985ffa99837efc6cdd00 100644
--- a/include/linux/iio/events.h
+++ b/include/linux/iio/events.h
@@ -30,7 +30,8 @@
 
 
 /**
- * IIO_MOD_EVENT_CODE() - create event identifier for modified channels
+ * IIO_MOD_EVENT_CODE() - create event identifier for modified (non
+ * differential) channels
  * @chan_type:	Type of the channel. Should be one of enum iio_chan_type.
  * @number:	Channel number.
  * @modifier:	Modifier for the channel. Should be one of enum iio_modifier.
@@ -43,7 +44,8 @@
 	IIO_EVENT_CODE(chan_type, 0, modifier, direction, type, number, 0, 0)
 
 /**
- * IIO_UNMOD_EVENT_CODE() - create event identifier for unmodified channels
+ * IIO_UNMOD_EVENT_CODE() - create event identifier for unmodified (non
+ * differential) channels
  * @chan_type:	Type of the channel. Should be one of enum iio_chan_type.
  * @number:	Channel number.
  * @type:	Type of the event. Should be one of enum iio_event_type.
@@ -53,4 +55,16 @@
 #define IIO_UNMOD_EVENT_CODE(chan_type, number, type, direction)	\
 	IIO_EVENT_CODE(chan_type, 0, 0, direction, type, number, 0, 0)
 
+/**
+ * IIO_DIFF_EVENT_CODE() - create event identifier for differential channels
+ * @chan_type:	Type of the channel. Should be one of enum iio_chan_type.
+ * @chan1:	First channel number for differential channels.
+ * @chan2:	Second channel number for differential channels.
+ * @type:	Type of the event. Should be one of enum iio_event_type.
+ * @direction:	Direction of the event. One of enum iio_event_direction.
+ */
+
+#define IIO_DIFF_EVENT_CODE(chan_type, chan1, chan2, type, direction)	\
+	IIO_EVENT_CODE(chan_type, 1, 0, direction, type, 0, chan1, chan2)
+
 #endif

-- 
2.47.0

On Mon, 28 Oct 2024 17:38:11 +0100
Julien Stephan <jstephan@baylibre.com> wrote:

> Currently, there are 3 helper macros in iio/events.h to create event
> identifiers:
> - IIO_EVENT_CODE : create generic event identifier for differential and non
>   differential channels
> - IIO_MOD_EVENT_CODE : create event identifier for modified (non
>   differential) channels
> - IIO_UNMOD_EVENT_CODE : create event identifier for unmodified (non
>   differential) channels
> 
> For differential channels, drivers are expected to use IIO_EVENT_CODE.
> However, only one driver in drivers/iio currently uses it correctly,
> leading to inconsistent event identifiers for differential channels that
> don’t match the intended attributes (such as max1363.c that supports
> differential channels, but only uses IIO_UNMOD_EVENT_CODE).

The max1363 is a weird beast IIRC. It's only been about 15 years since I implemented
events :(
When events are enabled it is really fiddly to read the data, so we never
bothered. Mind you, it does indeed seem to set up the differential mode
but not return differential events. oops.

> 
> To prevent such issues in future drivers, a new helper macro,
> IIO_DIFF_EVENT_CODE, is introduced to specifically create event identifiers
> for differential channels. Only one helper is needed for differential
> channels since they cannot have modifiers.
> 
> Additionally, the descriptions for IIO_MOD_EVENT_CODE and
> IIO_UNMOD_EVENT_CODE have been updated to clarify that they are intended
> for non-differential channels,
> 
> Signed-off-by: Julien Stephan <jstephan@baylibre.com>
Given comment below doesn't really matter, series applied.

I'm tempted to just say break ABI and fix these. It's a bug
even if a long standing one so a valid reason to cause people
problems if they are checking for wrong event. 

Thanks,

Jonathan

> ---
>  include/linux/iio/events.h | 18 ++++++++++++++++--
>  1 file changed, 16 insertions(+), 2 deletions(-)
> 
> diff --git a/include/linux/iio/events.h b/include/linux/iio/events.h
> index a4558c45a548834e33702927609ca9ad447c67de..eeaba5e1525e44fd3b51985ffa99837efc6cdd00 100644
> --- a/include/linux/iio/events.h
> +++ b/include/linux/iio/events.h
> @@ -30,7 +30,8 @@
>  
>  
>  /**
> - * IIO_MOD_EVENT_CODE() - create event identifier for modified channels
> + * IIO_MOD_EVENT_CODE() - create event identifier for modified (non
> + * differential) channels

Whilst subtle and maybe ok to state here, there is no such thing as a modified
differential channel (because they both use chan2).

So we could not mention it, but I guess it is harmless addition.

>   * @chan_type:	Type of the channel. Should be one of enum iio_chan_type.
>   * @number:	Channel number.
>   * @modifier:	Modifier for the channel. Should be one of enum iio_modifier.
> @@ -43,7 +44,8 @@
>  	IIO_EVENT_CODE(chan_type, 0, modifier, direction, type, number, 0, 0)
>  
>  /**
> - * IIO_UNMOD_EVENT_CODE() - create event identifier for unmodified channels
> + * IIO_UNMOD_EVENT_CODE() - create event identifier for unmodified (non
> + * differential) channels
>   * @chan_type:	Type of the channel. Should be one of enum iio_chan_type.
>   * @number:	Channel number.
>   * @type:	Type of the event. Should be one of enum iio_event_type.
> @@ -53,4 +55,16 @@
>  #define IIO_UNMOD_EVENT_CODE(chan_type, number, type, direction)	\
>  	IIO_EVENT_CODE(chan_type, 0, 0, direction, type, number, 0, 0)
>  
> +/**
> + * IIO_DIFF_EVENT_CODE() - create event identifier for differential channels
> + * @chan_type:	Type of the channel. Should be one of enum iio_chan_type.
> + * @chan1:	First channel number for differential channels.
> + * @chan2:	Second channel number for differential channels.
> + * @type:	Type of the event. Should be one of enum iio_event_type.
> + * @direction:	Direction of the event. One of enum iio_event_direction.
> + */
> +
> +#define IIO_DIFF_EVENT_CODE(chan_type, chan1, chan2, type, direction)	\
> +	IIO_EVENT_CODE(chan_type, 1, 0, direction, type, 0, chan1, chan2)
> +
>  #endif
>