Messages in this thread | | | Subject | Re: [PATCH v2] software_node: Add kernel-doc comments to exported symbols | From | Daniel Scally <> | Date | Thu, 14 Jan 2021 08:29:17 +0000 |
| |
Hi Randy
On 13/01/2021 01:01, Randy Dunlap wrote: > On 1/12/21 4:02 PM, 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. >> >> Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com> >> Reviewed-by: Heikki Krogerus <heikki.krogerus@linux.intel.com> >> Signed-off-by: Daniel Scally <djrscally@gmail.com> >> --- >> Changes in version 2: >> - Replaced "fwnode_handle" with either @fwnode or natural language >> reference to a firmware node handle as appropriate. >> >> drivers/base/swnode.c | 53 +++++++++++++++++++++++++++++++++++++++++++ >> 1 file changed, 53 insertions(+) >> >> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c >> index 4a4b2008fbc2..e98018aa8b2f 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 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,14 @@ software_node_to_swnode(const struct software_node *node) >> return swnode; >> } >> >> +/** >> + * to_software_node() - Fetch software node associated with 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 +94,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 +823,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 to @parent **must** be to a firmware node handle > maybe: passed as @parent > ? Sure, I'll make that change. > Otherwise, LGTM. Thanks for doing this. > > Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Thanks! > >> + * 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 +876,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); >> >
| |