Re: [PATCH 1/1] clk: Document of_clk_get_by_name() return values

[Jerome Brunet <jbrunet@baylibre.com>]

On mer. 16 sept. 2026 at 10:49, Dan Carpenter <error27@gmail.com> wrote:

> On Wed, Sep 16, 2026 at 09:28:56AM +0200, Jerome Brunet wrote:
>> On mar. 15 sept. 2026 at 19:38, Dan Carpenter <error27@gmail.com> wrote:
>> 
>> > Callers should test the return from of_clk_get_by_name() with IS_ERR().
>> > The function returns a valid clock on success and an error pointer on
>> > failure; NULL is not a valid return value.
>> >
>> > Document this explicitly to prevent callers from treating NULL as a
>> > separate failure case.
>> >
>> > Assisted-by: ChatGPT:gpt-5
>> > Signed-off-by: Dan Carpenter <error27@gmail.com>
>> > ---
>> > There are a few other functions which look like they return NULL but
>> > never actually do.  This is one which has caused some confusion in
>> > the past.
>> >
>> >  drivers/clk/clk.c | 3 +++
>> >  1 file changed, 3 insertions(+)
>> >
>> > diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
>> > index f1756fe59372..a71bcf780de4 100644
>> > --- a/drivers/clk/clk.c
>> > +++ b/drivers/clk/clk.c
>> > @@ -5430,6 +5430,9 @@ EXPORT_SYMBOL(of_clk_get);
>> >   * This function parses the clocks and clock-names properties,
>> >   * and uses them to look up the struct clk from the registered list of clock
>> >   * providers.
>> > + *
>> > + * Returns: A clock pointer on success or an error pointer on failure.  This
>> > + * function never returns NULL.
>> 
>> Thanks Dan. I was about to apply the change but it feels a bit strange
>> to document what a function never does.
>> 
>> Is this a documentation that should be added everywhere the return value
>> is to be tested with IS_ERR() ?
>> 
>> What about being more direct then:
>> 
>> "Returns: A clock pointer on success or an error pointer on failure.
>>  Caller should test the return value with IS_ERR()"
>
> First of all, I just want to confirm that actually it's true, right?
> I've read the code but this isn't my background so I might have been
> confused.

I think you got it right. Instead of NULL, it should return
ERR_PTR(-ENOENT).

Looking more closely, It is not entirely impossible to get NULL. If a
provider returns NULL instead of ERR_PTR(-ENOENT), we will just pass it
back.

clk_hw_create_clk() has this

	if (IS_ERR_OR_NULL(hw))
		return ERR_CAST(hw);

I could turn it into

	if (!hw)
		return ERR_PTR(-ENOENT);
        else if (IS_ERR(hw))
		return ERR_CAST(hw);

>
> If it only returns an error pointer then, it's obvious that it should
> only be tested with IS_ERR().  I would be fine with just saying the
> first part:
>
> Returns: A clock pointer on success or an error pointer on failure

Even better. 

>
> regards,
> dan carpenter
>

-- 
Jerome