Skip to content

General Configuration

Jump to bottom Edit New page
Derek J. Clark edited this page Feb 17, 2024 · 46 revisions

Introduction

ChimeraOS's design philosophy is to cast a wide net when it comes to compatibility of hardware. The ability to install on as many configurations as possible sometimes presents the opportunity for conflicts with necessary quirks or workarounds for some devices. As such, these are not normally enabled by default but if well understood they can be included in the image in a disabled state or documented with steps to reproduce. This page attempts to document general quirks and how to enable them.

Session Switching

Multiple sessions come pre-installed in ChimeraOS. A session is the selected user interface that you want to enable at boot time.

Available Sessions

steam-plus

Provides the Steam Big Picture UI with an additional OpenGamepadUI overlay. Primarily for TDP control, this is a transitional mode while we work on getting OpenGamepadUI feature complete. For many handhelds a button has been mapped on the built in controller to open the overlay. If using a controller the button combination guide + b will open the overlay.

opengamepadui

Provides a full replacement UI. It is intended as a multi-library launcher ecosystem with built in plugin support. Currently only the Steam plugin is available, but GOG and EGS are in development with plans for emulator support as well. This session also allows for updates to the client without the need for full OS releases.

steam

The default vanilla Steam user session.

desktop

Switch to desktop mode if for some reason "switch to desktop mode" is not working, or you always want to boot directly to the desktop

Identifying and Selecting a Session

Running the chimera-session command with no arguments will display the full list of sessions. The session with a * preceding it is the currently selected one

[gamer@lego ~]$ chimera-session
  desktop
  desktop-xorg
* steam
  steam-plus
  opengamepadui

Note: If no * is indicated, no session override has been done and you are using the default steam session

To select a session, run chimera-session <session-name> and the session will be loaded, e.g. chimera-session steam-plus

Firmware Overrides

Some devices have bugs in their ACPI tables or display firmware that can cause issues with various devices. The device-quirks scripts are able to install overrides that resolve these issues. The ChimeraOS team intentionally disables DSDT and EDID overrides by default. This decision is made to ensure that users have full control over their firmware settings and can make an informed decision about enabling overrides. Despite the community's extensive testing and belief in the safety of the override process, it is important to note that the ChimeraOS team intentionally leaves it up to the user to decide whether to take the "risk" of enabling DSDT overrides.

Enabling

There are two ways to enable firmware overrides:

  • Select the "Advanced Install" option when doing a fresh install or repair install. This will enable firmware overrides until disabled manually
  • Edit /etc/device-quirks/device-quirks.conf and change export USE_FIRMWARE_OVERRIDES=0 to export USE_FIRMWARE_OVERRIDES=1

Applying

To apply firmware overrides, as well as other configuration tweaks for your device, simply run frzr-tweaks with sudo to run the script to identify your device and apply changes.

For DSDT overrides, your system's checksum will be compared against the database of "fixed" DSDT's. If your checksum matches, the DSDT override will be installed and metadata from your BIOS is recorded. During upgrades, if the metadata information matches your current BIOS, the previously used DSDT can be loaded. Upgrading your BIOS will cause this check to fail and after the next boot your system will load without an override. If your new BIOS is supported by a quirk it will be applied by running frzr-tweaks again manually. If it is not supported but still requires an override, please open an issue on the device quirks GitHub page.

TDP Controls

⚠️ Warning

TDP control adjustment can have negative affects if set to levels that exceed the power or thermal capacity of your device. Not all device manufacturers have fully functional or entirely reliable thermal cutouts. Excessive settings or faulty manufacturing can have adverse affects on the longevity of your hardware and are used at you own risk

For handheld devices, it can be useful to adjust the amount of power used by the system to help preserve the battery or improve performance over initial settings. The TDP controls built into the Steam client UI are hard coded by Valve to a limit of 15W. It uses the same power limit path as dedicated AMD GPU's and thus cannot be enabled in ChimeraOS as it would limit the power of all AMD dedicated GPU's to 15w as well.

There are currently five methods of TDP Control in ChimeraOS:

  • The Chimera App in v42+ has support for controlling the TDP of the AYANEO 2. This is an operational test to see if this way of control is a good path forward.
  • The OpenGamepadUI Sessions can be used with AMD APU's and some Intel iGPU's.
  • The Decky-loader plugin PowerControl can be installed. There are some issues with decky-loader and its plugins breaking due to updates to the UI from Valve.
  • The Decky-loader plugin SimpleDeckyTDP can be installed.
  • Simple Ryzen TDP can be installed and added as a steam library item.

Chimera WebUI

  • Instructions to come

OpenGamepadUI

