Introduction

Until recently, I had been using a very old Dell laptop for my personal needs. However, when the motherboard started failing I decided it was time to look into options for replacing the laptop. I looked through many, many options from the “mainstream” manufacturers (e.g. Dell, Lenovo, Acer) and some of the lesser-known manufacturers who specialise in Linux (e.g. System76, Tuxedo Computers, Star Labs). Though I preferred the latter, neither they nor the mainstream manufacturers had options that met all of my goals. That’s when I remembered a relative new-comer to the laptop hardware industry: Framework.

Specifications

Checking their site, I found that the new Framework 13 met many of my needs:

• AMD options (instead of Intel or NVIDIA)
• Small form factor (13″)
• Matte display with 2560×1440 resolution (or higher) and 90Hz (or higher)
• UVC-supported webcam that wasn’t objectively awful
• No components soldered onto the motherboard (meaning, all upgradeable)
  • Even better if it came bare-bones so that I could choose the components
• A BIG bonus of the ports being expansion cards that are interchangeable
  • This allows the owner to install, say, 4 USB-C ports, or 2 of them with 2 HDMI ports for additional monitors, or any other combination needed at the time

So, I joined the pre-order list for the new Framework 13 with the following specs:

• AMD Ryzen 7 7840U with AMD 780M integrated GPU
• 13.5″ matte display at 2880×1920, 120Hz, and >500 nit brightness
• Omnivision 9.2MP OVO8X sensor webcam (assembled by Chicony)

and “brought my own” additional components:

• 96GiB (2×48) Crucial DDR5-5600 RAM kit
• 4TiB Samsung 990 Pro NVMe SSD
• Intel AX210NGW Wi-Fi card
• UGREEN Nexode X 100W USB-C charger
• UGREEN USB-C ethernet adapter

Configurations

Having gone through all that background information, I would like to document here some of the less-than-obvious configurations that I had to apply in order to get everything working nicely under Gentoo Linux. Though this guide focuses on Gentoo, much of the information is likely applicable to other Linux distributions.

This write-up isn’t meant to be an exhaustive list of Linux configurations for the Framework 13 laptop. There are some other great resources out there pertaining to getting this hardware working properly in Linux, including:

• The Arch Linux wiki specifically for the Framework 13 (note that it isn’t specific to this AMD version)
• The Gentoo Linux wiki for AMDGPU graphics

Now, onward to the configurations…

Firmware

AMD 780M iGPU

One of the more challenging parts to kernel configuration is the firmware blobs that are necessary for the AMD 780M iGPU (integrated graphics) that comes with the AMD Ryzen 7 7840U processor. Often with these chipsets, figuring out the firmware is a bit of trial-and-error by booting, checking dmesg to see which firmware blobs tried to load but couldn’t, adding them, and repeating until there are no further Failed to load firmware "$FIRMWARE_NAME.bin" error messages. Going through that process, I found the following list of firmware is needed:

dcn_3_1_4_dmcub.bin
gc_11_0_1_imu.bin
gc_11_0_1_me.bin
gc_11_0_1_mec.bin
gc_11_0_1_mes.bin
gc_11_0_1_mes1.bin
gc_11_0_1_mes_2.bin
gc_11_0_1_pfp.bin
gc_11_0_1_rlc.bin
psp_13_0_4_ta.bin
psp_13_0_4_toc.bin
sdma_6_0_1.bin
vcn_4_0_2.bin

I prefer to build the AMDGPU driver directly into the kernel instead of loading it as a module. As such, it’s necessary for me to list these firmware bin files directly via the kernel’s “Firmware loading facility”:

Device Drivers  --->
  Generic Driver Options --->
    Firmware loader  --->
      [*] Firmware loading facility 
      () 
      (/lib/firmware) Firmware blobs root directory

That results in this long single-line string being put into the “()” section of the kernel configuration:

