Debian on Thinkpad X13s

As of October 11 2023, Debian Trixie can be installed on the Thinkpad X13s using the daily netinst image.

Contents

  1. Debian on Thinkpad X13s
    1. Overall status
    2. Preparation
      1. Prepare a USB stick for installation
      2. Install Device Tree Blob on the EFI System Partition
      3. Note Wi-Fi and Bluetooth mac addresses
      4. Upgrade system firmware
      5. Create Windows Recovery Drive (optional)
      6. Disable BitLocker or backup recovery key (optional)
      7. BIOS configuration
    3. Installation
      1. Boot Debian Installer
      2. Install Debian
      3. Open the terminal
      4. Add missing modules to the initramfs
      5. Install additional packages
      6. Finish the installation
    4. Post installation fixes
      1. Wi-Fi and Bluetooth
      2. Modem (applies to use with physical SIM card that needs to be inserted)
        1. prerequisites
        2. FCC unlock procedure
        3. Connect to mobile broadband
        4. Delete redundant broadband connections in NetworkManager
      3. USB throughput and PCIe ASPM
      4. X.org brightness control
      5. Audio
      6. External Screen Setups (may require a DisplayLink certified Docking Station)
    5. Credits

Overall status

Core Components

[ATTACH]

Boot Standard Kernel:

{i}

LAN network card:

[-] ( {OK} The Realtek RTL8152-based dongle shipped with the X13s works out of the box)

Detect CD/DVD:

[-]

Detect hard drives:

{OK}

Extra Features

CPU Frequency Scaling

[?]

Hibernation

{X}

Sleep / Suspend

/!\ (works, but drains battery in a day)

Xorg

/!\ (external monitor support degradation)

- OpenGL

[?]

- Resize-and-Rotate(randr)

{X}

Switch to External Screen

