[PATCH RESEND] drm/bridge: drm_bridge_get/put(): document NULL pointer behaviour

[PATCH RESEND] drm/bridge: drm_bridge_get/put(): document NULL pointer behaviour

[Luca Ceresoli]

drm_bridge_get and drm_bridge_put() do nothing when they are passed a NULL
pointer, and they do so since their initial addition in commit 30d1b37d4c02
("drm/bridge: add support for refcounting").

This allows simpler code in various places when using these
functions. However it's not documented, so it's not clear whether it is
part of the API "contract" or just a current implementation detail that
might change in the future.

There is no visible reason to remove this NULL check, so document it,
making it part of the contract, letting users count on it.

Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
---
Historical note: I thought this was documented from the beginning and
realized it's not the case when someone proposed adding a 'if (bridge)
drm_bridge_put(bridge)' to a driver [0]. Let's fix it now.

[0] https://lore.kernel.org/lkml/DG0CHD0TAH9A.27UW4KKY2O9V7@bootlin.com/
---
 drivers/gpu/drm/drm_bridge.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
index 3b165a0d1e77..3108249a63cd 100644
--- a/drivers/gpu/drm/drm_bridge.c
+++ b/drivers/gpu/drm/drm_bridge.c
@@ -282,7 +282,7 @@ static void __drm_bridge_free(struct kref *kref)
 
 /**
  * drm_bridge_get - Acquire a bridge reference
- * @bridge: DRM bridge
+ * @bridge: DRM bridge; if NULL this function does nothing
  *
  * This function increments the bridge's refcount.
  *
@@ -300,7 +300,7 @@ EXPORT_SYMBOL(drm_bridge_get);
 
 /**
  * drm_bridge_put - Release a bridge reference
- * @bridge: DRM bridge
+ * @bridge: DRM bridge; if NULL this function does nothing
  *
  * This function decrements the bridge's reference count and frees the
  * object if the reference count drops to zero.

---
base-commit: a50007089e078a1b7a826559a02277b1601ee189
change-id: 20260129-drm-bridge-alloc-getput-document-null-check-a551e64b8fc1

Best regards,
-- 
Luca Ceresoli <luca.ceresoli@bootlin.com>

Re: [PATCH RESEND] drm/bridge: drm_bridge_get/put(): document NULL pointer behaviour

[Liu Ying]

Hi Luca,

On Tue, Mar 24, 2026 at 10:08:49AM +0100, Luca Ceresoli wrote:
> drm_bridge_get and drm_bridge_put() do nothing when they are passed a NULL
> pointer, and they do so since their initial addition in commit 30d1b37d4c02
> ("drm/bridge: add support for refcounting").
> 
> This allows simpler code in various places when using these
> functions. However it's not documented, so it's not clear whether it is
> part of the API "contract" or just a current implementation detail that
> might change in the future.
> 
> There is no visible reason to remove this NULL check, so document it,
> making it part of the contract, letting users count on it.
> 
> Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>
> ---
> Historical note: I thought this was documented from the beginning and
> realized it's not the case when someone proposed adding a 'if (bridge)
> drm_bridge_put(bridge)' to a driver [0]. Let's fix it now.
> 
> [0] https://lore.kernel.org/lkml/DG0CHD0TAH9A.27UW4KKY2O9V7@bootlin.com/
> ---
>  drivers/gpu/drm/drm_bridge.c | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> index 3b165a0d1e77..3108249a63cd 100644
> --- a/drivers/gpu/drm/drm_bridge.c
> +++ b/drivers/gpu/drm/drm_bridge.c
> @@ -282,7 +282,7 @@ static void __drm_bridge_free(struct kref *kref)
>  
>  /**
>   * drm_bridge_get - Acquire a bridge reference
> - * @bridge: DRM bridge
> + * @bridge: DRM bridge; if NULL this function does nothing
>   *
>   * This function increments the bridge's refcount.
>   *
> @@ -300,7 +300,7 @@ EXPORT_SYMBOL(drm_bridge_get);
>  
>  /**
>   * drm_bridge_put - Release a bridge reference
> - * @bridge: DRM bridge
> + * @bridge: DRM bridge; if NULL this function does nothing

So, we can drop the if(_T) check for cleanup action, right?

DEFINE_FREE(drm_bridge_put, struct drm_bridge *, if (_T) drm_bridge_put(_T))

Reviewed-by: Liu Ying <victor.liu@nxp.com>

>   *
>   * This function decrements the bridge's reference count and frees the
>   * object if the reference count drops to zero.
> 
> ---
> base-commit: a50007089e078a1b7a826559a02277b1601ee189
> change-id: 20260129-drm-bridge-alloc-getput-document-null-check-a551e64b8fc1
> 
> Best regards,

-- 
Regards,
Liu Ying

Re: [PATCH RESEND] drm/bridge: drm_bridge_get/put(): document NULL pointer behaviour

[Luca Ceresoli]

Hello Liu,

On Thu Mar 26, 2026 at 10:36 AM CET, Liu Ying wrote:

>> --- a/drivers/gpu/drm/drm_bridge.c
>> +++ b/drivers/gpu/drm/drm_bridge.c
>> @@ -282,7 +282,7 @@ static void __drm_bridge_free(struct kref *kref)
>>
>>  /**
>>   * drm_bridge_get - Acquire a bridge reference
>> - * @bridge: DRM bridge
>> + * @bridge: DRM bridge; if NULL this function does nothing
>>   *
>>   * This function increments the bridge's refcount.
>>   *
>> @@ -300,7 +300,7 @@ EXPORT_SYMBOL(drm_bridge_get);
>>
>>  /**
>>   * drm_bridge_put - Release a bridge reference
>> - * @bridge: DRM bridge
>> + * @bridge: DRM bridge; if NULL this function does nothing
>
> So, we can drop the if(_T) check for cleanup action, right?

We could, but it's supposed to be there to help compiler optimizations:
https://elixir.bootlin.com/linux/v7.0-rc5/source/include/linux/cleanup.h#L192-L207

> DEFINE_FREE(drm_bridge_put, struct drm_bridge *, if (_T) drm_bridge_put(_T))
>
> Reviewed-by: Liu Ying <victor.liu@nxp.com>

Thanks!

Luca

--
Luca Ceresoli, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [PATCH RESEND] drm/bridge: drm_bridge_get/put(): document NULL pointer behaviour

[Louis Chauvet]

On 3/24/26 10:08, Luca Ceresoli wrote:
> drm_bridge_get and drm_bridge_put() do nothing when they are passed a NULL
> pointer, and they do so since their initial addition in commit 30d1b37d4c02
> ("drm/bridge: add support for refcounting").
> 
> This allows simpler code in various places when using these
> functions. However it's not documented, so it's not clear whether it is
> part of the API "contract" or just a current implementation detail that
> might change in the future.
> 
> There is no visible reason to remove this NULL check, so document it,
> making it part of the contract, letting users count on it.
> 
> Signed-off-by: Luca Ceresoli <luca.ceresoli@bootlin.com>

Reviewed-by: Louis Chauvet <louis.chauvet@bootlin.com>

> ---
> Historical note: I thought this was documented from the beginning and
> realized it's not the case when someone proposed adding a 'if (bridge)
> drm_bridge_put(bridge)' to a driver [0]. Let's fix it now.
> 
> [0] https://lore.kernel.org/lkml/DG0CHD0TAH9A.27UW4KKY2O9V7@bootlin.com/
> ---
>   drivers/gpu/drm/drm_bridge.c | 4 ++--
>   1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/drivers/gpu/drm/drm_bridge.c b/drivers/gpu/drm/drm_bridge.c
> index 3b165a0d1e77..3108249a63cd 100644
> --- a/drivers/gpu/drm/drm_bridge.c
> +++ b/drivers/gpu/drm/drm_bridge.c
> @@ -282,7 +282,7 @@ static void __drm_bridge_free(struct kref *kref)
>   
>   /**
>    * drm_bridge_get - Acquire a bridge reference
> - * @bridge: DRM bridge
> + * @bridge: DRM bridge; if NULL this function does nothing
>    *
>    * This function increments the bridge's refcount.
>    *
> @@ -300,7 +300,7 @@ EXPORT_SYMBOL(drm_bridge_get);
>   
>   /**
>    * drm_bridge_put - Release a bridge reference
> - * @bridge: DRM bridge
> + * @bridge: DRM bridge; if NULL this function does nothing
>    *
>    * This function decrements the bridge's reference count and frees the
>    * object if the reference count drops to zero.
> 
> ---
> base-commit: a50007089e078a1b7a826559a02277b1601ee189
> change-id: 20260129-drm-bridge-alloc-getput-document-null-check-a551e64b8fc1
> 
> Best regards,

Re: [PATCH RESEND] drm/bridge: drm_bridge_get/put(): document NULL pointer behaviour

[Luca Ceresoli]

On Tue, 24 Mar 2026 10:08:49 +0100, Luca Ceresoli wrote:
> drm_bridge_get and drm_bridge_put() do nothing when they are passed a NULL
> pointer, and they do so since their initial addition in commit 30d1b37d4c02
> ("drm/bridge: add support for refcounting").
> 
> This allows simpler code in various places when using these
> functions. However it's not documented, so it's not clear whether it is
> part of the API "contract" or just a current implementation detail that
> might change in the future.
> 
> [...]

Applied, thanks!

[1/1] drm/bridge: drm_bridge_get/put(): document NULL pointer behaviour
      commit: af29fcbe806ecd10078c406470fecb902b3c0e55

Best regards,
-- 
Luca Ceresoli <luca.ceresoli@bootlin.com>