[PATCH v3 0/4] Add SWIG Bindings to libcpupower

[PATCH v3 0/4] Add SWIG Bindings to libcpupower

[John B. Wyatt IV]

SWIG is a tool packaged in Fedora and other distros that can generate
bindings from C and C++ code for several languages including Python,
Perl, and Go. Providing bindings for scripting languages is a common feature
to make use of libraries more accessible to more users and programs. My team
specifically wants to expand the features of rteval. rteval is a Python program
used to measure real time performance. We wanted to test the effect of enabling
some levels of idle-stat to see how it affects latency, and didn't want to
reinvent the wheel. Since SWIG requires the .o files created by libcpupower at
compilation it makes sense to include this in the cpupower directory so that
others can make use of them.

The V3 of this patchset includes:
* renaming header messages as requested and adding people to Cc as
requested
* moving the stub (dummy) commit to the front of the patchset
* small punctuation fixes

The V2 of this patchset includes:
* the full definition of libcpupower headers that is needed for the bindings
* dummy implementation in C of a function listed in the header of libcpupower
(requested by Shuah Khan)
* test_raw_pylibcpupower.py demonstrates an example of using the bindings
* adding myself and John Kacur to the cpupower section of the maintainers file
(requested by Shuah Khan)
* addressed review comments about doc, makefile, and maintainers file
* small style and other fixes

The name raw_pylibcpupower is used because a wrapper `pylibcpupower` may be
needed to make the bindings more 'pythonic' in the future. The bindings folder
is used because Go or Perl bindings may be useful for other users in the
future.

Note that while SWIG itself is GPL v3+ licensed; the resulting output, the
bindings code, has the same license as the .o files used to generate the
bindings (GPL v2 only). Please see
https://swig.org/legal.html
and
https://lore.kernel.org/linux-pm/Zqv9BOjxLAgyNP5B@hatbackup/#t
for more details on the license.

Sincerely,
John Wyatt
Software Engineer, Core Kernel
Red Hat

John B. Wyatt IV (4):
  pm:cpupower: Add missing powercap_set_enabled() stub function
  pm:cpupower: Add SWIG bindings files for libcpupower
  pm:cpupower: Include test_raw_pylibcpupower.py
  MAINTAINERS: Add Maintainers for SWIG Python bindings

 MAINTAINERS                                   |   3 +
 .../power/cpupower/bindings/python/.gitignore |   8 +
 tools/power/cpupower/bindings/python/Makefile |  31 +++
 tools/power/cpupower/bindings/python/README   |  59 +++++
 .../bindings/python/raw_pylibcpupower.i       | 247 ++++++++++++++++++
 .../bindings/python/test_raw_pylibcpupower.py |  42 +++
 tools/power/cpupower/lib/powercap.c           |   8 +
 7 files changed, 398 insertions(+)
 create mode 100644 tools/power/cpupower/bindings/python/.gitignore
 create mode 100644 tools/power/cpupower/bindings/python/Makefile
 create mode 100644 tools/power/cpupower/bindings/python/README
 create mode 100644 tools/power/cpupower/bindings/python/raw_pylibcpupower.i
 create mode 100755 tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py

-- 
2.46.0

[PATCH v3 1/4] pm:cpupower: Add missing powercap_set_enabled() stub function

[John B. Wyatt IV]

There was a symbol listed in the powercap.h file that was not implemented.
Implement it with a stub return of 0.

Programs like SWIG require that functions that are defined in the
headers be implemented.

Suggested-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: John B. Wyatt IV <jwyatt@redhat.com>
Signed-off-by: John B. Wyatt IV <sageofredondo@gmail.com>
---

Changes in v3:
	- Renamed commit header, moved commit to be the first in the
	  patchset as requested by Shuah Khan. Adjusted commit message
	  body to match.
	- Added pm:cpupower prefix to header and Rafael to Cc

Changes in v2:
	- Implemented the function so SWIG will accept the header
	  definition
---
 tools/power/cpupower/lib/powercap.c | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/tools/power/cpupower/lib/powercap.c b/tools/power/cpupower/lib/powercap.c
