[PATCH] Documentation: i2c: Document that client auto-detection is a legacy mechanism

[PATCH] Documentation: i2c: Document that client auto-detection is a legacy mechanism

[Heiner Kallweit]

Class-based client auto-detection has been considered a legacy mechanism
for 10 yrs now. See following change:
0c176170089c ("i2c: add deprecation warning for class based instantiation")
Change the documentation of how to write an i2c client accordingly.

Signed-off-by: Heiner Kallweit <hkallweit1@gmail.com>
---
 Documentation/i2c/writing-clients.rst | 32 ++++-----------------------
 1 file changed, 4 insertions(+), 28 deletions(-)

diff --git a/Documentation/i2c/writing-clients.rst b/Documentation/i2c/writing-clients.rst
index 41ddc10f1..ad4247414 100644
--- a/Documentation/i2c/writing-clients.rst
+++ b/Documentation/i2c/writing-clients.rst
@@ -48,10 +48,6 @@ driver model device node, and its I2C address.
 	.id_table	= foo_idtable,
 	.probe		= foo_probe,
 	.remove		= foo_remove,
-	/* if device autodetection is needed: */
-	.class		= I2C_CLASS_SOMETHING,
-	.detect		= foo_detect,
-	.address_list	= normal_i2c,
 
 	.shutdown	= foo_shutdown,	/* optional */
 	.command	= foo_command,	/* optional, deprecated */
@@ -203,27 +199,8 @@ reference for later use.
 Device Detection
 ----------------
 
-Sometimes you do not know in advance which I2C devices are connected to
-a given I2C bus.  This is for example the case of hardware monitoring
-devices on a PC's SMBus.  In that case, you may want to let your driver
-detect supported devices automatically.  This is how the legacy model
-was working, and is now available as an extension to the standard
-driver model.
-
-You simply have to define a detect callback which will attempt to
-identify supported devices (returning 0 for supported ones and -ENODEV
-for unsupported ones), a list of addresses to probe, and a device type
-(or class) so that only I2C buses which may have that type of device
-connected (and not otherwise enumerated) will be probed.  For example,
-a driver for a hardware monitoring chip for which auto-detection is
-needed would set its class to I2C_CLASS_HWMON, and only I2C adapters
-with a class including I2C_CLASS_HWMON would be probed by this driver.
-Note that the absence of matching classes does not prevent the use of
-a device of that type on the given I2C adapter.  All it prevents is
-auto-detection; explicit instantiation of devices is still possible.
-
-Note that this mechanism is purely optional and not suitable for all
-devices.  You need some reliable way to identify the supported devices
+The device detection mechanism comes with a number of disadvantages.
+You need some reliable way to identify the supported devices
 (typically using device-specific, dedicated identification registers),
 otherwise misdetections are likely to occur and things can get wrong
 quickly.  Keep in mind that the I2C protocol doesn't include any
@@ -231,9 +208,8 @@ standard way to detect the presence of a chip at a given address, let
 alone a standard way to identify devices.  Even worse is the lack of
 semantics associated to bus transfers, which means that the same
 transfer can be seen as a read operation by a chip and as a write
-operation by another chip.  For these reasons, explicit device
-instantiation should always be preferred to auto-detection where
-possible.
+operation by another chip.  For these reasons, device detection is
+considered a legacy mechanism and shouldn't be used in new code.
 
 
 Device Deletion
-- 
2.44.0

Re: [PATCH] Documentation: i2c: Document that client auto-detection is a legacy mechanism

[Wolfram Sang]

[-- Attachment #1: Type: text/plain, Size: 745 bytes --]

On Mon, Mar 04, 2024 at 09:44:21PM +0100, Heiner Kallweit wrote:
> Class-based client auto-detection has been considered a legacy mechanism
> for 10 yrs now. See following change:
> 0c176170089c ("i2c: add deprecation warning for class based instantiation")
> Change the documentation of how to write an i2c client accordingly.
> 
> Signed-off-by: Heiner Kallweit <hkallweit1@gmail.com>

Fixed this checkpatch warning:

===
ERROR: Please use git commit description style 'commit <12+ chars of sha1> ("<title line>")' - ie: 'commit 0c176170089c ("i2c: add deprecation warning for class based instantiation")'
#3: 
0c176170089c ("i2c: add deprecation warning for class based instantiation")
==

and applied to for-next, thanks!


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]