Instructions for flashing and installing the Debian installer

This document^[a][b] provides detailed instructions for installing Debian 11 on Snapdragon 8cx Gen 3 laptops, which are commercially available and running Microsoft Windows.

[Note: Sections 1 and 2 should be done on Windows OS only]

1- Creating the bootable USB driver on Windows OS:

1. Download the Rufus v3.21 application:
   https://github.com/pbatard/rufus/releases/download/v3.21/rufus-3.21.exe 
2. Download the Debian installer ISO:
   https://people.linaro.org/~manivannan.sadhasivam/lenovo_x13s/debian-11-arm64-DVD-2.iso 
3. Plug in a USB device to the Windows machine (Minimum 2GB is recommended).
4. Run Rufus.exe
5. Select the USB device under the “Device” category.
6. Select the ISO that was downloaded in Step 2 by clicking the “SELECT” button.
7. The GUI should now appear as like below:

8. Now start the application by clicking the “START” button.
9. In the next window, you’ll be prompted to select between “ISO Image mode” and “DD Image mode”. Select “DD Image mode” and click the “OK” button to kickstart the process of creating a bootable USB drive.
10. Once the process is finished, click the “CLOSE” button and eject the USB device.

NOTE: The installer can also be flashed using the “DD” utility in Linux.

2- Shrink the Windows drive for Debian installation

1. Open “Control Panel” and “Windows Tools/Create and format hard disk partitions”, open “Disk Management”^[c].
2. Select the “Windows” partition. Right click and select “Shrink Volume”.
3. In the next window, enter the new size for the Windows partition. We recommend providing “100000” in the “Enter the amount of space to shrink in MB” field. This corresponds to ~100GB of space for the Windows partition.
4. Then click the “Shrink” button to start the shrinking process.
5. Once done, verify that the “Windows” partition has 100GB of total space and the remaining space should be “Unallocated”.
6. The “Unallocated” space will be utilised by the Debian installer in the next section.

3- Installing Debian on Lenovo X13s

1. Disable Windows Bitlocker^[d]                                                                    
2. Power ON the Lenovo X13s, press F1 to enter setup. Under Security, Secure Boot, disable Secure Boot. Save and exit.^[e]
3. Power ON the Lenovo X13s while having the USB device inserted into the Type-C port. Press ENTER, followed by F12 to select USB as the temporary boot option.
4. In the GRUB menu, select “Install”.
5. In the next window, select “English” as the Language and press Enter.
6. In the next window, select the country based on your location and press Enter.
7. After loading all components, the “Detect network hardware” window will appear. In that, select “no ethernet card” and press Enter.
8. The next window will throw a warning that no network interfaces have been detected. Select “Continue”.
9. In the next window, enter the hostname for the system and select “Continue”.
10. In the next window, enter the password for root and select “Continue”.
11. In the next window, re-enter the same password and select “Continue”.
12. In the next window, enter the full name of the user and select “Continue”.
13. In the next window, enter the username for the account and select “Continue”.
14. In the next window, enter the password for the user and select “Continue”.
15. In the next window, re-enter the password for the user and select “Continue”.
16. After that, the “Partition Disks” window will appear. Select “Guided - Use the largest continuous free space” and press Enter.
17. In the next window, select “All files in one partition” and press Enter.
18. Then you’ll be back to the “Partition Disks” window. In that, select “Finish partitioning and write changes to disk” and press Enter.
19. In the next window, verify that partition changes are correct then select “Yes” and press Enter.
20. Once the partitions are fo
21. In the next window, select “Yes” and press Enter.
22. Finally, you’ll be prompted to participate in the package usage survey. Select the option “Yes” or “No” based on your preference and press Enter.
23. Afterward, GRUB will be installed on the NVMe. Accept the default option, “no”.
24. In the end, the “Installation complete” window will appear indicating that the installation has been completed.
25. Now proceed to the next section to modify the boot order.

4- Modifying the boot order on Lenovo X13s

1. In the “Installation complete” prompt, reboot by selecting “Continue” while leaving the USB device plugged in. Again, press ENTER, followed by F12 to select USB as the temporary boot media.
2. Press 'c' in Grub menu to get 'grub> ' command-line prompt.
3. Launch Shell.efi that resides in USB disk as below, use the “ls” command to list available chainloader devices e.g. it might be (hd0,msdos2) depending on which USB socket your USB flash drive is detected in

1. grub> chainloader (cd0,msdos1)/EFI/efi/shell/Shell.efi
2. grub> boot

4. Select the ESP partition as below:

