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

Heiner Kallweit
2024-03-04T20:44:20Z

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