[PATCH RFC v2 0/2] pmdomains: core: add support for domain hierarchies in DT

[PATCH RFC v2 0/2] pmdomains: core: add support for domain hierarchies in DT

[Kevin Hilman]

Currently, PM domains can only support hierarchy for simple
providers (e.g. ones with #power-domain-cells = 0).

Add support for oncell providers as well by adding support for a nexus
node map, as described in section 2.5.1 of the DT spec.

Signed-off-by: Kevin Hilman <khilman@baylibre.com>
---
Changes in v2:
- Use nexus map instead of creating new property as suggested by Rob H.
- Link to v1: https://lore.kernel.org/r/20250528-pmdomain-hierarchy-onecell-v1-1-851780700c68@baylibre.com

---
Kevin Hilman (2):
      dt-bindings: power: add nexus map for power-domains
      pmdomain: core: use DT map to support hierarchy

 Documentation/devicetree/bindings/power/power-domain.yaml |  35 ++++++++++++++++++++
 drivers/pmdomain/core.c                                   | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 201 insertions(+)
---
base-commit: 0ff41df1cb268fc69e703a08a57ee14ae967d0ca
change-id: 20250528-pmdomain-hierarchy-onecell-a46fad47d855

Best regards,
-- 
Kevin Hilman <khilman@baylibre.com>

[PATCH RFC v2 1/2] dt-bindings: power: add nexus map for power-domains

[Kevin Hilman]

Add support for nexus map to be able to support hierarchical power
domains for providers with #power-domain-cells > 0.

Suggested-by: Rob Herring <robh@kernel.org>
Signed-off-by: Kevin Hilman <khilman@baylibre.com>
---
 Documentation/devicetree/bindings/power/power-domain.yaml | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/Documentation/devicetree/bindings/power/power-domain.yaml b/Documentation/devicetree/bindings/power/power-domain.yaml
index 8fdb529d560b..9f099d326aee 100644
--- a/Documentation/devicetree/bindings/power/power-domain.yaml
+++ b/Documentation/devicetree/bindings/power/power-domain.yaml
@@ -68,6 +68,15 @@ properties:
       by the given provider should be subdomains of the domain specified
       by this binding.
 
+  power-domains-map:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    description:
+      Nexus node mapping property that establishes parent-child relationships
+      for PM domains using the format defined in the Device Tree specification
+      section 2.5.1. Each map entry consists of child domain specifier,
+      parent phandle, and optional parent specifier arguments. This property
+      is only supported for onecell providers (#power-domain-cells = 1).
+
 required:
   - "#power-domain-cells"
 
@@ -133,3 +142,29 @@ examples:
             min-residency-us = <7000>;
         };
     };
+
+  - |
+    // Example using power-domains-map for Nexus mapping
+    main_pd: power-controller@12370000 {
+        compatible = "foo,power-controller";
+        reg = <0x12370000 0x1000>;
+        #power-domain-cells = <0>;
+    };
+
+    wkup_pd: power-controller@12380000 {
+        compatible = "foo,power-controller";
+        reg = <0x12380000 0x1000>;
+        #power-domain-cells = <0>;
+    };
+
+    scmi_pds protocol@11 {
+        compatible = "arm,scmi-power-domain";
+        reg = <0x11>;
+        #power-domain-cells = <1>;
+        power-domains-map = <15 &main_pd>,
+                            <19 &wkup_pd>;
+    };
+
+    // In this example using Nexus node mapping:
+    // - Child domain 15 (scmi_pds 15) becomes a subdomain of main_pd
+    // - Child domain 19 (scmi_pds 19) becomes a subdomain of wkup_pd

-- 
2.49.0

[PATCH RFC v2 2/2] pmdomain: core: use DT map to support hierarchy

[Kevin Hilman]

