[1/3] i2c: convert SMBus alert setup function to return an ERRPTR
diff mbox series

Message ID 20200210172929.6001-2-wsa+renesas@sang-engineering.com
State New
Headers show
Series
  • i2c: updates to SMBus alert setup
Related show

Commit Message

Wolfram Sang Feb. 10, 2020, 5:29 p.m. UTC
Only few drivers use this call, so drivers and I2C core are converted at
once with this patch. By simply using i2c_new_client_device() instead of
i2c_new_device(), we easily can return an ERRPTR for this function as
well. To make out of tree users aware that something changed, the
function is renamed to i2c_install_smbus_alert().

Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
---
 Documentation/i2c/smbus-protocol.rst     |  2 +-
 drivers/i2c/busses/i2c-parport.c         | 11 +++++++----
 drivers/i2c/busses/i2c-thunderx-pcidrv.c | 11 ++++++++---
 drivers/i2c/busses/i2c-xlp9xx.c          | 10 +++++++---
 drivers/i2c/i2c-core-smbus.c             | 22 +++++++++++-----------
 drivers/i2c/i2c-smbus.c                  |  2 +-
 include/linux/i2c-smbus.h                |  2 +-
 7 files changed, 36 insertions(+), 24 deletions(-)

Comments

Jean Delvare Feb. 15, 2020, 6:20 a.m. UTC | #1
Hi Wolfram,

On Mon, 10 Feb 2020 18:29:25 +0100, Wolfram Sang wrote:
> Only few drivers use this call, so drivers and I2C core are converted at
> once with this patch. By simply using i2c_new_client_device() instead of
> i2c_new_device(), we easily can return an ERRPTR for this function as
> well. To make out of tree users aware that something changed, the
> function is renamed to i2c_install_smbus_alert().

I wouldn't bother renaming the function. Chances that there actually
are out-of-tree users of this function are pretty small, and if that is
the case, they can adjust their code easily in a way that is still
compatible with old kernels.
Wolfram Sang Feb. 15, 2020, 6:50 a.m. UTC | #2
On Sat, Feb 15, 2020 at 07:20:20AM +0100, Jean Delvare wrote:
> Hi Wolfram,
> 
> On Mon, 10 Feb 2020 18:29:25 +0100, Wolfram Sang wrote:
> > Only few drivers use this call, so drivers and I2C core are converted at
> > once with this patch. By simply using i2c_new_client_device() instead of
> > i2c_new_device(), we easily can return an ERRPTR for this function as
> > well. To make out of tree users aware that something changed, the
> > function is renamed to i2c_install_smbus_alert().
> 
> I wouldn't bother renaming the function. Chances that there actually
> are out-of-tree users of this function are pretty small, and if that is
> the case, they can adjust their code easily in a way that is still
> compatible with old kernels.

Agreed, it is easy. But they need to *know* that they need to adjust.
Build error makes it obvious. Otherwise, the code will compile and
silently not work anymore, I am afraid.
Jean Delvare Feb. 15, 2020, 8:11 a.m. UTC | #3
On Sat, 15 Feb 2020 07:50:18 +0100, Wolfram Sang wrote:
> On Sat, Feb 15, 2020 at 07:20:20AM +0100, Jean Delvare wrote:
> > Hi Wolfram,
> > 
> > On Mon, 10 Feb 2020 18:29:25 +0100, Wolfram Sang wrote:  
> > > Only few drivers use this call, so drivers and I2C core are converted at
> > > once with this patch. By simply using i2c_new_client_device() instead of
> > > i2c_new_device(), we easily can return an ERRPTR for this function as
> > > well. To make out of tree users aware that something changed, the
> > > function is renamed to i2c_install_smbus_alert().  
> > 
> > I wouldn't bother renaming the function. Chances that there actually
> > are out-of-tree users of this function are pretty small, and if that is
> > the case, they can adjust their code easily in a way that is still
> > compatible with old kernels.  
> 
> Agreed, it is easy. But they need to *know* that they need to adjust.
> Build error makes it obvious. Otherwise, the code will compile and
> silently not work anymore, I am afraid.

The code will keep working as long as there is no error, which is a
rare situation. If/when it happens, they'll get a very visible error
message in their kernel log.

