Framework Laptop

Resources

The Framework Laptop, released in 2021, is a laptop that focuses on extreme repairability. The DIY edition in particular comes without an OS and the developers and community are currently focused on supporting Arch Linux as an alternative to Windows.

Hardware

Intel Tiger Lake (11th-gen)

Device	Make/model	Status	Vendor ID / Product ID	Kernel driver(s)	Kernel version	Notes
Chipset	Intel Tiger Lake	Works	[multiple]	i801_smbus intel_ish_ipc intel_lpss_pci intel_pmt	5.14.15
Video card	Intel Tiger Lake-LP GT2	Works	f111:0001	i915	5.14.15	i965 and iris USE flags
Sound card	Intel Tiger Lake-LP Smart Sound	Works	8086:a0c8:f111:0001	snd_hda_intel, snd_soc_sof_tigerlake	5.14.15	Also requires either Realtek or IDT HD codec, depending on date of manufacture^[1]
Wireless network card	Intel AX210	Works	8086:2725:8086:0024	iwlwifi	5.14.15	Needs firmware from sys-kernel/linux-firmware
Bluetooth	Intel AX210	Works		bluetooth	5.14.15
Touchpad	PixArt PIXA3854	Works	093A:0274	hid_multitouch	5.14.15	Also depends on i2c_designware_core, intel_ishtp_hid
Fingerprint Reader	Goodix USB2.0 MISC	Works	27c6:609c			Requires sys-auth/fprintd-1.94.0
Webcam	Realtek Laptop Camera	Works	0bda:5634	uvc	5.15.8 (as tested)

Intel Alder Lake (12th-gen)

Device	Make/model	Status	Notes
Chipset	Intel Alder Lake	Works
Video card	Intel Alder Lake-LP GT2	Works
Sound card	Intel Alder Lake-LP Smart Sound	Works
Wireless network card	Intel AX210	Works
Bluetooth	Intel AX210	Works
Touchpad	PixArt PIXA3854	Works	Depends on pinctrl_tigerlake and not pinctrl_alderlake
Fingerprint Reader	Goodix USB2.0 MISC	Works
Webcam	Realtek Laptop Camera	Works
Ambient light sensor		Works

Expansion cards

The Framework Laptop features four modular expansion card slots allowing for custom port configurations. Each connects to an underlying USB-C interface. See https://frame.work/marketplace/expansion-cards

Device	Make/model	Status	Vendor ID / Product ID	Kernel driver(s)	Kernel version	Notes
DisplayPort	Framework	Works	32ac:0003
2.5GB Ethernet	Framework (RTL8156)	Works	0bda:8156	r8152 (net-misc/r8152)		Will show up but never gain link with vanilla kernel. Need official driver kernel module from net-misc/r8152.
HDMI	Framework	Works	32ac:0002
SSD	Framework	Works	13fe:6500 (1TB)	usb_storage, uas
MicroSD	Framework	Works	090c:3350	usb_storage, uas
USB-A	Framework	Works		xhci_hcd
USB-C	Framework	Works		xhci_hcd	5.14.15	Required for charging

Installation

Because of some boot menu and device selection issues, it may be necessary to update to BIOS version 3.06 before installing. See: https://community.frame.work/t/public-beta-test-bios-v3-06-driver-bundle-2021-10-29/10167 This update is also necessary to support the Tempo audio codec in the post-Oct 2021 Framework laptops.

There is not yet a Linux-based BIOS update mechanism, but the update can be run in a Windows PE environment such as Windows 10 setup media or Hiren's BootCD PE

Firmware

Firmware from sys-kernel/linux-firmware is needed for the GPU, wireless, and bluetooth interfaces. The TigerLake GPU firmware in particular needs to be loaded immediately at boot, so it must be included as a kernel blob or on an init ramdisk. See: Intel#Firmware

Kernel

There have been significant stability issues with Wifi and Bluetooth in kernels prior to 5.14.15, so we're starting there.

KERNEL Power Management

Processor type and features  --->
   [*] Intel Low Power Subsystem support
Power management and ACPI options  --->
   [*] ACPI (Advanced Configuration and Power Interface) Support  --->
   ~~ Your choice of AC, Battery, Fan, Thermal, etc ~~
      [*] Intel DPTF (Dynamic Platform and Thermal Framework) Support
   [*] Cpuidle Driver for Intel Processors
Firmware Drivers  --->
   [*] Load custom ACPI SSDT overlay from an EFI variable
Device Drivers   --->
   <*> Thermal Drivers  --->
      Intel thermal drivers  --->
         <*> X86 package temperature thermal driver
         <*> Intel SoCs DTS thermal driver
         ACPI INT340X thermal drivers  --->
            <*> ACPI INT340X thermal driver
         <*> Intel TCC offset cooling Driver
   Multifunction device drivers  --->
      <*> Intel Low Power Subsystem support in PCI mode 
      <*> Intel PMC Driver for Broxton
      <*> Intel Platform Monitoring Technology (PMT) support
   [*] X86 Platform Specific Device Drivers
      <*> Intel PMC Core driver

