software_node: Add kernel-doc comments to exported symbols
Subsystems (2)
Daniel Scally
reviewerPATCH 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
@@ -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
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
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.
Quoted 8 lines
drivers/base/swnode.c | 52 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+)drivers/base/swnode.c +0
-0
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
-0EXPORT_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
Daniel Scally
reviewerHi 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!
Reviewed-by Andy Shevchenko <[email protected]>after addressing few nitpicks
Thanks for reviewing
Quoted 6 lines
Quoted 4 lines
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.
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 thefwnode_handleis no longer needed is
+ * handled viasoftware_node_release()and does not need to be done separately.
+ *
+ * Returns:
+ * *fwnode_handle* - On success
+ * *-EINVAL- When @parent is not associated with asoftware_node
+ * *-ENOMEM- When memory allocation fails
+ * * -Other - Propagated errors from sub-functions
+ */
structfwnode_handle*
fwnode_create_software_node(const structproperty_entry*properties,drivers/base/swnode.c +0
-0const 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
-0EXPORT_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_handlein the comments, can you replace them with better approach depending on the case:
- &structfwnode_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)
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!
Reviewed-by Andy Shevchenko <[email protected]>after addressing few nitpicks
Quoted 8 lines
Thanks for reviewing
Quoted 6 lines
Quoted 4 lines
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:
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 thefwnode_handleis no longer needed is
+ * handled viasoftware_node_release()and does not need to be done separately.
+ *
+ * Returns:
+ * *fwnode_handle* - On success
+ * *-EINVAL- When @parent is not associated with asoftware_node
+ * *-ENOMEM- When memory allocation fails
+ * * -Other - Propagated errors from sub-functions
+ */
structfwnode_handle*
fwnode_create_software_node(const structproperty_entry*properties,drivers/base/swnode.c +0
-0const 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
-0EXPORT_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_handlein the comments, can you replace them with better approach depending on the case:
- &structfwnode_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_handleon the first reference (or at least earliest that it would fit) and thenfwnode_handlethereafter, but I think I like the suggestion to drop to plain English at that point instead, so I'll do that (and ditto forsoftware_node/ software node)
Signature · 1 line
heikki
Daniel Scally
reviewerHi 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!
Reviewed-by Andy Shevchenko <[email protected]>after addressing few nitpicks
Thanks for reviewing
Quoted 4 lines
Quoted 4 lines
Signed-off-by Daniel Scally <[email protected]>---
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:
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)