index a7a59c6bacda..94a0c69e55ef 100644
--- a/tools/power/cpupower/lib/powercap.c
+++ b/tools/power/cpupower/lib/powercap.c
@@ -77,6 +77,14 @@ int powercap_get_enabled(int *mode)
 	return sysfs_get_enabled(path, mode);
 }
 
+/*
+ * TODO: implement function. Returns dummy 0 for now.
+ */
+int powercap_set_enabled(int mode)
+{
+	return 0;
+}
+
 /*
  * Hardcoded, because rapl is the only powercap implementation
 - * this needs to get more generic if more powercap implementations
-- 
2.46.0

[PATCH v3 2/4] pm:cpupower: Add SWIG bindings files for libcpupower

[John B. Wyatt IV]

SWIG is a tool packaged in Fedora and other distros that can generate
bindings from C and C++ code for several languages including Python,
Perl, and Go.

These bindings allows users to easily write scripts that use and extend
libcpupower's functionality. Currently, only Python is provided in the
makefile, but additional languages may be added if there is demand.

Added suggestions from Shuah Khan for the README and license discussion.

Note that while SWIG itself is GPL v3+ licensed; the resulting output,
the bindings code, is permissively licensed + the license of the .o
files. Please see
https://swig.org/legal.html and [1] for more details.

[1]
https://lore.kernel.org/linux-pm/Zqv9BOjxLAgyNP5B@hatbackup/

Suggested-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: John B. Wyatt IV <jwyatt@redhat.com>
Signed-off-by: John B. Wyatt IV <sageofredondo@gmail.com>
---

Changes in v3:
	- Reordered patch series for cpupower stub implementation to be
	  first.
	- Added pm:cpupower prefix to header and Rafael to Cc.

Changes in v2:
	- Implemented the function so SWIG will accept the header
	  definition
---
 .../power/cpupower/bindings/python/.gitignore |   8 +
 tools/power/cpupower/bindings/python/Makefile |  31 +++
 tools/power/cpupower/bindings/python/README   |  59 +++++
 .../bindings/python/raw_pylibcpupower.i       | 247 ++++++++++++++++++
 4 files changed, 345 insertions(+)
 create mode 100644 tools/power/cpupower/bindings/python/.gitignore
 create mode 100644 tools/power/cpupower/bindings/python/Makefile
 create mode 100644 tools/power/cpupower/bindings/python/README
 create mode 100644 tools/power/cpupower/bindings/python/raw_pylibcpupower.i

diff --git a/tools/power/cpupower/bindings/python/.gitignore b/tools/power/cpupower/bindings/python/.gitignore
new file mode 100644
index 000000000000..5c9a1f0212dd
--- /dev/null
+++ b/tools/power/cpupower/bindings/python/.gitignore
@@ -0,0 +1,8 @@
+__pycache__/
+raw_pylibcpupower_wrap.c
+*.o
+*.so
+*.py
+!test_raw_pylibcpupower.py
+# git keeps ignoring this file, use git add -f raw_libcpupower.i
+!raw_pylibcpupower.i
diff --git a/tools/power/cpupower/bindings/python/Makefile b/tools/power/cpupower/bindings/python/Makefile
new file mode 100644
index 000000000000..d0418f902795
--- /dev/null
+++ b/tools/power/cpupower/bindings/python/Makefile
@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: GPL-2.0-only
+# Makefile for libcpupower's Python bindings
+#
+# This Makefile expects you have already run the makefile for cpupower to build
+# the .o files in the lib directory for the bindings to be created.
+
+CC=gcc
+
+LIB_DIR = ../../lib
+BIND_DIR = .
+PY_INCLUDE := $(firstword $(shell python-config --includes))
+#PY_INCLUDE = $(shell python-config --includes | awk '{ print $1 }')
+
+OBJECTS_LIB = $(wildcard $(LIB_DIR)/*.o)
+OBJECTS_BIND = $(wildcard $(BIND_DIR)/*.o)
+
+all: _raw_pylibcpupower.so
+
+_raw_pylibcpupower.so: raw_pylibcpupower_wrap.o
+	$(CC) -shared $(OBJECTS_LIB) raw_pylibcpupower_wrap.o -o _raw_pylibcpupower.so # raw_pylibcpupower_wrap.o
+#	$(CC) -shared $(OBJECTS_BIND) $(OBJECTS_LIB) -o _raw_pylibcpupower.so # raw_pylibcpupower_wrap.o
+
+raw_pylibcpupower_wrap.o: raw_pylibcpupower_wrap.c
+	$(CC) -fPIC -c raw_pylibcpupower_wrap.c $(PY_INCLUDE)
+
+raw_pylibcpupower_wrap.c: raw_pylibcpupower.i
+	swig -python raw_pylibcpupower.i
+
+# Will only clean the bindings folder; will not clean the actual cpupower folder
+clean:
+	rm -f raw_pylibcpupower.py raw_pylibcpupower_wrap.c raw_pylibcpupower_wrap.o _raw_pylibcpupower.so
diff --git a/tools/power/cpupower/bindings/python/README b/tools/power/cpupower/bindings/python/README
new file mode 100644
index 000000000000..0a4bb2581e8a
--- /dev/null
+++ b/tools/power/cpupower/bindings/python/README
@@ -0,0 +1,59 @@
+This folder contains the necessary files to build the Python bindings for
+libcpupower (aside from the libcpupower object files).
+
+
+requirements
+------------
+
+* You need the object files in the libcpupower directory compiled by
+cpupower's makefile.
+* The SWIG program must be installed.
+* The Python's development libraries installed.
+
+Please check that your version of SWIG is compatible with the version of Python
+installed on your machine by checking the SWIG changelog on their website.
+https://swig.org/
+
+Note that while SWIG itself is GPL v3+ licensed; the resulting output,
+the bindings code: is permissively licensed + the license of libcpupower's .o
+files. For these bindings that means GPL v2.
+
+Please see https://swig.org/legal.html and the discussion [1] for more details.
+
+[1]
+https://lore.kernel.org/linux-pm/Zqv9BOjxLAgyNP5B@hatbackup/
+
+
+build
+-----
+
+Install SWIG and the Python development files provided by your distribution.
+
+Build the object files for libcpupower by running make in the cpupower
+directory.
+
+Return to the directory this README is in to run:
+
+$ make
+
+
+testing
+-------
+
+Please verify the _raw_pylibcpupower.so and raw_pylibcpupower.py files have
+been created.
+
+To run the test script:
+
+$ python test_raw_pylibcpupower.py
+
+
+credits
+-------
+
+Original Bindings Author:
+John B. Wyatt IV
+jwyatt@redhat.com
+sageofredondo@gmail.com
+
+Copyright (C) 2024 Red Hat
diff --git a/tools/power/cpupower/bindings/python/raw_pylibcpupower.i b/tools/power/cpupower/bindings/python/raw_pylibcpupower.i
new file mode 100644
index 000000000000..96556d87a745
--- /dev/null
+++ b/tools/power/cpupower/bindings/python/raw_pylibcpupower.i
@@ -0,0 +1,247 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+
+%module raw_pylibcpupower
+%{
+#include "../../lib/cpupower_intern.h"
+#include "../../lib/acpi_cppc.h"
+#include "../../lib/cpufreq.h"
+#include "../../lib/cpuidle.h"
+#include "../../lib/cpupower.h"
+#include "../../lib/powercap.h"
+%}
+
+/*
+ * cpupower_intern.h
+ */
+
+#define PATH_TO_CPU "/sys/devices/system/cpu/"
+#define MAX_LINE_LEN 4096
+#define SYSFS_PATH_MAX 255
+
+int is_valid_path(const char *path);
+
+unsigned int cpupower_read_sysfs(const char *path, char *buf, size_t buflen);
+
+unsigned int cpupower_write_sysfs(const char *path, char *buf, size_t buflen);
+
+/*
+ * acpi_cppc.h
+ */
+
+enum acpi_cppc_value {
+	HIGHEST_PERF,
+	LOWEST_PERF,
+	NOMINAL_PERF,
+	LOWEST_NONLINEAR_PERF,
+	LOWEST_FREQ,
+	NOMINAL_FREQ,
+	REFERENCE_PERF,
+	WRAPAROUND_TIME,
+	MAX_CPPC_VALUE_FILES
+};
+
+unsigned long acpi_cppc_get_data(unsigned int cpu,
+				 enum acpi_cppc_value which);
+
+/*
+ * cpufreq.h
+ */
+
+struct cpufreq_policy {
+	unsigned long min;
+	unsigned long max;
+	char *governor;
+};
+
+struct cpufreq_available_governors {
+	char *governor;
+	struct cpufreq_available_governors *next;
+	struct cpufreq_available_governors *first;
+};
+
+struct cpufreq_available_frequencies {
+	unsigned long frequency;
+	struct cpufreq_available_frequencies *next;
+	struct cpufreq_available_frequencies *first;
+};
+
+
+struct cpufreq_affected_cpus {
+	unsigned int cpu;
+	struct cpufreq_affected_cpus *next;
+	struct cpufreq_affected_cpus *first;
+};
+
+struct cpufreq_stats {
+	unsigned long frequency;
+	unsigned long long time_in_state;
+	struct cpufreq_stats *next;
+	struct cpufreq_stats *first;
+};
+
+unsigned long cpufreq_get_freq_kernel(unsigned int cpu);
+
+unsigned long cpufreq_get_freq_hardware(unsigned int cpu);
+
+#define cpufreq_get(cpu) cpufreq_get_freq_kernel(cpu);
+
+unsigned long cpufreq_get_transition_latency(unsigned int cpu);
+
+int cpufreq_get_hardware_limits(unsigned int cpu,
+				unsigned long *min,
+				unsigned long *max);
+
+char *cpufreq_get_driver(unsigned int cpu);
+
+void cpufreq_put_driver(char *ptr);
+
+struct cpufreq_policy *cpufreq_get_policy(unsigned int cpu);
+
+void cpufreq_put_policy(struct cpufreq_policy *policy);
+
+struct cpufreq_available_governors
+*cpufreq_get_available_governors(unsigned int cpu);
+
+void cpufreq_put_available_governors(
+	struct cpufreq_available_governors *first);
+
+struct cpufreq_available_frequencies
+*cpufreq_get_available_frequencies(unsigned int cpu);
+
+void cpufreq_put_available_frequencies(
+		struct cpufreq_available_frequencies *first);
+
+struct cpufreq_available_frequencies
+*cpufreq_get_boost_frequencies(unsigned int cpu);
+
+void cpufreq_put_boost_frequencies(
+		struct cpufreq_available_frequencies *first);
+
+struct cpufreq_affected_cpus *cpufreq_get_affected_cpus(unsigned
+							int cpu);
+
+void cpufreq_put_affected_cpus(struct cpufreq_affected_cpus *first);
+
+struct cpufreq_affected_cpus *cpufreq_get_related_cpus(unsigned
+							int cpu);
+
+void cpufreq_put_related_cpus(struct cpufreq_affected_cpus *first);
+
+struct cpufreq_stats *cpufreq_get_stats(unsigned int cpu,
+					unsigned long long *total_time);
+
+void cpufreq_put_stats(struct cpufreq_stats *stats);
+
+unsigned long cpufreq_get_transitions(unsigned int cpu);
+
+int cpufreq_set_policy(unsigned int cpu, struct cpufreq_policy *policy);
+
+int cpufreq_modify_policy_min(unsigned int cpu, unsigned long min_freq);
+
+int cpufreq_modify_policy_max(unsigned int cpu, unsigned long max_freq);
+
+int cpufreq_modify_policy_governor(unsigned int cpu, char *governor);
+
+int cpufreq_set_frequency(unsigned int cpu,
+				unsigned long target_frequency);
+
+unsigned long cpufreq_get_sysfs_value_from_table(unsigned int cpu,
+						 const char **table,
+						 unsigned int index,
+						 unsigned int size);
+
+/*
+ * cpuidle.h
+ */
+
+int cpuidle_is_state_disabled(unsigned int cpu,
+				       unsigned int idlestate);
+int cpuidle_state_disable(unsigned int cpu, unsigned int idlestate,
+				   unsigned int disable);
+unsigned long cpuidle_state_latency(unsigned int cpu,
+						unsigned int idlestate);
+unsigned long cpuidle_state_usage(unsigned int cpu,
+					unsigned int idlestate);
+unsigned long long cpuidle_state_time(unsigned int cpu,
+						unsigned int idlestate);
+char *cpuidle_state_name(unsigned int cpu,
+				unsigned int idlestate);
+char *cpuidle_state_desc(unsigned int cpu,
+				unsigned int idlestate);
+unsigned int cpuidle_state_count(unsigned int cpu);
+
+char *cpuidle_get_governor(void);
+
+char *cpuidle_get_driver(void);
+
+/*
+ * cpupower.h
+ */
+
+struct cpupower_topology {
+	/* Amount of CPU cores, packages and threads per core in the system */
+	unsigned int cores;
+	unsigned int pkgs;
+	unsigned int threads; /* per core */
+
+	/* Array gets mallocated with cores entries, holding per core info */
+	struct cpuid_core_info *core_info;
+};
+
+struct cpuid_core_info {
+	int pkg;
+	int core;
+	int cpu;
+
+	/* flags */
+	unsigned int is_online:1;
+};
+
+int get_cpu_topology(struct cpupower_topology *cpu_top);
+
+void cpu_topology_release(struct cpupower_topology cpu_top);
+
+int cpupower_is_cpu_online(unsigned int cpu);
+
+/*
+ * powercap.h
+ */
+
+struct powercap_zone {
+	char name[MAX_LINE_LEN];
+	/*
+	 * sys_name relative to PATH_TO_POWERCAP,
+	 * do not forget the / in between
+	 */
+	char sys_name[SYSFS_PATH_MAX];
+	int tree_depth;
+	struct powercap_zone *parent;
+	struct powercap_zone *children[POWERCAP_MAX_CHILD_ZONES];
+	/* More possible caps or attributes to be added? */
+	uint32_t has_power_uw:1,
+		 has_energy_uj:1;
+
+};
+
+int powercap_walk_zones(struct powercap_zone *zone,
+			int (*f)(struct powercap_zone *zone));
+
+struct powercap_zone *powercap_init_zones(void);
+
+int powercap_get_enabled(int *mode);
+
+int powercap_set_enabled(int mode);
+
+int powercap_get_driver(char *driver, int buflen);
+
+int powercap_get_max_energy_range_uj(struct powercap_zone *zone, uint64_t *val);
+
+int powercap_get_energy_uj(struct powercap_zone *zone, uint64_t *val);
+
+int powercap_get_max_power_range_uw(struct powercap_zone *zone, uint64_t *val);
+
+int powercap_get_power_uw(struct powercap_zone *zone, uint64_t *val);
+
+int powercap_zone_get_enabled(struct powercap_zone *zone, int *mode);
+
+int powercap_zone_set_enabled(struct powercap_zone *zone, int mode);
-- 
2.46.0