{i} but may require X-( depending on setup

Mouse

- Built-in (Trackpoint)

{OK}

- Built-in (Touchpad)

{OK}

Modem

{OK}

Wi-Fi

{i}

Bluetooth

{i}

Keyboard's Special Keys

/!\ (only sound and screen brightness keys work)

Camera

/!\ (requires CONFIG_UDMABUF = m at kernel compilation - Viewport is restricted to a small face size)

Sound

{i} (see: Post-Installation Fixes.Audio)

Legend :
{OK} = OK ; {X} Unsupported(No Driver) ; /!\ = Error (Couldn't get it working); [?] Unknown, Not Test ; [-] Not-applicable
{i} = Configuration Required; X-( = Only works with a non-free driver and or firmware

Preparation

Prepare a USB stick for installation

Fetch the daily netinst build of Debian Installer and write it to a USB stick. sdX is used in all the examples on this page, replace X with the appropriate letter. You may have multiple sd device on your system, triple-check that you're writing to the right one and not to some other important drive. 

$ wget https://cdimage.debian.org/cdimage/daily-builds/sid_d-i/arch-latest/arm64/iso-cd/debian-testing-arm64-netinst.iso
$ sudo dd if=debian-testing-arm64-netinst.iso of=/dev/sdX

Note: the Thinkpad X13s will only boot from USB sticks directly connected to the USB port, not from sticks connected to a USB hub. So you either need a USB-C stick, or a USB-A stick with a dumb USB-C-to-USB-A adapter.

Install Device Tree Blob on the EFI System Partition

This step can be performed either under Windows or from a EFI shell. Given that the next step needs Windows anyways, we're documenting the Windows option here.

Run a command prompt as administrator: Start → cmd → Run as administrator.

Run diskpart.exe, and list all available volumes: 

C:\Windows\System32>diskpart.exe

Microsoft DiskPart version 10.0.22621.1

Copyright (C) Microsoft Corporation.
On computer: DESKTOP-778FOAP

DISKPART> list volume

  Volume ###  Ltr  Label        Fs     Type        Size     Status     Info
  ----------  ---  -----------  -----  ----------  -------  ---------  --------
  Volume 0     C   Windows      NTFS   Partition    465 GB  Healthy    Boot
  Volume 1         SYSTEM_DRV   FAT32  Partition    260 MB  Healthy    System
  Volume 2         WINRE_DRV    NTFS   Partition   2000 MB  Healthy    Hidden

Find the volume corresponding with the FAT32 System Partition, Volume 1 in the example above. Now select it and assign a letter. 

DISKPART> select volume 1

Volume 1 is the selected volume.

DISKPART> assign

DiskPart successfully assigned the drive letter or mount point.

DISKPART> list volume

  Volume ###  Ltr  Label        Fs     Type        Size     Status     Info
  ----------  ---  -----------  -----  ----------  -------  ---------  --------
  Volume 0     C   Windows      NTFS   Partition    465 GB  Healthy    Boot
* Volume 1     D   SYSTEM_DRV   FAT32  Partition    260 MB  Healthy    System
  Volume 2         WINRE_DRV    NTFS   Partition   2000 MB  Healthy    Hidden

As can be seen from the output above, in this case the letter assigned was D.

Now exit diskpart and download the Device Tree Blob for the X13s (right-click -> "Save link as" -> choose the "Downloads" folder) https://d-i.debian.org/daily-images/arm64/daily/device-tree/qcom/sc8280xp-lenovo-thinkpad-x13s.dtb

copy the Device Tree file to the EFI System Partition. Replace d: with the letters you got assigned, if it differs. 

copy Downloads\sc8280xp-lenovo-thinkpad-x13s.dtb d:\

Once Debian is installed, you are not going to need to repeat this procedure again. In case you ever need to update the DTB in the future, just copy the new version to /boot/efi/sc8280xp-lenovo-thinkpad-x13s.dtb and that's it.

Note Wi-Fi and Bluetooth mac addresses

This step is needed as currently the addresses have to be set manually under Debian.

Run a command prompt: Start → cmd

Run ipconfig /all

Write down the Physical Address of Wireless LAN adapter Wi-Fi and Ethernet adapter Bluetooth Network Connection on a separate media or a sheet of paper, so they can be accessed after installation.

Upgrade system firmware

This step needs to be performed under Windows.

Recent versions of Lenovo's firmware include a setting called Linux Boot (Beta), which needs to be enabled in order to use Debian on the X13s.

Go to the Drivers & Software section of Lenovo's website and download the BIOS Update Utility. Run the program and update the bios.

Create Windows Recovery Drive (optional)

It is recommended to create a Windows recovery drive in case you need it in the future (for example to upgrade the firmware).

To so, follow the steps in this guide: Create a recovery drive. Note: this will take a long time (~90 minutes).

Disable BitLocker or backup recovery key (optional)

If you plan to keep the current Windows installation, either disable BitLocker disk encryption or backup your recovery key, as disabling the Secure Boot in the next step will prevent you from booting the Windows without it.

BIOS configuration

Reboot, press F1 on system startup, go to: Config → Linux → Linux Boot (Beta), switch it on. Then, go to Security → Secure Boot → Secure Boot, switch this off.

Installation

Boot Debian Installer

On startup, press F12 and select booting from the USB.

At the boot prompt type e and replace quiet with arm64.nopauth.

The setting arm64.nopauth is needed to disable Pointer Authentication, a future BIOS update should allow us to run with Pointer Authentication.

By default console fonts are very small, to make life easier for your eyes you can also pass fbcon=font:TER16x32 to get bigger fonts but this is of course entirely optional.

Type CTRL+x to boot the installer.

Install Debian

The installer may prompt you for missing firmware (ath11k/WCN6855/hw2.1/firmware-2.bin), but you don't need to supply it, the WiFi will work regardless.

Install Debian according to your preferences. Perhaps go for Manual partitioning and keep Windows around in case you ever need to update the firmware again.

When asked by the installer Force GRUB installation to the EFI removable media path make sure to say Yes.

Finally, when the system says Installation complete, move to the next step. Don't press continue.

Open the terminal

Open the terminal by running CTRL+ALT+F2 (you may need to use Fn key to use F-keys).

Add missing modules to the initramfs

Edit the /target/etc/initramfs-tools/modules file by running: 

nano /target/etc/initramfs-tools/modules

Add the following lines to the end of the file: 

leds_qcom_lpg
qrtr
pmic_glink_altmode
gpio_sbu_mux
qnoc-sc8280xp

Exit the editor by pressing Ctrl + x and press y to save changes. Note: If you meet a problem that the status of battery is unknown with initramfs-tools (>=0.143.1), undo this step.

Run the command below to update initramfs: 

in-target update-initramfs -u -k all

Note: in-target will redirect any output to the fourth virtual console, you can see it by pressing ALT+F4 (switch back using ALT+F2). You can also inspect the commands exit status by typing echo $?: if it prints 0 the invocation was successful.

Install additional packages

If you selected Debian Desktop Environment during installation (or you want to know how much battery is left) it is necessary to install additional packages. Otherwise system will boot into the black screen. 

in-target apt install -y firmware-qcom-soc protection-domain-mapper qrtr-tools acpi

Finish the installation

Now go back to the main screen with CTRL+ALT+F1, choose Continue.

At the time of writing this Debian may not add itself to the boot options automatically. To fix that, on the first boot you will need to manually boot from the SSD.

Post installation fixes

Since Kernel 6.9.8 the battery state may not be shown after starting up; nor could an external montior be usable; nor could the sound work. One has to issue the following command with root privileges to make it work again: 

echo start > /sys/class/remoteproc/remoteproc0/state

Source: thanks to robclark's message found in irc

Wi-Fi and Bluetooth

Currently, the Wi-Fi mac address fallbacks to the random one after each boot. Bluetooth doesn't and it will not work without a proper one. A possible workaround for this is to use udev rules.

Create /etc/udev/rules.d/99-fix_mac_addresses.rules file with the following content (sudo permissions are required). Replace XX:XX:XX:XX:XX:XX with the Physical Address of Wireless LAN adapter Wi-Fi read on Windows. 

ACTION=="add", SUBSYSTEM=="net", KERNELS=="0006:01:00.0", \
  RUN+="/usr/bin/ip link set dev wlP6p1s0 address XX:XX:XX:XX:XX:XX"
ACTION=="add", SUBSYSTEM=="bluetooth", ENV{DEVTYPE}=="host" \
  ENV{DEVPATH}=="*/serial[0-9]*/serial[0-9]*/bluetooth/hci[0-9]*", \
  TAG+="systemd", ENV{SYSTEMD_WANTS}="hci-btaddress@%k.service"

Create /lib/systemd/system/hci-btaddress@.service file with the following content (sudo permissions are required). Replace XX:XX:XX:XX:XX:XX with the Physical Address of Ethernet adapter Bluetooth Network Connection read on Windows. 

[Unit]
Description=HCI bluetooth address fix

[Service]
Type=simple
ExecStart=/bin/sh -c 'sleep 5 && yes | btmgmt -i %I public-addr XX:XX:XX:XX:XX:XX'

Run systemctl daemon-reload and reboot. You may have to unblock the Bluetooth interface, for example using rfkill unblock bluetooth.

NOTE: If you hadn't noted the addresses before the installation, you will need to either manually generate valid mac addresses or (if you kept Windows) go back to the #Note_Wi-Fi_and_Bluetooth_mac_addresses section to get them.

Modem (applies to use with physical SIM card that needs to be inserted)

prerequisites

on Windows make sure you have the latest Lenovo Firmware Updates and remove the SIM PIN in Settings -> Network & internet -> Cellular -> Mobile operator settings -> Remove SIM PIN

FCC unlock procedure

identify Modems vendor and product ID 

$ lspci -knn | grep -i 'Modem'
0004:01:00.0 Wireless controller [0d40]: Foxconn International, Inc. T99W175 5G Modem [Snapdragon X55] [105b:e0c3]
        Subsystem: Foxconn International, Inc. T99W175 5G Modem [Snapdragon X55] [105b:e0c3]

enable automatic FCC unlock (use the ID you retrieved in the previous step, caution some devices ship with 105b:e0ab make sure you have the right one) 

$ sudo ln -sft /etc/ModemManager/fcc-unlock.d /usr/share/ModemManager/fcc-unlock.available.d/105b:e0c3

Connect to mobile broadband

Find your Providers APN Information (APN and your Provider Name in search engine should find you the required info)

In that case https://www.telekom.de/hilfe/mobilfunk/mobiles-internet/mobilfunkstandards/apn-ratgeber?samChecked=true

Find modem index and connect 

$ mmcli -L
/org/freedesktop/ModemManager1/Modem/0
$ mmcli -m 0 --simple-connect="apn=internet.telekom,user=telekom,password=tm"

caution don't confuse with SIM PIN

Delete redundant broadband connections in NetworkManager

$ nmcli con sh

$ nmcli con del 'Prepaid Contracts'

Any further management can be done from NetworkManager GUI

USB throughput and PCIe ASPM

To improve USB throughput and reduce PCIe power consumption add iommu.passthrough=0 iommu.strict=0 and pcie_aspm.policy=powersupersave to the kernel command line. To do it persitently add these to the GRUB_CMDLINE_LINUX_DEFAULT in /etc/default/grub file (sudo permissions are required), so it looks like this: 

GRUB_CMDLINE_LINUX_DEFAULT="iommu.passthrough=0 iommu.strict=0 pcie_aspm.policy=powersupersave quiet"

Run sudo update-grub and reboot for the changes to take effect.

X.org brightness control

To change the brightness under X11 one has to write the desired value to /sys/class/backlight/backlight/brightness manually. Wayland users are not affected.

Audio

The kernel of Debian Trixie (6.5) is not build so that module SND_SOC_WSA883X can be loaded. Therefore the speakers only work with a newer kernel; e.g. the 6.8 one from Debian sid (note that the sound may be quiet and also distorted for now). After installing pulseaudio (see https://github.com/jhovold/linux/wiki/X13s#audio) and the firmware (see below), internal speakers and the microphone do work.

The firmware-qcom-soc package needed comes with trixie or above. If your packages does not include the firmware file needed for audio to work (see Debian bug 1057040) you'll need to manually download audioreach-tplg.bin and move it to /lib/firmware/qcom/sc8280xp/LENOVO/21BX/audioreach-tplg.bin. Then create the following symlink: 

$ sudo ln -s /lib/firmware/qcom/sc8280xp/LENOVO/21BX/audioreach-tplg.bin /lib/firmware/qcom/sc8280xp/SC8280XP-LENOVO-X13S-tplg.bin

Maybe required: If your mouse pointer sporadically disappears or is only visible fractionally.

Common adapters work over both USB-C slots (at last for a single, second external Monitor). If you have any issues you should refer to Post-Installation Fixes: Remote procs may be started on each boot manually.

Downloading and installing ?DisplayLink-Debian Release: 6.1 (evdi v1.14.7) doesn't work with kernel versions 6.12 > have to wait for next ?DisplayLink-Debian Release with evdi v1.14.8: 

$ git clone https://github.com/AdnanHodzic/displaylink-debian.git
$ cd displaylink-debian
$ sudo ./displaylink-debian.sh

Checking service: 

$ systemctl status displaylink-driver.service

Credits

CategoryBootProcess CategoryVideo CategoryVideo CategoryVideo