Skip to contentSkip to conversation

software_node: Add kernel-doc comments to exported symbols

PATCH Superseded Daniel Scally 3 participants 5 messages Jan 4, 2021 – Jan 7, 2021

Subsystems (2)

v1 of 3 Superseded Latest is v3 →

lore
Share & tools
lore

Daniel Scally

author reviewer
#0 lore raw

PATCH 1/1 software_node: Add kernel-doc comments to exported symbols

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.

---
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(+)
drivers/base/swnode.c +52 -0
index 4a4b2008fbc2..ea52e5e9af92 100644
@@ -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);
Signature · 1 line
2.25.1
reviewer Reviewed-by on v1 1/1
#1 lore raw
Quoted 2 lines · Daniel Scally

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!

after addressing few nitpicks

Quoted 4 lines

---
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.

Quoted 8 lines
 drivers/base/swnode.c | 52 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)
drivers/base/swnode.c +0 -0
index 4a4b2008fbc2..ea52e5e9af92 100644

drivers/base/swnode.c static struct kset *swnode_kset; · line 40

Quoted 8 lines
drivers/base/swnode.c +5 -0
@@ -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

Quoted 6 lines
drivers/base/swnode.c +2 -0
+ * 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;

drivers/base/swnode.c software_node_to_swnode(const struct software_node *node) · line 86

Quoted 9 lines
drivers/base/swnode.c +6 -0
@@ -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.

Quoted 6 lines
drivers/base/swnode.c +2 -0
+ * 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);

drivers/base/swnode.c const struct software_node *to_software_node(const struct fwnode_handle *fwnode) · line 102

Quoted 9 lines
drivers/base/swnode.c +6 -0
@@ -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

drivers/base/swnode.c void software_node_unregister(const struct software_node *node) · line 829

Quoted 13 lines
drivers/base/swnode.c +6 -0
+ * 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 ?

drivers/base/swnode.c void software_node_unregister(const struct software_node *node) · line 831

Quoted 1 line
drivers/base/swnode.c +1 -0
+ * NOTE: The pointer passed to @parent **must** be to a fwnode_handle that was

Ditto ?

drivers/base/swnode.c void software_node_unregister(const struct software_node *node) · line 835

Quoted 4 lines
drivers/base/swnode.c +4 -0
+ * 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

Quoted 15 lines
drivers/base/swnode.c +10 -0
+ * 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,
 }

drivers/base/swnode.c fwnode_create_software_node(const struct property_entry *properties, · line 885

Quoted 10 lines
drivers/base/swnode.c +8 -0
 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)

Quoted 7 lines
drivers/base/swnode.c +1 -0
+ */
 void fwnode_remove_software_node(struct fwnode_handle *fwnode)
 {
 	struct swnode *swnode = to_swnode(fwnode);
Signature · 1 line
2.25.1
Signature · 2 lines
With Best Regards,
Andy Shevchenko
author reviewer
#2 lore raw

Hi Andy

Quoted 6 lines · Andy Shevchenko
Quoted 2 lines · Daniel Scally

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!

after addressing few nitpicks

Thanks for reviewing

Quoted 6 lines
Quoted 4 lines

---
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.

Quoted 27 lines
Quoted 15 lines

+ * 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,

drivers/base/swnode.c +0 -0
 			    const struct fwnode_handle *parent)
@@ -832,6 +875,15 @@ fwnode_create_software_node(const struct property_entry *properties,
 }

drivers/base/swnode.c fwnode_create_software_node(const struct property_entry *properties, · line 885

Quoted 10 lines
drivers/base/swnode.c +8 -0
 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.

Quoted 6 lines

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)

reviewer Reviewed-by
#3 lore raw
Quoted 9 lines · Daniel Scally

Hi Andy

Quoted 6 lines · Andy Shevchenko
Quoted 2 lines · Daniel Scally

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!

after addressing few nitpicks

Quoted 8 lines

Thanks for reviewing

Quoted 6 lines
Quoted 4 lines

---
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:

Quoted 38 lines
Quoted 27 lines
Quoted 15 lines

+ * 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,

drivers/base/swnode.c +0 -0
 			    const struct fwnode_handle *parent)
@@ -832,6 +875,15 @@ fwnode_create_software_node(const struct property_entry *properties,
 }

drivers/base/swnode.c fwnode_create_software_node(const struct property_entry *properties, · line 885

Quoted 10 lines
drivers/base/swnode.c +8 -0
 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.

Quoted 6 lines

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)

Signature · 1 line
heikki
author reviewer
#4 lore raw

Hi Heikki

Quoted 15 lines · Heikki Krogerus
Quoted 14 lines · Daniel Scally

Hi Andy

Quoted 6 lines · Andy Shevchenko
Quoted 2 lines · Daniel Scally

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!

after addressing few nitpicks

Thanks for reviewing

Quoted 4 lines
Quoted 4 lines

---
With a view to maybe writing some documentation once the fwnode_graph_*() functions are also added.

Quoted 8 lines
Quoted 3 lines
Quoted 2 lines

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:

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)