amdgpu/dcn_3_1_4_dmcub.bin amdgpu/gc_11_0_1_imu.bin amdgpu/gc_11_0_1_me.bin amdgpu/gc_11_0_1_mec.bin amdgpu/gc_11_0_1_mes.bin amdgpu/gc_11_0_1_mes1.bin amdgpu/gc_11_0_1_mes_2.bin amdgpu/gc_11_0_1_pfp.bin amdgpu/gc_11_0_1_rlc.bin amdgpu/psp_13_0_4_ta.bin amdgpu/psp_13_0_4_toc.bin amdgpu/sdma_6_0_1.bin amdgpu/vcn_4_0_2.bin

If you don’t want to deal with that mess of building the firmware and driver directly into the kernel, you can always build the AMDGPU driver as a module and leave it out of your initramfs, so that it loads later in the boot process. It should then select the appropriate firmware blobs for you.

Intel AX210 WiFi

This generation of Framework 13 laptops (at least the AMD variants) ship with the AMD RZ616 WiFi chip, which is manufactured by MediaTek. This chipset has been known to have performance problems in Linux, and also requires at least a 6.5 kernel. Instead of dealing with those problems, I decided to replace it with an Intel AX210 WiFi chip.

As with the AMD iGPU mentioned above, the Intel AX210 WiFi chipset requires two firmware blobs be added to the kernel. In this case, the two needed ones are:

iwlwifi-ty-a0-gf-a0-89.ucode
iwlwifi-ty-a0-gf-a0.pnvm

and they can simply be appended to the “Firmware loading facility” line mentioned above.

Display

One of the reasons that I wanted the Framework 13 was this generation’s new display panel. I like that it’s a 13.5″ display with matte finish, 2880×1920 resolution, and 120Hz refresh rate. However, the colours were quite drab by default. By decoding the EDID for the panel, I found the actual model to be a BOE NE135A1M-NY1:

$ cat /sys/class/drm/card0-eDP-1/edid | edid-decode | grep -e 'Manufacturer' -e 'Display Product Name'
    Manufacturer: BOE
    Display Product Name: 'NE135A1M-NY1'

Knowing the panel manufacturer and model allowed me to get an Image Colour Management (ICM) file for the panel, which is essentially a colour profile for a more accurate calibration. I have uploaded the ICM file here for safekeeping (which you are free to download directly), but it was originally found on the NotebookCheck website.

In Linux, the method for applying a colour profile varies based on your Desktop Environment or Window Manager. For instance, KDE and GNOME both have colour management GUI applications available with easy ways of importing and managing profiles. I use the OpenBox Window Manager, so I would prefer to have a desktop-agnostic approach. The solution for me is a combination of colord and xiccd.

The colord application allows for importing the colour profile and assigning it to a particular device (i.e. a particular display panel), and then xiccd acts as a bridge between colord and Xorg. It is xiccd that will automatically apply the colour profile to the panel when starting Xorg, and subsequently, my OpenBox Window Manager session.

## Get the Device ID of the display panel:
$ colormgr get-devices | grep 'Device ID'
Device ID:     xrandr-BOE-NE135A1M-NY1

## Copy the ICM file to the proper location and change the extension:
$ sudo mv $CURRENT_LOCATION/BOE0CB4.icm /usr/share/color/icc/colord/BOE0CB4.icc

## Import the colour profile into colormgr:
$ colormgr import-profile /usr/share/color/icc/colord/BOE0CB4.icc

## Find the Profile ID for the newly-imported colour profile:
$ colormgr get-profiles | grep -A1 'BOE0CB4.icc'
Filename:      /usr/share/color/icc/colord/BOE0CB4.icc
Profile ID:    icc-6cf5096a086792f1797bc4fa262bdfae

## Using the Device ID and the Profile ID, add the profile to the device:
## Syntax is:  colormgr device-add-profile $DEVICE_ID $PROFILE_ID$ colormgr device-add-profile xrandr-BOE-NE135A1M-NY1 icc-6cf5096a086792f1797bc4fa262bdfa
## Make that profile the default for the device:
## Syntax is:  colormgr device-make-profile-default $DEVICE_ID $PROFILE_ID
$ colormgr device-make-profile-default xrandr-BOE-NE135A1M-NY1 icc-6cf5096a086792f1797bc4fa262bdfae

