Skip to content

Commit

Permalink
EnvyControl V3 (#90)
Browse files Browse the repository at this point in the history
  • Loading branch information
@bayasdev
bayasdev authored Mar 13, 2023
1 parent 26e14ea commit de75209
Show file tree
Hide file tree
Showing 2 changed files with 389 additions and 282 deletions.
172 changes: 101 additions & 71 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,112 +1,111 @@
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./logos/dark.png">
<img alt="EnvyControl Logo" src="./logos/light.png" height="100px">
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/bayasdev/envycontrol/raw/main/logos/dark.png">
<img alt="EnvyControl Logo" src="https://github.com/bayasdev/envycontrol/raw/main/logos/light.png" height="100px">
</picture>
<br>
Optimus made easy
</div>
<br>

# 👁‍🗨 EnvyControl

EnvyControl is a program aimed to provide an easy way to switch GPU modes on Nvidia Optimus systems (i.e laptops with hybrid Intel + Nvidia or AMD + Nvidia graphics configurations) under Linux.
EnvyControl is a CLI tool that provides an easy way to switch between GPU modes on Nvidia Optimus systems (i.e laptops with hybrid Intel + Nvidia or AMD + Nvidia graphics configurations) under Linux.

### 📖 License

EnvyControl is free and open-source software released under the [MIT](https://github.com/bayasdev/envycontrol/blob/main/LICENSE) license.

### ⚠️ Disclaimer

**This software is provided 'as-is' without any express or implied warranty.**

Keep it mind any custom X.org configuration may get deleted or overwritten when switching modes, please review this README and the source code before proceeding.

## 🐧 Compatible distros

EnvyControl should work on any distribution of Linux, see [tested distros](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#tested-distros).
**This software is provided 'as-is' without any express or implied warranty.**

**If you're using Ubuntu or its derivatives please follow [these instructions](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#instructions-for-ubuntu-and-its-derivatives).**
Keep it mind any custom X.org configuration may get deleted or overwritten when switching modes.

### 🖥️ Supported display managers

- GDM
- SDDM
- LightDM

If your display manager isn't currently supported by EnvyControl you might have to [manually configure it](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#what-to-do-if-my-display-manager-is-not-supported).

## 💡 Tips
## ✨ Features

### Wayland session is missing on Gnome 43+
- 🐍 Written in Python 3+ for portability and compatibility
- 🐧 Works across all major Linux distros ([tested distros](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#tested-distros))
- 🖥️ Supports GDM, SDDM and LightDM display managers ([manual setup instructions](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#what-to-do-if-my-display-manager-is-not-supported) also available)
- 🔋 Save battery with integrated graphics mode
- 💻 PCI-Express Runtime D3 (RTD3) Power Management support for Turing and later
- 🎮 Coolbits support for GPU overclocking
- 🔥 Fix screen tearing with ForceCompositionPipeline

Latest changes in GDM now require `NVreg_PreserveVideoMemoryAllocations` kernel parameter to be set to 1 as well as `nvidia-suspend` services to be enabled for Wayland sessions to appear.
## 📖 Graphics modes

```
# 1. Re-run EnvyControl 2.2+ (either nvidia or hybrid mode)
sudo envycontrol -s nvidia
### Integrated

# 2. Now enable the required Nvidia services
sudo systemctl enable nvidia-{suspend,resume,hibernate}
- The integrated Intel or AMD iGPU is used exclusively
- Nvidia dGPU is turned off to reduce power consumption
- External screens cannot be used if the video ports are wired to the dGPU

# 3. Reboot
```
### Hybrid

### `/usr/share/sddm/scripts/Xsetup` is missing on my system
- Enables PRIME render offloading
- RTD3 allows the dGPU to be dynamically turned off when it's not used
- Available choices for the `--rtd3` flag (based on the [official documentation](http://us.download.nvidia.com/XFree86/Linux-x86_64/530.30.02/README/dynamicpowermanagement.html))
- `0` disabled
- `1` coarse-grained
- `2` fine-grained
- `3` fine-grained for Ampere and later
- Only works in Turing and later
- Performance on external screens might be reduced

Please run `sudo envycontrol --reset-sddm`.
### Nvidia

## ⬇️ Getting EnvyControl

### Arch Linux ([AUR](https://aur.archlinux.org/packages/envycontrol))
1. `yay -S envycontrol`.
2. Run `sudo envycontrol -s <MODE>` to switch graphics modes.

### From source

1. Clone this repository with `git clone https://github.com/bayasdev/envycontrol.git` or download the latest tarball from the releases page.
2. Run `sudo python envycontrol.py -s <MODE>` from the root of the repository to switch to a different graphics mode.

### Install globally as a pip package

- From the root of the cloned repository run `sudo pip install .`
- Now you can run `sudo envycontrol -s <MODE>` from any directory to switch graphics modes.
- The Nvidia dGPU is used exclusively
- Higher graphical performance and higher power consumption
- Recommended when working with external screens
- If facing screen tearing enable ForceCompositionPipeline with the `--force-comp` flag
- Allows overlocking (not recommended) with the `--coolbits` flag
- The default value is `28` bits however it can be manually adjusted according to this [guide](https://wiki.archlinux.org/title/NVIDIA/Tips_and_tricks#Overclocking_and_cooling)
- Wayland sessions default to hybrid mode

## ⚡️ Usage

```
usage: envycontrol.py [-h] [-v] [-s MODE] [-q] [--dm DISPLAY_MANAGER] [--reset] [--reset-sddm]
usage: envycontrol.py [-h] [-v] [-q] [-s MODE] [--dm DISPLAY_MANAGER] [--force-comp] [--coolbits [VALUE]] [--rtd3 [VALUE]] [--reset-sddm] [--reset] [--verbose]
options:
-h, --help show this help message and exit
-v, --version show this program's version number and exit
-v, --version Output the current version
-q, --query Query the current graphics mode
-s MODE, --switch MODE
switch the graphics mode, supported modes: integrated, hybrid, nvidia
-q, --query query the current graphics mode set by EnvyControl
--dm DISPLAY_MANAGER Manually specify your Display Manager. This is required only for systems without systemd.
Supported DMs: gdm, sddm, lightdm
--reset remove EnvyControl settings
--reset-sddm restore original SDDM Xsetup file
Switch the graphics mode. Available choices: integrated, hybrid, nvidia
--dm DISPLAY_MANAGER Manually specify your Display Manager for Nvidia mode. Available choices: gdm, gdm3, sddm, lightdm
--force-comp Enable ForceCompositionPipeline on Nvidia mode
--coolbits [VALUE] Enable Coolbits on Nvidia mode. Default if specified: 28
--rtd3 [VALUE] Setup PCI-Express Runtime D3 (RTD3) Power Management on Hybrid mode. Available choices: 0, 1, 2, 3. Default if specified: 2
--reset-sddm Restore default Xsetup file
--reset Revert changes made by EnvyControl
--verbose Enable verbose mode
```

**Read a detailed explanation about EnvyControl graphics modes [here](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions#graphics-modes-explained).**

### Usage examples
### Some examples

Set current graphics mode to `integrated` (power off the Nvidia dGPU):
Set graphics mode to integrated:

```
sudo envycontrol -s integrated
```

Set current graphics mode to `nvidia` (automatic display manager setup)
Set graphics mode to hybrid and enable coarse-grained power control:

```
sudo envycontrol -s nvidia
sudo envycontrol -s hybrid --rtd3
```

Set current graphics mode to `nvidia` and setup `SDDM` display manager
Set graphics mode to nvidia, enable ForceCompositionPipeline and Coolbits with a value of 24:

```
sudo envycontrol -s nvidia --dm sddm
sudo envycontrol -s nvidia --force-comp --coolbits 24
```

Set current graphics mode to nvidia and specify to setup LightDM display manager

```
sudo envycontrol -s nvidia --dm lightdm
```

Query the current graphics mode:
Expand All @@ -115,6 +114,31 @@ Query the current graphics mode:
envycontrol --query
```

Revert all changes made by EnvyControl:

```
sudo envycontrol --reset
```

## ⬇️ Getting EnvyControl

### Arch Linux ([AUR](https://aur.archlinux.org/packages/envycontrol))

1. `yay -S envycontrol`
2. Run `sudo envycontrol -s <MODE>` to switch graphics modes

### From source

1. Clone this repository with `git clone https://github.com/bayasdev/envycontrol.git` or download the latest tarball from the releases page
2. Run the script from the root of the repository like this `python envycontrol.py -s <MODE>`

💡 Replace `python` with `python3` on Ubuntu/Debian

### Install globally as a pip package

- From the root of the cloned repository run `sudo pip install .`
- Now you can run `sudo envycontrol -s <MODE>` from any directory to switch graphics modes.

## 📦 Gnome Extension

The [GPU profile selector](https://github.com/LorenzoMorelli/GPU_profile_selector) extension provides a simple way to switch between graphics modes in a few clicks, you can get it from [here](https://extensions.gnome.org/extension/5009/gpu-profile-selector/).
Expand All @@ -123,25 +147,31 @@ The [GPU profile selector](https://github.com/LorenzoMorelli/GPU_profile_selecto

![gpu profile selector screenshot](https://github.com/LorenzoMorelli/GPU_profile_selector/raw/main/img/extension_screenshot.png)

## ❓ Frequently Asked Questions (FAQ)
## 💡 Tips

- [See here](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions).
### Wayland session is missing on Gnome 43+

- Also read [fixes for some common problems](https://github.com/DaVikingMan/EnvyControl/wiki/Fixes-for-some-common-problems)
Latest changes in GDM now require `NVreg_PreserveVideoMemoryAllocations` kernel parameter to be set to 1 as well as `nvidia-suspend` services to be enabled for Wayland sessions to appear.

## 📝 Roadmap for v3
```
sudo systemctl enable nvidia-{suspend,resume,hibernate}
```

### `/usr/share/sddm/scripts/Xsetup` is missing on my system

Please run `sudo envycontrol --reset-sddm`.

## ❓ Frequently Asked Questions (FAQ)

- [ ] Make customizable options available as switches (eg: RTD3, composition pipeline, etc).
- [ ] Nvidia mode on Wayland (Nvidia needs to fix their Linux drivers first).
- [ ] Plasma applet.
- [ ] COPR package.
[Read here](https://github.com/bayasdev/envycontrol/wiki/Frequently-Asked-Questions)

## 🐞 I found a bug

Feel free to open an issue, don't forget to provide some basic info such as:

- Linux distribution
- Linux kernel version and type
- Linux kernel version
- Desktop Environment or Window Manager as well as your Display Manager
- Nvidia driver version
- EnvyControl version
- EnvyControl output with the `--verbose` flag
Loading

0 comments on commit de75209

Please sign in to comment.