OpengamepadUI supports most AMD APU's and some Intel iGPU's. It is available in v42+ of ChimeraOS. If available for your hardware it can control the following settings:

  • Toggle CPU Boosting
  • Toggle SMT
  • Set max number of usable cores
  • Adjust Average TDP
  • Adjust peak TDP
  • Adjust Tjunction temperature limit
  • Adjust GPU Min/Max Clock
  • Adjust power profiles

The software will automatically detect and enable any detected capabilities. See session switching above to use one of the two methods OpenGamepadUI provides

PowerControl with DeckyLoader

⚠️ Warning PowerControl only works on AMD APU's. It will not detect the limits of your hardware so use caution as unsafe TDP levels can be set. Due to DeckyLoaders method of patching the SteamDeck UI it can break frequently and require the loader and the plugins to require updates. As a result, ChimeraOS does not recommend using these tools.

The following options are available for adjustment in PowerControl:

  • Toggle CPU boost
  • Toggle SMT
  • Adjust Core Count
  • Adjsut TDP
  • Adjust GPU frequency

Install DeckyLoader

Use the fast install by running the following command in console:

curl -L https://github.com/SteamDeckHomebrew/decky-installer/releases/latest/download/install_release.sh | sh

type your password when prompted, default password is gamer.

Full instructions at the Decky-Loader installation guide on their Github.

Install PowerControl

Navigate to https://github.com/mengmeet/PowerControl/releases and identify the latest release.

Download the latest release, then extract the file.

Then move the entire PowerControl folder to /home/gamer/homebrew/plugins/. Note that you might need to move it with sudo.

After adding it to the correct folder, reboot your device.

  • Once back in the Steam Deck UI open the Quick Access Menu, either by pressing guide + A or if it is a device managed by HandyGCCS there is likely a dedicated QAM button.
  • An ElectricPlug Icon will be present at the bottom for DeckyLoader, highlight it and press A
  • PowerControl will now be present in the DeckyLoader list.

SimpleDeckyTDP

Note that ChimeraOS should already ship with ryzenadj pre-installed, which is one of the requirements for SimpleDeckyTDP.

  1. If not already installed, install decky loader: curl -L https://github.com/SteamDeckHomebrew/decky-installer/releases/latest/download/install_release.sh | sh
  2. Install Simple Decky TDP: curl -L https://github.com/aarron-lee/SimpleDeckyTDP/raw/main/install.sh | sh
  3. Reboot, you should see SimpleDeckyTDP in your Steam QAM under the new tab for Decky plugins

For full install instructions, see here

Simple Ryzen TDP

Follow the Installation Guide on the Simple Ryzen TDP Github.

Screen Rotation

Given the verity of mobile devices they can all handle gamescope differently. While we make every effort to ensure compatibility across as many devices as possible some devices may require some additional tweaks. A common tweak that is required is rotating the screen either left or right when loading into gamescope.

Gamescope is initiated when the OS loads, and when you click "Game Mode" from the desktop environment. It is a highly flexible system but can work differently on mobile devices. After preforming these steps, you will have a custom Gamescope launch command that should address screen rotation. In these steps you will be asked to create a custom XX-my.conf file where the XX denotes order it should be run. We will use 01 as the numeral in the fix below.

Note: The variable that handles rotation is --force-orientation right, your device may require this to be right, or left. The GPD Win 2 requires the value "right" for the Gamescope rotation to be correct.

  1. Boot the system normally
  2. In GamepadUI press the “menu” button in the bottom left of the screen
  3. In the menu click “Shutdown” >> “Switch to Desktop”
  4. At the Desktop click the icon with 9 squares >> Applications
  5. Open Console
  6. Use the following command:
echo “export GAMESCOPECMD="/usr/bin/gamescope -e --generate-drm-mode-fixed --xwayland-count 2 -O *,DSI-1, --default-touch-mode --hide-cursor-delay 3000 --fade-out-duration 200 --force-orientation right” > ~/.config/environment.d/01-my.conf”
  1. Verify the file was created, you can do so by running this command:
“cat ~/.config/environment.d/01-my.conf”
  1. Reboot your system.

Depending on the system you may need to modify the above command, we'll update the wiki with Gamescope variables.

Multi-GPU Management Utility (eGPU and iGPU + Dedicated GPU Configurations)

Starting with chimeraOS v42 it is now possible to configure what GPU you want to be used for the gamescope-session making it really easy to to specify what GPU you want to be used for gamescope. This helps us do the following:

  • Use an iGPU of any compatible CPU to do the compositing and use a dedicated GPU to run the games. (Extremely useful for Nvidia)
  • Configure gamescope to prefer an eGPU whenever it's available at boot instead of the integrated graphics

