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.shevche...@linux.intel.com>
Reviewed-by: Heikki Krogerus <heikki.kroge...@linux.intel.com>
Reviewed-by: Randy Dunlap <rdun...@infradead.org>
Reviewed-by: Sakari Ailus <sakari.ai...@linux.intel.com>
Signed-off-by: Daniel Scally <djrsca...@gmail.com>
---
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(+)
diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
index 4a4b2008fbc2..39fbb653c58a 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,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);
--
2.25.1
