[PATCH v2] docs: driver-api pinctrl cleanup

[PATCH v2] docs: driver-api pinctrl cleanup

[Alex Tran]

changelog:
v2
Replace FIXME comments in the pinctrl documentation example with
proper cleanup code:
- Add devm_pinctrl_put() calls in error paths 
  (pinctrl_lookup_state, pinctrl_select_state) 
  after successful devm_pinctrl_get()
- Set foo->p to NULL when devm_pinctrl_get() fails
- Add ret variable for cleaner error handling
- provides proper example of pinctrl resource management on failure

Signed-off-by: Alex Tran <alex.t.tran@gmail.com>
---
 Documentation/driver-api/pin-control.rst | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst
index 27ea12363..281533c33 100644
--- a/Documentation/driver-api/pin-control.rst
+++ b/Documentation/driver-api/pin-control.rst
@@ -1202,22 +1202,24 @@ default state like this:
 	{
 		/* Allocate a state holder named "foo" etc */
 		struct foo_state *foo = ...;
+		int ret;
 
 		foo->p = devm_pinctrl_get(&device);
 		if (IS_ERR(foo->p)) {
-			/* FIXME: clean up "foo" here */
-			return PTR_ERR(foo->p);
+			ret = PTR_ERR(foo->p);
+			foo->p = NULL;
+			return ret;
 		}
 
 		foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
 		if (IS_ERR(foo->s)) {
-			/* FIXME: clean up "foo" here */
+			devm_pinctrl_put(foo->p);
 			return PTR_ERR(foo->s);
 		}
 
 		ret = pinctrl_select_state(foo->p, foo->s);
 		if (ret < 0) {
-			/* FIXME: clean up "foo" here */
+			devm_pinctrl_put(foo->p);
 			return ret;
 		}
 	}
-- 
2.51.0

Re: [PATCH v2] docs: driver-api pinctrl cleanup

[Linus Walleij]

On Wed, Aug 27, 2025 at 9:45 AM Alex Tran <alex.t.tran@gmail.com> wrote:

> changelog:
> v2

I think Jonathan will trim these two lines when applying...

> Replace FIXME comments in the pinctrl documentation example with
> proper cleanup code:
> - Add devm_pinctrl_put() calls in error paths
>   (pinctrl_lookup_state, pinctrl_select_state)
>   after successful devm_pinctrl_get()
> - Set foo->p to NULL when devm_pinctrl_get() fails
> - Add ret variable for cleaner error handling
> - provides proper example of pinctrl resource management on failure
>
> Signed-off-by: Alex Tran <alex.t.tran@gmail.com>

... but it looks good otherwise!
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij

Re: [PATCH v2] docs: driver-api pinctrl cleanup

[Jonathan Corbet]

Alex Tran <alex.t.tran@gmail.com> writes:

> changelog:
> v2

It's best to keep this kind of stuff out of changelogs so the maintainer
doesn't have to edit it out when applying the patch.  I've taken care of
it this time.

> Replace FIXME comments in the pinctrl documentation example with
> proper cleanup code:
> - Add devm_pinctrl_put() calls in error paths 
>   (pinctrl_lookup_state, pinctrl_select_state) 
>   after successful devm_pinctrl_get()
> - Set foo->p to NULL when devm_pinctrl_get() fails
> - Add ret variable for cleaner error handling
> - provides proper example of pinctrl resource management on failure
>
> Signed-off-by: Alex Tran <alex.t.tran@gmail.com>
> ---
>  Documentation/driver-api/pin-control.rst | 10 ++++++----
>  1 file changed, 6 insertions(+), 4 deletions(-)

Applied, thanks.

jon