Skip to contentSkip to conversation

powercap: Introduce generic hierarchy helpers and selftests

PATCH In review Daniel Lezcano 4 participants 11 messages Aug 6 – Sep 23

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

cover powercap: Introduce generic hierarchy helpers and selftests

Powercap controllers frequently expose a hierarchy of power zones (for example package, clusters and CPUs). Until now, each driver had to implement its own hierarchy traversal, parent lookup, error handling and teardown logic.

This series introduces a generic hierarchy description and helper functions allowing a controller to instantiate and destroy an entire powercap hierarchy from a static description. The framework takes care of duplicating the hierarchy description, rebasing parent pointers, creating zones in dependency order and performing the appropriate rollback and cleanup on errors.

The series also adds a kselftest exercising the new API by creating a synthetic hierarchy, validating the exported sysfs hierarchy and attributes, and ensuring that all resources are correctly released when the hierarchy is destroyed.

The patches are organized as follows:

1. powercap: Add generic zone hierarchy creation helpers
2. selftests/powercap: Add powercap hierarchy creation API tests

The API was primarily motivated by the recently posted SPEL series and also provides a migration path for DTPM to use the same generic infrastructure instead of maintaining its own hierarchy handling.

Daniel Lezcano (2):
powercap: Add generic zone hierarchy creation helpers selftests/powercap: Add powercap hierarchy creation API tests

--
2.50.1

Daniel Lezcano (2):
powercap: Add generic zone hierarchy creation helpers selftests/powercap: Add powercap hierarchy creation API tests

 drivers/powercap/powercap_sys.c               | 148 +++++++++++
 include/linux/powercap.h                      | 178 +++++++++++++
 tools/testing/selftests/Makefile              |   1 +
 tools/testing/selftests/powercap/Kbuild       |   3 +
 tools/testing/selftests/powercap/Makefile     |  17 ++
 .../selftests/powercap/powercap_hierarchy.c   | 247 ++++++++++++++++++
 .../selftests/powercap/powercap_hierarchy.sh  | 118 +++++++++
 7 files changed, 712 insertions(+)
 create mode 100644 tools/testing/selftests/powercap/Kbuild
 create mode 100644 tools/testing/selftests/powercap/Makefile
 create mode 100644 tools/testing/selftests/powercap/powercap_hierarchy.c
 create mode 100755 tools/testing/selftests/powercap/powercap_hierarchy.sh
Signature · 1 line
2.53.0
#1 lore raw

PATCH 1/2 powercap: Add generic zone hierarchy creation helpers

Powercap controllers may need to create several powercap zones organized as a hierarchy. At present, each controller has to open-code the hierarchy traversal, parent lookup, error rollback and reverse-order destruction.

Introduce struct powercap_hierarchy to describe a powercap hierarchy. Each node contains its name, parent, backend-specific data and the powercap zone created for it.

For example, the following description:

  static struct powercap_node nodes[] = {
          { .name = "package" },
          { .name = "cpu", .parent = &nodes[0] },
          { .name = "gpu", .parent = &nodes[0] },

};

  static struct powercap_hierarchy hierarchy = {
          .nodes = nodes,
          .nr_nodes = ARRAY_SIZE(nodes),
  };

creates the following hierarchy:

