postmarketOS

Porting to a new device

If you have any questions, feel free to ask in the matrix/irc channel or bug tracker! This is a wiki, so please adjust everything that isn't detailed enough or would have helped you with porting.

Please write your porting progress to the devices page, even if you didn't get very far. This helps to determine what can be improved to make porting easier.

Please use a spare device for experimenting with postmarketOS! You won't be able to use typical phone features right now, such as making calls, writing SMS, using Wi-Fi, using Bluetooth. Although everything has been tested, there is no guarantee that you won't break your device.

Initialization

Device-specific package

Create an appropriate device-$vendor-$name package in the aports/device folder:

cp -r aports/device/device-samsung-i9100 aports/device/device-vendor-name

The important files are APKBUILD (build recipe, [[apk is an Alpine Linux term|Glossary#apk]]) and [[deviceinfo|deviceinfo reference]]. Please adjust them as necessary. Note that if your device uses fastboot, you will need to add mkbootimg to the depends= list in the APKBUILD, and the following variables at the end of deviceinfo (guide, example):

# Fastboot related
deviceinfo_generate_bootimg="true"
deviceinfo_flash_offset_kernel=""
deviceinfo_flash_offset_ramdisk=""
deviceinfo_flash_offset_second=""
deviceinfo_flash_offset_tags=""
deviceinfo_flash_pagesize=""

A post-install script can be created to append device-specific partitions to /etc/fstab. See the post-install script for device-nokia-rx51 for an example.

Once the device package is configured, you will need to update checksums in the APKBUILD to match the new configuration files. You can do that by running:

./pmbootstrap.py checksum device-$vendor-$name

Now, you can build your device package with:

./pmbootstrap.py build device-$vendor-$name

Kernel package

While the goal is to use a mainline kernel for all devices in the long run, this certainly can not be done in one step when porting to a new device. Create a new package for the kernel by copying the kernel package of the most similar device with an existing port. For example:

cp -r aports/device/linux-lg-mako aports/device/linux-vendor-name

Now edit the APKBUILD. Replace the kernel source with a kernel suitable for your device. For Android devices we usually use the kernels from LineageOS. Copy the right defconfig from your kernel's source folder into your new linux-... folder and adjust its file name. Please adjust the comments in the APKBUILD file about which defconfig you have used, and which modifications you have made. Please also adjust the pkgver/pkgrel to match the kernel version.

Next, generate the checksum for the kernel package files using:

./pmbootstrap.py checksum linux-$vendor-$name

Now, before building the kernel itself, it is required to run the kernel's menuconfig with:

./pmbootstrap.py menuconfig linux-$vendor-$name

The first time, you run the menuconfig command, you will get prompted about new config options, that the default config does not address (in Android's build process, these options get ignored, but in pmOS they must be specified). Please accept the defaults it presents. After that, you will be shown a menu, in which the DEVTMPFS kconfig flag should be enabled, to get udev working, which is needed for touchscreen support in Weston. It should be located under Device Drivers ---> Generic Driver Options.

Once you have configured the kernel, build it (the arch specification is necessary here, because we're really compiling code - the device package just contains text/scripts and no native code, therefore it is architecture independent):

./pmbootstrap.py build linux-$vendor-$name --arch=armhf

NOTE: The linux-lg-mako package has a patch called gpu-msm-fix-gcc5-compile.patch, to fix compiler errors with GCC6. If your kernel doesn't need that specific patch (if it does not apply correctly, as in this report), just remove the file, and remove it from the source= line in the APKBUILD.

If your manufacturer has not released the source code of your kernel and you don't want to give up on porting your device, you can try the prebuilt kernels approach.

Appended device trees

Some devices need an appended device tree to boot. In LineageOS kernels this will mean that beside the generated zImage there is also a zImage-dtb file. To use this you have to enable in your kernel appending the dtb as in lg-hammerhead and change the package step in the build script to use the dtb file:

# Change zImage to zImage-dtb on this command:    
install -Dm644 "$srcdir/build/arch/arm/boot/zImage-dtb" \
               "$pkgdir/boot/vmlinuz-$_flavor"

In Android kernels, you usually enable BUILD_ARM_APPENDED_DTB_IMAGE and get an image with dtb appended and the filename will be zImage-dtb.

In the mainline kernel instead, you enable ARM_APPENDED_DTB (without trialing _IMAGE) and will get a bunch of .dtb files for the boards that are selected in the kernel config. In this case you need to manually append the correct .dtb file to the compiled kernel image zImage. An example of this is in the kernel package for the nokia n900:

cd "$srcdir/build/arch/arm/boot"
cat zImage dts/omap3-n900.dtb > zImage-dtb

If you are unsure, whether your device has an appended dtb file, use extract-dtb on an existing kernel image (e.g. from LineageOS). extract-dtb is packaged for postmarketOS, you can build it with pmbootstrap build extract-dtb.

Installation

If you want to install to the system partition of an image file, run the following:

./pmbootstrap.py install

If you want to install to a SD card, insert it and run the following. Replace mmcblk0 with the actual device name (lsblk is handy to find out the correct device name).

./pmbootstrap.py install --sdcard=/dev/mmcblk0

Flashing

Before you can run any flash command, you must put your device in the flashing mode. It is usually done holding Volume Down & Power simultaneously when the device is switched off but it may vary depending on the device. For more information see the specific page for your device in the LineageOS Wiki.

If you want to install to the system partition, run the following (not for the SD card installation!):

./pmbootstrap.py flasher flash_system

If the system partition for your device is less than 850MB, you should find the size and change the value of install_size_system in the file pmb/config/__init__.py

If you have a device, that works with fastboot, you can boot the kernel now without flashing it:

./pmbootstrap.py flasher boot

Otherwise, you will need to flash the kernel to the device boot partition:

./pmbootstrap.py flasher flash_kernel

Alternative to flashing: export

If the flashing method does not work, it is also possible to export all generated image files to a specific directory (with symlinks), so you can flash it manually with your host Linux system (or even on Windows with proprietary flashers such as Odin, if this is the only way it works for you):

./pmbootstrap flasher export

After flashing

If you are lucky, your screen may give some clues that you are booted into pmOS. If not, do not get discouraged, the graphics on your device may not yet be setup correctly. The next steps are to see if you can connect to the device through telnet over USB. See the [[Inspecting the initramfs]] page for more details.

Don't forget to create a specific wiki page for your device, and add it to the [[devices]] page. If you noticed anything that was unclear or discovered something useful, please help to improve the wiki!

Feel free to ask / help on IRC or Matrix group