Difference between revisions of "Porting to a new device"

From postmarketOS
Jump to navigation Jump to search
Line 15: Line 15:
<pre class="shell">cp -r aports/device/device-samsung-i9100 aports/device/device-vendor-name</pre>
<pre class="shell">cp -r aports/device/device-samsung-i9100 aports/device/device-vendor-name</pre>
The important files are <code>APKBUILD</code> (''build recipe, [[Glossary#apk|apk is an Alpine Linux term]]'') and [[deviceinfo]]. Please adjust them as necessary. (More info [https://wiki.postmarketos.org/wiki/How_to_find_device_specific_information#Fastboot_.28boot.img.29_flash_offsets])<br/>Note that if your device uses '''fastboot''' or [https://wiki.postmarketos.org/wiki/Deviceinfo_flash_methods#Isorec_or_bootimg.3F '''heimdall-bootimg'''], you will need to add <code>mkbootimg</code> to the <code>depends=</code> list in the <code>APKBUILD</code>, and the following variables at the end of <code>deviceinfo</code> ([https://wiki.postmarketos.org/wiki/How_to_find_device_specific_information#Fastboot_.28boot.img.29_flash_offsets guide], [https://github.com/postmarketOS/pmbootstrap/blob/eddf81a730b68076e59b66f2a6163e6587b7fc84/aports/device/device-sony-yuga/deviceinfo#L22-L28 example]):
The important files are <code>APKBUILD</code> (''build recipe, [[Glossary#apk|apk is an Alpine Linux term]]'') and [[deviceinfo]]. Please adjust them as necessary. (More info [[How_to_find_device_specific_information#Fastboot_.28boot.img.29_flash_offsets]])<br/>Note that if your device uses '''fastboot''' or [https://wiki.postmarketos.org/wiki/Deviceinfo_flash_methods#Isorec_or_bootimg.3F '''heimdall-bootimg'''], you will need to add <code>mkbootimg</code> to the <code>depends=</code> list in the <code>APKBUILD</code>, and the following variables at the end of <code>deviceinfo</code> ([https://wiki.postmarketos.org/wiki/How_to_find_device_specific_information#Fastboot_.28boot.img.29_flash_offsets guide], [https://github.com/postmarketOS/pmbootstrap/blob/eddf81a730b68076e59b66f2a6163e6587b7fc84/aports/device/device-sony-yuga/deviceinfo#L22-L28 example]):
<pre class="shell"># Fastboot related
<pre class="shell"># Fastboot related

Revision as of 06:52, 22 October 2017


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.

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
  • Run ./pmbootstrap.py init and configure for a new device
  • Open a second terminal and run ./pmbootstrap.py log to get detailed output from the following pmbootstrap commands

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) and deviceinfo. Please adjust them as necessary. (More info How_to_find_device_specific_information#Fastboot_.28boot.img.29_flash_offsets)
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

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

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 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 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 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:

./pmbootstrap.py kconfig_check

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

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.

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 dtb file:

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

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

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 deviceinfo.

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

The --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

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 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