[PATCH v3 3/4] pm:cpupower: Include test_raw_pylibcpupower.py

[John B. Wyatt IV]

This script demonstrates how to make use of, and tests, the bindings.

In the future, this script could become part of a larger test suite to
test the bindings and libcpupower.

Signed-off-by: John B. Wyatt IV <jwyatt@redhat.com>
Signed-off-by: John B. Wyatt IV <sageofredondo@gmail.com>
---

Changes in v3:
	- Small puncations below fixed.
	- Reordered patch series for cpupower stub implementation to be
	  first.
	- Added pm:cpupower prefix to header and Rafael to Cc.

Changes in v2:
	- None.
---
 .../bindings/python/test_raw_pylibcpupower.py | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)
 create mode 100755 tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py

diff --git a/tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py b/tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py
new file mode 100755
index 000000000000..3d6f62b9556a
--- /dev/null
+++ b/tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: GPL-2.0-only
+
+import raw_pylibcpupower as p
+
+# Simple function call
+
+"""
+Get cstate count
+"""
+cpu_cstates_count = p.cpuidle_state_count(0)
+if cpu_cstates_count > -1:
+    print(f"CPU 0 has {cpu_cstates_count} c-states")
+else:
+    print(f"cstate count error: return code: {cpu_cstates_count}")
+
+"""
+Disable cstate (will fail if the above is 0, ex: a virtual machine)
+"""
+cstate_disabled = p.cpuidle_state_disable(0, 0, 1)
+if cpu_cstates_count == 0:
+    print(f"CPU 0 has {cpu_cstates_count} c-states")
+else:
+    print(f"cstate count error: return code: {cpu_cstates_count}")
+
+match cstate_disabled:
+    case 0:
+        print(f"CPU state disabled")
+    case -1:
+        print(f"Idlestate not available")
+    case _:
+        print(f"Not documented")
+
+
+# Pointer example
+
+topo = p.cpupower_topology()
+total_cpus = p.get_cpu_topology(topo)
+if total_cpus > 0:
+    print(f"Number of total cpus: {total_cpus} and number of cores: {topo.cores}")
+else:
+    print(f"Error: could not get cpu topology")
-- 
2.46.0

