kevin/linux
1
Fork 0
Code

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

Browse Source 
Class-based client auto-detection has been considered a legacy mechanism
for 10 yrs now. See commit 0c17617008 ("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>
Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
This commit is contained in:
Heiner Kallweit 2024-03-04 21:44:21 +01:00 committed by Wolfram Sang
parent f311507c53
commit 68a04aeebe
1 changed files with 4 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
Documentation/i2c/writing-clients.rst
View File

@ -48,10 +48,6 @@ driver model device node, and its I2C address.
.id_table = foo_idtable, .id_table = foo_idtable,
.probe = foo_probe, .probe = foo_probe,
.remove = foo_remove, .remove = foo_remove,
/* if device autodetection is needed: */
.class = I2C_CLASS_SOMETHING,
.detect = foo_detect,
.address_list = normal_i2c,
.shutdown = foo_shutdown, /* optional */ .shutdown = foo_shutdown, /* optional */
.command = foo_command, /* optional, deprecated */ .command = foo_command, /* optional, deprecated */
@ -203,27 +199,8 @@ reference for later use.
Device Detection Device Detection
---------------- ----------------
Sometimes you do not know in advance which I2C devices are connected to The device detection mechanism comes with a number of disadvantages.
a given I2C bus. This is for example the case of hardware monitoring You need some reliable way to identify the supported devices
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
(typically using device-specific, dedicated identification registers), (typically using device-specific, dedicated identification registers),
otherwise misdetections are likely to occur and things can get wrong otherwise misdetections are likely to occur and things can get wrong
quickly. Keep in mind that the I2C protocol doesn't include any 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 alone a standard way to identify devices. Even worse is the lack of
semantics associated to bus transfers, which means that the same 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 transfer can be seen as a read operation by a chip and as a write
operation by another chip. For these reasons, explicit device operation by another chip. For these reasons, device detection is
instantiation should always be preferred to auto-detection where considered a legacy mechanism and shouldn't be used in new code.
possible.
Device Deletion Device Deletion