[PATCH] iio: adc: at91-sama5d2_adc: explain why indio_dev->name = dev_name() is wrong

[PATCH] iio: adc: at91-sama5d2_adc: explain why indio_dev->name = dev_name() is wrong

[David Lechner]

Add an explanatory comment on why indio_dev->name = dev_name(dev) is
wrong, and that we can't fix it without breaking userspace.

The idea is to prevent future drivers from making the same mistake by
copying this code. And if this driver is ever modified again, we can
at least make sure any new compatible IDs use the correct name.

Signed-off-by: David Lechner <dlechner@baylibre.com>
---
It came up in a recent review that there are some (mostly older) IIO
drivers that are incorrectly setting indio_dev->name = dev_name()
instead of the "part number" of the device and that we can't fix these
without breaking userspace.

There are actually about 40 instances of this that I found, so it is
likely that these will be copied to new drivers and we don't catch it
like happened somewhat recently with magnetometer/si7210.

I'm just submitting a single patch for now to see if this is looks like
the right approach. After we refine it, then I can make a series that
fixes it everywhere. I assume we would want one patch per file for this?
---
 drivers/iio/adc/at91-sama5d2_adc.c | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/drivers/iio/adc/at91-sama5d2_adc.c b/drivers/iio/adc/at91-sama5d2_adc.c
index b4c36e6a7490aa9002a702e70a8b37ee3eae6324..cac408fda8eb6f45ab79531a71d5ad868115d735 100644
--- a/drivers/iio/adc/at91-sama5d2_adc.c
+++ b/drivers/iio/adc/at91-sama5d2_adc.c
@@ -2318,6 +2318,13 @@ static int at91_adc_probe(struct platform_device *pdev)
 	else
 		num_channels = st->soc_info.platform->max_channels;
 
+	/*
+	 * The device name is supposed to be the "part number", not the kobject
+	 * name. Do not copy this code for new drivers. We can't "fix" this
+	 * without breaking userspace, so we have to live with it. However, if
+	 * any new compatible IDs are added, please do something similar to
+	 * adc/ltc2497-core.c so that at least the new part numbers are correct.
+	 */
 	indio_dev->name = dev_name(&pdev->dev);
 	indio_dev->modes = INDIO_DIRECT_MODE | INDIO_BUFFER_SOFTWARE;
 	indio_dev->info = &at91_adc_info;

---
base-commit: 411e8b72c181e4f49352c12ced0fd8426eb683aa
change-id: 20250912-iio-indio_dev-name-wrong-f5098d2447f1

Best regards,
-- 
David Lechner <dlechner@baylibre.com>

Re: [PATCH] iio: adc: at91-sama5d2_adc: explain why indio_dev->name = dev_name() is wrong

[Andy Shevchenko]

On Sat, Sep 20, 2025 at 7:44 PM David Lechner <dlechner@baylibre.com> wrote:
>
> Add an explanatory comment on why indio_dev->name = dev_name(dev) is
> wrong, and that we can't fix it without breaking userspace.
>
> The idea is to prevent future drivers from making the same mistake by
> copying this code. And if this driver is ever modified again, we can
> at least make sure any new compatible IDs use the correct name.

...

> +       /*
> +        * The device name is supposed to be the "part number", not the kobject
> +        * name. Do not copy this code for new drivers. We can't "fix" this
> +        * without breaking userspace, so we have to live with it. However, if
> +        * any new compatible IDs are added, please do something similar to
> +        * adc/ltc2497-core.c so that at least the new part numbers are correct.

Please, use the full path from the root of the source tree, i.e.
drivers/iio/adc/ltc2497-core.c. IIRC the Sphynx might even render the
links properly (if it ever goes to this deep comment, which is not
marked as kernel-doc).

> +        */
>         indio_dev->name = dev_name(&pdev->dev);

-- 
With Best Regards,
Andy Shevchenko

Re: [PATCH] iio: adc: at91-sama5d2_adc: explain why indio_dev->name = dev_name() is wrong

[Jonathan Cameron]

On Sun, 21 Sep 2025 21:33:02 +0300
Andy Shevchenko <andy.shevchenko@gmail.com> wrote:

> On Sat, Sep 20, 2025 at 7:44 PM David Lechner <dlechner@baylibre.com> wrote:
> >
> > Add an explanatory comment on why indio_dev->name = dev_name(dev) is
> > wrong, and that we can't fix it without breaking userspace.
> >
> > The idea is to prevent future drivers from making the same mistake by
> > copying this code. And if this driver is ever modified again, we can
> > at least make sure any new compatible IDs use the correct name.  
> 
> ...
> 
> > +       /*
> > +        * The device name is supposed to be the "part number", not the kobject
> > +        * name. Do not copy this code for new drivers. We can't "fix" this
> > +        * without breaking userspace, so we have to live with it. However, if
> > +        * any new compatible IDs are added, please do something similar to
> > +        * adc/ltc2497-core.c so that at least the new part numbers are correct.  
> 
> Please, use the full path from the root of the source tree, i.e.
> drivers/iio/adc/ltc2497-core.c. IIRC the Sphynx might even render the
> links properly (if it ever goes to this deep comment, which is not
> marked as kernel-doc).

Other than that this looks like a good approach to me.
I was thinking maybe a reference to central doc, but that might be a bit fragile
so I think I prefer this approach of stating it fully at each place it matters.

Thanks,

Jonathan

> 
> > +        */
> >         indio_dev->name = dev_name(&pdev->dev);  
>