1. Shell> map -r -b
2. Shell> fs5:
3. FS5:\> ls EFI\debian

1. This should list DtbLoader.efi and grubaa64.efi files.
2. If this doesn’t show the files above, try other values for fsXX: (XX for values 1…) in step b above and repeat.
3. Note you should keep searching fsXX: until you find this directory structure even as high as FS15: or more

5. Modify EFI variable Boot#### to get it to point to DtbLoader.efi:

1. FS5:\> bcfg boot dump

...

Option 00. Variable: Boot0001

Desc   - Windows Boot Manager

…

2. NOTE: The number 0 in the below command is identified by looking at the Option field in the first command output for Windows Boot Manager. This could be different on your laptop.
3. FS5:\> bcfg boot add  0 EFI\debian\DtbLoader.efi “Debian^[f]”

6. Now the installation is really completed. Remove the USB disk and reboot as below:

1. FS5:\> reset^[g]

5- Post installation

This section has a collection of tips and tricks which might be handy after the initial installation.

Configure package manager

If the network was not used during the installation (no USB Ethernet adapter used), the sources.list file is not properly configured , and the main Debian repositories are not set. As such you need to add the following line into the file /etc/apt/sources.list, before trying to install any other package

deb https^[h]://deb.debian.org/debian bullseye main

Update the system

After the installation is complete, the system is a fully functional Debian configuration. It is possible (and recommended) to keep the system up to date, by running regularly the following commands:

sudo apt update

sudo apt upgrade

Update date and time

The RTC driver is not functioning properly, so the time is not set correctly on boot. It can be set manually with the following command:

date -s "yyyy-mm-dd hh:mm:ss"

Alternatively, the ‘ntp’ package can be installed so that date and time are synchronized from the network:

sudo apt update

sudo apt install ntp

Restrict Wifi 5Ghz usage

There is a limitation for now for WiFI, since the Linux build is missing the appropriate ‘board’ file for the laptop (which mostly contains calibration data). As such the performance of 5Gz bands is not great. For now it is recommended to avoid using 5Ghz bands. Debian uses NetworkManager to manage network connections, and the tool nm-connection-editor can be used to remove 5Ghz bands.

First make sure the tool is installed correctly:

sudo apt install network-manager-gnome

Now, from a Terminal open ‘nm-connection-editor’, locate your WiFi connection, and in the Settings, remove ‘Automatic’ from the Bands settings, and choose 2.4Ghz only. This needs to be done for each WiFi network the device connects to.

Build and installing a custom Linux kernel

The installer comes with a custom Linux kernel. On Debian systems, the Linux kernel is installed as a Debian package (.deb file). The Debian package contains the following files:

1. Kernel image (vmlinux)
2. kernel modules (*.ko files)
3. DTBs files

On the Debian system, after the installation, these files are installed in the following locations:

1. Kernel image is in /boot directory
2. Kernel modules are in /lib/modules/<kernel version>
3. DTBs files are in /usr/lib/linux-image-<kernel version>

It is possible to install multiple kernel packages at the same time, the ‘advanced’ grub menu will list all versions, and the user can select which version to boot with.

It is possible to build a new kernel locally on the device running Debian. The kernel build system has built-in support to generate a proper Debian package, which can be installed and used to boot.

The instructions to build a custom kernel branch are:

git clone <git URL>

git checkout -t origin/<branch>

make <DEFCONFIG>

make -j8 bindeb-pkg

For example the following instructions can be followed to build a kernel package using the current work-in-progress development branch:

$ sudo apt install bc bison build-essential debhelper flex libssl-dev make rsync

git clone https://github.com/aarch64-laptops/linux.git^[i]

cd linux

git checkout -t origin/lenovo-x13s

make laptop_defconfig

make -j8 bindeb-pkg

Building the kernel from scratch the first time will take ~15 minutes. Next builds will be faster, since only modified files will be rebuilt.

Of course changes can be made into the tree (source code changes, defconfig changes) and tested directly on the laptop.

At the end of the build, the .deb file is generated in the parent folder, e.g. "linux-image-6.0.0-rc3+_6.0.0-rc3+-3_arm64.deb", which can be installed using

dpkg -i linux-image-6.0.0-rc3+_6.0.0-rc3+-3_arm64.deb

The DTB file which is used during the boot process is located in /boot/efi/dtb folder. Hence after installing a new kernel it is recommended to update the DTB file with the new version. The DTB files are different for the Lenovo X13s and the Makena CRD:

