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. We even have a tutorial for that.
- Clone the repository:
git clone https://github.com/postmarketOS/pmbootstrap
./pmbootstrap.py initand configure for a new device
- Open a second terminal and run
./pmbootstrap.py logto get detailed output from the following pmbootstrap commands
Create an appropriate
device-$vendor-$name package in the
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) and deviceinfo. Please adjust them as necessary. (More info )
Note that if your device uses fastboot or heimdall-bootimg, 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_base="" 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 chttps://wiki.postmarketos.org/wiki/How_to_find_device_specific_information#Fastboot_.28boot.img.29_flash_offsetsreated 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
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 default config 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
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 required kernel options must be set for pmOS to work.
The easiest way is getting out of the menu with "Exit", and confirming when asked whether the changes should be saved. Then run the following to see what needs to be changed in your config:
Adjust your kernel config until
kconfig_check doesn't complain anymore.
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
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
Important: You will need to patch your kernel to get it working with GCC6 - read how to create a patch when packaging software for instructions.
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
# 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
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
Is it possible that your device need the dtb file appended to the boot.img instead of the kernel itself. In that case you have to pack all the generated dtb files into a single master dtb.img file (see example here and here) and add the variable
deviceinfo_bootimg_qcdt="true" in the
If you are unsure, whether your device has an appended dtb file, use extract-dtb on an existing kernel image or boot.img file (e.g. from LineageOS or TWRP).
extract-dtb is packaged for postmarketOS, you can build it with
pmbootstrap build extract-dtb.
If you want to install to the system partition of an image file, run the following:
./pmbootstrap.py install --no-fde
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 --no-fde --sdcard=/dev/mmcblk0
--no-fde disables full disk encryption. You can enable it once you have graphical output and touchscreen or physical keyboard working, so you can actually type in the password. Additional porting steps to get that working are described here.
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 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
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 Boot process and Inspecting the initramfs pages for more details. Also check Tuning sysfs.
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.
Adding osk-sdl support
If the display & the touchscreen interface are working, then it's time to add support for osk-sdl, so that you are able to use full disk encryption on the root filesystem. Instructions for adding support can be found here: Porting Osk-SDL to New Devices