Framework Laptop

From Gentoo Wiki
Jump to:navigation Jump to:search
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 Vendor ID / Product ID Kernel driver(s) Kernel version 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

AMD 7040 Series

Device Make/model Status Vendor ID / Product ID Kernel driver(s) Kernel version Notes
Chipset AMD Pink Sardine Works
Video card AMD Radeon 780M Works amdgpu
Sound card AMD Rembrandt Radeon High Definition Audio Controller Works snd_hda_intel snd_sof_amd_rembrandt snd_sof_amd_acp
Wireless network card MediaTek MT7922 Works mt7921e
Bluetooth MediaTek MT7922 Works bluetooth btmtk btusb mt7921e
Touchpad PixArt PIXA3854 Works hid_multitouch i2c_designware_platform pinctrl_amd
Fingerprint Reader Goodix USB2.0 MISC Works* 27c6:609c *Requires firmware update: see [1]
Webcam Generic Laptop Camera (?) Works uvcvideo
Ambient light sensor

Backlight:

The backlight brightness keys (on the 7840U at least) show up as ACPI events rather than keyboard keys, and require the CONFIG_I2C_DESIGNWARE_PLATFORM kernel option to be set to work. The backlight itself can still be adjusted without that config option, via the usual echoing to the appropriate brightness file: /sys/class/backlight/amdgpu_bl0/brightness

The backlight keys will also need sys-power/acpilight installed, replacing x11-apps/xbacklight if it was previously installed.

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 read 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: [2].

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