[PATCH v3 4/4] MAINTAINERS: Add Maintainers for SWIG Python bindings

[John B. Wyatt IV]

Adding myself as the primary maintainer and John Kacur as the backup
maintainer for the libcpupower SWIG generated Python bindings.

Suggested-by: Shuah Khan <skhan@linuxfoundation.org>
Signed-off-by: John B. Wyatt IV <jwyatt@redhat.com>
Signed-off-by: John B. Wyatt IV <sageofredondo@gmail.com>
---

Changes in v3:
	- Added Rafael to Cc.

Changes in v2:
	- Added as requested.
---
 MAINTAINERS | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/MAINTAINERS b/MAINTAINERS
index 62a00f9471c1..1b2bbc8c5adb 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -5821,6 +5821,9 @@ CPU POWER MONITORING SUBSYSTEM
 M:	Thomas Renninger <trenn@suse.com>
 M:	Shuah Khan <shuah@kernel.org>
 M:	Shuah Khan <skhan@linuxfoundation.org>
+M:	John B. Wyatt IV <jwyatt@redhat.com>
+M:	John B. Wyatt IV <sageofredondo@gmail.com>
+M:	John Kacur <jkacur@redhat.com>
 L:	linux-pm@vger.kernel.org
 S:	Maintained
 F:	tools/power/cpupower/
