Configure & Build

Configure and build Linux kernel for Surface RT

Editing kernel build configuration

First run the command make ARCH=arm tegra_defconfigThis will create a standard kernel config for tegra SoC's.

Open the file .config in the kernel source directory with your favorite text editor and paste the following at the end of the file

CONFIG_EFI_STUB=y 
CONFIG_EFI=y
CONFIG_I2C_HID_OF=y
CONFIG_I2C_HOTPLUG_GPIO=y
CONFIG_BATTERY_CHARGER_SURFACE_RT=y
CONFIG_MWIFIEX=m
CONFIG_MWIFIEX_SDIO=m
CONFIG_SND_SOC_TEGRA_WM8962=y
CONFIG_HID_MICROSOFT=y

Note that some drivers (Wi-Fi) are built as modules. See exporting modules below to use them.

Build the kernel

To build the kernel use the command make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j $(nproc)- $(nproc) sets the number of threads to your CPU core count This command can take a while depending on your computer's speed. (5+ minutes)

Note: If you get asked what configuration you want to choose, just press enter, this will take the standard value.

If compiling was successful you should see some output similar to this: (This doesn't need to be a the end of the log. Scroll up a bit ;) ) CALL    scripts/checksyscalls.sh CALL    scripts/atomic/check-atomics.sh CHK     include/generated/compile.h Kernel: arch/arm/boot/Image is ready Kernel: arch/arm/boot/zImage is ready

The output kernel image is located at arch/arm/boot/zImage

The output device tree is located at EFI:arch/arm/boot/dts/tegra30-microsoft-surface-rt-efi.dtb. APX:arch/arm/boot/dts/tegra30-microsoft-surface-rt.dtb.

Build the kernel using shell script

You can create a .sh script in kernel root to speed up your workflow

plsMake.sh

#!/bin/bash
make ARCH=arm CROSS_COMPILE=arm-linux-gnueabihf- -j $(nproc)

Using modules

Some drivers will be built as modules. This reduces the kernel image size.

The module folder needs to be placed on the rootfilesystem in /lib/modules.

Some drivers need to be built as module. For example the Wi-Fi driver. Wi-Fi needs a firmware which will be send to the Wi-Fi SoC at the time the hardware is probed. This can happen before the root filesystem is mounted. Therefore the driver can't load the firmware. If wifi is built as module it won't be loaded before the root filesystem was mounted.

Exporting modules

make INSTALL_MOD_PATH=../ modules_install > /dev/null

This command will place the modules folder next to your Linux kernel folder.

You need to copy the modules after: - Modifying the kernel source for the first time - Every git commit - Editing a driver which is built as module (obvious?)

Appended devicetree

Append devicetree

Append the devicetree to zImage to make a single Image which contains the kernel and the devicetree. This allows to use simpler bootloaders and minimizes errors that the bootloader can make.

cat ./arch/arm/boot/zImage ./arch/arm/boot/dts/tegra30-microsoft-surface-rt.dtb > ./arch/arm/boot/zImage

Your kernel with appended devicetree should be located at ./arch/arm/boot/zImage

Kernel parameters

Commonly used kernel parameters

dtb=

microsoft-surface-rt.dtb for APX booting
microsoft-surface-rt-efi.dtb for EFI booting

root=

Specifies the root filesystem which should be used.

/dev/mmcblk0pN eMMC partition N
/dev/mmcblk1pN µSD Card partition N
/dev/sdaN USB partition N

console=

tty0 for normal console (internal screen+tCover/USB keyboard)

ttyS0,115200n8 for serial console at 115200 Baud, no parity bit, 8bits (need uart access)

You can specify multiple console= options on the kernel command line. Output will appear on all of them. The last device will be used when you open /dev/console. So, for example:

console=ttyS1,9600 console=tty0

defines that opening /dev/console will get you the current foreground virtual console, and kernel messages will appear on both the VGA console and the 2nd serial port (ttyS1 or COM2) at 9600 baud.

Note that you can only define one console per device type (serial, video). - https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html

rootwait

Waits for root filesystem. Some root filesystems will be mounted after the kernel finished initalizing hardware. Thats the case for USB. eMMC/SD seems to work without this parameter.

cpuidle.off=1

EFI doesn't support CPU idle therefore it must be disabled for efi booting. You shouldn't use this param for APX booting.

UEFI boot

Boot an EFI-based Linux kernel on your Surface RT.

Prerequisites

A Surface RT with secure boot disabled. Visit Yahallo for more information on how to disable it.

A USB drive, formatted as FAT32 with either MBR or GPT. The partition doesn't require being marked as EFI system partition. Be aware that FAT32 isn't FAT32.

A root filesystem/distro on your SD card (recommended)/internal storage/USB. See root filesystem.

Preparing the files

There is a premade ZIP below.

There are prebuilt binaries.

Most people use UEFI shell to chainload an EFI linux kernel. Using UEFI shell gives the option to easily specify and modify the kernel command line.

bootarm.efi

721KB

Binary

UEFI shell

You may want to use different bootloaders, like GRUB.

Place UEFI shell onto your bootable USB drive (as efi/boot/bootarm.efi) and place the zImage and the tegra30-microsoft-surface-rt-efi.dtb files onto the root of your usb drive.

You will need to create a startup script for UEFI shell:

startup.nsh

fs0:
# add initrd=<initrd.img-filename> if you want to boot a ramdisk image
# replace console=tty0 with console=ttyS0,115200 if you want serial output on UART A
zImage dtb=tegra30-microsoft-surface-rt-efi.dtb root=/dev/mmcblk1p2 console=tty0 cpuidle.off=1

# shutdown if something went wrong
reset -s

You may want to change the line that begins with zImage. It is the kernel command line. root=/dev/mmcblk1p2 is the second partition of the sdcard, change this if you want to use a different device/partition. RPI OS is a recommended distro, as it runs smooth

root=/dev/mmcblk0p2 is a location set to internal storage (eMMC) second partition, set it to this after cloning the installation over to internal storage.

root=/dev/sda2 is a second partition for USB only boot, set it to this if you want to USB boot only

See Kernel parameters for further information.

Premade ZIP

usb-linux-boot.zip

288KB

Binary

Extract this ZIP to your USB, and add your zImage and device tree to it. You can find precompiled binaries here.

Booting linux

With the USB drive set up, a distro installed and secure boot disabled, you are ready to boot linux.

1.Shut the device off

2.Plug in your USB drive

3.Boot from the USB

    1.Hold the volume down button

    2.Press the power button for a second

3.Wait until the surface logo appears

4.Release volume down

4.You should see kernel logs onscreen (after a short while (15 seconds), wait for 1 minute if nothing happens try again)

If you have any issues, feel free to contact us on discord.

Installing boot files on internal storage

With the method shown above, you will need your USB always on hand to boot linux. You can also install these boot files on the internal storage.

The easiest method is to just clean the windows boot files from the EFI partition, and replace them with the contents of your USB drive.

This will make you unable to boot Windows!

It is possible to make Windows and Linux dual-boot. For example, you can use GRUB.

Using UEFI shell to copy the files

Replace the contents of your startup.nsh on the USB with the following:

fs0:
cp fs1:\efi/boot/bootarm.efi fs1:\efi/boot/bootarm.efi.backup >> log.txt
cp efi/boot/bootarm.efi fs1:\efi/boot/bootarm.efi >> log.txt
cp tegra30-microsoft-surface-rt-efi.dtb fs1: >> log.txt
cp zImage fs1: >> log.txt
cp startup-system.nsh fs1:\startup.nsh >> log.txt
reset -s

After booting, it will copy the devicetree, zImage and the startup-system.nsh over to the EFI partition on the internal storage. Fill your startup-system.nsh with the linux boot commands. (The commands you normally have in your startup.nsh)

This method is also useful for updating the device tree and zImage, if you already have existing linux files there.