When using this utility to use an iGPU you will need to plug into your motherboard and not the GPU itself or else you won't get an image on the screen.

To do this you will need the following:

  • Have a motherboard that allows you to enable both the iGPU and dedicated GPU at the same time (usually called iGPU multi-montior support or something similar). In same cases using auto will work just fine if the setting is available.
  • A keyboard to enter the TTY or type into a console in the desktop to use the export-gpu utility.

To run the utility all you need to do is either open console from the activities menu on the desktop or use the TTY, see here for instructions on how to do that.

Type export-gpu and follow the simple instructions to create the configuration needed for gamescope-session and reboot the system.

Sometimes plugging into the motherboard is all you need to do to get things working, but you may find that session-switching does not work. This is the time where you need to use the export-gpu utility to make sure gamescope always uses the iGPU and not use the dedicated GPU by mistake.

This is useful for desktops AND laptops alike. If you have a Ryzen CPU with an iGPU and a RTX 4090 this is your way of using Nvidia with ChimeraOS with excellent performance and as trouble free as it can be! You can use an Intel CPU as well, and it will be fine, but AMD is the preferred option.

Dual booting Windows and ChimeraOS on the same Disk

Some considerations first:

1. This guide assumes you already have a fully functional installation of Windows 10 or later on the target disk, complete with a properly configured EFI partition.

2. This guide was made with the ROG Ally as a target device. For others you may be able to simplify the process.

  1. Enter the BIOS and disable Secure Boot

Some users have encountered issues with this step. For example, on the ROG Ally, ASUS sometimes resets the value. To successfully disable it, I disabled Secure Boot, booted into Windows, unlocked the HD with a Bitlocker key obtained from the Microsoft website, and on the next boot, Secure Boot was successfully disabled.

  1. Disable Bitlocker (if you have it disabled, skip this step)

In Windows settings, search for 'Bitlocker' or 'Encryption' and disable disk encryption. This process can take approximately one hour as it decrypts each file on the disk.

  1. Prepare to Install ChimeraOS from a USB Stick

You can use Balena Etcher for this step.

  1. Boot from the ChimeraOS USB Stick via BIOS

You should have another disk connected to the hub, either another USB drive or a micro SD card. This is because the system will not allow you to install ChimeraOS on the same disk as Windows without completely erasing it. Hence, we first install it onto an intermediate disk.

  1. Shrink the Data Partition in Windows

There are multiple ways to do this; choose the method that works best for you. I used the Device Manager that comes bundled with Windows.

  1. Migrate frzr_root partition to the internal drive

After installing ChimeraOS, migrate the big partition (frzr_root) to the internal NVMe drive using the space you freed in step 5. The duration of this process will be proportional to the size of the partition being migrated. For that step you can use a tool called "Macrium Reflect" that has a free trial.

  1. Patch the EFI Folder

Manually merge the EFI partition created by the ChimeraOS installer with the one on the internal NVMe. If you installed rEFInd previously, there's no need to replace '/EFI/BOOT/BOOTX64.efi', as we will use the Systemd one to boot ChimeraOS.

  1. Create a Boot Option in BIOS for ChimeraOS

In BIOS, go to advanced mode and to Bios tab, create a manual boot entry pointing to '/EFI/systemd/systemd-bootx64.efi' and name it 'ChimeraOS'. You can use this to boot directly.

  1. Partition Labels Required by ChimeraOS

ChimeraOS expects to find two partitions by label:

  • frzr_root: This is where your system and home directories are located. If you cloned using the software mentioned above, the label will be automatically applied. If not apply it using e2label /dev/nvme0n1pX frzr_root (replace X with the right partition)
  • frzr_efi: This is the boot partition. You should rename it using fatlabel /dev/nvme0n1p1 frzr_efi.
  1. Dual Boot Windows and ChimeraOS

At this point, you should be able to dual boot Windows and ChimeraOS and also apply OTA updates from ChimeraOS without affecting Windows. You can change the boot order in BIOS to choose the default system.

  1. Bonus Step: Install rEFInd to Manage Dual Boot

Although it might seem redundant now (on the Ally, more information bellow), installing rEFInd could be very useful in the near future. Here are the steps:

  • Install rEFInd on the internal NVMe drive by following the instructions on the rEFInd page.

  • Configure rEFInd. There are many documents available to guide you, and the sample configuration file provided is comprehensive. Perhaps someone can provide examples at a later stage.

  • IMPORTANT: On the Ally, currently, the D-pad and touchscreen will only work in rEFInd if you boot manually from BIOS. We are hoping for a solution from ASUS to address this issue.

Add a custom footer
Add a custom sidebar
Clone this wiki locally