-- 
2.46.0

Re: [PATCH v3 0/4] Add SWIG Bindings to libcpupower

[Shuah Khan]

On 9/4/24 20:19, John B. Wyatt IV wrote:
> SWIG is a tool packaged in Fedora and other distros that can generate
> bindings from C and C++ code for several languages including Python,
> Perl, and Go. Providing bindings for scripting languages is a common feature
> to make use of libraries more accessible to more users and programs. My team
> specifically wants to expand the features of rteval. rteval is a Python program
> used to measure real time performance. We wanted to test the effect of enabling
> some levels of idle-stat to see how it affects latency, and didn't want to
> reinvent the wheel. Since SWIG requires the .o files created by libcpupower at
> compilation it makes sense to include this in the cpupower directory so that
> others can make use of them.
> 
> The V3 of this patchset includes:
> * renaming header messages as requested and adding people to Cc as
> requested
> * moving the stub (dummy) commit to the front of the patchset
> * small punctuation fixes
> 
> The V2 of this patchset includes:
> * the full definition of libcpupower headers that is needed for the bindings
> * dummy implementation in C of a function listed in the header of libcpupower
> (requested by Shuah Khan)
> * test_raw_pylibcpupower.py demonstrates an example of using the bindings
> * adding myself and John Kacur to the cpupower section of the maintainers file
> (requested by Shuah Khan)
> * addressed review comments about doc, makefile, and maintainers file
> * small style and other fixes
> 
> The name raw_pylibcpupower is used because a wrapper `pylibcpupower` may be
> needed to make the bindings more 'pythonic' in the future. The bindings folder
> is used because Go or Perl bindings may be useful for other users in the
> future.
> 
> Note that while SWIG itself is GPL v3+ licensed; the resulting output, the
> bindings code, has the same license as the .o files used to generate the
> bindings (GPL v2 only). Please see
> https://swig.org/legal.html
> and
> https://lore.kernel.org/linux-pm/Zqv9BOjxLAgyNP5B@hatbackup/#t
> for more details on the license.
> 
> Sincerely,
> John Wyatt
> Software Engineer, Core Kernel
> Red Hat
> 
> John B. Wyatt IV (4):
>    pm:cpupower: Add missing powercap_set_enabled() stub function
>    pm:cpupower: Add SWIG bindings files for libcpupower
>    pm:cpupower: Include test_raw_pylibcpupower.py
>    MAINTAINERS: Add Maintainers for SWIG Python bindings
> 
>   MAINTAINERS                                   |   3 +
>   .../power/cpupower/bindings/python/.gitignore |   8 +
>   tools/power/cpupower/bindings/python/Makefile |  31 +++
>   tools/power/cpupower/bindings/python/README   |  59 +++++
>   .../bindings/python/raw_pylibcpupower.i       | 247 ++++++++++++++++++
>   .../bindings/python/test_raw_pylibcpupower.py |  42 +++
>   tools/power/cpupower/lib/powercap.c           |   8 +
>   7 files changed, 398 insertions(+)
>   create mode 100644 tools/power/cpupower/bindings/python/.gitignore
>   create mode 100644 tools/power/cpupower/bindings/python/Makefile
>   create mode 100644 tools/power/cpupower/bindings/python/README
>   create mode 100644 tools/power/cpupower/bindings/python/raw_pylibcpupower.i
>   create mode 100755 tools/power/cpupower/bindings/python/test_raw_pylibcpupower.py
> 