I understand that this makes them discover the problem later. But we
are talking about a case which most likely does not exist. On the other
hand, renaming makes compatibility harder to achieve for them in the
long term (#ifdefs needed forever), and it makes the work of the
distribution kernel maintainers harder.

I don't think we should make our lives harder to help people who keep
their kernel drivers out of tree. If they are not happy, they know what
they should do.

Just my 2 cents anyway, your call.
Robert Richter Feb. 17, 2020, 7:58 a.m. UTC | #4
On 10.02.20 18:29:25, Wolfram Sang wrote:
> Only few drivers use this call, so drivers and I2C core are converted at
> once with this patch. By simply using i2c_new_client_device() instead of
> i2c_new_device(), we easily can return an ERRPTR for this function as
> well. To make out of tree users aware that something changed, the
> function is renamed to i2c_install_smbus_alert().
> 
> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>

> -struct i2c_client *i2c_setup_smbus_alert(struct i2c_adapter *adapter,
> +struct i2c_client *i2c_install_smbus_alert(struct i2c_adapter *adapter,
>  					 struct i2c_smbus_alert_setup *setup);

This function naming is a bit odd. It creates a struct i2c_client.
Then, there is also i2c_new_client_device() and i2c_new_device(). For
i2c_new_client_device() there are no users at all outside of
i2c-core-base.c (except for Falcon NIC), it is only a wrapper.

So how about reducing the interface to those both only to:?

 i2c_new_device()
 i2c_new_device_smbus()

To avoid a namespace collision it could also get new names using
*_create_*.

Thanks,

-Robert
Wolfram Sang Feb. 17, 2020, 8:17 a.m. UTC | #5
> > Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
> 
> > -struct i2c_client *i2c_setup_smbus_alert(struct i2c_adapter *adapter,
> > +struct i2c_client *i2c_install_smbus_alert(struct i2c_adapter *adapter,
> >  					 struct i2c_smbus_alert_setup *setup);
> 
> This function naming is a bit odd. It creates a struct i2c_client.
> Then, there is also i2c_new_client_device() and i2c_new_device(). For
> i2c_new_client_device() there are no users at all outside of
> i2c-core-base.c (except for Falcon NIC), it is only a wrapper.

i2c_new_device (and friends) returned NULL on error. I am currently
converting all i2c_new_* functions to return an ERRPTR. So,
i2c_new_client_device is the new function, i2c_new_device is deprecated.
If you check v5.6-rc1, you will find many more users. Similarily,
i2c_new_dummy is deprecated (and removed already), i2c_new_dummy_device
is the new thing.

> So how about reducing the interface to those both only to:?
> 
>  i2c_new_device()
>  i2c_new_device_smbus()

Given the above, it would be:

	i2c_new_client_device()
	i2c_new_smbus_device()

Yet, I think this is too vague. Maybe

	i2c_new_smbus_alert_device()

? Note that I never used SMBus Alert, so I am happy for feedback from
people actually using it.

Thanks for the comment!
Luca Ceresoli Feb. 17, 2020, 9:14 a.m. UTC | #6
Hi,

On 17/02/20 09:17, Wolfram Sang wrote:
> 
>>> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
>>
>>> -struct i2c_client *i2c_setup_smbus_alert(struct i2c_adapter *adapter,
>>> +struct i2c_client *i2c_install_smbus_alert(struct i2c_adapter *adapter,
>>>  					 struct i2c_smbus_alert_setup *setup);
>>
>> This function naming is a bit odd. It creates a struct i2c_client.
>> Then, there is also i2c_new_client_device() and i2c_new_device(). For
>> i2c_new_client_device() there are no users at all outside of
>> i2c-core-base.c (except for Falcon NIC), it is only a wrapper.
> 
> i2c_new_device (and friends) returned NULL on error. I am currently
> converting all i2c_new_* functions to return an ERRPTR. So,
> i2c_new_client_device is the new function, i2c_new_device is deprecated.
> If you check v5.6-rc1, you will find many more users. Similarily,
> i2c_new_dummy is deprecated (and removed already), i2c_new_dummy_device
> is the new thing.
> 
>> So how about reducing the interface to those both only to:?
>>
>>  i2c_new_device()
>>  i2c_new_device_smbus()
> 
> Given the above, it would be:
> 
> 	i2c_new_client_device()
> 	i2c_new_smbus_device()
> 
> Yet, I think this is too vague. Maybe
> 
> 	i2c_new_smbus_alert_device()

I always found the function naming a bit messy in the linux i2c
implementation. Among the names proposed in this thread,
i2c_new_smbus_alert_device() is the only one that makes sense to me for
the new function: it is not vague, and it is coherent with other names
of recently introduced functions (i2c_new_*_device()). Of course the
"alert device" is not a real device, but it looks like it is as it has
its own "slave" address. So I vote for this name...

> ? Note that I never used SMBus Alert, so I am happy for feedback from
> people actually using it.

...but that said, I'm afraid I'm not using smbus alert.

My 2c,
Robert Richter Feb. 17, 2020, 10 a.m. UTC | #7
On 17.02.20 10:14:52, Luca Ceresoli wrote:
> Hi,
> 
> On 17/02/20 09:17, Wolfram Sang wrote:
> > 
> >>> Signed-off-by: Wolfram Sang <wsa+renesas@sang-engineering.com>
> >>
> >>> -struct i2c_client *i2c_setup_smbus_alert(struct i2c_adapter *adapter,
> >>> +struct i2c_client *i2c_install_smbus_alert(struct i2c_adapter *adapter,
> >>>  					 struct i2c_smbus_alert_setup *setup);
> >>
> >> This function naming is a bit odd. It creates a struct i2c_client.
> >> Then, there is also i2c_new_client_device() and i2c_new_device(). For
> >> i2c_new_client_device() there are no users at all outside of
> >> i2c-core-base.c (except for Falcon NIC), it is only a wrapper.
> > 
> > i2c_new_device (and friends) returned NULL on error. I am currently
> > converting all i2c_new_* functions to return an ERRPTR. So,
> > i2c_new_client_device is the new function, i2c_new_device is deprecated.
> > If you check v5.6-rc1, you will find many more users. Similarily,
> > i2c_new_dummy is deprecated (and removed already), i2c_new_dummy_device
> > is the new thing.
> > 
> >> So how about reducing the interface to those both only to:?
> >>
> >>  i2c_new_device()
> >>  i2c_new_device_smbus()
> > 
> > Given the above, it would be:
> > 
> > 	i2c_new_client_device()
> > 	i2c_new_smbus_device()
> > 
> > Yet, I think this is too vague. Maybe
> > 
> > 	i2c_new_smbus_alert_device()
> 
> I always found the function naming a bit messy in the linux i2c
> implementation. Among the names proposed in this thread,
> i2c_new_smbus_alert_device() is the only one that makes sense to me for
> the new function: it is not vague, and it is coherent with other names
> of recently introduced functions (i2c_new_*_device()). Of course the
> "alert device" is not a real device, but it looks like it is as it has
> its own "slave" address. So I vote for this name...

Yes, better fix the naming now that the i/f is new. As all these
function create a i2c_client struct, the whole set of functions could
be also named i2c_client_create*() with specialized functions such as
i2c_client_create_smbus() or so. It will be clear it is a subset.

Anyway, it's just a function name, but while reading the code it was
not obvious to me that i2c_install_smbus_alert() is actually a subset
of i2c_new_client_device(). That said, I like the i2c_client_create*()
variants.

-Robert
Wolfram Sang Feb. 17, 2020, 1:29 p.m. UTC | #8
> Anyway, it's just a function name, but while reading the code it was
> not obvious to me that i2c_install_smbus_alert() is actually a subset
> of i2c_new_client_device(). That said, I like the i2c_client_create*()
> variants.

I agree that i2c_client_create* is a nice naming, but it came in a bit
too late. Renaming the API is a tiresome job, and it shouldn't be done
(again) just for the sake of renaming IMO.

That all being said, I think i2c_new_smbus_alert_device is a better
naming than what is in this patchset and it is my favourite until now.

Patch
diff mbox series

diff --git a/Documentation/i2c/smbus-protocol.rst b/Documentation/i2c/smbus-protocol.rst
index c122ed239f7f..4783670a0420 100644
--- a/Documentation/i2c/smbus-protocol.rst
+++ b/Documentation/i2c/smbus-protocol.rst
@@ -274,7 +274,7 @@  to know which slave triggered the interrupt.
 This is implemented the following way in the Linux kernel:
 
 * I2C bus drivers which support SMBus alert should call
-  i2c_setup_smbus_alert() to setup SMBus alert support.
+  i2c_install_smbus_alert() to install SMBus alert support.
 * I2C drivers for devices which can trigger SMBus alerts should implement
   the optional alert() callback.
 
diff --git a/drivers/i2c/busses/i2c-parport.c b/drivers/i2c/busses/i2c-parport.c
index 81eb441b2387..1aee13e2d3da 100644
--- a/drivers/i2c/busses/i2c-parport.c
+++ b/drivers/i2c/busses/i2c-parport.c
@@ -333,13 +333,16 @@  static void i2c_parport_attach(struct parport *port)
 
 	/* Setup SMBus alert if supported */
 	if (adapter_parm[type].smbus_alert) {
-		adapter->ara = i2c_setup_smbus_alert(&adapter->adapter,
-						     &adapter->alert_data);
-		if (adapter->ara)
+		struct i2c_client *ara;
+
+		ara = i2c_install_smbus_alert(&adapter->adapter, &adapter->alert_data);
+		if (!IS_ERR(ara)) {
+			adapter->ara = ara;
 			parport_enable_irq(port);
-		else
+		} else {
 			dev_warn(&adapter->pdev->dev,
 				 "Failed to register ARA client\n");
+		}
 	}
 
 	/* Add the new adapter to the list */
diff --git a/drivers/i2c/busses/i2c-thunderx-pcidrv.c b/drivers/i2c/busses/i2c-thunderx-pcidrv.c
index 19f8eec38717..8626a97739e1 100644
--- a/drivers/i2c/busses/i2c-thunderx-pcidrv.c
+++ b/drivers/i2c/busses/i2c-thunderx-pcidrv.c
@@ -118,6 +118,8 @@  static void thunder_i2c_clock_disable(struct device *dev, struct clk *clk)
 static int thunder_i2c_smbus_setup_of(struct octeon_i2c *i2c,
 				      struct device_node *node)
 {
+	struct i2c_client *ara;
+
 	if (!node)
 		return -EINVAL;
 
@@ -125,9 +127,12 @@  static int thunder_i2c_smbus_setup_of(struct octeon_i2c *i2c,
 	if (!i2c->alert_data.irq)
 		return -EINVAL;
 
-	i2c->ara = i2c_setup_smbus_alert(&i2c->adap, &i2c->alert_data);
-	if (!i2c->ara)
-		return -ENODEV;
+	ara = i2c_install_smbus_alert(&i2c->adap, &i2c->alert_data);
+	if (IS_ERR(ara))
+		return PTR_ERR(ara);
+
+	i2c->ara = ara;
+
 	return 0;
 }
 
diff --git a/drivers/i2c/busses/i2c-xlp9xx.c b/drivers/i2c/busses/i2c-xlp9xx.c
index 8a873975cf12..3e57723e1194 100644
--- a/drivers/i2c/busses/i2c-xlp9xx.c
+++ b/drivers/i2c/busses/i2c-xlp9xx.c
@@ -491,12 +491,16 @@  static int xlp9xx_i2c_get_frequency(struct platform_device *pdev,
 static int xlp9xx_i2c_smbus_setup(struct xlp9xx_i2c_dev *priv,
 				  struct platform_device *pdev)
 {
+	struct i2c_client *ara;
+
 	if (!priv->alert_data.irq)
 		return -EINVAL;
 
-	priv->ara = i2c_setup_smbus_alert(&priv->adapter, &priv->alert_data);
-	if (!priv->ara)
-		return -ENODEV;
+	ara = i2c_install_smbus_alert(&priv->adapter, &priv->alert_data);
+	if (IS_ERR(ara))
+		return PTR_ERR(ara);
+
+	priv->ara = ara;
 
 	return 0;
 }
diff --git a/drivers/i2c/i2c-core-smbus.c b/drivers/i2c/i2c-core-smbus.c
index 3ac426a8ab5a..06f2e4d78d3c 100644
--- a/drivers/i2c/i2c-core-smbus.c
+++ b/drivers/i2c/i2c-core-smbus.c
@@ -666,12 +666,12 @@  s32 i2c_smbus_read_i2c_block_data_or_emulated(const struct i2c_client *client,
 EXPORT_SYMBOL(i2c_smbus_read_i2c_block_data_or_emulated);
 
 /**
- * i2c_setup_smbus_alert - Setup SMBus alert support
+ * i2c_install_smbus_alert - Install SMBus alert support
  * @adapter: the target adapter
  * @setup: setup data for the SMBus alert handler
  * Context: can sleep
  *
- * Setup handling of the SMBus alert protocol on a given I2C bus segment.
+ * Install handling of the SMBus alert protocol on a given I2C bus segment.
  *
  * Handling can be done either through our IRQ handler, or by the
  * adapter (from its handler, periodic polling, or whatever).
@@ -682,20 +682,20 @@  EXPORT_SYMBOL(i2c_smbus_read_i2c_block_data_or_emulated);
  * should have said it's level triggered.
  *
  * This returns the ara client, which should be saved for later use with
- * i2c_handle_smbus_alert() and ultimately i2c_unregister_device(); or NULL
- * to indicate an error.
+ * i2c_handle_smbus_alert() and ultimately i2c_unregister_device(); or an
+ * ERRPTR to indicate an error.
  */
-struct i2c_client *i2c_setup_smbus_alert(struct i2c_adapter *adapter,
-					 struct i2c_smbus_alert_setup *setup)
+struct i2c_client *i2c_install_smbus_alert(struct i2c_adapter *adapter,
+					   struct i2c_smbus_alert_setup *setup)
 {
 	struct i2c_board_info ara_board_info = {
 		I2C_BOARD_INFO("smbus_alert", 0x0c),
 		.platform_data = setup,
 	};
 
-	return i2c_new_device(adapter, &ara_board_info);
+	return i2c_new_client_device(adapter, &ara_board_info);
 }
-EXPORT_SYMBOL_GPL(i2c_setup_smbus_alert);
+EXPORT_SYMBOL_GPL(i2c_install_smbus_alert);
 
 #if IS_ENABLED(CONFIG_I2C_SMBUS) && IS_ENABLED(CONFIG_OF)
 int of_i2c_setup_smbus_alert(struct i2c_adapter *adapter)
@@ -710,9 +710,9 @@  int of_i2c_setup_smbus_alert(struct i2c_adapter *adapter)
 	else if (irq < 0)
 		return irq;
 
-	client = i2c_setup_smbus_alert(adapter, NULL);
-	if (!client)
-		return -ENODEV;
+	client = i2c_install_smbus_alert(adapter, NULL);
+	if (IS_ERR(client))
+		return PTR_ERR(client);
 
 	return 0;
 }
diff --git a/drivers/i2c/i2c-smbus.c b/drivers/i2c/i2c-smbus.c
index 7e2f5d0eacdb..174a89d3e415 100644
--- a/drivers/i2c/i2c-smbus.c
+++ b/drivers/i2c/i2c-smbus.c
@@ -184,7 +184,7 @@  static struct i2c_driver smbalert_driver = {
  * corresponding I2C device driver's alert function.
  *
  * It is assumed that ara is a valid i2c client previously returned by
- * i2c_setup_smbus_alert().
+ * i2c_install_smbus_alert().
  */
 int i2c_handle_smbus_alert(struct i2c_client *ara)
 {
diff --git a/include/linux/i2c-smbus.h b/include/linux/i2c-smbus.h
index 585ad6fc3847..409da1e478d6 100644
--- a/include/linux/i2c-smbus.h
+++ b/include/linux/i2c-smbus.h
@@ -31,7 +31,7 @@  struct i2c_smbus_alert_setup {
 	int			irq;
 };
 
-struct i2c_client *i2c_setup_smbus_alert(struct i2c_adapter *adapter,
+struct i2c_client *i2c_install_smbus_alert(struct i2c_adapter *adapter,
 					 struct i2c_smbus_alert_setup *setup);
 int i2c_handle_smbus_alert(struct i2c_client *ara);