The Framework Laptop 16 is my new laptop of choice that I purchased to replace my dying older machine. While this laptop enjoys official Linux support, there are still a few things to take care of post-install.
This might be useful for people who stumble onto this gist to debug. My laptop is configured as such, with notes on the Linux support:
- CPU - AMD Ryzen 7 7840HS
- GPU - Integrated UMA graphics (AMD Radeon 780M)
- RAM - Kingston 32 GB kit (2x16), 5600 MT/s, CL40 SODIMM memory
- SSD - WD_Black SN850x NVMe 4x4 m.2 2280 format, 2 TB
- I previously used a SK Hynix P41 Platinum, which I recommend against due to the buggy controller, constant crashes during write operations, and the fact that it does not report its own size correctly to
udisks.
- I previously used a SK Hynix P41 Platinum, which I recommend against due to the buggy controller, constant crashes during write operations, and the fact that it does not report its own size correctly to
Before we proceed with Fedora installation, we need to get a few things done in the BIOS. While booting up the laptop, press F2. Then, select "BIOS Setup". Here, make sure to change the following settings:
- Advanced
- iGPU Memory -->
Gaming(hardware-reserves 4 GB of memory to the iGPU) - Linux Audio Compatibility -->
Linux - (optional) Battery Charge Limit -->
80(choose this if you want to preserve battery longevity, but still need to have the battery ready for use on battery)60(choose this if you mainly use your laptop connected to a power outlet - wears the battery down even slower)
- (optional / subjective) Power Button LED Brightness Level -->
Low(now better matches the keyboard module!)
- iGPU Memory -->
It is good practice to reset your BIOS (Load Optimal Settings) if you just upgraded to BIOS version 3.03 and re-do these settings.
I chose Fedora Workstation 41 because it's officially support and it's a sweet development environment all in all - podman and toolbox are nice to work with, dnf + gdb integration, easy-to-install debug symbols for all packages to help debug upstream, and great support for all on-board hardware as well as nice support for multi-touch gestures are a compelling package.
Flathub is the accepted central repository to download Flatpak applications through. Flatpak is the next-generation container-based, distro-agnostic, arbitrarily sandboxed packaging system for GUI applications. It provides a host of important advantages over traditional packaging, except for applications like software development, so I recommend using it for most software you install - especially proprietary commercial software, which benefits greatly from the stable and tested runtime target.
flatpak remote-add --if-not-exists flathub https://dl.flathub.org/repo/flathub.flatpakrepoBy default, all codecs and hardware video acceleration are not configured, although they work splendidly with the onboard AMD platform. This is easily remedied with RPMFusion. These instructions may be out of date if a lot of time has passed - refer to upstream website to double check.
First, add both the free and non-free repos:
sudo dnf -y install https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm && \
sudo dnf -y config-manager --enable fedora-cisco-openh264 && \
sudo dnf -y groupupdate core # Entries in GNOME-SoftwareNext, swap ffmpeg-free for full-fledged ffmpeg:
sudo dnf -y swap ffmpeg-free ffmpeg --allowerasingNext, install the codecs:
sudo dnf -y groupupdate multimedia --setopt="install_weak_deps=False" --exclude=PackageKit-gstreamer-plugin && \
sudo dnf -y groupupdate sound-and-videoIf you want to have hardware acceleration for codecs other than av1 and vp9, you may install the patched mesa vaapi drivers. Note that I have personally reverted this since this has caused me some issues with updates when the rpmfusion repos were not caught up to the Fedora repos, and as a troubleshooting step to try and reduce GPU crashes.
sudo dnf -y swap mesa-va-drivers mesa-va-drivers-freeworld && \
sudo dnf -y swap mesa-vdpau-drivers mesa-vdpau-drivers-freeworld && \
sudo dnf -y swap mesa-va-drivers.i686 mesa-va-drivers-freeworld.i686 && \
sudo dnf -y swap mesa-vdpau-drivers.i686 mesa-vdpau-drivers-freeworld.i686The integrated Radeon 780M in this laptop is not particularly stable and it is pretty prone to hanging, crashing and several other artifacts - common GPU-related bugs are random screen flickering, or the computer slowing down to the point where it updates the screen once every N seconds. I have, however, found some mitigations for the constant crashes.
This section is currently full of many different solutions until the community settles on an universal fix / workaround. I will remove the extra fluff as soon as a consensus is reached.
To apply all of the AMDGPU flags that I applied in one command:
grubby --update-kernel=ALL --args="amdgpu.abmlevel=0 amdgpu.sg_display=0 amdgpu.dcdebugmask=0x410"Linux 6.11.3 seems to have a mitigation for the above bug. You should really run Linux 6.11.3 or more recent. In case you cannot do that or the crashes persist, try with the following troubleshooting steps.
Update 28/10/2024: This problem seems resolved, but it was replaced by other artifcats.
Update 08/11/2024: There seems to be a regression introduced by Panel Replay. You can try disabling all PSR, PSR-SU and PR by replacing amdgpu.dcdebugmask=0x10 (only disables PSR, leaves PSR-SU and PR) with amdgpu.dcdebugmask=410 (disables all three). When you turn off PR, you must also turn off PSR and PSR-SU to avoid problems and heavy framebuffer corruption / flickering.
Try these in order. Do not try any of these without having tried the preceding items first. The compromises to functionality and efficiency get bigger the further down this list.
Graphical artifacts and random parts of the screen get corrupted, particularly when scrolling or right clicking
Try to disable PSR, PSR-SU (both should be covered by 0x10 and PR (covered by 0x400):
grubby --update-kernel=ALL --args="amdgpu.dcdebugmask=0x410"Laptop becomes very laggy and starts working at a very low fps --> Disable PSR (Panel Self Refresh) on AMDGPU
Panel Self Refresh is a very useful power-saving feature that limits the frequency at which the internal monitor gets refreshed according to how often the GPU actually has to draw new content. Without PSR, your panel refreshes 165 times per second, which is very battery-intensive. Unfortunately, multiple users report that this feature is currently broken on the Framework Laptop 16 AMD laptop. You can disable this feature to mitigate or reduce the times the GPU misbehaves:
sudo grubby --update-kernel=ALL --args="amdgpu.dcdebugmask=0x10"You may check the documentation to verify for yourself that hex 10 in the DC_DEBUG_MASK enum corresponds to DC_DISABLE_PSR.
VAAPI is the API that gets used on Linux for decoding video streams in hardware. Unfortunately, some AMD APU users face problems with VAAPI. The symptoms are, most often, a panel that flickers - sometimes several times in a row - when VAAPI is used.
We may prevent applications from loading the AMD VAAPI driver by overriding it.
Add this environment variable to /etc/environment using a root shell,
echo "LIBVA_DRIVER_NAME=no" >> /etc/environmentAnd reboot.
If you have tried the above two steps and your GPU is still causing issues, you should try disabling AMD Scatter/Gather as a last-ditch solution. It is not a "free" solution, and it might cause other problems when memory pressure on the APU is high. Nevertheless, it is worth trying in desperate cases, and several Framework users have reported some degree of success with it:
sudo grubby --update-kernel=ALL --args="amdgpu.sg_display=0"I really hope you, unlike me, did not reach this point. You likely have defective hardware. It's time to open a RMA ticket. Good luck.
As of Linux kernel 6.9, AMD added the equivalent of Windows feature AMD Vari-Bright to Linux. It is a power saving feature that reduces the contrast and brightness of the panel when on battery and especially when using a power-saving setting in order to preserve battery. It makes the display colours very inaccurate and unpleasant to look at when the laptop is being used on battery.
To revert this, add the amdgpu.abmlevel=0 parameter to the kernel:
grubby --update-kernel=ALL --args="amdgpu.abmlevel=0"Universal Blue is a great Linux distribution - an immutable one with several flavours, based upon Fedora Silverblue, which ships ISOs with optimized configurations for several laptop vendors. We will be stealing the set of Framework 16-specific udev rules from their configuration and copy it over to our vanilla Fedora configuration, though. These rules fix a bug that causes the laptop to wake up during sleep in a backpack when the very flexy lid presses on the keyboard, and it also works around a bug that causes the Audio Expansion Card from getting put to sleep.
The udev rules are here.
wget https://github.com/ublue-os/config/blob/main/files/etc/udev/rules.d/50-framework16.rules
sudo cp 50-framework16.rules /etc/udev/rules.d/
sudo udevadm control --reload
sudo udevadm triggerLinux 6.11 has introduced a regression that causes Bluetooth to interfere with wake from sleep with the default Mediatek Wi-Fi adapter.
Apply Framework's workaround to retain sleep and wake behaviour until this is fixed. Copied from this link for your comfort,
curl -s https://raw.githubusercontent.com/FrameworkComputer/linux-docs/refs/heads/main/hibernation/kernel-6-11-workarounds/rfkill-suspender.sh -o rfkill-suspender.sh && clear && bash rfkill-suspender.shThe internal keyboard has QMK + VIA, and you can use keyboard.frame.work from any Chromium-based browser to configure it and access the VIA web interface.
To be able to to this, you need to follow this guide on how to set up the QMK udev rules on Linux.
wget https://github.com/qmk/qmk_firmware/blob/master/util/udev/50-qmk.rules
sudo cp 50-qmk.rules /etc/udev/rules.d
sudo udevadm control --reload-rules
sudo udevadm triggerThe internal speakers can be made sound much better after applying an EasyEffects profile. EasyEffects is an application that allows you to apply various filters and equalization to input and output devices. This is effectively the same trick that a lot of manufacturers use in their own customized audio drivers that they ship on their own OEM Windows image to make the speakers sound better. Linux does not do any of that by default, and by default, you are getting the raw output.
Simply follow Framework's guide. Unless it has changed, I will copy the same quick setup command that Framework has here:
curl https://raw.githubusercontent.com/FrameworkComputer/linux-docs/main/easy-effects/Fedora-easy-effects-16-installer.sh | bashAfter that, click on "Presets" and click "Load" next to the new fw16-easy-effects profile.
This panel supports VRR (Variable Refresh Rate), a way to match the refresh rate to the frame rate that is being output by a full-screen video or a game. Run this command to enable it. Do mind that this feature is still experimental, and you might want to skip this if you don't want to deal with bugs.
gsettings set org.gnome.mutter experimental-features "['variable-refresh-rate','scale-monitor-framebuffer',`xwayland-native-scaling`]"You may then access Settings > Display and toggle both of those features on after restarting the compositor.
Ensure Fractional Scaling is properly configured if you upgraded to Feodra 41+ from a previous version
Fedora Workstation 41 finally provides working fractional scaling out of the box. However, there are cases where it does not get configured properly for users upgrading from a previous version of the OS. To ensure the fractional scaling is properly configured, run:
gsettings reset org.gnome.mutter experimental-featuresAnd log out and back in.
This will enable experimental features scale-monitor-framebuffer and xwayland-native-scaling, which are the Fedora 41 default.
If you want to add something else, like VRR, after this step, query the default active options:
gsettings get org.gnome.mutter experimental-featuresThen copy the array, add whatever other non-default feature you want to add, and plug it in the next command. For example, to enable VRR again on Fedora 41g, you would:
gsettings set org.gnome.mutter experimental-features ['scale-monitor-framebuffer', 'xwayland-native-scaling','variable-refresh-rate']Fractional scaling should now be configurable from the settings and seamlessly followed by all your apps - including XWayland clients.
What to do in case of...
The first thing you want to do is rule out DRAM failure.
First of all, install memtest86+:
sudo dnf -y install memtest86+After that, reboot your laptop. While it's booting, keep pressing F2. Navigate into "Administer Secure Boot", then to "Enforce Secure Boot" and set that value to "Disabled". Press F10, and the reboot will once again reboot. Keep pressing the arrow down button to reveal GRUB. Then, navigate down to Memory Test (memtest86+) and run it. Let it run overnight, preferably for a good 9-10 hours. After you have a solid number of "Pass" and no failures, you can safely assume that memory instability is not the reason for your crashes.
If your problems persist, contact Support. You will be guided through further troubleshooting steps like performing a mainboard state reset, and you will get an hardware replacement if none of the steps solve the problem for you.
Some Linux games will have graphical artifacts, because they bundled dependencies are too old for the very recent RDNA 3 graphics. This is easily worked around by forcing the Windows version through Proton. This will, oddly enough, load modern MESA and other dependencies, eliminating the artifacts and improving the performance.
Sometimes, the subwoofers somehow stop working and only the tweeters stay on. To quickly fix this, open and close EasyEffects, or reboot.
Plug the official charger out and back in
Flip your laptop, unlatch the Expansion Card latch that holds your USB-A card snug, then remove the card, wait a few seconds, and insert it again.
There is a suspend bug with this laptop tha triggers when you suspend your laptop before unplugging it from AC power. To make your laptop sleep properly, make sure to remove the charger and wait a few seconds before you suspend the laptop.
Par for course.
systemctl restart fprintd