Applied the series for Linux 6.12-rc1 to

https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux.git cpupower branch

I chose to walk through the steps without installing SWIG
to see what make would do.

Some things to improve:

Running make in tools/power/cpupower/bindings/python directory without
installing SWIG gives me the following errors:

make: python-config: No such file or directory
swig -python raw_pylibcpupower.i
make: swig: No such file or directory
make: *** [Makefile:27: raw_pylibcpupower_wrap.c] Error 127

I think it would be good to provide better help message walking
user through installing the dependencies.

Documentation/Makefile is a good example to look at for useful
message on the dependencies to be installed.

You can send me patch on top of
https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux.git cpupower branch

thanks,
-- Shuah

Re: [PATCH v3 2/4] pm:cpupower: Add SWIG bindings files for libcpupower

[Guenter Roeck]

Hi,

On Wed, Sep 04, 2024 at 10:19:09PM -0400, John B. Wyatt IV wrote:
> SWIG is a tool packaged in Fedora and other distros that can generate
> bindings from C and C++ code for several languages including Python,
> Perl, and Go.
> 
> These bindings allows users to easily write scripts that use and extend
> libcpupower's functionality. Currently, only Python is provided in the
> makefile, but additional languages may be added if there is demand.
> 
> Added suggestions from Shuah Khan for the README and license discussion.
> 
> Note that while SWIG itself is GPL v3+ licensed; the resulting output,
> the bindings code, is permissively licensed + the license of the .o
> files. Please see
> https://swig.org/legal.html and [1] for more details.
> 
> [1]
> https://lore.kernel.org/linux-pm/Zqv9BOjxLAgyNP5B@hatbackup/
> 
> Suggested-by: Shuah Khan <skhan@linuxfoundation.org>
> Signed-off-by: John B. Wyatt IV <jwyatt@redhat.com>
> Signed-off-by: John B. Wyatt IV <sageofredondo@gmail.com>
> ---
> 
> Changes in v3:
> 	- Reordered patch series for cpupower stub implementation to be
> 	  first.
> 	- Added pm:cpupower prefix to header and Rafael to Cc.
> 
> Changes in v2:
> 	- Implemented the function so SWIG will accept the header
> 	  definition
> ---
>  .../power/cpupower/bindings/python/.gitignore |   8 +
>  tools/power/cpupower/bindings/python/Makefile |  31 +++
>  tools/power/cpupower/bindings/python/README   |  59 +++++
>  .../bindings/python/raw_pylibcpupower.i       | 247 ++++++++++++++++++
>  4 files changed, 345 insertions(+)
>  create mode 100644 tools/power/cpupower/bindings/python/.gitignore
>  create mode 100644 tools/power/cpupower/bindings/python/Makefile
>  create mode 100644 tools/power/cpupower/bindings/python/README
>  create mode 100644 tools/power/cpupower/bindings/python/raw_pylibcpupower.i