KERNEL I2C Bus (needed for Touchpad, Camera, and probably other stuff)

Device Drivers  --->
   <*> I2C Support  --->
      <*>   I2C device interface
      I2C Hardware Bus Support  --->
         <*> Intel 82801 (ICH/PCH)
         <*> Synopsys Designware Platform

KERNEL Touchpad

Device Drivers  --->
   Input device support  --->
   HID support  ---> 
      <*> Generic HID driver
      Special HID driver  --->
         <*> HID Multitouch panels
         <*> HID Sensors framework support
      I2C HID support --->
        <*> HID over I2C transport layer ACPI driver
      Intel ISH HID support  --->
         <*> Intel Integrated Sensor Hub

KERNEL Wireless LAN

[*] Networking support  --->
   [*] Wireless  --->
      <*> cfg80211 - wireless configuration API
      <*> Generic IEEE 802.11 Networking Stack (mac80211)
Device Drivers  --->
   [*] Network device support  --->
      [*] Wireless LAN  --->
         [*] Intel devices
         <*>   Intel Wireless WiFi Next Gen AGN - Wireless-N/Advanced-N/Ultimate-N (iwlwifi)
         <*>      Intel Wireless WiFi MVM Firmware support

KERNEL Graphics card

Device Drivers  --->
   <*> /dev/agpgart (AGP Support)  --->
   <*> Direct Rendering Manager (XFree86 4.1.0 and higher DRI support)  --->
   <*> Intel 8xx/9xx/G3x/G4x/HD Graphics

KERNEL Sound

Device Drivers  --->
   <*> Sound card support  --->
      <*> Advanced Linux Sound Architecture  --->
         HD Audio  --->
            <*> HD Audio PCI
            <*> Build Realtek HD-audio codec support
            <*> Build IDT/Sigmatel HD-audio codec support
            <*> Build HDMI/DisplayPort HD-audio codec support
         ALSA for SoC audio support  --->
            [*] Sound Open Firmware Support
            <*>   SOF PCI enumeration support
            [*]   SOF support for Intel audio DSPs
            <*>      SOF support for Tigerlake

KERNEL Storage (NVMe)

Device Drivers  --->
   NVME Support  ---> 
       <*> NVM Express block device
            [*] NVMe multipath support

KERNEL Ambient light sensor

Device Drivers  --->
   <M> Industrial I/O support   ---> 
       Light sensors --->
            <M> HID ALS (CONFIG_HID_SENSOR_ALS)

The ambient light sensors values can be red using the command:

root #cat /sys/bus/iio/devices/iio\:device0/in_illuminance_raw

Note
Post-October '21 Frameworks use a Tempo (also known as IDT/Sigmatel) audio codec instead of Realtek

Troubleshooting

BIOS updates

Upgrading the Framework Laptop's BIOS will erase the EFI boot entries, leaving a Gentoo system unbootable afterwards. This can be fixed by booting from Gentoo install media, mounting and chrooting into the local install root and re-running grub-install.

Follow the Mounting the necessary filesystems, Entering the new environment, and Mounting the boot partition steps from the Handbook, substituting device names as necessary (Handbook:AMD64/Parts/Installation/Base)

Then recreate the necessary EFI entry

root #grub-install --target=x86_64-efi --efi-directory=/boot

Motherboard and/or CPU upgrades

Intel 12th Gen Alder Lake CPUs have a subset of the features of the 11th gen CPUs. Recompile the system to something more generic if attempting to use a Gentoo installation from an 11th gen Framework laptop after upgrading it to 12th gen. See the GCC optimization article for more details on adjusting the -march and -mtune compiler flags.

Touchpad not working

If the touchpad is not working (no movement, no clicks, no gestures), verify the "HID over I2C transport layer ACPI" driver (see Kernel section / Touchpad) is available as a module or built-in driver.

If "PIXA3854" cannot be found in the dmesg log, then the kernel is likely missing driver support.

Without "HID over I2C transport layer ACPI"

user $dmesg |grep -i hid

[    2.499342] hid: raw HID events driver (C) Jiri Kosina
[    2.499362] usbcore: registered new interface driver usbhid
[    2.499363] usbhid: USB HID core driver
[    3.376794] hid-generic 0003:32AC:0002.0001: hiddev96,hidraw0: USB HID v1.11 Device [Framework HDMI Expansion Card] on usb-0000:00:14.0-4/input1

With "HID over I2C transport layer ACPI"

user $dmesg |grep -i hid