## Confirm that the colour profile is applied to the device:
$ colormgr get-devices | grep -A2 'xrandr-BOE-NE135A1M-NY1'
Device ID:     xrandr-BOE-NE135A1M-NY1
Profile 1:     icc-6cf5096a086792f1797bc4fa262bdfae
               /usr/share/color/icc/colord/BOE0CB4.icc

As mentioned above, xiccd has to be running with the Window Manager session, so I choose to have it start automatically with OpenBox by adding xiccd & to ~/.config/openbox/autostart.

Keyboard bindings

As said, I use OpenBox as my Window Manager, so there isn’t a GUI application by default for adding or modifying the function keys. Instead, I mapped the keys to the actual functions that I wanted to perform. Here are my specific choices (with comments for the details of each binding):

    <!-- Keybinding for exiting Openbox with prompt with Alt+Esc -->
    <keybind key="A-Escape">
      <action name="Exit">
        <prompt>yes</prompt>
      </action>
    </keybind>
    <!-- Keybinding for showing the menu with left Windows key -->
    <keybind key="Super_L">
      <action name="ShowMenu">
        <menu>root-menu</menu>
      </action>
    </keybind>
    <!-- Keybinding for muting audio -->
    <keybind key="XF86AudioMute">
      <action name="Execute">
        <command>/usr/bin/amixer set Master toggle</command>
      </action>
    </keybind>
    <!-- Keybinding for lowering audio volume -->
    <keybind key="XF86AudioLowerVolume">
      <action name="Execute">
        <command>/usr/bin/amixer set Master 2%-</command>
      </action>
    </keybind>
    <!-- Keybinding for raising audio volume -->
    <keybind key="XF86AudioRaiseVolume">
      <action name="Execute">
        <command>/usr/bin/amixer set Master 2%+</command>
      </action>
    </keybind>
    <!-- Keybinding for audio previous track set in Audacious -->
    <!-- Keybinding for audio pause/play set in Audacious -->
    <!-- Keybinding for audio next track set in Audacious -->
    <!-- Keybinding for decreasing the brightness -->
    <keybind key="XF86MonBrightnessDown">
      <action name="Execute">
        <command>/usr/bin/xbacklight -dec 10</command>
      </action>
    </keybind>
    <!-- Keybinding for increasing the brightness -->
    <keybind key="XF86MonBrightnessUp">
      <action name="Execute">
        <command>/usr/bin/xbacklight -inc 10</command>
      </action>
    </keybind>

UGREEN USB-C ethernet adapter

Even though this particular adapter isn’t directly related to the Framework 13, I think it warrants a section here as I prefer it to the protrusive Framework Ethernet Expansion Card. The UGREEN USB-C gigabit ethernet adapter is based on the ASIX AX88179A chipset, which is supported directly in recent Linux kernels:

Device Drivers  --->
  Network Device Support --->
    USB Network Adapters --> 
      <*> Multipurpose USB Networking Framework
      <*>   ASIX AX88XXX Based USB 2.0 Ethernet Adapters
      <*>   ASIX AX88179/178A USB 3.0/2.0 to Gigabit Ethernet
      ...
      <*>   CDC NCM Support

The “gotcha” here, though, is that enabling the two ASIX AX88 drivers doesn’t automatically include the needed ‘CDC NCM Support’. For more information, see the following kernel bug 217204.

Conclusion

Hopefully this guide helped answer some questions about configuring the Framework 13’s hardware under Linux. As said, it wasn’t meant to be an exhaustive guide, but rather one focusing on some of the “gotchas” that I encountered when setting up mine with Gentoo Linux. If you run into any trouble, please feel free to comment and I will try to help.