This file is deleted when running "make mrproper".

$ git reset --hard HEAD
$ make mrproper
$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
	deleted:    tools/power/cpupower/bindings/python/raw_pylibcpupower.i

That is a bit more than annoying when trying to switch branches after
that happened.

Guenter

Re: [PATCH v3 2/4] pm:cpupower: Add SWIG bindings files for libcpupower

[Linus Torvalds]

On Sat, 21 Sept 2024 at 14:23, Guenter Roeck <linux@roeck-us.net> wrote:
>
> On Wed, Sep 04, 2024 at 10:19:09PM -0400, John B. Wyatt IV wrote:
> >
> >  .../bindings/python/raw_pylibcpupower.i       | 247 ++++++++++++++++++
>
> This file is deleted when running "make mrproper".

Yes, please don't create files called '*.i", "*.s" or "*.o".  We
assume they are generated files (the result of the preprocessor, the
compiler, and the assembler respectively).

And yeah, obviously "*.i" and "*.s" and not _usually_ seen, because
they are only steps on the way to "*.o", so maybe they aren't _quite_
as obvious as some "*.o" file would be, but they are very much
standard naming, and we have build rules for them (ie "make
kernel/exit.i" will create the pre-processed result of exit.c).

                    Linus

Re: [PATCH v3 2/4] pm:cpupower: Add SWIG bindings files for libcpupower

[John B. Wyatt IV]

On Sun, Sep 22, 2024 at 08:39:28AM -0700, Linus Torvalds wrote:
> On Sat, 21 Sept 2024 at 14:23, Guenter Roeck <linux@roeck-us.net> wrote:
> >
> > On Wed, Sep 04, 2024 at 10:19:09PM -0400, John B. Wyatt IV wrote:
> > >
> > >  .../bindings/python/raw_pylibcpupower.i       | 247 ++++++++++++++++++
> >
> > This file is deleted when running "make mrproper".
> 
> Yes, please don't create files called '*.i", "*.s" or "*.o".  We
> assume they are generated files (the result of the preprocessor, the
> compiler, and the assembler respectively).
> 
> And yeah, obviously "*.i" and "*.s" and not _usually_ seen, because
> they are only steps on the way to "*.o", so maybe they aren't _quite_
> as obvious as some "*.o" file would be, but they are very much
> standard naming, and we have build rules for them (ie "make
> kernel/exit.i" will create the pre-processed result of exit.c).
> 

My apologies. This was reported and fixed with this patch by renaming
the file to '.swg'. '.swg' is the second filename extension used by
SWIG.

https://lore.kernel.org/linux-pm/20240913201705.7764-1-minhuadotchen@gmail.com/

-- 
Sincerely,
John Wyatt
Software Engineer, Core Kernel
Red Hat

Re: [PATCH v3 2/4] pm:cpupower: Add SWIG bindings files for libcpupower

[Shuah Khan]

On 9/23/24 07:29, John B. Wyatt IV wrote:
> On Sun, Sep 22, 2024 at 08:39:28AM -0700, Linus Torvalds wrote:
>> On Sat, 21 Sept 2024 at 14:23, Guenter Roeck <linux@roeck-us.net> wrote:
>>>
>>> On Wed, Sep 04, 2024 at 10:19:09PM -0400, John B. Wyatt IV wrote:
>>>>
>>>>   .../bindings/python/raw_pylibcpupower.i       | 247 ++++++++++++++++++
>>>
>>> This file is deleted when running "make mrproper".
>>
>> Yes, please don't create files called '*.i", "*.s" or "*.o".  We
>> assume they are generated files (the result of the preprocessor, the
>> compiler, and the assembler respectively).
>>
>> And yeah, obviously "*.i" and "*.s" and not _usually_ seen, because
>> they are only steps on the way to "*.o", so maybe they aren't _quite_
>> as obvious as some "*.o" file would be, but they are very much
>> standard naming, and we have build rules for them (ie "make
>> kernel/exit.i" will create the pre-processed result of exit.c).
>>
> 
> My apologies. This was reported and fixed with this patch by renaming
> the file to '.swg'. '.swg' is the second filename extension used by
> SWIG.
> 
> https://lore.kernel.org/linux-pm/20240913201705.7764-1-minhuadotchen@gmail.com/
> 

It was quickly found and fixed. I will send this to Rafael to get this into rc1.

thanks,
-- Shuah