Documentation: i2c: Document that client auto-detection is a legacy mechanism
Subsystems (2)
PATCH 1/1 Documentation: i2c: Document that client auto-detection is a legacy mechanism
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.
--- Documentation/i2c/writing-clients.rst | 32 ++++----------------------- 1 file changed, 4 insertions(+), 28 deletions(-)
Documentation/i2c/writing-clients.rst +4 -28
@@ -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
Signature · 1 line
2.44.0
Quoted 6 lines · 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 <[email protected]>
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!