Messages in this thread Patch in this message | | | From | Daniel Scally <> | Subject | [PATCH] software_node: Add kernel-doc comments to exported symbols | Date | Mon, 4 Jan 2021 23:47:36 +0000 |
| |
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 <djrscally@gmail.com> --- 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
| |