package
|-- cpu
`-- gpu

Add powercap_hierarchy_dup() to create a runtime copy of a hierarchy description. Rebase the parent pointers so that the copy does not keep references to the original array, which may be stored in init memory.

Add powercap_hierarchy_create() to walk the description in order and create each zone through a controller-provided callback. The parent zone is passed to the callback, keeping the node creation operation specific to the controller.

The backend is responsible for allocating and registering each powercap zone from the creation callback. The powercap_zone object is expected to be embedded in a backend-specific structure, allowing the backend callbacks to retrieve their private data later using container_of().

For example:

  struct foo_powercap_zone {
          struct powercap_zone zone;
          struct foo_domain *domain;
  };

  foo_zone = kzalloc(sizeof(*foo_zone), GFP_KERNEL);
  if (!foo_zone)
          return ERR_PTR(-ENOMEM);

  foo_zone->domain = domain;

pcz = powercap_register_zone(&foo_zone->zone, pct, name, parent,

                               &foo_zone_ops, nr_constraints,
                               &foo_constraint_ops);

Its allocation, private state and lifetime remain under the control of the backend.

The creation callback therefore returns the same powercap_zone pointer that was passed to powercap_register_zone(). The hierarchy helper stores this pointer to provide it as the parent of subsequent nodes and to pass it back to the backend during hierarchy destruction.

Add powercap_hierarchy_destroy() to destroy the hierarchy in reverse order, ensuring that children are removed before their parents. Use the same mechanism to roll back previously created zones when the creation of a subsequent node fails.

Serialize creation and destruction of each hierarchy to prevent concurrent updates of the powercap zone pointers stored in its runtime copy.

This provides a common mechanism for creating controller-defined powercap hierarchies while keeping controller-specific operations outside the powercap core.

Cc Manaf Meethalavalappu Pallikunhi <[email protected]>
---
 drivers/powercap/powercap_sys.c | 148 ++++++++++++++++++++++++++
 include/linux/powercap.h        | 178 ++++++++++++++++++++++++++++++++
 2 files changed, 326 insertions(+)
drivers/powercap/powercap_sys.c +148 -0
index 9197fa20d93f..fefb36c5bcd2 100644
@@ -667,6 +667,154 @@ int powercap_unregister_control_type(struct powercap_control_type *control_type)
 }
 EXPORT_SYMBOL_GPL(powercap_unregister_control_type);
 
+struct powercap_hierarchy *
+powercap_hierarchy_dup(const struct powercap_hierarchy *hierarchy)
+{
+	struct powercap_hierarchy *copy;
+	size_t i;
+
+	if (!hierarchy || !hierarchy->nodes || !hierarchy->nr_nodes)
+		return ERR_PTR(-EINVAL);
+
+	copy = kzalloc_obj(*copy);
+	if (!copy)
+		return ERR_PTR(-ENOMEM);
+
+	/*
+	 * The source node array may live in init memory. A shallow copy would
+	 * leave parent pointers referencing that array after it has been freed.
+	 * Copy the nodes now and rebase their parent pointers below. The name
+	 * and data objects remain owned by the backend and are not duplicated.
+	 */
+	copy->nodes = kmemdup_array(hierarchy->nodes, hierarchy->nr_nodes,
+				    sizeof(*copy->nodes), GFP_KERNEL);
+	if (!copy->nodes) {
+		kfree(copy);
+		return ERR_PTR(-ENOMEM);
+	}
+
+	copy->nr_nodes = hierarchy->nr_nodes;
+	mutex_init(&copy->lock);
+
+	for (i = 0; i < copy->nr_nodes; i++) {
+		const struct powercap_node *parent = hierarchy->nodes[i].parent;
+		ptrdiff_t index;
+
+		copy->nodes[i].pcz = NULL;
+
+		if (!copy->nodes[i].name)
+			goto invalid;
+
+		if (!parent)
+			continue;
+
+		index = parent - hierarchy->nodes;
+		if (index < 0 || index >= i)
+			goto invalid;
+
+		copy->nodes[i].parent = &copy->nodes[index];
+	}
+
+	return copy;
+
+invalid:
+	mutex_destroy(&copy->lock);
+	kfree(copy->nodes);
+	kfree(copy);
+
+	return ERR_PTR(-EINVAL);
+}
+EXPORT_SYMBOL_GPL(powercap_hierarchy_dup);
+
+void powercap_hierarchy_free(struct powercap_hierarchy *hierarchy)
+{
+	if (!hierarchy)
+		return;
+
+	mutex_destroy(&hierarchy->lock);
+	kfree(hierarchy->nodes);
+	kfree(hierarchy);
+}
+EXPORT_SYMBOL_GPL(powercap_hierarchy_free);
+
+static void __powercap_hierarchy_destroy(struct powercap_control_type *pct,
+					 struct powercap_hierarchy *hierarchy,
+					 powercap_node_destroy_t powercap_node_destroy)
+{
+	size_t i;
+
+	for (i = hierarchy->nr_nodes; i-- > 0;) {
+		if (!hierarchy->nodes[i].pcz)
+			continue;
+
+		powercap_node_destroy(pct, hierarchy->nodes[i].pcz,
+				      hierarchy->nodes[i].data);
+
+		hierarchy->nodes[i].pcz = NULL;
+	}
+}
+
+int powercap_hierarchy_destroy(struct powercap_control_type *pct,
+			       struct powercap_hierarchy *hierarchy,
+			       powercap_node_destroy_t powercap_node_destroy)
+{
+	if (!pct || !hierarchy || !hierarchy->nodes ||
+	    !hierarchy->nr_nodes || !powercap_node_destroy)
+		return -EINVAL;
+
+	guard(mutex)(&hierarchy->lock);
+
+	__powercap_hierarchy_destroy(pct, hierarchy, powercap_node_destroy);
+
+	return 0;
+}
+EXPORT_SYMBOL_GPL(powercap_hierarchy_destroy);
+
+int powercap_hierarchy_create(struct powercap_control_type *pct,
+			      struct powercap_hierarchy *hierarchy,
+			      powercap_node_create_t powercap_node_create,
+			      powercap_node_destroy_t powercap_node_destroy)
+{
+	struct powercap_zone *pcz;
+	int ret;
+	size_t i;
+
+	if (!pct || !hierarchy || !hierarchy->nodes || !hierarchy->nr_nodes ||
+	    !powercap_node_create || !powercap_node_destroy)
+		return -EINVAL;
+
+	guard(mutex)(&hierarchy->lock);
+
+	for (i = 0; i < hierarchy->nr_nodes; i++) {
+		struct powercap_zone *parent = NULL;
+
+		if (hierarchy->nodes[i].parent) {
+			parent = hierarchy->nodes[i].parent->pcz;
+			if (!parent) {
+				ret = -EINVAL;
+				goto rollback;
+			}
+		}
+
+		pcz = powercap_node_create(pct, hierarchy->nodes[i].name,
+					   hierarchy->nodes[i].data, parent);
+		if (IS_ERR_OR_NULL(pcz)) {
+			ret = pcz ? PTR_ERR(pcz) : -EINVAL;
+			goto rollback;
+		}
+
+		hierarchy->nodes[i].pcz = pcz;
+	}
+
+	return 0;
+
+rollback:
+	__powercap_hierarchy_destroy(pct, hierarchy, powercap_node_destroy);
+
+	return ret;
+}
+EXPORT_SYMBOL_GPL(powercap_hierarchy_create);
+
 static int __init powercap_init(void)
 {
 	int result;
include/linux/powercap.h +178 -0

188 lines not on this page · raw message

Signature · 1 line
2.53.0
#2 lore raw

PATCH 2/2 selftests/powercap: Add powercap hierarchy creation API tests

In reply to Daniel Lezcano

The powercap hierarchy API introduces generic helpers to duplicate, instantiate and destroy a complete powercap hierarchy from a static description.

Add a kselftest exercising this API. The test builds a synthetic powercap hierarchy composed of a package, three CPU clusters and twelve CPUs, registers it as a powercap control type and verifies that the expected sysfs hierarchy and attributes are created. It also validates that the hierarchy is correctly removed when the module is unloaded.

The test consists of:

* a kernel module implementing a synthetic powercap hierarchy and dummy callbacks;
* a userspace kselftest script that loads the module, validates the exported sysfs hierarchy and attribute values, unloads the module and verifies that all objects have been removed.

This provides a regression test for the powercap hierarchy helpers and their integration with the powercap core.

Cc Manaf Meethalavalappu Pallikunhi <[email protected]>
---
 tools/testing/selftests/Makefile              |   1 +
 tools/testing/selftests/powercap/Kbuild       |   3 +
 tools/testing/selftests/powercap/Makefile     |  17 ++
 .../selftests/powercap/powercap_hierarchy.c   | 247 ++++++++++++++++++
 .../selftests/powercap/powercap_hierarchy.sh  | 118 +++++++++
 5 files changed, 386 insertions(+)
 create mode 100644 tools/testing/selftests/powercap/Kbuild
 create mode 100644 tools/testing/selftests/powercap/Makefile
 create mode 100644 tools/testing/selftests/powercap/powercap_hierarchy.c
 create mode 100755 tools/testing/selftests/powercap/powercap_hierarchy.sh
tools/testing/selftests/Makefile +1 -0
index 8d4db2241cc2..2fac671e9145 100644
@@ -93,6 +93,7 @@ TARGETS += pidfd
 TARGETS += pid_namespace
 TARGETS += pipe
 TARGETS += power_supply
+TARGETS += powercap
 TARGETS += powerpc
 TARGETS += prctl
 TARGETS += proc
tools/testing/selftests/powercap/Kbuild new file +3 -0
new file mode 100644
index 000000000000..baa0d0ba9593
@@ -0,0 +1,3 @@
+# SPDX-License-Identifier: GPL-2.0
+
+obj-m += powercap_hierarchy.o
\ No newline at end of file
tools/testing/selftests/powercap/Makefile new file +17 -0
new file mode 100644
index 000000000000..210d6e6c5577
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: GPL-2.0
+
+# User-space test script
+TEST_PROGS := powercap_hierarchy.sh
+
+# Kernel module built as part of the test
+TEST_FILES := powercap_hierarchy.ko
+
+KDIR ?= $(if $(O),$(O),$(realpath ../../../..))
+
+all:
+	$(MAKE) -C $(KDIR) M=$(CURDIR) modules
+
+clean:
+	$(MAKE) -C $(KDIR) M=$(CURDIR) clean
+
+include ../lib.mk
tools/testing/selftests/powercap/powercap_hierarchy.c new file +247 -0

247 lines not on this page · raw message

tools/testing/selftests/powercap/powercap_hierarchy.sh new file +118 -0

118 lines not on this page · raw message

Signature · 1 line
2.53.0
#3 lore raw
In reply to Daniel Lezcano

Hi Rafael,

Quoted 26 lines · Daniel Lezcano

Powercap controllers frequently expose a hierarchy of power zones (for example package, clusters and CPUs). Until now, each driver had to implement its own hierarchy traversal, parent lookup, error handling and teardown logic.

This series introduces a generic hierarchy description and helper functions allowing a controller to instantiate and destroy an entire powercap hierarchy from a static description. The framework takes care of duplicating the hierarchy description, rebasing parent pointers, creating zones in dependency order and performing the appropriate rollback and cleanup on errors.

The series also adds a kselftest exercising the new API by creating a synthetic hierarchy, validating the exported sysfs hierarchy and attributes, and ensuring that all resources are correctly released when the hierarchy is destroyed.

The patches are organized as follows:

1. powercap: Add generic zone hierarchy creation helpers
2. selftests/powercap: Add powercap hierarchy creation API tests

The API was primarily motivated by the recently posted SPEL series and also provides a migration path for DTPM to use the same generic infrastructure instead of maintaining its own hierarchy handling.

Quoted 7 lines

Daniel Lezcano (2):
powercap: Add generic zone hierarchy creation helpers selftests/powercap: Add powercap hierarchy creation API tests

--

It was easy to migrate DTPM to this API and AFAICT Manaf was able to migrate also its series to this new API.

Is it possible to consider it for merging ?

Thanks

-- Daniel

[1] https://lore.kernel.org/all/[email protected]/

[2] https://lore.kernel.org/all/20260702-qcom_spel_driver_upstream-v3-0-434d50f0c5b0@oss.qualcomm.com/

#4 lore raw

Hi Daniel,

Quoted 32 lines · Daniel Lezcano

Hi Rafael,

Quoted 28 lines · Daniel Lezcano

Powercap controllers frequently expose a hierarchy of power zones (for example package, clusters and CPUs). Until now, each driver had to implement its own hierarchy traversal, parent lookup, error handling and teardown logic.

This series introduces a generic hierarchy description and helper functions allowing a controller to instantiate and destroy an entire powercap hierarchy from a static description. The framework takes care of duplicating the hierarchy description, rebasing parent pointers, creating zones in dependency order and performing the appropriate rollback and cleanup on errors.

The series also adds a kselftest exercising the new API by creating a synthetic hierarchy, validating the exported sysfs hierarchy and attributes, and ensuring that all resources are correctly released when the hierarchy is destroyed.

The patches are organized as follows:

1. powercap: Add generic zone hierarchy creation helpers
2. selftests/powercap: Add powercap hierarchy creation API tests

The API was primarily motivated by the recently posted SPEL series and also provides a migration path for DTPM to use the same generic infrastructure instead of maintaining its own hierarchy handling.

Quoted 8 lines
Quoted 5 lines

Daniel Lezcano (2):
powercap: Add generic zone hierarchy creation helpers selftests/powercap: Add powercap hierarchy creation API tests

It was easy to migrate DTPM to this API and AFAICT Manaf was able to migrate also its series to this new API.

Is it possible to consider it for merging ?

I will do a review for this patch set today...

I can see some potential improvements there.

Regards,
Lukasz

#5 lore raw

Hi,

Quoted 39 lines · Lukasz Luba

Hi Daniel,

Quoted 36 lines · Daniel Lezcano

Hi Rafael,

Quoted 32 lines · Daniel Lezcano

Powercap controllers frequently expose a hierarchy of power zones (for example package, clusters and CPUs). Until now, each driver had to implement its own hierarchy traversal, parent lookup, error handling and teardown logic.

This series introduces a generic hierarchy description and helper functions allowing a controller to instantiate and destroy an entire powercap hierarchy from a static description. The framework takes care of duplicating the hierarchy description, rebasing parent pointers, creating zones in dependency order and performing the appropriate rollback and cleanup on errors.

The series also adds a kselftest exercising the new API by creating a synthetic hierarchy, validating the exported sysfs hierarchy and attributes, and ensuring that all resources are correctly released when the hierarchy is destroyed.

The patches are organized as follows:

1. powercap: Add generic zone hierarchy creation helpers
2. selftests/powercap: Add powercap hierarchy creation API tests

The API was primarily motivated by the recently posted SPEL series and also provides a migration path for DTPM to use the same generic infrastructure instead of maintaining its own hierarchy handling.

Daniel Lezcano (2):
powercap: Add generic zone hierarchy creation helpers selftests/powercap: Add powercap hierarchy creation API tests

Quoted 8 lines
Quoted 4 lines
Quoted 1 line

It was easy to migrate DTPM to this API and AFAICT Manaf was able to migrate also its series to this new API.

Is it possible to consider it for merging ?

I will do a review for this patch set today...

I can see some potential improvements there.

This patch is a blocker for more changes: DTPM, powercap cooling device and SPEL drivers from Manaf.

It has been tested and there is a selftest with. Is it possible to consider these two patches for merging.

Given it is not a fast path, improvements can be proposed later.

#6 lore raw

Hi,

On 9/15/26 12:54, Daniel Lezcano wrote:

[ ... ]

Quoted 6 lines
Quoted 1 line

I can see some potential improvements there.

This patch is a blocker for more changes: DTPM, powercap cooling device and SPEL drivers from Manaf.

It has been tested and there is a selftest with. Is it possible to consider these two patches for merging.

Given it is not a fast path, improvements can be proposed later.

Given that there has been no feedback so far, would it be possible to consider merging these two patches? They are currently blocking further work.

There is also a selftest covering this functionality, so future changes can be made with regression testing in place.

#7 lore raw

Hi Daniel,

Quoted 18 lines · Daniel Lezcano

Hi,

On 9/15/26 12:54, Daniel Lezcano wrote:

[ ... ]

Quoted 8 lines
Quoted 1 line

I can see some potential improvements there.

This patch is a blocker for more changes: DTPM, powercap cooling device and SPEL drivers from Manaf.

It has been tested and there is a selftest with. Is it possible to consider these two patches for merging.

Given it is not a fast path, improvements can be proposed later.

Quoted 6 lines

Given that there has been no feedback so far, would it be possible to consider merging these two patches? They are currently blocking further work.

There is also a selftest covering this functionality, so future changes can be made with regression testing in place.

I'd prefer to handle this along with

https://lore.kernel.org/linux-pm/[email protected]/

which appears to be the only user of it.

I thought that Lukasz would send comments on those, but in the absence of his comments, it would help if you combined those two patch series into one and resend.

Thanks!

#8 lore raw
Quoted 31 lines · Rafael J. Wysocki (Intel)

Hi Daniel,

Quoted 18 lines · Daniel Lezcano

Hi,

On 9/15/26 12:54, Daniel Lezcano wrote:

[ ... ]

Quoted 8 lines
Quoted 1 line

I can see some potential improvements there.

This patch is a blocker for more changes: DTPM, powercap cooling device and SPEL drivers from Manaf.

It has been tested and there is a selftest with. Is it possible to consider these two patches for merging.

Given it is not a fast path, improvements can be proposed later.

Quoted 6 lines

Given that there has been no feedback so far, would it be possible to consider merging these two patches? They are currently blocking further work.

There is also a selftest covering this functionality, so future changes can be made with regression testing in place.

I'd prefer to handle this along with

Quoted 7 lines

https://lore.kernel.org/linux-pm/[email protected]/

which appears to be the only user of it.

I thought that Lukasz would send comments on those, but in the absence of his comments, it would help if you combined those two patch series into one and resend.

Sure, will do

#9 lore raw
In reply to Daniel Lezcano

Hi Daniel,

Quoted 30 lines · Daniel Lezcano

Hi Rafael,

Quoted 26 lines · Daniel Lezcano

Powercap controllers frequently expose a hierarchy of power zones (for example package, clusters and CPUs). Until now, each driver had to implement its own hierarchy traversal, parent lookup, error handling and teardown logic.

This series introduces a generic hierarchy description and helper functions allowing a controller to instantiate and destroy an entire powercap hierarchy from a static description. The framework takes care of duplicating the hierarchy description, rebasing parent pointers, creating zones in dependency order and performing the appropriate rollback and cleanup on errors.

The series also adds a kselftest exercising the new API by creating a synthetic hierarchy, validating the exported sysfs hierarchy and attributes, and ensuring that all resources are correctly released when the hierarchy is destroyed.

The patches are organized as follows:

1. powercap: Add generic zone hierarchy creation helpers
2. selftests/powercap: Add powercap hierarchy creation API tests

The API was primarily motivated by the recently posted SPEL series and also provides a migration path for DTPM to use the same generic infrastructure instead of maintaining its own hierarchy handling.

Quoted 8 lines
Quoted 7 lines

Daniel Lezcano (2):
powercap: Add generic zone hierarchy creation helpers selftests/powercap: Add powercap hierarchy creation API tests

It was easy to migrate DTPM to this API and AFAICT Manaf was able to migrate also its series to this new API.

Yes, I rebased my Qualcomm SPEL powercap driver series on top of this patch and migrated the series without any issues.
These APIs significantly simplify the driver code for creating and managing the powercap hierarchy.

Thanks,
Manaf

Quoted 10 lines

Is it possible to consider it for merging ?

Thanks

  -- Daniel

[1] https://lore.kernel.org/all/20260819165605.1398880-1- [email protected]/

[2] https://lore.kernel.org/all/20260702-qcom_spel_driver_upstream- [email protected]/

#10 lore raw

Le 11/09/2026 à 17:44, Manaf Meethalavalappu Pallikunhi a écrit :

Quoted 40 lines

Hi Daniel,

Quoted 37 lines · Daniel Lezcano

Hi Rafael,

Quoted 33 lines · Daniel Lezcano

Powercap controllers frequently expose a hierarchy of power zones (for example package, clusters and CPUs). Until now, each driver had to implement its own hierarchy traversal, parent lookup, error handling and teardown logic.

This series introduces a generic hierarchy description and helper functions allowing a controller to instantiate and destroy an entire powercap hierarchy from a static description. The framework takes care of duplicating the hierarchy description, rebasing parent pointers, creating zones in dependency order and performing the appropriate rollback and cleanup on errors.

The series also adds a kselftest exercising the new API by creating a synthetic hierarchy, validating the exported sysfs hierarchy and attributes, and ensuring that all resources are correctly released when the hierarchy is destroyed.

The patches are organized as follows:

1. powercap: Add generic zone hierarchy creation helpers
2. selftests/powercap: Add powercap hierarchy creation API tests

The API was primarily motivated by the recently posted SPEL series and also provides a migration path for DTPM to use the same generic infrastructure instead of maintaining its own hierarchy handling.

Daniel Lezcano (2):
powercap: Add generic zone hierarchy creation helpers selftests/powercap: Add powercap hierarchy creation API tests

Quoted 8 lines
Quoted 1 line

It was easy to migrate DTPM to this API and AFAICT Manaf was able to migrate also its series to this new API.

Yes, I rebased my Qualcomm SPEL powercap driver series on top of this patch and migrated the series without any issues.
These APIs significantly simplify the driver code for creating and managing the powercap hierarchy.

Great! Thanks Manaf