linux-kernel - Re: [PATCH v1 2/3] device property: Add fwnode_graph_get_port

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Date:   Mon, 22 May 2017 09:18:18 +0300
From:   Sakari Ailus <sakari.ailus@....fi>
To:     Laurent Pinchart <laurent.pinchart@...asonboard.com>
Cc:     kieran.bingham@...asonboard.com,
        Kieran Bingham <kbingham@...nel.org>,
        linux-renesas-soc@...r.kernel.org, linux-media@...r.kernel.org,
        niklas.soderlund@...natech.se,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Mika Westerberg <mika.westerberg@...ux.intel.com>,
        Sakari Ailus <sakari.ailus@...ux.intel.com>,
        "Rafael J. Wysocki" <rafael.j.wysocki@...el.com>,
        Dmitry Torokhov <dmitry.torokhov@...il.com>,
        Adam Thomson <Adam.Thomson.Opensource@...semi.com>,
        John Youn <johnyoun@...opsys.com>,
        open list <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH v1 2/3] device property: Add fwnode_graph_get_port_parent

Hi Laurent and Kieran,

On Fri, May 19, 2017 at 05:42:07PM +0300, Laurent Pinchart wrote:
> Hi Kieran,
> 
> On Friday 19 May 2017 14:34:33 Kieran Bingham wrote:
> > On 18/05/17 14:36, Laurent Pinchart wrote:
> > > On Wednesday 17 May 2017 16:03:38 Kieran Bingham wrote:
> > >> From: Kieran Bingham <kieran.bingham+renesas@...asonboard.com>
> > >> 
> > >> V4L2 async notifiers can pass the endpoint fwnode rather than the device
> > >> fwnode.
> > > 
> > > I'm not sure I would mention V4L2 in the commit message, as this is
> > > generic.
> >
> > Good point
> > 
> > >> Provide a helper to obtain the parent device fwnode without first
> > >> parsing the remote-endpoint as per fwnode_graph_get_remote_port_parent.
> > >> 
> > >> Signed-off-by: Kieran Bingham <kieran.bingham+renesas@...asonboard.com>
> > >> ---
> > >> 
> > >>  drivers/base/property.c  | 25 +++++++++++++++++++++++++
> > >>  include/linux/property.h |  2 ++
> > >>  2 files changed, 27 insertions(+)
> > >> 
> > >> diff --git a/drivers/base/property.c b/drivers/base/property.c
> > >> index 627ebc9b570d..caf4316fe565 100644
> > >> --- a/drivers/base/property.c
> > >> +++ b/drivers/base/property.c
> > >> @@ -1245,6 +1245,31 @@ fwnode_graph_get_next_endpoint(struct
> > >> fwnode_handle
> > >> *fwnode, EXPORT_SYMBOL_GPL(fwnode_graph_get_next_endpoint);
> > >> 
> > >>  /**
> > >> 
> > >> + * fwnode_graph_get_port_parent - Return device node of a port endpoint
> > >> + * @fwnode: Endpoint firmware node pointing of the port
> > >> + *
> > >> + * Extracts firmware node of the device the @fwnode belongs to.
> > > 
> > > I'm not too familiar with the fwnode API, but I know it's written in C,
> > > where functions don't extract something but return a value :-) How about
> > > 
> > > Return: the firmware node of the device the @endpoint belongs to.
> > 
> > I'm not averse to the reword - but it is different to the other functions in
> > the same context:
> > 
> > fwnode_graph_get_remote_endpoint(struct fwnode_handle *fwnode)
> >  * Extracts firmware node of a remote endpoint the @fwnode points to.
> > 
> > struct fwnode_handle *fwnode_graph_get_remote_port(struct fwnode_handle
> > *fwnode)
> >  * Extracts firmware node of a remote port the @fwnode points to.
> > 
> > fwnode_graph_get_remote_port_parent(struct fwnode_handle *fwnode)
> >  * Extracts firmware node of a remote device the @fwnode points to.
> > 
> > Then with this function becoming:
> > 
> > fwnode_graph_get_port_parent(struct fwnode_handle *endpoint)
> >  * Returns firmware node of the device the @endpoint belongs to.
> > 
> > 
> > I guess those could be changed too ...
> 
> My point is that the kerneldoc format documents return values with a "Return:" 
> tag. The documentation for the function can still provide extra information.

Yeah, let's do this right and then fix the rest. I've already submitted the
pull request on this one --- the origin of that text is actually the V4L2 OF
framework. Feel free to submit a patch that fixes it, I can do it as well.

-- 
Regards,

Sakari Ailus
e-mail: sakari.ailus@....fi	XMPP: sailus@...iisi.org.uk