Add of_genpd_[add|remove]_subdomain_map() helper functions to support
hierarchical PM domains defined by using power-domains-map
property (c.f. nexus node maps in DT spec, section 2.5.1).
This enables PM domain providers with #power-domain-cells > 0 to
establish subdomain relationships via the power-domain-map property,
which was not previously possible.
These new helper functions:
- uses an OF helper to iterate to over entries in power-domain-map
- For each mapped entry: extracts child specifier, resolves parent phandle,
extracts parent specifier args, and establishes subdomain relationship
- Calls genpd_[add|remove]_subdomain() with proper gpd_list_lock mutex protection
Example from k3-am62l.dtsi:
scmi_pds: protocol@11 {
#power-domain-cells = <1>;
power-domain-map = <15 &MAIN_PD>, /* TIMER0 */
<19 &WKUP_PD>; /* WKUP_TIMER0 */
};
MAIN_PD: power-controller-main {
#power-domain-cells = <0>;
};
WKUP_PD: power-controller-main {
#power-domain-cells = <0>;
};
This allows SCMI power domain 15 to become a subdomain of MAIN_PD, and
domain 19 to become a subdomain of WKUP_PD.
Signed-off-by: Kevin Hilman (TI) <khilman@baylibre.com>
---
drivers/pmdomain/core.c | 160 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
include/linux/pm_domain.h | 16 ++++++++++++++++
2 files changed, 176 insertions(+)
diff --git a/drivers/pmdomain/core.c b/drivers/pmdomain/core.c
index bf82775f6a67..cee7fbbda829 100644
--- a/drivers/pmdomain/core.c
+++ b/drivers/pmdomain/core.c
@@ -3556,6 +3556,166 @@ static struct device_driver genpd_provider_drv = {
.suppress_bind_attrs = true,
};
+/**
+ * of_genpd_remove_subdomain_map - Remove subdomain relationships from map
+ *
+ * @np: pointer to parent node containing map property
+ * @data: pointer to PM domain onecell data
+ *
+ * Iterate over entries in a power-domain-map, and remove the subdomain
+ * relationships that were previously established by of_genpd_add_subdomain_map().
+ * This allows cleanup during driver removal or error handling.
+ *
+ * Return: 0 on success, negative error code on failure
+ */
+int of_genpd_remove_subdomain_map(struct device_node *np,
+ struct genpd_onecell_data *data)
+{
+ struct generic_pm_domain *genpd, *parent_genpd;
+ struct of_phandle_args child_args, parent_args;
+ int index = 0;
+ int ret = 0;
+ u32 child_index;
+
+ if (!np || !data)
+ return -EINVAL;
+
+ /* Iterate through power-domain-map entries using the OF helper */
+ while (!of_parse_map_iter(np, "power-domain", &index,
+ &child_args, &parent_args)) {
+ /* Extract the child domain index from the child specifier */
+ if (child_args.args_count < 1) {
+ of_node_put(parent_args.np);
+ continue;
+ }
+ child_index = child_args.args[0];
+
+ /* Validate child domain index */
+ if (child_index >= data->num_domains) {
+ of_node_put(parent_args.np);
+ continue;
+ }
+
+ genpd = data->domains[child_index];
+ if (!genpd) {
+ of_node_put(parent_args.np);
+ continue;
+ }
+
+ /* Get parent power domain from provider */
+ mutex_lock(&gpd_list_lock);
+
+ parent_genpd = genpd_get_from_provider(&parent_args);
+ if (IS_ERR(parent_genpd)) {
+ mutex_unlock(&gpd_list_lock);
+ of_node_put(parent_args.np);
+ dev_warn(&genpd->dev, "failed to get parent domain for removal\n");
+ continue;
+ }
+
+ /* Remove subdomain relationship */
+ ret = pm_genpd_remove_subdomain(parent_genpd, genpd);
+ mutex_unlock(&gpd_list_lock);
+ of_node_put(parent_args.np);
+
+ if (ret)
+ dev_warn(&genpd->dev, "failed to remove as subdomain of %s: %d\n",
+ parent_genpd->name, ret);
+ else
+ dev_dbg(&genpd->dev, "removed as subdomain of %s\n",
+ parent_genpd->name);
+ }
+
+ return 0;
+}
+EXPORT_SYMBOL_GPL(of_genpd_remove_subdomain_map);
+
+/**
+ * of_genpd_add_subdomain_map - Parse and map child PM domains
+ *
+ * @np: pointer to parent node containing map property
+ * @data: pointer to PM domain onecell data
+ *
+ * Iterate over entries in a power-domain-map, and add them as
+ * children of the parent domain. If any child fails to be added,
+ * all previously added children are removed to maintain atomicity.
+ *
+ * Return: 0 on success, negative error code on failure
+ */
+int of_genpd_add_subdomain_map(struct device_node *np,
+ struct genpd_onecell_data *data)
+{
+ struct generic_pm_domain *genpd, *parent_genpd;
+ struct of_phandle_args child_args, parent_args;
+ int index = 0;
+ int ret = 0;
+ u32 child_index;
+
+ if (!np || !data)
+ return -EINVAL;
+
+ /* Iterate through power-domain-map entries using the OF helper */
+ while (!of_parse_map_iter(np, "power-domain", &index,
+ &child_args, &parent_args)) {
+ /* Extract the child domain index from the child specifier */
+ if (child_args.args_count < 1) {
+ of_node_put(parent_args.np);
+ ret = -EINVAL;
+ goto cleanup;
+ }
+ child_index = child_args.args[0];
+
+ /* Validate child domain index */
+ if (child_index >= data->num_domains) {
+ of_node_put(parent_args.np);
+ pr_debug("map's child index (%u) > number of domains (%u). Skipping.\n",
+ child_index, data->num_domains);
+ ret = -EINVAL;
+ goto cleanup;
+ }
+
+ genpd = data->domains[child_index];
+ if (!genpd) {
+ of_node_put(parent_args.np);
+ continue;
+ }
+
+ /* Get parent power domain from provider and establish subdomain relationship */
+ mutex_lock(&gpd_list_lock);
+
+ parent_genpd = genpd_get_from_provider(&parent_args);
+ if (IS_ERR(parent_genpd)) {
+ mutex_unlock(&gpd_list_lock);
+ of_node_put(parent_args.np);
+ ret = PTR_ERR(parent_genpd);
+ dev_err(&genpd->dev, "failed to get parent domain: %d\n", ret);
+ goto cleanup;
+ }
+
+ ret = genpd_add_subdomain(parent_genpd, genpd);
+ mutex_unlock(&gpd_list_lock);
+ of_node_put(parent_args.np);
+
+ if (ret) {
+ dev_err(&genpd->dev, "failed to add as subdomain of %s: %d\n",
+ parent_genpd->name, ret);
+ goto cleanup;
+ }
+
+ dev_dbg(&genpd->dev, "added as subdomain of %s\n",
+ parent_genpd->name);
+ }
+
+ return 0;
+
+cleanup:
+ /* Remove all successfully added subdomains using the removal function */
+ pr_err("rolling back child map additions due to error: %d\n", ret);
+ of_genpd_remove_subdomain_map(np, data);
+ return ret;
+}
+EXPORT_SYMBOL_GPL(of_genpd_add_subdomain_map);
+
static int __init genpd_bus_init(void)
{
int ret;
diff --git a/include/linux/pm_domain.h b/include/linux/pm_domain.h
index 93ba0143ca47..3baf224e4f24 100644
--- a/include/linux/pm_domain.h
+++ b/include/linux/pm_domain.h
@@ -463,6 +463,10 @@ int of_genpd_add_subdomain(const struct of_phandle_args *parent_spec,
int of_genpd_remove_subdomain(const struct of_phandle_args *parent_spec,
const struct of_phandle_args *subdomain_spec);
struct generic_pm_domain *of_genpd_remove_last(struct device_node *np);
+int of_genpd_add_subdomain_map(struct device_node *np,
+ struct genpd_onecell_data *data);
+int of_genpd_remove_subdomain_map(struct device_node *np,
+ struct genpd_onecell_data *data);
int of_genpd_parse_idle_states(struct device_node *dn,
struct genpd_power_state **states, int *n);
void of_genpd_sync_state(struct device_node *np);
@@ -505,6 +509,18 @@ static inline int of_genpd_remove_subdomain(const struct of_phandle_args *parent
return -ENODEV;
}
+static inline int of_genpd_add_subdomain_map(struct device_node *np,
+ struct genpd_onecell_data *data)
+{
+ return -ENODEV;
+}
+
+static inline int of_genpd_remove_subdomain_map(struct device_node *np,
+ struct genpd_onecell_data *data)
+{
+ return -ENODEV;
+}
+
static inline int of_genpd_parse_idle_states(struct device_node *dn,
struct genpd_power_state **states, int *n)
{
--
2.51.0On Thu, Jan 22, 2026 at 05:14:00PM -0800, Kevin Hilman (TI) wrote:
> Add of_genpd_[add|remove]_subdomain_map() helper functions to support
> hierarchical PM domains defined by using power-domains-map
power-domain-map. No 's'.
> property (c.f. nexus node maps in DT spec, section 2.5.1).
>
> This enables PM domain providers with #power-domain-cells > 0 to
> establish subdomain relationships via the power-domain-map property,
> which was not previously possible.
>
> These new helper functions:
> - uses an OF helper to iterate to over entries in power-domain-map
> - For each mapped entry: extracts child specifier, resolves parent phandle,
> extracts parent specifier args, and establishes subdomain relationship
> - Calls genpd_[add|remove]_subdomain() with proper gpd_list_lock mutex protection
>
> Example from k3-am62l.dtsi:
>
> scmi_pds: protocol@11 {
> #power-domain-cells = <1>;
> power-domain-map = <15 &MAIN_PD>, /* TIMER0 */
> <19 &WKUP_PD>; /* WKUP_TIMER0 */
> };
>
> MAIN_PD: power-controller-main {
> #power-domain-cells = <0>;
> };
>
> WKUP_PD: power-controller-main {
> #power-domain-cells = <0>;
> };
>
> This allows SCMI power domain 15 to become a subdomain of MAIN_PD, and
> domain 19 to become a subdomain of WKUP_PD.
One concern I have here is generally *-map is transparent meaning when
you lookup <&scmi_pds 15>, &MAIN_PD is returned as the provider. It's
also possible to have a map point to another map until you get to the
final provider. The only way we have to support both behaviors is the
consumer has to specify (i.e. with of_parse_phandle_with_args_map() vs.
of_parse_phandle_with_args()), but the consumer shouldn't really know
this detail.
Maybe a transparent map of power-domains would never make sense. IDK. If
so, then there's not really any issue since the pmdomain core handles
everyone the same way.
Rob
Rob Herring <robh@kernel.org> writes:
> On Thu, Jan 22, 2026 at 05:14:00PM -0800, Kevin Hilman (TI) wrote:
>> Add of_genpd_[add|remove]_subdomain_map() helper functions to support
>> hierarchical PM domains defined by using power-domains-map
>
> power-domain-map. No 's'.
>
>> property (c.f. nexus node maps in DT spec, section 2.5.1).
>>
>> This enables PM domain providers with #power-domain-cells > 0 to
>> establish subdomain relationships via the power-domain-map property,
>> which was not previously possible.
>>
>> These new helper functions:
>> - uses an OF helper to iterate to over entries in power-domain-map
>> - For each mapped entry: extracts child specifier, resolves parent phandle,
>> extracts parent specifier args, and establishes subdomain relationship
>> - Calls genpd_[add|remove]_subdomain() with proper gpd_list_lock mutex protection
>>
>> Example from k3-am62l.dtsi:
>>
>> scmi_pds: protocol@11 {
>> #power-domain-cells = <1>;
>> power-domain-map = <15 &MAIN_PD>, /* TIMER0 */
>> <19 &WKUP_PD>; /* WKUP_TIMER0 */
>> };
>>
>> MAIN_PD: power-controller-main {
>> #power-domain-cells = <0>;
>> };
>>
>> WKUP_PD: power-controller-main {
>> #power-domain-cells = <0>;
>> };
>>
>> This allows SCMI power domain 15 to become a subdomain of MAIN_PD, and
>> domain 19 to become a subdomain of WKUP_PD.
>
> One concern I have here is generally *-map is transparent meaning when
> you lookup <&scmi_pds 15>, &MAIN_PD is returned as the provider. It's
> also possible to have a map point to another map until you get to the
> final provider. The only way we have to support both behaviors is the
> consumer has to specify (i.e. with of_parse_phandle_with_args_map() vs.
> of_parse_phandle_with_args()), but the consumer shouldn't really know
> this detail.
>
> Maybe a transparent map of power-domains would never make sense. IDK. If
> so, then there's not really any issue since the pmdomain core handles
> everyone the same way.
I don't really know enough about potential usage of maps to know if
there's ever a usecase for transparent maps. However, the problem I'm
trying to solve is less about transparent maps, and more about
describing hierarchy in a situation where "leaf" domains of the same
type (e.g. SCMI) can have different parent domains.
When I first proposed this[1], I didn't use a map, but you suggested I
try using a map[2]. So I'm not sure if I misunderstood what you
proposed, or if now that you see it implemented, you're second guessing if
the map is the right approach.
Kevin
[1] https://lore.kernel.org/r/20250528-pmdomain-hierarchy-onecell-v1-1-851780700c68@baylibre.com
[2] https://lore.kernel.org/r/20250528203532.GA704342-robh@kernel.org
© 2016 - 2026 Red Hat, Inc.