From: Heiner Kallweit <hkallweit1@gmail.com>
To: Wolfram Sang <wsa@kernel.org>
Cc: "linux-i2c@vger.kernel.org" <linux-i2c@vger.kernel.org>
Subject: [PATCH] Documentation: i2c: Document that client auto-detection is a legacy mechanism
Date: Mon, 4 Mar 2024 21:44:21 +0100 [thread overview]
Message-ID: <d013d57f-bd75-4c79-b829-e19740fa3848@gmail.com> (raw)
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
next reply other threads:[~2024-03-04 20:44 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-04 20:44 Heiner Kallweit [this message]
2024-03-07 8:44 ` [PATCH] Documentation: i2c: Document that client auto-detection is a legacy mechanism Wolfram Sang
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=d013d57f-bd75-4c79-b829-e19740fa3848@gmail.com \
--to=hkallweit1@gmail.com \
--cc=linux-i2c@vger.kernel.org \
--cc=wsa@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).