[PATCH v1 1/1] device property: Sync descriptions of swnode array and group APIs

[PATCH v1 1/1] device property: Sync descriptions of swnode array and group APIs

[Andy Shevchenko]

After a few updates against swnode APIs the kernel documentation, i.e.
for swnode group registration and unregistration deviates from the one
for swnode array. In general, the same rules are applied to both.
Hence, synchronize descriptions of swnode array and group APIs

Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
 drivers/base/swnode.c | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
index 37179a8b1ceb..46c48d602915 100644
--- a/drivers/base/swnode.c
+++ b/drivers/base/swnode.c
@@ -880,7 +880,11 @@ EXPORT_SYMBOL_GPL(software_node_unregister_nodes);
  * software_node_register_node_group - Register a group of software nodes
  * @node_group: NULL terminated array of software node pointers to be registered
  *
- * Register multiple software nodes at once.
+ * Register multiple software nodes at once. If any node in the array
+ * has its .parent pointer set (which can only be to another software_node),
+ * then its parent **must** have been registered before it is; either outside
+ * of this function or by ordering the array such that parent comes before
+ * child.
  */
 int software_node_register_node_group(const struct software_node **node_group)
 {
@@ -906,10 +910,14 @@ EXPORT_SYMBOL_GPL(software_node_register_node_group);
  * software_node_unregister_node_group - Unregister a group of software nodes
  * @node_group: NULL terminated array of software node pointers to be unregistered
  *
- * Unregister multiple software nodes at once. The array will be unwound in
- * reverse order (i.e. last entry first) and thus if any members of the array are
- * children of another member then the children must appear later in the list such
- * that they are unregistered first.
+ * Unregister multiple software nodes at once. If parent pointers are set up
+ * in any of the software nodes then the array **must** be ordered such that
+ * parents come before their children.
+ *
+ * NOTE: If you are uncertain whether the array is ordered such that
+ * parents will be unregistered before their children, it is wiser to
+ * remove the nodes individually, in the correct order (child before
+ * parent).
  */
 void software_node_unregister_node_group(
 		const struct software_node **node_group)
-- 
2.30.1

Re: [PATCH v1 1/1] device property: Sync descriptions of swnode array and group APIs

[Heikki Krogerus]

On Mon, Mar 08, 2021 at 12:36:44PM +0200, Andy Shevchenko wrote:
> After a few updates against swnode APIs the kernel documentation, i.e.
> for swnode group registration and unregistration deviates from the one
> for swnode array. In general, the same rules are applied to both.
> Hence, synchronize descriptions of swnode array and group APIs
> 
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

Reviewed-by: Heikki Krogerus <heikki.krogerus@linux.intel.com>

> ---
>  drivers/base/swnode.c | 18 +++++++++++++-----
>  1 file changed, 13 insertions(+), 5 deletions(-)
> 
> diff --git a/drivers/base/swnode.c b/drivers/base/swnode.c
> index 37179a8b1ceb..46c48d602915 100644
> --- a/drivers/base/swnode.c
> +++ b/drivers/base/swnode.c
> @@ -880,7 +880,11 @@ EXPORT_SYMBOL_GPL(software_node_unregister_nodes);
>   * software_node_register_node_group - Register a group of software nodes
>   * @node_group: NULL terminated array of software node pointers to be registered
>   *
> - * Register multiple software nodes at once.
> + * Register multiple software nodes at once. If any node in the array
> + * has its .parent pointer set (which can only be to another software_node),
> + * then its parent **must** have been registered before it is; either outside
> + * of this function or by ordering the array such that parent comes before
> + * child.
>   */
>  int software_node_register_node_group(const struct software_node **node_group)
>  {
> @@ -906,10 +910,14 @@ EXPORT_SYMBOL_GPL(software_node_register_node_group);
>   * software_node_unregister_node_group - Unregister a group of software nodes
>   * @node_group: NULL terminated array of software node pointers to be unregistered
>   *
> - * Unregister multiple software nodes at once. The array will be unwound in
> - * reverse order (i.e. last entry first) and thus if any members of the array are
> - * children of another member then the children must appear later in the list such
> - * that they are unregistered first.
> + * Unregister multiple software nodes at once. If parent pointers are set up
> + * in any of the software nodes then the array **must** be ordered such that
> + * parents come before their children.
> + *
> + * NOTE: If you are uncertain whether the array is ordered such that
> + * parents will be unregistered before their children, it is wiser to
> + * remove the nodes individually, in the correct order (child before
> + * parent).
>   */
>  void software_node_unregister_node_group(
>  		const struct software_node **node_group)
> -- 
> 2.30.1

-- 
heikki