Commit d9194e00 authored Feb 13, 2023 by Frank Rowand Committed by Rob Herring Feb 20, 2023

of: dynamic: add lifecycle docbook info to node creation functions



The existing docbook comments for the functions related to creating
a devicetree node do not explain the reference count of a newly
created node, how decrementing the reference count to zero will
free the associated memory, and the caller's responsibility to
call of_node_put() on the node.  Explain what happens when the
reference count is decremented to zero.

Signed-off-by: Frank Rowand <frowand.list@gmail.com>
Link: https://lore.kernel.org/r/20230213185702.395776-8-frowand.list@gmail.com


Signed-off-by: Rob Herring <robh@kernel.org>

parent ec0b7e24

drivers/of/dynamic.c

+2 −1

Original line number	Diff line number	Diff line
		@@ -443,7 +443,8 @@ struct property __of_prop_dup(const struct property prop, gfp_t allocflags)
		* another node. The node data are dynamically allocated and all the node
		* flags have the OF_DYNAMIC & OF_DETACHED bits set.
		*
		* Return: The newly allocated node or NULL on out of memory error.
		* Return: The newly allocated node or NULL on out of memory error. Use
		* of_node_put() on it when done to free the memory allocated for it.
		*/
		struct device_node __of_node_dup(const struct device_node np,
		const char *full_name)

include/linux/of.h

+11 −0

Original line number	Diff line number	Diff line
		@@ -100,6 +100,17 @@ struct of_reconfig_data {
		struct property *old_prop;
		};

		/**
		* of_node_init - initialize a devicetree node
		* @node: Pointer to device node that has been created by kzalloc()
		* @phandle_name: Name of property holding a phandle value
		*
		* On return the device_node refcount is set to one. Use of_node_put()
		* on @node when done to free the memory allocated for it. If the node
		* is NOT a dynamic node the memory will not be freed. The decision of
		* whether to free the memory will be done by node->release(), which is
		* of_node_release().
		*/
		/* initialize a node */
		extern const struct kobj_type of_node_ktype;
		extern const struct fwnode_operations of_fwnode_ops;