[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <Y+9omTMIzAxWM2by@kekkonen.localdomain>
Date: Fri, 17 Feb 2023 13:44:25 +0200
From: Sakari Ailus <sakari.ailus@...ux.intel.com>
To: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Cc: linux-acpi@...r.kernel.org, linux-kernel@...r.kernel.org,
Daniel Scally <djrscally@...il.com>,
Heikki Krogerus <heikki.krogerus@...ux.intel.com>,
Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
"Rafael J. Wysocki" <rafael@...nel.org>,
Daniel Kaehn <kaehndan@...il.com>
Subject: Re: [PATCH v1 1/1] device property: Clarify description on returned
value in some functions
On Fri, Feb 17, 2023 at 01:28:55PM +0200, Andy Shevchenko wrote:
> On Fri, Feb 17, 2023 at 01:18:31PM +0200, Sakari Ailus wrote:
> > On Fri, Feb 17, 2023 at 01:01:39PM +0200, Andy Shevchenko wrote:
> > > On Fri, Feb 17, 2023 at 12:27:53PM +0200, Sakari Ailus wrote:
> > > > On Thu, Feb 16, 2023 at 10:57:08PM +0200, Andy Shevchenko wrote:
>
> ...
>
> > > > > * fwnode_get_next_child_node - Return the next child node handle for a node
> > > > > * @fwnode: Firmware node to find the next child node for.
> > > > > * @child: Handle to one of the node's child nodes or a %NULL handle.
> > > > > + *
> > > > > + * Caller is responsible to call fwnode_handle_put() on the returned fwnode
> > > > > + * pointer.
> > > >
> > > > The loop itself will also put the child node, so this is only relevant
> > > > outside the loop.
> > >
> > > Yes and this is exactly what people stumbled over. Hence this note.
> > > This call per se doesn't loop, so I didn't get how your comment can
> > > be transformed to anything here. Care to elaborate a bit more on
> > > what I have to add here or reword?
> >
> > Ah, indeed. This is achieved by putting the previous child. Generally this
> > function is used via the loop helper macro and not called directly, hence
> > the documentation there matters the most. Those functions appear to be
> > without any documentation though.
>
> So, what should I do?
Good question.
How about this text:
The caller is responsible for calling fwnode_handle_put() put on the
returned fwnode. Note that this function also puts a reference to @child
unconditionally.
This is actually done by the firmware specific implementation, namely on OF
and at least should be done on swnode.
A second patch to document the fwnode iterator macros would be nice.
--
Sakari Ailus
Powered by blists - more mailing lists