[PATCH] i2c: core: document preference for i2c_get_adapter_by_fwnode()

[PATCH] i2c: core: document preference for i2c_get_adapter_by_fwnode()

[Johan Hovold]

The i2c subsystem currently blocks during adapter deregistration
whenever there are consumers holding a reference.

Document that i2c_get_adapter_by_fwnode(), which also takes a module
reference, should almost always be preferred over
i2c_find_adapter_by_fwnode() so that an attempt to unload the adapter
module while in use fails gracefully instead of blocking
uninterruptibly.

Note that by implication of_get_i2c_adapter_by_node() is also generally
preferred over of_find_i2c_adapter_by_node().

Signed-off-by: Johan Hovold <johan@kernel.org>
---
 drivers/i2c/i2c-core-base.c | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/drivers/i2c/i2c-core-base.c b/drivers/i2c/i2c-core-base.c
index 3ec04787a737..dd4a813d4360 100644
--- a/drivers/i2c/i2c-core-base.c
+++ b/drivers/i2c/i2c-core-base.c
@@ -1895,6 +1895,9 @@ static int i2c_dev_or_parent_fwnode_match(struct device *dev, const void *data)
  * If no adapter can be found, or @fwnode is NULL, this returns NULL.
  *
  * The user must call put_device(&adapter->dev) once done with the i2c adapter.
+ *
+ * Note that i2c_get_adapter_by_fwnode(), which also takes a module reference,
+ * should almost always be used instead of this one.
  */
 struct i2c_adapter *i2c_find_adapter_by_fwnode(struct fwnode_handle *fwnode)
 {
-- 
2.54.0