Currently, PM domains can only support hierarchy for simple
providers (e.g. ones with #power-domain-cells = 0).

Add support for oncell providers as well by adding support for a nexus
node map, as described in section 2.5.1 of the DT spec.

For example, an SCMI PM domain provider might be a subdomain of
multiple parent domains. In this example, the parent domains are
MAIN_PD and WKUP_PD:

    scmi_pds: protocol@11 {
        reg = <0x11>;
        #power-domain-cells = <1>;
        power-domain-map = <15 &MAIN_PD>,
                           <19 &WKUP_PD>;
    };

With the new map, child domain 15 (scmi_pds 15) becomes a
subdomain of MAIN_PD, and child domain 19 (scmi_pds 19) becomes a
subdomain of WKUP_PD.

Signed-off-by: Kevin Hilman <khilman@baylibre.com>
---
 drivers/pmdomain/core.c | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 166 insertions(+)

diff --git a/drivers/pmdomain/core.c b/drivers/pmdomain/core.c
index d6c1ddb807b2..b8e505516f3d 100644
--- a/drivers/pmdomain/core.c
+++ b/drivers/pmdomain/core.c
@@ -2441,6 +2441,9 @@ static LIST_HEAD(of_genpd_providers);
 /* Mutex to protect the list above. */
 static DEFINE_MUTEX(of_genpd_mutex);
 
+static int of_genpd_parse_domains_map(struct device_node *np,
+				      struct genpd_onecell_data *data);
+
 /**
  * genpd_xlate_simple() - Xlate function for direct node-domain mapping
  * @genpdspec: OF phandle args to map into a PM domain
@@ -2635,6 +2638,14 @@ int of_genpd_add_provider_onecell(struct device_node *np,
 	if (ret < 0)
 		goto error;
 
+	/* Parse power-domains-map property for Nexus node mapping */
+	ret = of_genpd_parse_domains_map(np, data);
+	if (ret < 0 && ret != -ENOENT) {
+		pr_err("Failed to parse power-domains-map for %pOF: %d\n", np, ret);
+		of_genpd_del_provider(np);
+		goto error;
+	}
+
 	return 0;
 
 error:
@@ -2734,6 +2745,161 @@ static struct generic_pm_domain *genpd_get_from_provider(
 	return genpd;
 }
 
+/**
+ * of_genpd_parse_domains_map() - Parse power-domains-map property for Nexus mapping
+ * @np: Device node pointer associated with the PM domain provider.
+ * @data: Pointer to the onecell data associated with the PM domain provider.
+ *
+ * Parse the power-domains-map property to establish parent-child relationships
+ * for PM domains using Nexus node mapping as defined in the device tree
+ * specification section v2.5.1.
+ *
+ * The power-domains-map property format is:
+ * power-domains-map = <child_specifier target_phandle [target_specifier]>, ...;
+ *
+ * Where:
+ * - child_specifier: The child domain ID that should be mapped
+ * - target_phandle: Phandle to the parent PM domain provider
+ * - target_specifier: Optional arguments for the parent provider (if it has #power-domain-cells > 0)
+ *
+ * Returns 0 on success, -ENOENT if property doesn't exist, or negative error code.
+ */
+static int of_genpd_parse_domains_map(struct device_node *np,
+				      struct genpd_onecell_data *data)
+{
+	struct of_phandle_args parent_args;
+	struct generic_pm_domain *parent_genpd, *child_genpd;
+	u32 *map_entries;
+	int map_len, child_cells, i, ret;
+	u32 child_id;
+
+	/* Check if power-domains-map property exists */
+	map_len = of_property_count_u32_elems(np, "power-domains-map");
+	if (map_len <= 0)
+		return -ENOENT;
+
+	/* Get #power-domain-cells from this node (should be 1 for onecell) */
+	ret = of_property_read_u32(np, "#power-domain-cells", &child_cells);
+	if (ret) {
+		pr_err("Missing #power-domain-cells property for %pOF\n", np);
+		return ret;
+	}
+
+	if (child_cells != 1) {
+		pr_err("power-domains-map only supported for #power-domain-cells = 1, got %u for %pOF\n",
+		       child_cells, np);
+		return -EINVAL;
+	}
+
+	map_entries = kcalloc(map_len, sizeof(*map_entries), GFP_KERNEL);
+	if (!map_entries)
+		return -ENOMEM;
+
+	ret = of_property_read_u32_array(np, "power-domains-map", map_entries, map_len);
+	if (ret) {
+		pr_err("Failed to read power-domains-map for %pOF: %d\n", np, ret);
+		goto out_free;
+	}
+
+	/* Parse the map entries */
+	i = 0;
+	while (i < map_len) {
+		struct device_node *parent_np;
+		u32 parent_cells;
+
+		/* Extract child domain ID */
+		if (i >= map_len) {
+			pr_err("Incomplete power-domains-map entry at index %d for %pOF\n", i, np);
+			ret = -EINVAL;
+			goto out_free;
+		}
+		child_id = map_entries[i++];
+
+		/* Extract parent phandle */
+		if (i >= map_len) {
+			pr_err("Missing parent phandle in power-domains-map at index %d for %pOF\n", i, np);
+			ret = -EINVAL;
+			goto out_free;
+		}
+		parent_np = of_find_node_by_phandle(map_entries[i++]);
+		if (!parent_np) {
+			pr_err("Invalid parent phandle 0x%x in power-domains-map for %pOF\n",
+			       map_entries[i-1], np);
+			ret = -EINVAL;
+			goto out_free;
+		}
+
+		/* Get #power-domain-cells from parent */
+		ret = of_property_read_u32(parent_np, "#power-domain-cells", &parent_cells);
+		if (ret) {
+			pr_err("Missing #power-domain-cells in parent %pOF for %pOF\n", parent_np, np);
+			of_node_put(parent_np);
+			goto out_free;
+		}
+
+		/* Build parent_args structure */
+		parent_args.np = parent_np;
+		parent_args.args_count = parent_cells;
+
+		/* Extract parent specifier arguments if any */
+		if (parent_cells > 0) {
+			if (i + parent_cells > map_len) {
+				pr_err("Insufficient parent specifier args in power-domains-map for %pOF\n", np);
+				of_node_put(parent_np);
+				ret = -EINVAL;
+				goto out_free;
+			}
+			memcpy(parent_args.args, &map_entries[i], parent_cells * sizeof(u32));
+			i += parent_cells;
+		}
+
+		/* Validate child ID is within bounds */
+		if (child_id >= data->num_domains) {
+			pr_err("Child ID %u out of bounds (max %u) in power-domains-map for %pOF\n",
+			       child_id, data->num_domains - 1, np);
+			of_node_put(parent_np);
+			ret = -EINVAL;
+			goto out_free;
+		}
+
+		/* Get the child domain */
+		child_genpd = data->domains[child_id];
+		if (!child_genpd) {
+			pr_err("Child domain %u is NULL in power-domains-map for %pOF\n", child_id, np);
+			of_node_put(parent_np);
+			ret = -EINVAL;
+			goto out_free;
+		}
+
+		/* Get the parent domain */
+		parent_genpd = genpd_get_from_provider(&parent_args);
+		of_node_put(parent_np);
+		if (IS_ERR(parent_genpd)) {
+			pr_err("Failed to get parent domain for child %u in power-domains-map for %pOF: %ld\n",
+			       child_id, np, PTR_ERR(parent_genpd));
+			ret = PTR_ERR(parent_genpd);
+			goto out_free;
+		}
+
+		/* Establish parent-child relationship */
+		ret = genpd_add_subdomain(parent_genpd, child_genpd);
+		if (ret) {
+			pr_err("Failed to add child domain %u to parent in power-domains-map for %pOF: %d\n",
+			       child_id, np, ret);
+			goto out_free;
+		}
+
+		pr_debug("Added child domain %u (%s) to parent %s via power-domains-map for %pOF\n",
+			 child_id, child_genpd->name, parent_genpd->name, np);
+	}
+
+	ret = 0;
+
+out_free:
+	kfree(map_entries);
+	return ret;
+}
+
 /**
  * of_genpd_add_device() - Add a device to an I/O PM domain
  * @genpdspec: OF phandle args to use for look-up PM domain

-- 
2.49.0

Re: [PATCH RFC v2 1/2] dt-bindings: power: add nexus map for power-domains

[Rob Herring (Arm)]

On Wed, 28 May 2025 14:58:51 -0700, Kevin Hilman wrote:
> Add support for nexus map to be able to support hierarchical power
> domains for providers with #power-domain-cells > 0.
> 
> Suggested-by: Rob Herring <robh@kernel.org>
> Signed-off-by: Kevin Hilman <khilman@baylibre.com>
> ---
>  Documentation/devicetree/bindings/power/power-domain.yaml | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
> 

My bot found errors running 'make dt_binding_check' on your patch:

yamllint warnings/errors:

dtschema/dtc warnings/errors:
Error: Documentation/devicetree/bindings/power/power-domain.example.dts:136.18-19 syntax error
FATAL ERROR: Unable to parse input tree
make[2]: *** [scripts/Makefile.dtbs:131: Documentation/devicetree/bindings/power/power-domain.example.dtb] Error 1
make[2]: *** Waiting for unfinished jobs....
make[1]: *** [/builds/robherring/dt-review-ci/linux/Makefile:1519: dt_binding_check] Error 2
make: *** [Makefile:248: __sub-make] Error 2

doc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/project/devicetree-bindings/patch/20250528-pmdomain-hierarchy-onecell-v2-1-7885ae45e59c@baylibre.com

The base for the series is generally the latest rc1. A different dependency
should be noted in *this* patch.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit after running the above command yourself. Note
that DT_SCHEMA_FILES can be set to your schema file to speed up checking
your schema. However, it must be unset to test all examples with your schema.

Re: [PATCH RFC v2 1/2] dt-bindings: power: add nexus map for power-domains

[Ulf Hansson]

On Wed, 28 May 2025 at 23:59, Kevin Hilman <khilman@baylibre.com> wrote:
>
> Add support for nexus map to be able to support hierarchical power
> domains for providers with #power-domain-cells > 0.
>
> Suggested-by: Rob Herring <robh@kernel.org>
> Signed-off-by: Kevin Hilman <khilman@baylibre.com>

Reviewed-by: Ulf Hansson <ulf.hansson@linaro.org>

Kind regards
Uffe

> ---
>  Documentation/devicetree/bindings/power/power-domain.yaml | 35 +++++++++++++++++++++++++++++++++++
>  1 file changed, 35 insertions(+)
>
> diff --git a/Documentation/devicetree/bindings/power/power-domain.yaml b/Documentation/devicetree/bindings/power/power-domain.yaml
> index 8fdb529d560b..9f099d326aee 100644
> --- a/Documentation/devicetree/bindings/power/power-domain.yaml
> +++ b/Documentation/devicetree/bindings/power/power-domain.yaml
> @@ -68,6 +68,15 @@ properties:
>        by the given provider should be subdomains of the domain specified
>        by this binding.
>
> +  power-domains-map:
> +    $ref: /schemas/types.yaml#/definitions/uint32-array
> +    description:
> +      Nexus node mapping property that establishes parent-child relationships
> +      for PM domains using the format defined in the Device Tree specification
> +      section 2.5.1. Each map entry consists of child domain specifier,
> +      parent phandle, and optional parent specifier arguments. This property
> +      is only supported for onecell providers (#power-domain-cells = 1).
> +
>  required:
>    - "#power-domain-cells"
>
> @@ -133,3 +142,29 @@ examples:
>              min-residency-us = <7000>;
>          };
>      };
> +
> +  - |
> +    // Example using power-domains-map for Nexus mapping
> +    main_pd: power-controller@12370000 {
> +        compatible = "foo,power-controller";
> +        reg = <0x12370000 0x1000>;
> +        #power-domain-cells = <0>;
> +    };
> +
> +    wkup_pd: power-controller@12380000 {
> +        compatible = "foo,power-controller";
> +        reg = <0x12380000 0x1000>;
> +        #power-domain-cells = <0>;
> +    };
> +
> +    scmi_pds protocol@11 {
> +        compatible = "arm,scmi-power-domain";
> +        reg = <0x11>;
> +        #power-domain-cells = <1>;
> +        power-domains-map = <15 &main_pd>,
> +                            <19 &wkup_pd>;
> +    };
> +
> +    // In this example using Nexus node mapping:
> +    // - Child domain 15 (scmi_pds 15) becomes a subdomain of main_pd
> +    // - Child domain 19 (scmi_pds 19) becomes a subdomain of wkup_pd
>
> --
> 2.49.0
>

Re: [PATCH RFC v2 2/2] pmdomain: core: use DT map to support hierarchy

[Rob Herring]

On Wed, May 28, 2025 at 02:58:52PM -0700, Kevin Hilman wrote:
> Currently, PM domains can only support hierarchy for simple
> providers (e.g. ones with #power-domain-cells = 0).
> 
> Add support for oncell providers as well by adding support for a nexus
> node map, as described in section 2.5.1 of the DT spec.
> 
> For example, an SCMI PM domain provider might be a subdomain of
> multiple parent domains. In this example, the parent domains are
> MAIN_PD and WKUP_PD:
> 
>     scmi_pds: protocol@11 {
>         reg = <0x11>;
>         #power-domain-cells = <1>;
>         power-domain-map = <15 &MAIN_PD>,
>                            <19 &WKUP_PD>;
>     };
> 
> With the new map, child domain 15 (scmi_pds 15) becomes a
> subdomain of MAIN_PD, and child domain 19 (scmi_pds 19) becomes a
> subdomain of WKUP_PD.
> 
> Signed-off-by: Kevin Hilman <khilman@baylibre.com>
> ---
>  drivers/pmdomain/core.c | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 166 insertions(+)
> 
> diff --git a/drivers/pmdomain/core.c b/drivers/pmdomain/core.c
> index d6c1ddb807b2..b8e505516f3d 100644
> --- a/drivers/pmdomain/core.c
> +++ b/drivers/pmdomain/core.c
> @@ -2441,6 +2441,9 @@ static LIST_HEAD(of_genpd_providers);
>  /* Mutex to protect the list above. */
>  static DEFINE_MUTEX(of_genpd_mutex);
>  
> +static int of_genpd_parse_domains_map(struct device_node *np,
> +				      struct genpd_onecell_data *data);
> +
>  /**
>   * genpd_xlate_simple() - Xlate function for direct node-domain mapping
>   * @genpdspec: OF phandle args to map into a PM domain
> @@ -2635,6 +2638,14 @@ int of_genpd_add_provider_onecell(struct device_node *np,
>  	if (ret < 0)
>  		goto error;
>  
> +	/* Parse power-domains-map property for Nexus node mapping */
> +	ret = of_genpd_parse_domains_map(np, data);
> +	if (ret < 0 && ret != -ENOENT) {
> +		pr_err("Failed to parse power-domains-map for %pOF: %d\n", np, ret);
> +		of_genpd_del_provider(np);
> +		goto error;
> +	}
> +
>  	return 0;
>  
>  error:
> @@ -2734,6 +2745,161 @@ static struct generic_pm_domain *genpd_get_from_provider(
>  	return genpd;
>  }
>  
> +/**
> + * of_genpd_parse_domains_map() - Parse power-domains-map property for Nexus mapping
> + * @np: Device node pointer associated with the PM domain provider.
> + * @data: Pointer to the onecell data associated with the PM domain provider.
> + *
> + * Parse the power-domains-map property to establish parent-child relationships
> + * for PM domains using Nexus node mapping as defined in the device tree
> + * specification section v2.5.1.
> + *
> + * The power-domains-map property format is:
> + * power-domains-map = <child_specifier target_phandle [target_specifier]>, ...;
> + *
> + * Where:
> + * - child_specifier: The child domain ID that should be mapped
> + * - target_phandle: Phandle to the parent PM domain provider
> + * - target_specifier: Optional arguments for the parent provider (if it has #power-domain-cells > 0)
> + *
> + * Returns 0 on success, -ENOENT if property doesn't exist, or negative error code.
> + */
> +static int of_genpd_parse_domains_map(struct device_node *np,
> +				      struct genpd_onecell_data *data)
> +{
> +	struct of_phandle_args parent_args;
> +	struct generic_pm_domain *parent_genpd, *child_genpd;
> +	u32 *map_entries;
> +	int map_len, child_cells, i, ret;
> +	u32 child_id;
> +
> +	/* Check if power-domains-map property exists */
> +	map_len = of_property_count_u32_elems(np, "power-domains-map");
> +	if (map_len <= 0)
> +		return -ENOENT;

Don't implement your own map parsing. Use or extend 
of_parse_phandle_with_args_map().

Rob

Re: [PATCH RFC v2 2/2] pmdomain: core: use DT map to support hierarchy

[Ulf Hansson]

On Wed, 28 May 2025 at 23:59, Kevin Hilman <khilman@baylibre.com> wrote:
>
> Currently, PM domains can only support hierarchy for simple
> providers (e.g. ones with #power-domain-cells = 0).
>
> Add support for oncell providers as well by adding support for a nexus
> node map, as described in section 2.5.1 of the DT spec.
>
> For example, an SCMI PM domain provider might be a subdomain of
> multiple parent domains. In this example, the parent domains are
> MAIN_PD and WKUP_PD:
>
>     scmi_pds: protocol@11 {
>         reg = <0x11>;
>         #power-domain-cells = <1>;
>         power-domain-map = <15 &MAIN_PD>,
>                            <19 &WKUP_PD>;
>     };
>
> With the new map, child domain 15 (scmi_pds 15) becomes a
> subdomain of MAIN_PD, and child domain 19 (scmi_pds 19) becomes a
> subdomain of WKUP_PD.
>
> Signed-off-by: Kevin Hilman <khilman@baylibre.com>
> ---
>  drivers/pmdomain/core.c | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 166 insertions(+)
>
> diff --git a/drivers/pmdomain/core.c b/drivers/pmdomain/core.c
> index d6c1ddb807b2..b8e505516f3d 100644
> --- a/drivers/pmdomain/core.c
> +++ b/drivers/pmdomain/core.c
> @@ -2441,6 +2441,9 @@ static LIST_HEAD(of_genpd_providers);
>  /* Mutex to protect the list above. */
>  static DEFINE_MUTEX(of_genpd_mutex);
>
> +static int of_genpd_parse_domains_map(struct device_node *np,
> +                                     struct genpd_onecell_data *data);
> +
>  /**
>   * genpd_xlate_simple() - Xlate function for direct node-domain mapping
>   * @genpdspec: OF phandle args to map into a PM domain
> @@ -2635,6 +2638,14 @@ int of_genpd_add_provider_onecell(struct device_node *np,
>         if (ret < 0)
>                 goto error;
>
> +       /* Parse power-domains-map property for Nexus node mapping */
> +       ret = of_genpd_parse_domains_map(np, data);
> +       if (ret < 0 && ret != -ENOENT) {
> +               pr_err("Failed to parse power-domains-map for %pOF: %d\n", np, ret);
> +               of_genpd_del_provider(np);
> +               goto error;
> +       }

To be consistent with the current way for how we usually add
parent/child-domains in genpd (see of_genpd_add|remove_subdomain), I
suggest we keep this part being specific to each genpd provider
driver, rather than calling this from of_genpd_add_provider_onecell().

That said, I don't mind if we need to export another genpd helper
function along the lines of of_genpd_parse_domains_map() as below.
Also don't forget to consider if there is a corresponding "cleanup"
helper function needed.

[...]

Kind regards
Uffe

Re: [PATCH RFC v2 2/2] pmdomain: core: use DT map to support hierarchy

[Kevin Hilman]

Hi Rob,

Rob Herring <robh@kernel.org> writes:

> On Wed, May 28, 2025 at 02:58:52PM -0700, Kevin Hilman wrote:
>> Currently, PM domains can only support hierarchy for simple
>> providers (e.g. ones with #power-domain-cells = 0).
>> 
>> Add support for oncell providers as well by adding support for a nexus
>> node map, as described in section 2.5.1 of the DT spec.
>> 
>> For example, an SCMI PM domain provider might be a subdomain of
>> multiple parent domains. In this example, the parent domains are
>> MAIN_PD and WKUP_PD:
>> 
>>     scmi_pds: protocol@11 {
>>         reg = <0x11>;
>>         #power-domain-cells = <1>;
>>         power-domain-map = <15 &MAIN_PD>,
>>                            <19 &WKUP_PD>;
>>     };
>> 
>> With the new map, child domain 15 (scmi_pds 15) becomes a
>> subdomain of MAIN_PD, and child domain 19 (scmi_pds 19) becomes a
>> subdomain of WKUP_PD.
>> 
>> Signed-off-by: Kevin Hilman <khilman@baylibre.com>

[...]

>> +/**
>> + * of_genpd_parse_domains_map() - Parse power-domains-map property for Nexus mapping
>> + * @np: Device node pointer associated with the PM domain provider.
>> + * @data: Pointer to the onecell data associated with the PM domain provider.
>> + *
>> + * Parse the power-domains-map property to establish parent-child relationships
>> + * for PM domains using Nexus node mapping as defined in the device tree
>> + * specification section v2.5.1.
>> + *
>> + * The power-domains-map property format is:
>> + * power-domains-map = <child_specifier target_phandle [target_specifier]>, ...;
>> + *
>> + * Where:
>> + * - child_specifier: The child domain ID that should be mapped
>> + * - target_phandle: Phandle to the parent PM domain provider
>> + * - target_specifier: Optional arguments for the parent provider (if it has #power-domain-cells > 0)
>> + *
>> + * Returns 0 on success, -ENOENT if property doesn't exist, or negative error code.
>> + */
>> +static int of_genpd_parse_domains_map(struct device_node *np,
>> +				      struct genpd_onecell_data *data)
>> +{
>> +	struct of_phandle_args parent_args;
>> +	struct generic_pm_domain *parent_genpd, *child_genpd;
>> +	u32 *map_entries;
>> +	int map_len, child_cells, i, ret;
>> +	u32 child_id;
>> +
>> +	/* Check if power-domains-map property exists */
>> +	map_len = of_property_count_u32_elems(np, "power-domains-map");
>> +	if (map_len <= 0)
>> +		return -ENOENT;
>
> Don't implement your own map parsing. Use or extend 
> of_parse_phandle_with_args_map().

So I've been wrestling with this for a bit, and I need some guidance.
TBH, these "nexus node maps" and of_parse_phandle_with_args_map() are
breaking my brain.

So, my node looks like this:

	scmi_pds: protocol@11 {
		reg = <0x11>;
		#power-domain-cells = <1>;
		bootph-all;

		power-domain-map = <15 &MAIN_PD>,
				   <19 &WKUP_PD>;
	};

my first attempt was to iterate over the child domains by calling:

  of_parse_phandle_with_args_map(np, "power-domains", "power-domain", i,  &mapped_args);  

but this doesn't find any entries because my node doesn't have the
"base" property.  So I gathered (perhaps mistakenly) that I was missing
something, so I added:

		power-domains = <&MAIN_PD>, <&WKUP_PD>;

to that node and try to iterate again. Now I got a match for i=0 (it
returns the node for MAIN_PD) and i=1 (it returns the node for WKUP_PD)

So I gather from that that the index arg to of_parse_phandle_with_args_map()
is the index into the -map array.  OK, fine.

So I know that the 0th entry in my -map points to &MAIN_PD, an dthe 1st
entry in the -map points to &WKUP_PD, but I don't see how to get the
child ID without (re)parsing the -map again myself because
of_parse_phandle_with_args_map() doesn't give me any information about
the child ID.

I can maybe see that in other usecases, the caller might not need the
child ID because it's being (re)mapped, but I need the child ID because
it's the pmdomain belonging to the child ID that I need to add as a
subdomain to the pmdomain of the parent.

However, thinking through this, I'm now realizing that maybe the problem
is that I cannot have a sparse -map table.  For this to work properly,
maybe my <15 &MAIN_PD> needs to be the 15th entry in the table (or
technically 16th if it's zero based)?

But before I go down any more rabbit holes, I wanted to check with folks
who understand this stuff and see if I'm on the right track or if I've
missed the boat on how to use of_parse_phandle_with_args_map().

Guidance, suggetions and/or public riducle are welcome. ;)

Kevin

Re: [PATCH RFC v2 2/2] pmdomain: core: use DT map to support hierarchy

[Kevin Hilman]

Kevin Hilman <khilman@baylibre.com> writes:

> Hi Rob,
>
> Rob Herring <robh@kernel.org> writes:
>
>> On Wed, May 28, 2025 at 02:58:52PM -0700, Kevin Hilman wrote:
>>> Currently, PM domains can only support hierarchy for simple
>>> providers (e.g. ones with #power-domain-cells = 0).
>>> 
>>> Add support for oncell providers as well by adding support for a nexus
>>> node map, as described in section 2.5.1 of the DT spec.
>>> 
>>> For example, an SCMI PM domain provider might be a subdomain of
>>> multiple parent domains. In this example, the parent domains are
>>> MAIN_PD and WKUP_PD:
>>> 
>>>     scmi_pds: protocol@11 {
>>>         reg = <0x11>;
>>>         #power-domain-cells = <1>;
>>>         power-domain-map = <15 &MAIN_PD>,
>>>                            <19 &WKUP_PD>;
>>>     };
>>> 
>>> With the new map, child domain 15 (scmi_pds 15) becomes a
>>> subdomain of MAIN_PD, and child domain 19 (scmi_pds 19) becomes a
>>> subdomain of WKUP_PD.
>>> 
>>> Signed-off-by: Kevin Hilman <khilman@baylibre.com>
>
> [...]
>
>>> +/**
>>> + * of_genpd_parse_domains_map() - Parse power-domains-map property for Nexus mapping
>>> + * @np: Device node pointer associated with the PM domain provider.
>>> + * @data: Pointer to the onecell data associated with the PM domain provider.
>>> + *
>>> + * Parse the power-domains-map property to establish parent-child relationships
>>> + * for PM domains using Nexus node mapping as defined in the device tree
>>> + * specification section v2.5.1.
>>> + *
>>> + * The power-domains-map property format is:
>>> + * power-domains-map = <child_specifier target_phandle [target_specifier]>, ...;
>>> + *
>>> + * Where:
>>> + * - child_specifier: The child domain ID that should be mapped
>>> + * - target_phandle: Phandle to the parent PM domain provider
>>> + * - target_specifier: Optional arguments for the parent provider (if it has #power-domain-cells > 0)
>>> + *
>>> + * Returns 0 on success, -ENOENT if property doesn't exist, or negative error code.
>>> + */
>>> +static int of_genpd_parse_domains_map(struct device_node *np,
>>> +				      struct genpd_onecell_data *data)
>>> +{
>>> +	struct of_phandle_args parent_args;
>>> +	struct generic_pm_domain *parent_genpd, *child_genpd;
>>> +	u32 *map_entries;
>>> +	int map_len, child_cells, i, ret;
>>> +	u32 child_id;
>>> +
>>> +	/* Check if power-domains-map property exists */
>>> +	map_len = of_property_count_u32_elems(np, "power-domains-map");
>>> +	if (map_len <= 0)
>>> +		return -ENOENT;
>>
>> Don't implement your own map parsing. Use or extend 
>> of_parse_phandle_with_args_map().
>
> So I've been wrestling with this for a bit, and I need some guidance.
> TBH, these "nexus node maps" and of_parse_phandle_with_args_map() are
> breaking my brain.

OK, nevermind.  I *think* I have a better grasp on how they should be used
now.  I've submitted a v3 of the RFC[1], but could defintely still use
some guidance.

Kevin

[1] https://lore.kernel.org/linux-pm/20250613-pmdomain-hierarchy-onecell-v3-0-5c770676fce7@baylibre.com/