adjustor 3.2.0__tar.gz → 3.3.0__tar.gz

adjustor-3.3.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.1
+Name: adjustor
+Version: 3.3.0
+Summary: Adjustor, a userspace program for managing the TDP of handheld devices.
+Author-email: Kapenekakis Antheas <pypi@antheas.dev>
+Project-URL: Homepage, https://github.com/hhd-dev/adjustor
+Project-URL: Bug Tracker, https://github.com/hhd-dev/adjustor/issues
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.5.2
+Requires-Dist: pyroute2>=0.7.3
+Requires-Dist: fuse-python>=1.0.7
+Requires-Dist: PyGObject>=3.46.0
+Requires-Dist: dbus-python>=1.3.2
+
+# Adjustor
+Home of the Adjustor TDP plugin for Handheld Daemon.
+Adjustor currently allows for TDP control of all AMD Handhelds past generation
+6### (support is added manually).
+Intel is not currently supported.
+For installation and usage, see the [main readme](https://github.com/hhd-dev/hhd).
+Adjustor supports all handhelds in the Handheld Daemon supported list,
+except intel handhelds and older prior to 6XXX AMD handhelds.
+
+> [!IMPORTANT]
+> Adjustor supports per-device TDP values but its database is not fully featured
+> yet, with a fallback to 0-30W for missing devices
+> that use the ALIB driver. Use common sense while on battery and reference
+> your manufacturer's spec sheet. Open an issue so your device can have correct
+> limits.
+
+## TDP Control
+For the ROG Ally, Ally X and Legion Go that have an ACPI/EC implementation for 
+bios and fan curves,
+Adjustor uses the manufactuer functions for setting TDP.
+For the Allys, the asus-wmi kernel driver is used to set the tdp and manage the
+fan curves.
+For the Go, Lenovo's WMI methods are called through `acpi_call`, which will hopefully
+become part of a driver in the future.
+
+For other devices, Adjustor implements a reverse engineered version of AMD's 
+vendor function for setting TDP on demand in Ryzen processors, through ACPI.
+This means that it can be used regardless of the current memory policy
+or secure-boot/lockdown status (provided the module `acpi_call` is installed.).
+For more, see [AMD TDP Control Details](#amd-tdp).
+
+In all cases, there are checks to ensure that the TDP is within the safe range
+of the processors.
+
+## Energy Management
+Adjustor can also manage the energy profile of the processor, by setting EPP
+and proper frequency values.
+After we transitioned people away from Decky plugins (which had some governor controls)
+to using Handheld Daemon for TDP, we found that Power Profiles Daemon (PPD) 
+would use aggressive CPU values.
+These values are optimized for devices that have a dedicated power budget for the CPU
+(e.g., laptops, desktops), which caused issues with handhelds.
+
+For example, the balanced PPD profile would set EPP to balance_performance and
+enable CPU boost, which would increase the draw of the CPU during gaming by 2W
+and idle CPU temperature from 55C to around 70C.
+The performance profile would switch the governor to performance and set EPP to 
+performance, which would exacerbate this problem.
+In addition, the KDE and Gnome sliders were confusing for users, as they did not
+affect TDP (which is mostly determined by the GPU which is unaffected by PPD).
+
+Starting with version 3.1, when PPD is not present, Adjustor will manage the
+EPP, boost, and minimum frequency of the processor itself.
+By default, this is automatic, with sane values for handhelds: 
+ - governor is always powersave
+ - EPP is power or balance_power
+ - boost is enabled only on high TDPs
+ - On high TDPs, minimum frequency is ~1Ghz (min. nonlinear). Was found to help frame
+    pacing on the Ally and VRR displays.
+
+The user can also tweak the values themselves, as certain games have a preference
+for high CPU utilization.
+During testing, it was found that disabling CPU boost and lowering EPP results
+in a modest 10 fps increase on high TDPs and around 1W of less power consumption 
+on non-demanding games.
+
+In addition, Adjustor will emulate the dbus protocol of PPD, so that the sliders in
+KDE Powerdevil and Gnome shell work as expected, and make them control the
+TDP range instead of CPU values (which is the user's expectation).
+Of course, depending on TDP and user preference, the CPU governor values will be set
+accordingly.
+
+## AMD TDP Control Details<a name="amd-tdp"></a>
+Adjustor controls TDP through the Dynamic Power and Thermal Configuration Interface
+of AMD, which exposes a superset of the parameters that can be currently found in 
+[RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/), through ACPI.
+This vendor interface is part of the ACPI ASL library, and provided through the
+ALIB method 0x0C.
+The underlying implementation of the interface is SMU calls.
+This means that as long as the kernel module `acpi_call` is loaded, Adjustor
+can control TDP in an equivalent way to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
+
+The ABI of this vendor function (as it is provided to manufacturers) can be 
+considered mostly stable, so little work is needed between subsequent 
+processor generations (it has not changed since 6XXX; previous
+generations only had additions).
+Of course, support for processors is only added after the ACPI bindings have
+been reviewed, to avoid surprises.
+Both the Ally and Legion Go use this function, in the exact same way, so setting
+TDP with it is very stable, and we have had no reported crashes.
+It should not be used (and is not used) with those devices, however, as the 
+manufacturer functions will interfere.
+
+Unfortunately for devices that do have an ACPI/EC implementation for TDP, there
+is no official way of setting TDP on demand, either on Linux or Windows, with
+TDP remaining to what is set on the BIOS level.
+Vendors that offer this functionality without an ACPI implementation
+(such as Ayaneo), use RyzenAdj on Windows (can be seen on the Ayaneo Space directory).
+This is not ideal, as RyzenAdj does not hold a lock while performing
+SMU calls, and may perform them at the same time as the GPU driver which can
+confuse it and cause a kernel panic.
+We have recorded crashes with it both on Windows and Linux with implementations 
+which set TDP at a frequent interval (5-10s; unrelated
+to this project; as neither AutoTDP or RyzenAdj are used).
+
+Right now, Adjustor only implements a subset of useful ALIB parameters that are
+well documented.
+In addition, ALIB does not provide a way for reading the performance metrics table,
+which is meant for debugging, so Adjustor can only write (not read) TDP values.
+For that purpose, refer to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
+From reverse engineering the Legion Go (see [here](./alib.md)), and seeing how it
+interacts with ALIB, it was found that there are at least 10 parameters which control
+the method STTv2 and are not part of RyzenAdj or have been documented elsewhere.
+
+## Installation
+Adjustor is installed as part of Handheld Daemon now, so follow the instructions
+at [the main repository](https://github.com/hhd-dev/hhd#installation-instructions).
+It is available in [AUR](https://aur.archlinux.org/packages/adjustor), 
+[COPR](https://copr.fedorainfracloud.org/coprs/hhd-dev/hhd/package/adjustor/), 
+and [PyPi](https://github.com/hhd-dev/adjustor/issues).
+
+## Development
+Install to the same virtual environment as Handheld Daemon to have Adjustor picked up
+as a plugin upon restart, or to its own virtual environment to use independently.
+```python
+pip install -e .
+```
+
+# License
+Adjustor is licensed under THE GNU GPLv3+. See LICENSE for details.
+Versions prior to and excluding 2.0.0 are licensed using MIT.

{adjustor-3.2.0 → adjustor-3.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "adjustor"
-version = "3.2.0"
+version = "3.3.0"
 authors = [
   { name="Kapenekakis Antheas", email="pypi@antheas.dev" },
 ]

adjustor-3.3.0/readme.md

@@ -0,0 +1,131 @@
+# Adjustor
+Home of the Adjustor TDP plugin for Handheld Daemon.
+Adjustor currently allows for TDP control of all AMD Handhelds past generation
+6### (support is added manually).
+Intel is not currently supported.
+For installation and usage, see the [main readme](https://github.com/hhd-dev/hhd).
+Adjustor supports all handhelds in the Handheld Daemon supported list,
+except intel handhelds and older prior to 6XXX AMD handhelds.
+
+> [!IMPORTANT]
+> Adjustor supports per-device TDP values but its database is not fully featured
+> yet, with a fallback to 0-30W for missing devices
+> that use the ALIB driver. Use common sense while on battery and reference
+> your manufacturer's spec sheet. Open an issue so your device can have correct
+> limits.
+
+## TDP Control
+For the ROG Ally, Ally X and Legion Go that have an ACPI/EC implementation for 
+bios and fan curves,
+Adjustor uses the manufactuer functions for setting TDP.
+For the Allys, the asus-wmi kernel driver is used to set the tdp and manage the
+fan curves.
+For the Go, Lenovo's WMI methods are called through `acpi_call`, which will hopefully
+become part of a driver in the future.
+
+For other devices, Adjustor implements a reverse engineered version of AMD's 
+vendor function for setting TDP on demand in Ryzen processors, through ACPI.
+This means that it can be used regardless of the current memory policy
+or secure-boot/lockdown status (provided the module `acpi_call` is installed.).
+For more, see [AMD TDP Control Details](#amd-tdp).
+
+In all cases, there are checks to ensure that the TDP is within the safe range
+of the processors.
+
+## Energy Management
+Adjustor can also manage the energy profile of the processor, by setting EPP
+and proper frequency values.
+After we transitioned people away from Decky plugins (which had some governor controls)
+to using Handheld Daemon for TDP, we found that Power Profiles Daemon (PPD) 
+would use aggressive CPU values.
+These values are optimized for devices that have a dedicated power budget for the CPU
+(e.g., laptops, desktops), which caused issues with handhelds.
+
+For example, the balanced PPD profile would set EPP to balance_performance and
+enable CPU boost, which would increase the draw of the CPU during gaming by 2W
+and idle CPU temperature from 55C to around 70C.
+The performance profile would switch the governor to performance and set EPP to 
+performance, which would exacerbate this problem.
+In addition, the KDE and Gnome sliders were confusing for users, as they did not
+affect TDP (which is mostly determined by the GPU which is unaffected by PPD).
+
+Starting with version 3.1, when PPD is not present, Adjustor will manage the
+EPP, boost, and minimum frequency of the processor itself.
+By default, this is automatic, with sane values for handhelds: 
+ - governor is always powersave
+ - EPP is power or balance_power
+ - boost is enabled only on high TDPs
+ - On high TDPs, minimum frequency is ~1Ghz (min. nonlinear). Was found to help frame
+    pacing on the Ally and VRR displays.
+
+The user can also tweak the values themselves, as certain games have a preference
+for high CPU utilization.
+During testing, it was found that disabling CPU boost and lowering EPP results
+in a modest 10 fps increase on high TDPs and around 1W of less power consumption 
+on non-demanding games.
+
+In addition, Adjustor will emulate the dbus protocol of PPD, so that the sliders in
+KDE Powerdevil and Gnome shell work as expected, and make them control the
+TDP range instead of CPU values (which is the user's expectation).
+Of course, depending on TDP and user preference, the CPU governor values will be set
+accordingly.
+
+## AMD TDP Control Details<a name="amd-tdp"></a>
+Adjustor controls TDP through the Dynamic Power and Thermal Configuration Interface
+of AMD, which exposes a superset of the parameters that can be currently found in 
+[RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/), through ACPI.
+This vendor interface is part of the ACPI ASL library, and provided through the
+ALIB method 0x0C.
+The underlying implementation of the interface is SMU calls.
+This means that as long as the kernel module `acpi_call` is loaded, Adjustor
+can control TDP in an equivalent way to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
+
+The ABI of this vendor function (as it is provided to manufacturers) can be 
+considered mostly stable, so little work is needed between subsequent 
+processor generations (it has not changed since 6XXX; previous
+generations only had additions).
+Of course, support for processors is only added after the ACPI bindings have
+been reviewed, to avoid surprises.
+Both the Ally and Legion Go use this function, in the exact same way, so setting
+TDP with it is very stable, and we have had no reported crashes.
+It should not be used (and is not used) with those devices, however, as the 
+manufacturer functions will interfere.
+
+Unfortunately for devices that do have an ACPI/EC implementation for TDP, there
+is no official way of setting TDP on demand, either on Linux or Windows, with
+TDP remaining to what is set on the BIOS level.
+Vendors that offer this functionality without an ACPI implementation
+(such as Ayaneo), use RyzenAdj on Windows (can be seen on the Ayaneo Space directory).
+This is not ideal, as RyzenAdj does not hold a lock while performing
+SMU calls, and may perform them at the same time as the GPU driver which can
+confuse it and cause a kernel panic.
+We have recorded crashes with it both on Windows and Linux with implementations 
+which set TDP at a frequent interval (5-10s; unrelated
+to this project; as neither AutoTDP or RyzenAdj are used).
+
+Right now, Adjustor only implements a subset of useful ALIB parameters that are
+well documented.
+In addition, ALIB does not provide a way for reading the performance metrics table,
+which is meant for debugging, so Adjustor can only write (not read) TDP values.
+For that purpose, refer to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
+From reverse engineering the Legion Go (see [here](./alib.md)), and seeing how it
+interacts with ALIB, it was found that there are at least 10 parameters which control
+the method STTv2 and are not part of RyzenAdj or have been documented elsewhere.
+
+## Installation
+Adjustor is installed as part of Handheld Daemon now, so follow the instructions
+at [the main repository](https://github.com/hhd-dev/hhd#installation-instructions).
+It is available in [AUR](https://aur.archlinux.org/packages/adjustor), 
+[COPR](https://copr.fedorainfracloud.org/coprs/hhd-dev/hhd/package/adjustor/), 
+and [PyPi](https://github.com/hhd-dev/adjustor/issues).
+
+## Development
+Install to the same virtual environment as Handheld Daemon to have Adjustor picked up
+as a plugin upon restart, or to its own virtual environment to use independently.
+```python
+pip install -e .
+```
+
+# License
+Adjustor is licensed under THE GNU GPLv3+. See LICENSE for details.
+Versions prior to and excluding 2.0.0 are licensed using MIT.

{adjustor-3.2.0 → adjustor-3.3.0}/src/adjustor/core/const.py

@@ -41,12 +41,24 @@ DEV_PARAMS_7040: dict[str, DeviceParams] = {
     "temp_target": D(60, 70, 85, 90, 100),
 }
 
+DEV_PARAMS_NEO: dict[str, DeviceParams] = {
+    "stapm_limit": D(0, 4, 15, 28, 35),
+    "skin_limit": D(0, 4, 15, 28, 35),
+    "slow_limit": D(0, 4, 20, 32, 37),
+    "fast_limit": D(0, 4, 25, 35, 40),
+    # Times
+    "slow_time": D(5, 5, 10, 10, 10),
+    "stapm_time": D(100, 100, 100, 200, 200),
+    # Temp
+    "temp_target": D(60, 70, 85, 90, 100),
+}
+
 DEV_PARAMS_6040: dict[str, DeviceParams] = DEV_PARAMS_7040
 DEV_PARAMS_8040: dict[str, DeviceParams] = DEV_PARAMS_7040
 DEV_PARAMS_LEGO = DEV_PARAMS_7040
 
 DEV_DATA: dict[str, tuple[dict[str, DeviceParams], dict[str, AlibParams], bool]] = {
-    "NEO-01": (DEV_PARAMS_7040, ALIB_PARAMS_7040, False),
+    "NEO-01": (DEV_PARAMS_NEO, ALIB_PARAMS_7040, False),
     "83E1": (DEV_PARAMS_LEGO, ALIB_PARAMS_7040, False),
 }
 

{adjustor-3.2.0 → adjustor-3.3.0}/src/adjustor/drivers/amd/__init__.py

@@ -2,10 +2,11 @@ import logging
 import os
 import subprocess
 import sys
-from threading import Event as TEvent
 from threading import Thread
 from typing import Literal
+import shutil
 import time
+import signal
 
 from hhd.plugins import Context, HHDPlugin, load_relative_yaml
 from hhd.plugins.conf import Config
@@ -67,14 +68,18 @@ class AmdGPUPlugin(HHDPlugin):
         self.ppd_conflict = False
         self.initialized = False
         self.supports_boost = False
+        self.supports_sched = False
+        self.avail_scheds = {}
 
         self.proc = None
         self.t = None
 
         self.queue = None
+        self.sched_proc = None
         self.old_ppd = False
         self.old_gpu = None
         self.old_freq = None
+        self.old_sched = "disabled"
         self.old_boost = None
         self.old_epp = None
         self.old_target = None
@@ -174,6 +179,31 @@ class AmdGPUPlugin(HHDPlugin):
                 "cpu_pref"
             ]
 
+        self.avail_scheds = {}
+        avail_pretty = {}
+        kernel_supports = os.path.isfile("/sys/kernel/sched_ext/state")
+        if kernel_supports:
+            for sched, pretty in sets["enabled"]["children"]["mode"]["modes"]["manual"][
+                "children"
+            ]["sched"]["options"].items():
+                if sched == "disabled":
+                    avail_pretty[sched] = pretty
+                    continue
+
+                exe = shutil.which(sched)
+                if exe:
+                    self.avail_scheds[sched] = exe
+                    avail_pretty[sched] = pretty
+
+        if self.avail_scheds:
+            sets["enabled"]["children"]["mode"]["modes"]["manual"]["children"]["sched"][
+                "options"
+            ] = avail_pretty
+        else:
+            del sets["enabled"]["children"]["mode"]["modes"]["manual"]["children"][
+                "sched"
+            ]
+
         self.logged_boost = True
         return {
             "tdp": {"amd_energy": sets["enabled"]},
@@ -197,7 +227,7 @@ class AmdGPUPlugin(HHDPlugin):
                         self.proc.stdin.flush()
                 except Exception as e:
                     logger.error(f"Failed to send PPD mode:\n{e}")
-                    self.close()
+                    self.close_ppd()
 
     def update(self, conf: Config):
         self.core_enabled = conf["hhd.settings.tdp_enable"].to(bool)
@@ -224,9 +254,9 @@ class AmdGPUPlugin(HHDPlugin):
                     self.proc, self.t = _open_ppd_server(self.emit)
                 except Exception as e:
                     logger.error(f"Failed to open PPD server:\n{e}")
-                    self.close()
+                    self.close_ppd()
             else:
-                self.close()
+                self.close_ppd()
 
         if conf["tdp.amd_energy.mode.mode"].to(str) == "auto":
             curr = time.perf_counter()
@@ -239,6 +269,8 @@ class AmdGPUPlugin(HHDPlugin):
                 logger.info(
                     f"Handling energy settings for power profile '{self.target}'."
                 )
+                # Unless it is set manually, use the default scheduler.
+                self.close_sched()
                 try:
                     match self.target:
                         case "balanced":
@@ -329,10 +361,43 @@ class AmdGPUPlugin(HHDPlugin):
                     except Exception as e:
                         logger.error(f"Failed to set minimum CPU frequency:\n{e}")
 
-    def close(self):
+            if self.avail_scheds:
+                # Check health and print error
+                if self.sched_proc and self.sched_proc.poll():
+                    err = self.sched_proc.poll()
+                    self.sched_proc = None
+                    logger.error(
+                        f"Scheduler from sched_ext '{self.old_sched}' closed with error code: {err}"
+                    )
+
+                new_sched = conf.get("tdp.amd_energy.mode.manual.sched", "disabled")
+                if new_sched != self.old_sched:
+                    self.close_sched()
+                    self.old_sched = new_sched
+                    if new_sched and new_sched != "disabled":
+                        logger.info(f"Starting sched_ext scheduler '{new_sched}'")
+                        self.sched_proc = subprocess.Popen(
+                            self.avail_scheds[new_sched],
+                            stderr=subprocess.DEVNULL,
+                            stdout=subprocess.DEVNULL,
+                        )
+
+    def close_ppd(self):
         if self.proc is not None:
-            self.proc.terminate()
+            self.proc.send_signal(signal.SIGINT)
             self.proc.wait()
+            self.proc = None
         if self.t is not None:
             self.t.join()
             self.t = None
+
+    def close_sched(self):
+        if self.sched_proc is not None:
+            logger.info(f"Closing sched_ext scheduler '{self.old_sched}'.")
+            self.sched_proc.send_signal(signal.SIGINT)
+            self.sched_proc.wait()
+            self.sched_proc = None
+
+    def close(self):
+        self.close_ppd()
+        self.close_sched()

{adjustor-3.2.0 → adjustor-3.3.0}/src/adjustor/drivers/amd/settings.yml

@@ -1,7 +1,7 @@
 enabled:
   title: Energy Management
   type: container
-  tags: [ hide-title ]
+  tags: [ hide-title, non-essential ]
   children:
     mode:
       type: mode
@@ -87,6 +87,19 @@ enabled:
                       max: 2000
                       step: 100
                       default: 1000
+            sched:
+              type: multiple
+              title: Custom Scheduler
+              hint: >-
+                Allows attaching a scheduler to the kernel sched_ext.
+                Schedulers need to be installed.
+                "Kernel" .
+              options:
+                disabled: Disabled
+                scx_lavd: LAVD
+                scx_bpfland: bpfland 
+                scx_rusty: rusty
+              default: disabled
 
 conflict:
   title: Energy Management
@@ -119,6 +132,6 @@ core:
     amd_energy_ppd:
       title: Enable PPD Emulation (KDE/Gnome Power)
       type: bool
-      default: False
+      default: True
       hint: >-
         Enable PPD service to manage the power preferences for the system.

{adjustor-3.2.0 → adjustor-3.3.0}/src/adjustor/drivers/asus/settings.yml

@@ -100,17 +100,16 @@ children:
   charge_limit:
     type: multiple
     title: Charge Limit (%)
-    tags: [ non-essential ]
+    tags: [ non-essential, ordinal ]
     hint: >-
       Applies a charge limit to the battery, 75% and up.
     options:
-      disabled: Disabled
-      p65: 65%
       p70: 70%
       p80: 80%
       p85: 85%
       p90: 90%
       p95: 95%
+      disabled: Unset
     default: disabled
   
   # disclaimer:

{adjustor-3.2.0 → adjustor-3.3.0}/src/adjustor/hhd.py

@@ -274,6 +274,18 @@ def autodetect(existing: Sequence[HHDPlugin]) -> Sequence[HHDPlugin]:
 
     if not drivers_matched and prod in DEV_DATA:
         dev, cpu, pp_enable = DEV_DATA[prod]
+
+        try:
+            # Set values for the steam slider
+            if dev["skin_limit"].smin:
+                min_tdp = dev["skin_limit"].smin
+            if dev["skin_limit"].default:
+                default_tdp = dev["skin_limit"].default
+            if dev["skin_limit"].smax:
+                max_tdp = dev["skin_limit"].smax
+        except Exception as e:
+            logger.error(f"Failed to get TDP limits for {prod}:\n{e}")
+
         pp_enable |= bool(os.environ.get("HHD_ADJ_DEBUG"))
         drivers.append(
             SmuDriverPlugin(

adjustor-3.3.0/src/adjustor.egg-info/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.1
+Name: adjustor
+Version: 3.3.0
+Summary: Adjustor, a userspace program for managing the TDP of handheld devices.
+Author-email: Kapenekakis Antheas <pypi@antheas.dev>
+Project-URL: Homepage, https://github.com/hhd-dev/adjustor
+Project-URL: Bug Tracker, https://github.com/hhd-dev/adjustor/issues
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.5.2
+Requires-Dist: pyroute2>=0.7.3
+Requires-Dist: fuse-python>=1.0.7
+Requires-Dist: PyGObject>=3.46.0
+Requires-Dist: dbus-python>=1.3.2
+
+# Adjustor
+Home of the Adjustor TDP plugin for Handheld Daemon.
+Adjustor currently allows for TDP control of all AMD Handhelds past generation
+6### (support is added manually).
+Intel is not currently supported.
+For installation and usage, see the [main readme](https://github.com/hhd-dev/hhd).
+Adjustor supports all handhelds in the Handheld Daemon supported list,
+except intel handhelds and older prior to 6XXX AMD handhelds.
+
+> [!IMPORTANT]
+> Adjustor supports per-device TDP values but its database is not fully featured
+> yet, with a fallback to 0-30W for missing devices
+> that use the ALIB driver. Use common sense while on battery and reference
+> your manufacturer's spec sheet. Open an issue so your device can have correct
+> limits.
+
+## TDP Control
+For the ROG Ally, Ally X and Legion Go that have an ACPI/EC implementation for 
+bios and fan curves,
+Adjustor uses the manufactuer functions for setting TDP.
+For the Allys, the asus-wmi kernel driver is used to set the tdp and manage the
+fan curves.
+For the Go, Lenovo's WMI methods are called through `acpi_call`, which will hopefully
+become part of a driver in the future.
+
+For other devices, Adjustor implements a reverse engineered version of AMD's 
+vendor function for setting TDP on demand in Ryzen processors, through ACPI.
+This means that it can be used regardless of the current memory policy
+or secure-boot/lockdown status (provided the module `acpi_call` is installed.).
+For more, see [AMD TDP Control Details](#amd-tdp).
+
+In all cases, there are checks to ensure that the TDP is within the safe range
+of the processors.
+
+## Energy Management
+Adjustor can also manage the energy profile of the processor, by setting EPP
+and proper frequency values.
+After we transitioned people away from Decky plugins (which had some governor controls)
+to using Handheld Daemon for TDP, we found that Power Profiles Daemon (PPD) 
+would use aggressive CPU values.
+These values are optimized for devices that have a dedicated power budget for the CPU
+(e.g., laptops, desktops), which caused issues with handhelds.
+
+For example, the balanced PPD profile would set EPP to balance_performance and
+enable CPU boost, which would increase the draw of the CPU during gaming by 2W
+and idle CPU temperature from 55C to around 70C.
+The performance profile would switch the governor to performance and set EPP to 
+performance, which would exacerbate this problem.
+In addition, the KDE and Gnome sliders were confusing for users, as they did not
+affect TDP (which is mostly determined by the GPU which is unaffected by PPD).
+
+Starting with version 3.1, when PPD is not present, Adjustor will manage the
+EPP, boost, and minimum frequency of the processor itself.
+By default, this is automatic, with sane values for handhelds: 
+ - governor is always powersave
+ - EPP is power or balance_power
+ - boost is enabled only on high TDPs
+ - On high TDPs, minimum frequency is ~1Ghz (min. nonlinear). Was found to help frame
+    pacing on the Ally and VRR displays.
+
+The user can also tweak the values themselves, as certain games have a preference
+for high CPU utilization.
+During testing, it was found that disabling CPU boost and lowering EPP results
+in a modest 10 fps increase on high TDPs and around 1W of less power consumption 
+on non-demanding games.
+
+In addition, Adjustor will emulate the dbus protocol of PPD, so that the sliders in
+KDE Powerdevil and Gnome shell work as expected, and make them control the
+TDP range instead of CPU values (which is the user's expectation).
+Of course, depending on TDP and user preference, the CPU governor values will be set
+accordingly.
+
+## AMD TDP Control Details<a name="amd-tdp"></a>
+Adjustor controls TDP through the Dynamic Power and Thermal Configuration Interface
+of AMD, which exposes a superset of the parameters that can be currently found in 
+[RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/), through ACPI.
+This vendor interface is part of the ACPI ASL library, and provided through the
+ALIB method 0x0C.
+The underlying implementation of the interface is SMU calls.
+This means that as long as the kernel module `acpi_call` is loaded, Adjustor
+can control TDP in an equivalent way to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
+
+The ABI of this vendor function (as it is provided to manufacturers) can be 
+considered mostly stable, so little work is needed between subsequent 
+processor generations (it has not changed since 6XXX; previous
+generations only had additions).
+Of course, support for processors is only added after the ACPI bindings have
+been reviewed, to avoid surprises.
+Both the Ally and Legion Go use this function, in the exact same way, so setting
+TDP with it is very stable, and we have had no reported crashes.
+It should not be used (and is not used) with those devices, however, as the 
+manufacturer functions will interfere.
+
+Unfortunately for devices that do have an ACPI/EC implementation for TDP, there
+is no official way of setting TDP on demand, either on Linux or Windows, with
+TDP remaining to what is set on the BIOS level.
+Vendors that offer this functionality without an ACPI implementation
+(such as Ayaneo), use RyzenAdj on Windows (can be seen on the Ayaneo Space directory).
+This is not ideal, as RyzenAdj does not hold a lock while performing
+SMU calls, and may perform them at the same time as the GPU driver which can
+confuse it and cause a kernel panic.
+We have recorded crashes with it both on Windows and Linux with implementations 
+which set TDP at a frequent interval (5-10s; unrelated
+to this project; as neither AutoTDP or RyzenAdj are used).
+
+Right now, Adjustor only implements a subset of useful ALIB parameters that are
+well documented.
+In addition, ALIB does not provide a way for reading the performance metrics table,
+which is meant for debugging, so Adjustor can only write (not read) TDP values.
+For that purpose, refer to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
+From reverse engineering the Legion Go (see [here](./alib.md)), and seeing how it
+interacts with ALIB, it was found that there are at least 10 parameters which control
+the method STTv2 and are not part of RyzenAdj or have been documented elsewhere.
+
+## Installation
+Adjustor is installed as part of Handheld Daemon now, so follow the instructions
+at [the main repository](https://github.com/hhd-dev/hhd#installation-instructions).
+It is available in [AUR](https://aur.archlinux.org/packages/adjustor), 
+[COPR](https://copr.fedorainfracloud.org/coprs/hhd-dev/hhd/package/adjustor/), 
+and [PyPi](https://github.com/hhd-dev/adjustor/issues).
+
+## Development
+Install to the same virtual environment as Handheld Daemon to have Adjustor picked up
+as a plugin upon restart, or to its own virtual environment to use independently.
+```python
+pip install -e .
+```
+
+# License
+Adjustor is licensed under THE GNU GPLv3+. See LICENSE for details.
+Versions prior to and excluding 2.0.0 are licensed using MIT.

adjustor-3.2.0/PKG-INFO

@@ -1,82 +0,0 @@
-Metadata-Version: 2.1
-Name: adjustor
-Version: 3.2.0
-Summary: Adjustor, a userspace program for managing the TDP of handheld devices.
-Author-email: Kapenekakis Antheas <pypi@antheas.dev>
-Project-URL: Homepage, https://github.com/hhd-dev/adjustor
-Project-URL: Bug Tracker, https://github.com/hhd-dev/adjustor/issues
-Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Operating System :: POSIX :: Linux
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: rich>=13.5.2
-Requires-Dist: pyroute2>=0.7.3
-Requires-Dist: fuse-python>=1.0.7
-Requires-Dist: PyGObject>=3.46.0
-Requires-Dist: dbus-python>=1.3.2
-
-# Adjustor
-Home of the Adjustor TDP plugin for Handheld Daemon.
-Adjustor currently allows for TDP control of all AMD Handhelds past generation
-6### (support is added manually).
-Since it integrates with Handheld Daemon, it is available through 
-[Decky](https://github.com/hhd-dev/hhd-decky),
-and through [hhd-ui](https://github.com/hhd-dev/hhd-ui).
-
-Adjustor implements a reversed engineered version of AMD's vendor function for
-setting TDP on demand in Ryzen processors, through ACPI.
-This means that it can be used regardless of the current memory policy
-or secure-boot/lockdown status (provided the module `acpi_call` is installed.).
-
-For the ROG Ally and Legion Go that have an ACPI/EC implementation for bios and fan curves,
-Adjustor uses the manufactuer way for setting TDP.
-For the ally, the asus-wmi kernel driver is used to set the tdp and manage the
-fan curves.
-For the go, Lenovo's WMI methods are called through `acpi_call`, which will hopefully
-become part of a driver in the future.
-
-## AMD TDP Control
-Adjustor controls TDP through the Dynamic Power and Thermal Configuration Interface
-of AMD, which exposes a superset of the parameters that can be currently found in 
-[RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/), through ACPI.
-This vendor interface is part of the ACPI ASL library, and provided through the
-ALIB method 0x0C.
-The underlying implementation of the interface is SMU calls.
-This means that as long as the kernel module `acpi_call` is loaded, Adjustor
-can control TDP in an equivalent way to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
-
-Right now, Adjustor only implements a subset of useful ALIB parameters that are
-well documented.
-In addition, ALIB does not provide a way for reading the performance metrics table, 
-so Adjustor can only write (not read) TDP values.
-From reverse engineering the Legion Go (see [here](./alib.md)), and seeing how it
-interacts with ALIB, it was found that there are at least 10 parameters which control
-the method STTv2 and are not part of RyzenAdj or have been documented elsewhere.
-
-## Installation
-Adjustor is available on [AUR](https://aur.archlinux.org/packages/adjustor)
-and provided Handheld Daemon has been installed through 
-[AUR](https://aur.archlinux.org/packages/hhd) too, it will load it automatically
-on restart.
-COPR coming soon.
-
-Alternatively, on a local install of Handheld Daemon you may:
-```bash
-~/.local/share/hhd/venv/bin/pip install --upgrade adjustor
-```
-However, the autoupdater in Handheld Daemon does not support updating yet.
-
-## Development
-Install to the same virtual environment as hhd to have Adjustor picked up
-as a plugin upon restart, or to its own venv to use independently.
-```python
-pip install -e .
-```
-
-# License
-Adjustor is licensed under THE GNU GPLv3+. See LICENSE for details.
-Versions prior to and excluding 2.0.0 are licensed using MIT.

adjustor-3.2.0/readme.md

@@ -1,61 +0,0 @@
-# Adjustor
-Home of the Adjustor TDP plugin for Handheld Daemon.
-Adjustor currently allows for TDP control of all AMD Handhelds past generation
-6### (support is added manually).
-Since it integrates with Handheld Daemon, it is available through 
-[Decky](https://github.com/hhd-dev/hhd-decky),
-and through [hhd-ui](https://github.com/hhd-dev/hhd-ui).
-
-Adjustor implements a reversed engineered version of AMD's vendor function for
-setting TDP on demand in Ryzen processors, through ACPI.
-This means that it can be used regardless of the current memory policy
-or secure-boot/lockdown status (provided the module `acpi_call` is installed.).
-
-For the ROG Ally and Legion Go that have an ACPI/EC implementation for bios and fan curves,
-Adjustor uses the manufactuer way for setting TDP.
-For the ally, the asus-wmi kernel driver is used to set the tdp and manage the
-fan curves.
-For the go, Lenovo's WMI methods are called through `acpi_call`, which will hopefully
-become part of a driver in the future.
-
-## AMD TDP Control
-Adjustor controls TDP through the Dynamic Power and Thermal Configuration Interface
-of AMD, which exposes a superset of the parameters that can be currently found in 
-[RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/), through ACPI.
-This vendor interface is part of the ACPI ASL library, and provided through the
-ALIB method 0x0C.
-The underlying implementation of the interface is SMU calls.
-This means that as long as the kernel module `acpi_call` is loaded, Adjustor
-can control TDP in an equivalent way to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
-
-Right now, Adjustor only implements a subset of useful ALIB parameters that are
-well documented.
-In addition, ALIB does not provide a way for reading the performance metrics table, 
-so Adjustor can only write (not read) TDP values.
-From reverse engineering the Legion Go (see [here](./alib.md)), and seeing how it
-interacts with ALIB, it was found that there are at least 10 parameters which control
-the method STTv2 and are not part of RyzenAdj or have been documented elsewhere.
-
-## Installation
-Adjustor is available on [AUR](https://aur.archlinux.org/packages/adjustor)
-and provided Handheld Daemon has been installed through 
-[AUR](https://aur.archlinux.org/packages/hhd) too, it will load it automatically
-on restart.
-COPR coming soon.
-
-Alternatively, on a local install of Handheld Daemon you may:
-```bash
-~/.local/share/hhd/venv/bin/pip install --upgrade adjustor
-```
-However, the autoupdater in Handheld Daemon does not support updating yet.
-
-## Development
-Install to the same virtual environment as hhd to have Adjustor picked up
-as a plugin upon restart, or to its own venv to use independently.
-```python
-pip install -e .
-```
-
-# License
-Adjustor is licensed under THE GNU GPLv3+. See LICENSE for details.
-Versions prior to and excluding 2.0.0 are licensed using MIT.

adjustor-3.2.0/src/adjustor.egg-info/PKG-INFO

@@ -1,82 +0,0 @@
-Metadata-Version: 2.1
-Name: adjustor
-Version: 3.2.0
-Summary: Adjustor, a userspace program for managing the TDP of handheld devices.
-Author-email: Kapenekakis Antheas <pypi@antheas.dev>
-Project-URL: Homepage, https://github.com/hhd-dev/adjustor
-Project-URL: Bug Tracker, https://github.com/hhd-dev/adjustor/issues
-Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Operating System :: POSIX :: Linux
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: rich>=13.5.2
-Requires-Dist: pyroute2>=0.7.3
-Requires-Dist: fuse-python>=1.0.7
-Requires-Dist: PyGObject>=3.46.0
-Requires-Dist: dbus-python>=1.3.2
-
-# Adjustor
-Home of the Adjustor TDP plugin for Handheld Daemon.
-Adjustor currently allows for TDP control of all AMD Handhelds past generation
-6### (support is added manually).
-Since it integrates with Handheld Daemon, it is available through 
-[Decky](https://github.com/hhd-dev/hhd-decky),
-and through [hhd-ui](https://github.com/hhd-dev/hhd-ui).
-
-Adjustor implements a reversed engineered version of AMD's vendor function for
-setting TDP on demand in Ryzen processors, through ACPI.
-This means that it can be used regardless of the current memory policy
-or secure-boot/lockdown status (provided the module `acpi_call` is installed.).
-
-For the ROG Ally and Legion Go that have an ACPI/EC implementation for bios and fan curves,
-Adjustor uses the manufactuer way for setting TDP.
-For the ally, the asus-wmi kernel driver is used to set the tdp and manage the
-fan curves.
-For the go, Lenovo's WMI methods are called through `acpi_call`, which will hopefully
-become part of a driver in the future.
-
-## AMD TDP Control
-Adjustor controls TDP through the Dynamic Power and Thermal Configuration Interface
-of AMD, which exposes a superset of the parameters that can be currently found in 
-[RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/), through ACPI.
-This vendor interface is part of the ACPI ASL library, and provided through the
-ALIB method 0x0C.
-The underlying implementation of the interface is SMU calls.
-This means that as long as the kernel module `acpi_call` is loaded, Adjustor
-can control TDP in an equivalent way to [RyzenAdj](https://github.dev/FlyGoat/RyzenAdj/).
-
-Right now, Adjustor only implements a subset of useful ALIB parameters that are
-well documented.
-In addition, ALIB does not provide a way for reading the performance metrics table, 
-so Adjustor can only write (not read) TDP values.
-From reverse engineering the Legion Go (see [here](./alib.md)), and seeing how it
-interacts with ALIB, it was found that there are at least 10 parameters which control
-the method STTv2 and are not part of RyzenAdj or have been documented elsewhere.
-
-## Installation
-Adjustor is available on [AUR](https://aur.archlinux.org/packages/adjustor)
-and provided Handheld Daemon has been installed through 
-[AUR](https://aur.archlinux.org/packages/hhd) too, it will load it automatically
-on restart.
-COPR coming soon.
-
-Alternatively, on a local install of Handheld Daemon you may:
-```bash
-~/.local/share/hhd/venv/bin/pip install --upgrade adjustor
-```
-However, the autoupdater in Handheld Daemon does not support updating yet.
-
-## Development
-Install to the same virtual environment as hhd to have Adjustor picked up
-as a plugin upon restart, or to its own venv to use independently.
-```python
-pip install -e .
-```
-
-# License
-Adjustor is licensed under THE GNU GPLv3+. See LICENSE for details.
-Versions prior to and excluding 2.0.0 are licensed using MIT.