software_node: Add kernel-doc comments to exported symbols
Subsystems (2)
Daniel Scally
reviewerPATCH v3 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.
---
Changelog for v3:
- s/passed to @parent/passed as @parent
- Wrapped a long summary line - TIL that you can do that, thanks Sakari
drivers/base/swnode.c | 54 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+)
drivers/base/swnode.c +54 -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 firmware node 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,15 @@ software_node_to_swnode(const struct software_node *node)return swnode; } +/** +* to_software_node() - Fetch the software node used to create a firmware +* node 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 the given @fwnode. 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 +95,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode) }EXPORT_SYMBOL_GPL (to_software_node); +/** +* software_node_fwnode() - Fetch firmware node 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 the given @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 +824,27 @@ 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 &struct fwnode_handle to assign as parent to the new +* node +* +* NOTE: The pointer passed as @parent **must** be to a firmware node handle +* that was created by registering a 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 +877,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 +* firmware node 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
Sakari Ailus
reviewerHi Dan,
Quoted 75 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.Reviewed-by Andy Shevchenko <[email protected]>Reviewed-by Heikki Krogerus <[email protected]>Reviewed-by Randy Dunlap <[email protected]>Reviewed-by Sakari Ailus <[email protected]>Signed-off-by Daniel Scally <[email protected]>---
Changelog for v3:- s/passed to @parent/passed as @parent
- Wrapped a long summary line - TIL that you can do that, thanks Sakaridrivers/base/swnode.c | 54 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+)drivers/base/swnode.c +28
-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 firmware node 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,15 @@ software_node_to_swnode(const struct software_node *node)return swnode; } +/** +* to_software_node() - Fetch the software node used to create a firmware +* node 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 the given @fwnode. 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 +95,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode) }EXPORT_SYMBOL_GPL (to_software_node); +/** +* software_node_fwnode() - Fetch firmware node 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 the given @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 +824,27 @@ 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 &struct fwnode_handle to assign as parent to the new
drivers/base/swnode.c void software_node_unregister(const struct software_node *node) · line 840
Quoted 10 lines
drivers/base/swnode.c +10
-0+* node +* +* NOTE: The pointer passed as @parent **must** be to a firmware node handle +* that was created by registering a 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.
Please wrap all lines over 80 unless there's a reason to keep them longer.
Quoted 29 lines
drivers/base/swnode.c +16
-0+* +* 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 +877,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 +* firmware node 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
Signature · 1 line
Sakari Ailus
Daniel Scally
reviewerHi Sakari
Quoted 74 lines · Sakari Ailus
Hi Dan,
Quoted 71 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.Reviewed-by Andy Shevchenko <[email protected]>Reviewed-by Heikki Krogerus <[email protected]>Reviewed-by Randy Dunlap <[email protected]>Reviewed-by Sakari Ailus <[email protected]>Signed-off-by Daniel Scally <[email protected]>---
Changelog for v3:- s/passed to @parent/passed as @parent
- Wrapped a long summary line - TIL that you can do that, thanks Sakaridrivers/base/swnode.c | 54 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+)drivers/base/swnode.c +24
-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 firmware node 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,15 @@ software_node_to_swnode(const struct software_node *node)return swnode; } +/** +* to_software_node() - Fetch the software node used to create a firmware +* node 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 the given @fwnode. 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 +95,14 @@ const struct software_node *to_software_node(const struct fwnode_handle *fwnode) }EXPORT_SYMBOL_GPL (to_software_node); +/** +* software_node_fwnode() - Fetch firmware node 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 the given @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 +824,27 @@ void software_node_unregister(const struct software_node *node) }EXPORT_SYMBOL_GPL (software_node_unregister);
Quoted 15 lines
Quoted 4 lines
drivers/base/swnode.c +4
-0+/** +* 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 &struct fwnode_handle to assign as parent to the new drivers/base/swnode.c void software_node_unregister(const struct software_node *node) · line 840
Quoted 10 lines
drivers/base/swnode.c +10
-0+* node +* +* NOTE: The pointer passed as @parent **must** be to a firmware node handle +* that was created by registering a 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. Please wrap all lines over 80 unless there's a reason to keep them longer.
Apologies; I'll cat | awk for lines over the limit from now on rather than half-arsing it.
Quoted 30 lines
Quoted 30 lines
drivers/base/swnode.c +16
-0+* +* 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 +877,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 +* firmware node 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
Andy Shevchenko
reviewerQuoted 17 lines · Daniel Scally
Quoted 16 lines · Sakari Ailus
Quoted 14 lines · Daniel Scally
+/**
+ *fwnode_create_software_node()- Create and register a newsoftware_node
+ * @properties: NULL terminated array of properties to assign to the new node
+ * @parent: Pointer to a &structfwnode_handleto assign as parent to the new
+ * node
+ *
+ * NOTE: The pointer passed as @parent **must** be to a firmware node handle
+ * that was created by registering a software node, meaningis_software_node()
+ * must return true when passed that pointer.
+ *
+ * This function creates a new instance of &structsoftware_node, assigns it a
+ * copy of the given array of properties and registers it as a newfwnode_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.
Quoted 4 lines
Quoted 1 line
Please wrap all lines over 80 unless there's a reason to keep them longer.
Apologies; I'll cat | awk for lines over the limit from now on rather than half-arsing it.
In Vim, for example, you may set the threshold and it will wrap it for you. Also, taking into account famous *useless use of cat*, you may use fold or fmt
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
+ *
+ * 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
+ */
Signature · 2 lines
With Best Regards, Andy Shevchenko