A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
kernel-doc comments; add those in so all exported symbols are documented.
Signed-off-by: Daniel Scally <[email protected]>
---
With a view to maybe writing some documentation once the fwnode_graph_*()
functions are also added.
drivers/base/swnode.c | 52 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 52 insertions(+)
diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
index 4a4b2008fbc2..ea52e5e9af92 100644
--- a/drivers/base/swnode.c
+++ b/drivers/base/swnode.c
@@ -33,6 +33,13 @@ static struct kset *swnode_kset;
static const struct fwnode_operations software_node_ops;
+/**
+ * is_software_node() - check if given fwnode was created from a software_node
+ * @fwnode: The &struct fwnode_handle to check
+ *
+ * This function is used to check whether a given fwnode_handle was created by
+ * registering a &struct software_node or not.
+ */
bool is_software_node(const struct fwnode_handle *fwnode)
{
return !IS_ERR_OR_NULL(fwnode) && fwnode->ops == &software_node_ops;
@@ -71,6 +78,14 @@ software_node_to_swnode(const struct software_node *node)
return swnode;
}
+/**
+ * to_software_node() - Fetch software_node associated with a given fwnode_handle
+ * @fwnode: The pointer to a &struct fwnode_handle to parse
+ *
+ * This function attempts to fetch a pointer to the &struct software_node which
+ * was used to create a given fwnode_handle. Note that this will only work if
+ * the software_node has **not** been released.
+ */
const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
{
const struct swnode *swnode = to_swnode(fwnode);
@@ -79,6 +94,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
}
EXPORT_SYMBOL_GPL(to_software_node);
+/**
+ * software_node_fwnode() - Fetch fwnode_handle associated with a given software_node
+ * @node: The pointer to a &struct software_node to parse
+ *
+ * This function attempts to fetch a pointer to the &struct fwnode_handle which
+ * was created from a given software_node. Note that this will only work after
+ * the software_node has been registered.
+ */
struct fwnode_handle *software_node_fwnode(const struct software_node *node)
{
struct swnode *swnode = software_node_to_swnode(node);
@@ -800,6 +823,26 @@ void software_node_unregister(const struct software_node *node)
}
EXPORT_SYMBOL_GPL(software_node_unregister);
+/**
+ * fwnode_create_software_node() - Create and register a new software_node
+ * @properties: NULL terminated array of properties to assign to the new node
+ * @parent: Pointer to a fwnode_handle to assign as parent to the new node
+ *
+ * NOTE: The pointer passed to @parent **must** be to a fwnode_handle that was
+ * created by registering a &struct software_node, meaning is_software_node()
+ * must return true when passed that pointer.
+ *
+ * This function creates a new instance of struct software_node, assigns it a
+ * copy of the given array of properties and registers it as a new fwnode_handle.
+ * Freeing of the allocated memory when the fwnode_handle is no longer needed is
+ * handled via software_node_release() and does not need to be done separately.
+ *
+ * Returns:
+ * * fwnode_handle * - On success
+ * * -EINVAL - When @parent is not associated with a software_node
+ * * -ENOMEM - When memory allocation fails
+ * * -Other - Propagated errors from sub-functions
+ */
struct fwnode_handle *
fwnode_create_software_node(const struct property_entry *properties,
const struct fwnode_handle *parent)
@@ -832,6 +875,15 @@ fwnode_create_software_node(const struct property_entry *properties,
}
EXPORT_SYMBOL_GPL(fwnode_create_software_node);
+/**
+ * fwnode_remove_software_node() - Put a reference to a registered software_node
+ * @fwnode: The pointer to the &struct fwnode_handle you want to release
+ *
+ * Release a reference to a registered &struct software_node. This function
+ * differs from software_node_put() in that it takes no action if the
+ * fwnode_handle passed to @fwnode turns out not to have been created by
+ * registering a software_node
+ */
void fwnode_remove_software_node(struct fwnode_handle *fwnode)
{
struct swnode *swnode = to_swnode(fwnode);
--
2.25.1
On Mon, Jan 04, 2021 at 11:47:36PM +0000, Daniel Scally wrote:
> A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
> kernel-doc comments; add those in so all exported symbols are documented.
Thanks, it's helpful!
Reviewed-by: Andy Shevchenko <[email protected]>
after addressing few nitpicks
> Signed-off-by: Daniel Scally <[email protected]>
> ---
> With a view to maybe writing some documentation once the fwnode_graph_*()
> functions are also added.
FWIW, Heikki used to have a draft patch of swnode documentation, not sure
what's the current status of it.
> drivers/base/swnode.c | 52 +++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 52 insertions(+)
>
> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
> index 4a4b2008fbc2..ea52e5e9af92 100644
> --- a/drivers/base/swnode.c
> +++ b/drivers/base/swnode.c
> @@ -33,6 +33,13 @@ static struct kset *swnode_kset;
>
> static const struct fwnode_operations software_node_ops;
>
> +/**
> + * is_software_node() - check if given fwnode was created from a software_node
> + * @fwnode: The &struct fwnode_handle to check
> + *
> + * This function is used to check whether a given fwnode_handle was created by
fwnode_handle -> @fwnode
> + * registering a &struct software_node or not.
> + */
> bool is_software_node(const struct fwnode_handle *fwnode)
> {
> return !IS_ERR_OR_NULL(fwnode) && fwnode->ops == &software_node_ops;
> @@ -71,6 +78,14 @@ software_node_to_swnode(const struct software_node *node)
> return swnode;
> }
>
> +/**
> + * to_software_node() - Fetch software_node associated with a given fwnode_handle
> + * @fwnode: The pointer to a &struct fwnode_handle to parse
> + *
> + * This function attempts to fetch a pointer to the &struct software_node which
> + * was used to create a given fwnode_handle. Note that this will only work if
Ditto.
> + * the software_node has **not** been released.
> + */
> const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
> {
> const struct swnode *swnode = to_swnode(fwnode);
> @@ -79,6 +94,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode)
> }
> EXPORT_SYMBOL_GPL(to_software_node);
>
> +/**
> + * software_node_fwnode() - Fetch fwnode_handle associated with a given software_node
> + * @node: The pointer to a &struct software_node to parse
> + *
> + * This function attempts to fetch a pointer to the &struct fwnode_handle which
> + * was created from a given software_node. Note that this will only work after
software_node -> @node
> + * the software_node has been registered.
> + */
> struct fwnode_handle *software_node_fwnode(const struct software_node *node)
> {
> struct swnode *swnode = software_node_to_swnode(node);
> @@ -800,6 +823,26 @@ void software_node_unregister(const struct software_node *node)
> }
> EXPORT_SYMBOL_GPL(software_node_unregister);
>
> +/**
> + * fwnode_create_software_node() - Create and register a new software_node
> + * @properties: NULL terminated array of properties to assign to the new node
> + * @parent: Pointer to a fwnode_handle to assign as parent to the new node
fwnode_handle -> &struct fwnode_handle ?
> + * NOTE: The pointer passed to @parent **must** be to a fwnode_handle that was
Ditto ?
> + * created by registering a &struct software_node, meaning is_software_node()
> + * must return true when passed that pointer.
> + *
> + * This function creates a new instance of struct software_node, assigns it a
struct -> &struct
> + * copy of the given array of properties and registers it as a new fwnode_handle.
> + * Freeing of the allocated memory when the fwnode_handle is no longer needed is
> + * handled via software_node_release() and does not need to be done separately.
> + *
> + * Returns:
> + * * fwnode_handle * - On success
> + * * -EINVAL - When @parent is not associated with a software_node
> + * * -ENOMEM - When memory allocation fails
> + * * -Other - Propagated errors from sub-functions
> + */
> struct fwnode_handle *
> fwnode_create_software_node(const struct property_entry *properties,
> const struct fwnode_handle *parent)
> @@ -832,6 +875,15 @@ fwnode_create_software_node(const struct property_entry *properties,
> }
> EXPORT_SYMBOL_GPL(fwnode_create_software_node);
>
> +/**
> + * fwnode_remove_software_node() - Put a reference to a registered software_node
> + * @fwnode: The pointer to the &struct fwnode_handle you want to release
> + *
> + * Release a reference to a registered &struct software_node. This function
> + * differs from software_node_put() in that it takes no action if the
> + * fwnode_handle passed to @fwnode turns out not to have been created by
> + * registering a software_node
Period at the end.
I'm a bit confused by amount of fwnode_handle in the comments, can you replace
them with better approach depending on the case:
- &struct fwnode_handle
- a parameter as @fwnode or so
- a general mention (better to use plain English here, something like firmware
node handle or so)
> + */
> void fwnode_remove_software_node(struct fwnode_handle *fwnode)
> {
> struct swnode *swnode = to_swnode(fwnode);
> --
> 2.25.1
>
--
With Best Regards,
Andy Shevchenko
Hi Andy
On 05/01/2021 14:53, Andy Shevchenko wrote:
> On Mon, Jan 04, 2021 at 11:47:36PM +0000, Daniel Scally wrote:
>> A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
>> kernel-doc comments; add those in so all exported symbols are documented.
> Thanks, it's helpful!
> Reviewed-by: Andy Shevchenko <[email protected]>
> after addressing few nitpicks
Thanks for reviewing
>> Signed-off-by: Daniel Scally <[email protected]>
>> ---
>> With a view to maybe writing some documentation once the fwnode_graph_*()
>> functions are also added.
> FWIW, Heikki used to have a draft patch of swnode documentation, not sure
> what's the current status of it.
Oh cool ok; I'll defer to him then.
>> + * copy of the given array of properties and registers it as a new fwnode_handle.
>> + * Freeing of the allocated memory when the fwnode_handle is no longer needed is
>> + * handled via software_node_release() and does not need to be done separately.
>> + *
>> + * Returns:
>> + * * fwnode_handle * - On success
>> + * * -EINVAL - When @parent is not associated with a software_node
>> + * * -ENOMEM - When memory allocation fails
>> + * * -Other - Propagated errors from sub-functions
>> + */
>> struct fwnode_handle *
>> fwnode_create_software_node(const struct property_entry *properties,
>> const struct fwnode_handle *parent)
>> @@ -832,6 +875,15 @@ fwnode_create_software_node(const struct property_entry *properties,
>> }
>> EXPORT_SYMBOL_GPL(fwnode_create_software_node);
>>
>> +/**
>> + * fwnode_remove_software_node() - Put a reference to a registered software_node
>> + * @fwnode: The pointer to the &struct fwnode_handle you want to release
>> + *
>> + * Release a reference to a registered &struct software_node. This function
>> + * differs from software_node_put() in that it takes no action if the
>> + * fwnode_handle passed to @fwnode turns out not to have been created by
>> + * registering a software_node
> Period at the end.
>
> I'm a bit confused by amount of fwnode_handle in the comments, can you replace
> them with better approach depending on the case:
> - &struct fwnode_handle
> - a parameter as @fwnode or so
> - a general mention (better to use plain English here, something like firmware
> node handle or so)
Yeah ok, I was trying to do &struct fwnode_handle on the first reference
(or at least earliest that it would fit) and then fwnode_handle
thereafter, but I think I like the suggestion to drop to plain English
at that point instead, so I'll do that (and ditto for software_node /
software node)
On Tue, Jan 05, 2021 at 03:39:42PM +0000, Daniel Scally wrote:
> Hi Andy
>
> On 05/01/2021 14:53, Andy Shevchenko wrote:
> > On Mon, Jan 04, 2021 at 11:47:36PM +0000, Daniel Scally wrote:
> >> A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
> >> kernel-doc comments; add those in so all exported symbols are documented.
> > Thanks, it's helpful!
> > Reviewed-by: Andy Shevchenko <[email protected]>
> > after addressing few nitpicks
> Thanks for reviewing
> >> Signed-off-by: Daniel Scally <[email protected]>
> >> ---
> >> With a view to maybe writing some documentation once the fwnode_graph_*()
> >> functions are also added.
> > FWIW, Heikki used to have a draft patch of swnode documentation, not sure
> > what's the current status of it.
> Oh cool ok; I'll defer to him then.
I actually had a similar patch prepared as part of the series adding
the documentation for software nodes, but your comments are better
than mine. So, after you have addressed Andy's comments:
Reviewed-by: Heikki Krogerus <[email protected]>
> >> + * copy of the given array of properties and registers it as a new fwnode_handle.
> >> + * Freeing of the allocated memory when the fwnode_handle is no longer needed is
> >> + * handled via software_node_release() and does not need to be done separately.
> >> + *
> >> + * Returns:
> >> + * * fwnode_handle * - On success
> >> + * * -EINVAL - When @parent is not associated with a software_node
> >> + * * -ENOMEM - When memory allocation fails
> >> + * * -Other - Propagated errors from sub-functions
> >> + */
> >> struct fwnode_handle *
> >> fwnode_create_software_node(const struct property_entry *properties,
> >> const struct fwnode_handle *parent)
> >> @@ -832,6 +875,15 @@ fwnode_create_software_node(const struct property_entry *properties,
> >> }
> >> EXPORT_SYMBOL_GPL(fwnode_create_software_node);
> >>
> >> +/**
> >> + * fwnode_remove_software_node() - Put a reference to a registered software_node
> >> + * @fwnode: The pointer to the &struct fwnode_handle you want to release
> >> + *
> >> + * Release a reference to a registered &struct software_node. This function
> >> + * differs from software_node_put() in that it takes no action if the
> >> + * fwnode_handle passed to @fwnode turns out not to have been created by
> >> + * registering a software_node
> > Period at the end.
> >
> > I'm a bit confused by amount of fwnode_handle in the comments, can you replace
> > them with better approach depending on the case:
> > - &struct fwnode_handle
> > - a parameter as @fwnode or so
> > - a general mention (better to use plain English here, something like firmware
> > node handle or so)
> Yeah ok, I was trying to do &struct fwnode_handle on the first reference
> (or at least earliest that it would fit) and then fwnode_handle
> thereafter, but I think I like the suggestion to drop to plain English
> at that point instead, so I'll do that (and ditto for software_node /
> software node)
--
heikki
Hi Heikki
On 07/01/2021 14:19, Heikki Krogerus wrote:
> On Tue, Jan 05, 2021 at 03:39:42PM +0000, Daniel Scally wrote:
>> Hi Andy
>>
>> On 05/01/2021 14:53, Andy Shevchenko wrote:
>>> On Mon, Jan 04, 2021 at 11:47:36PM +0000, Daniel Scally wrote:
>>>> A number of functions which are exported via EXPORT_SYMBOL_GPL() lack any
>>>> kernel-doc comments; add those in so all exported symbols are documented.
>>> Thanks, it's helpful!
>>> Reviewed-by: Andy Shevchenko <[email protected]>
>>> after addressing few nitpicks
>> Thanks for reviewing
>>>> Signed-off-by: Daniel Scally <[email protected]>
>>>> ---
>>>> With a view to maybe writing some documentation once the fwnode_graph_*()
>>>> functions are also added.
>>> FWIW, Heikki used to have a draft patch of swnode documentation, not sure
>>> what's the current status of it.
>> Oh cool ok; I'll defer to him then.
> I actually had a similar patch prepared as part of the series adding
> the documentation for software nodes, but your comments are better
> than mine. So, after you have addressed Andy's comments:
>
> Reviewed-by: Heikki Krogerus <[email protected]>
Great, thanks - and for the other R-bs just now also. I'll send a v2 of
this one tonight/tomorrow (depends how much else I get through)