• Lenovo X13s DTB is f249803d-0d95-54f3-a28f-f26c14a03f3b.dtb
• Makena CRD DTB is 5c9ad52c-f641-5df5-9494-25fca457669e.dtb

To update the DTB, simply override them, e.g.:

sudo cp /usr/lib/<kernel version>/qcom/sc8280xp-lenovo-thinkpad-x13s.dtb /boot/efi/dtb/f249803d-0d95-54f3-a28f-f26c14a03f3b.dtb

Update to Debian ‘unstable’ e.g. ‘sid’

The Debian installer is based on the current Debian ‘stable’ version (e.g. Debian 11, aka ‘bullseye’. After the initial installation, it is possible to upgrade to Debian unstable (e.g. sid). Edit the file /etc/apt/sources.list and remove (or comment) all lines, and add the following:

deb https://deb.debian.org/debian unstable main contrib non-free

Then to run a full system upgrade run the following commands:

sudo apt update

sudo apt dist-upgrade

New packages will be downloaded and installed, it might take some time. To finalize the upgrade, simply reboot the system.

If everything worked fine, you might want to cleanup orphan packages which might have not been removed automatically with:

sudo apt autoremove --purge

Next step is to update firmware, kernel to enable WiFi, battery and audio

Download the entire contents of

https://people.linaro.org/~manivannan.sadhasivam/x13s_upgrade/

sudo ./upgrade_debian.sh

This will install an updated kernel and sound topology, plus some user-space dependencies.

Finally pull in the latest firmware for ath11k firmware, this is necessary to enumerate the board-id for the laptop

git clone https://github.com/kvalo/ath11k-firmware.git

cd ath11k-firmware

sudo cp -r WCN6855/hw2.0/* /lib/firmware/ath11k/WCN6855/hw2.0/

Update sources.list to include additional Linaro repo

During the development process, Linaro will deliver new packages in a custom package archive (while things settle upstream). For example, newer Linux kernel packages will be pushed into this archive.

To use this packages archive, first create the file /etc/apt/sources.list.d/linaro.list, with the following content:

deb https://download.opensuse.org/repositories/home:/ndec/Debian_11/ ./

To use this archive, it’s key needs to be configured on the system, with:

wget -nv  https://download.opensuse.org/repositories/home:/ndec/Debian_11/Release.key -O Release.key

apt-key add - < Release.key

If you have upgraded the system to Debian Unstable, replace Debian_11 with Debian_Unstable in the instructions above.

Update only the Linux kernel using the Linaro repository

Once you have set up the system to use the Linaro repository (in the previous section), you can install additional prebuilt Linux kernel packages from this repository. The Linaro team will provide kernel upgrades for users who have already installed Debian on their Lenovo x13s device.

The Linux kernel package is pushed here. The source package name is in the format: linux-upstream_<version string>-<build number>.dsc

To install the corresponding Linux package on your device, run:

sudo apt update

sudo apt install linux-image-<version string>

E.g.

sudo apt update

sudo apt install linux-image-6.0.0-rc3-aarch64-laptops

During the installation of the new kernel package, the Grub configuration file will be updated, and a new entry will be added, so that this kernel can be selected during the boot.

This command downloads and install the custom Debian package (.deb) and install the following files:

• The Kernel ELF file (vmlinux) in /boot
• The kernel modules in /usr/lib/modules/<version>
• The kernel DTBs files in /usr/lib/linux-image-<version>

It is important to remember that the DTB is loaded during the boot by a special 'DtbLoader' EFI app which is executed before grub. DtbLoader will load the DTB from the ESP partition, e.g. generally from /boot/efi/dtb folder, and the Linux kernel will use it when it starts.

The DTB filename is based on a Computer Hardware ID (CHID), which is unique per device type. The ID for the Lenovo x13s is f249803d-0d95-54f3-a28f-f26c14a03f3b, as such the DTB file for the Lenovo x13s used during the boot by DtBloader is the following file:

/boot/efi/dtb/f249803d-0d95-54f3-a28f-f26c14a03f3b.dtb

During the early stage of the development, it is expected that the DTB will be incompatible when updating to a newer kernel. As such when installing a new kernel, we also need to update the DTB file used by the DtbLoader.

To update the device tree provided by the new kernel, run the following command:

sudo cp /usr/lib/linux-image-<XXXX>/qcom/sc8280xp-lenovo-thinkpad-x13s.dtb /boot/efi/dtb/f249803d-0d95-54f3-a28f-f26c14a03f3b.dtb

The system can now reboot into the new kernel.