tlp.conf: Make the profile-specific nature of the parameters clearer?

[linrunner]

Situation

With TLP 1.9.0, an additional operating mode called power-saver (for maximum energy savings) was introduced. The previously existing modes for AC power and battery operation were renamed performance and balanced. From then on, the modes were referred to as “profiles".

To reflect this in tlp.conf, parameters with a new suffix, _ON_SAV, were introduced. The existing suffixes for the old modes, _ON_AC and _ON_BAT, were left unchanged and directly assigned to the performance and balanced profiles.

The result shows the following example:

CPU_ENERGY_PERF_POLICY_ON_AC # Assigned to the performance profile
CPU_ENERGY_PERF_POLICY_ON_BAT # Assigned to the balanced profile
CPU_ENERGY_PERF_POLICY_ON_SAV # Assigned to the power-saver profile

This approach was deliberately chosen at the time to ensure backward compatibility with the large base of existing customised user configurations.

With TLP 1.10.0, another complication arose that made the configuration harder to understand. In response to user feature requests, the fixed relationship AC power == performance and battery power == balanced was removed and made configurable via TLP_PROFILE_AC and TLP_PROFILE_BAT instead.

Recently, I received feedback that this situation is confusing, as people still tend to associate the suffixes _ON_AC and _ON_BAT with the power sources themselves rather than the assigned profiles.

Proposal

The following alternative was proposed, which clearly indicates the assignment to the profiles:

CPU_ENERGY_PERF_POLICY_ON_PRF # Assigned to the performance profile
CPU_ENERGY_PERF_POLICY_ON_BAL # Assigned to the balanced profile
CPU_ENERGY_PERF_POLICY_ON_SAV # Assigned to the power-saver profile

Since backward compatibility with existing configurations must not be compromised, TLP would need to map the old parameter names to the new ones at runtime. In other words, your configuration files remain as they are; TLP converts the parameters each time it runs. I believe this is feasible. On the other hand, I can't imagine a reliable, automated way to rewrite the configuration files.

Since older versions of TLP remain in use for extended periods due to the distribution release cycles, the docsite would need to list the old names alongside the new ones for all parameters. That would make the documentation harder to read.

Questions for you:

1. From your perspective, do the advantages of the new solution outweigh its disadvantages?
2. What advantages and disadvantages do you see in the new solution for your specific use cases?
3. Any other thoughts?

I'm looking forward to your opinions. Thanks in advance for your participation!

[BarbUk]

Since backward compatibility with existing configurations must not be compromised

This is good.

TLP would need to map the old parameter names to the new ones at runtime. In other words, your configuration files remain as they are; TLP converts the parameters each time it runs

One way to handle this is to have two separate code path for old config / new config handling for the next release(s?) and inform users to update their configuration when starting.

I believe this is feasible

If this will not impact to much the complexity / maintenance of tlp, this is the best way.
User following the changelog / communication will update their config.
Other will keep a working up to date tlp with their config.

On the other hand, I can't imagine a reliable, automated way to rewrite the configuration files.

Maybe I don't have the full context on this, but is this not just a sed of the config file under /etc/tlp.d/*.conf ?

