[PATCH v2] driver core: platform: document registration-failure requirement

[PATCH v2] driver core: platform: document registration-failure requirement

[Johan Hovold]

Add an explicit comment to document that the reference initialised by
platform_device_register() needs to be released by a call to
platform_device_put() also when registration fails (cf.
device_register()).

Signed-off-by: Johan Hovold <johan@kernel.org>
---

Greg,

I took a quick look at driver code registering non-static platform
devices and only found four drivers getting this wrong.

I've fixed up two of them and of the remaining two, one media driver is
using devres (hurray!) and the other ignores registration failures
completely anyway:

	- vpif_probe()
	- sm501_register_device()

It seems to me that the right thing to do here, at least short term, is
to add a comment clarifying this behaviour and fix up the few driver
that got it wrong.

Johan


Changes in v2
 - s/platform_put_device/platform_device_put/


 drivers/base/platform.c | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/drivers/base/platform.c b/drivers/base/platform.c
index 598acf93a360..5dad6edb1d55 100644
--- a/drivers/base/platform.c
+++ b/drivers/base/platform.c
@@ -762,6 +762,10 @@ EXPORT_SYMBOL_GPL(platform_device_del);
 /**
  * platform_device_register - add a platform-level device
  * @pdev: platform device we're adding
+ *
+ * NOTE: _Never_ directly free @pdev after calling this function, even if it
+ * returned an error! Always use platform_device_put() to give up the
+ * reference initialised in this function instead.
  */
 int platform_device_register(struct platform_device *pdev)
 {
-- 
2.32.0

Re: [PATCH v2] driver core: platform: document registration-failure requirement

[Greg Kroah-Hartman]

On Wed, Dec 22, 2021 at 11:42:13AM +0100, Johan Hovold wrote:
> Add an explicit comment to document that the reference initialised by
> platform_device_register() needs to be released by a call to
> platform_device_put() also when registration fails (cf.
> device_register()).
> 
> Signed-off-by: Johan Hovold <johan@kernel.org>
> ---
> 
> Greg,
> 
> I took a quick look at driver code registering non-static platform
> devices and only found four drivers getting this wrong.
> 
> I've fixed up two of them and of the remaining two, one media driver is
> using devres (hurray!) and the other ignores registration failures
> completely anyway:
> 
> 	- vpif_probe()
> 	- sm501_register_device()
> 
> It seems to me that the right thing to do here, at least short term, is
> to add a comment clarifying this behaviour and fix up the few driver
> that got it wrong.

Looks good, thanks for this, now queued up.

greg k-h