[    2.494448] hid: raw HID events driver (C) Jiri Kosina
[    2.494474] usbcore: registered new interface driver usbhid
[    2.494475] usbhid: USB HID core driver
[    3.371391] hid-generic 0003:32AC:0002.0001: hiddev96,hidraw0: USB HID v1.11 Device [Framework HDMI Expansion Card] on usb-0000:00:14.0-4/input1
[   19.053758] hid-generic 0018:32AC:0006.0002: input,hidraw1: I2C HID v1.00 Device [FRMW0001:00 32AC:0006] on i2c-FRMW0001:00
[   19.079450] hid-generic 0018:093A:0274.0003: input,hidraw2: I2C HID v1.00 Mouse [PIXA3854:00 093A:0274] on i2c-PIXA3854:00
[   19.280641] Module hid_sensor_hub is blacklisted
[   19.430450] hid-multitouch 0018:093A:0274.0003: input,hidraw2: I2C HID v1.00 Mouse [PIXA3854:00 093A:0274] on i2c-PIXA3854:00

https://forums.gentoo.org/viewtopic-p-8692426.html#8692426

https://forums.gentoo.org/viewtopic-t-1148336-highlight-framework+laptop.html

https://community.frame.work/t/quick-note-on-the-touchpad-linux-kernel-config-for-the-12th-gen-based-laptop/22267/4?u=malachay

Built-in Keyboard not working on boot to unlock encrypted device

Set CONFIG_KEYBOARD_ATKBD to y to enable built-in keyboard to unlock encrypted luks devices

KERNEL

Device Drivers  --->
   Input device support  --->
      [*] Keyboards  --->
         <*> AT keyboard

EFI Stub Kernel Boot Failed

If CONFIG_EFI_DISABLE_PCI_DMAis set to y, manually selecting the EFI stub kernel on boot will fail with errors:

EFI stub: ERROR exit_boot() failed!
EFI stub: ERROR efi_main() failed!

These errors flash by quickly and one may only see a blue box stating boot failed.

Disable CONFIG_EFI_DISABLE_PCI_DMA and recompile to boot the efi stub kernel.

KERNEL

Device Drivers  --->
   Firmware Drivers --->
      EFI (Extensible Firmware Interface) Support  --->
         [ ] Clear Busmaster bit on PCI bridges during ExitBootServices()

Fingerprint reader

Note
For the last generation of keyboard (generation 13 and recent replacement keyboard), the fingerprint sensor is not working properly with the default firmware. You can wait for framework to push the new firmware to fwupd, but if you know what you are doing and you want an immediate fix, you can follow the instructions here: [1].

Fingerprints are read via the fprintd package installed by

root #emerge --ask sys-auth/fprintd

Fingerprints are stored on the fingerprint reader itself, so if you register a fingerprint and then switch operating systems, you won't be able to register it on the second OS as fprintd gives you "Enroll result: enroll-duplicate". This is a problem if you dual-boot or have to re-install linux.

To wipe these fingerprints, install fprintd and use the following python script^[2]:

FILE wipe_fingerprints.pyWipe Fingerprint Script

#! /usr/bin/python3

import gi
gi.require_version('FPrint', '2.0')
from gi.repository import FPrint

ctx = FPrint.Context()

for dev in ctx.get_devices():
    print(dev)
    print(dev.get_driver())
    print(dev.props.device_id);

    dev.open_sync()

    dev.clear_storage_sync()
    print("All prints deleted.")

    dev.close_sync()

Then run the script with python3 as root:

root #python3 ./wipe_fingerprints.py

Brightness Keys Not Working

Due to a quirk^[3] with Linux drivers and how the Framework laptop is setup, one cannot have both the ambient light sensor and the brightness keys work. For the brightness keys to function and send XF86MonBrightnessUp / Down events the ambient light sensor driver must be disabled.

To do this ensure that the hid_sensor_hub Kernel module is not being loaded. If the CONFIG_HID_SENSOR_HUB kernel build option is set to m then either unset it and rebuild the kernel, or add a modprobe blacklist rule:

# /etc/modprobe.d/framework.conf
blacklist hid_sensor_hub

If CONFIG_HID_SENSOR_HUB is set to y then unset it and rebuild the kernel^[4].

Freezing with 6.4 series kernels

It is necessary to boot with tpm_tis.interrupts=0 in order to avoid a hang at boot as of 6.4.3.^[5]

References

[1] ttps://frame.work/blog/solving-for-silicon-shortages

[2] ttps://community.frame.work/t/fingerprint-scanner-compatibility-with-linux-ubuntu-fedora-etc/1501/206

[3] ttps://community.frame.work/t/responded-12th-gen-not-sending-xf86monbrightnessup-down/20605/11

[4] ttps://community.frame.work/t/some-issues-running-gentoo-linux/12017/20

[5] ttps://community.frame.work/t/tracking-kernel-6-4-hangs-at-ima-allocated-hash-algorithm-sha1/32956/41?page=3

[1]

[2]

[3]

[4]

[5]