# Migrate all _ON_AC to _ON_PRF (including comment references)
sed -i 's/_ON_AC/_ON_PRF/g' /etc/tlp.d/*.conf

# Migrate all _ON_BAT to _ON_BAL (including comment references)
sed -i 's/_ON_BAT/_ON_BAL/g' /etc/tlp.d/*.conf

# Migrate special compound references in comments like CPU_MIN/MAX_PERF_ON_AC/BAT
sed -i 's/_ON_PRF\/BAT/_ON_PRF\/BAL/g' /etc/tlp.d/*.conf

Since older versions of TLP remain in use for extended periods due to the distribution release cycles, the docsite would need to list the old names alongside the new ones for all parameters. That would make the documentation harder to read.

We can also have two version of the documentation, via https://docs.readthedocs.com/platform/latest/versions.html.

So the current documentation can be kept in a 1.10 tag, and the new one updated on a new tag.

[dusklinux]

YESSS! The bat and ac names are definitely confusing. I've had trouble reasoning about them myself at times. Mapping the old variables to the new, more descriptive names—ac → performance and bat → balanced—isn't just a good idea, it's much more intuitive.

I know TLP has a large user base, but it's also a fairly technical one, especially among users who have configured it themselves instead of sticking with the defaults. I'd recommend avoiding unnecessary complexity in the codebase and just biting the bullet: deprecate the old naming scheme and don't carry backward compatibility.

I know that sounds a bit harsh, but you certainly wouldn't be the first project to make a breaking change for the sake of a cleaner design. Much larger projects do it all the time. Take Hyprland, for example, they recently switched from a simple configuration format to Lua configs, which required users to do a significant rewrite of their configuration. Hyprland's user base is orders of magnitude larger than TLP's, yet the transition was still considered worthwhile.

I wouldn't let the size of the user base discourage you from making the cleaner long-term decision. Just make sure the website and GitHub README are updated with clear migration anouncment. Word spreads pretty quickly in the Linux community, so I don't think users will be left in the dark.

[Mylinde]

You all have in mind that SAV/BAL/PRF can be applied on BAT and also on AC. So you can't just map the AC and BAT variables to performance or balanced. You need it like _ON_PRF_ON_AC, _ON_PRF_ON_BAT, _ON_BAL_ON_AC, _ON_BAL_ON_BAT, _ON_SAV_ON_BAT and _ON_SAV_ON_AC to make it consistent.

[dusklinux]

You're not wrong, Only adds to the point - that it could be more intuitive than it is right now. Its confusing.

[xantrk]

Genuinely opened up the issues to write something about after keep having misconfigs after I installed the Power Profiles daemon from TLP. I love this proposal!

One other thing I spotted is that, WIFI_PWR for example, only support AC and BAT, no SAV option which means I can't properly tie it to powersave on my case.

[linrunner]

@BarbUk

Maybe I don't have the full context on this, but is this not just a sed of the config file under /etc/tlp.d/*.conf ?

I could try that, but ideally this should happen during the package upgrade, which would require each distro maintainer to take individual action for his package. Alternatively I could modify the configuration files while TLP is running in the background, but I don't like doing it that way. It’s opaque for the user. Besides, you never know what might go wrong.

I’d rather use existing the in-flight rename mechanism, which only adjusts the parameter names during the respective processing. In addition, I could include hints in the command output, particularly for tlp-stat [-c|--cdiff].

We can also have two version of the documentation, via https://docs.readthedocs.com/platform/latest/versions.html.

Thanks for pointing that out, I hadn't thought of that. I'm familiar with it from the kernel documentation, but the downside there is that it's cumbersome to navigate from version to version or even to see which are available.

@Mylinde

So you can't just map the AC and BAT variables to performance or balanced. You need it like _ON_PRF_ON_AC, _ON_PRF_ON_BAT, _ON_BAL_ON_AC, _ON_BAL_ON_BAT, _ON_SAV_ON_BAT and _ON_SAV_ON_AC to make it consistent.

That's already been taken care of in the proposal. It uses the existing two level mapping:

1. From power source to profile with TLP_PROFILE_AC and TLP_PROFILE_BAT
2. From profile to the actual setting with FEATURE_ON_PRF/BAL/SAV

[braveheartleo]

That's already been taken care of in the proposal. It uses the existing two level mapping:

1. From power source to profile with TLP_PROFILE_AC and TLP_PROFILE_BAT
2. From profile to the actual setting with FEATURE_ON_PRF/BAL/SAV

I support this solution, and don't find any issues with it in my regular use case. I may have to update my config at some point in the future to use FEATURE_ON_PRF/BAL/SAV.

[NicholasFlamy]

I agree with this move, maybe to solve the issue with old versions having the old names you could version the docs the way I see a lot of ReadTheDocs documentation versioned. As a Devuan (Debian) user I appreciate having docs matching my version (though in my case I'm running the latest for this particular piece of software).