Jump to content

Porting to a new device/Preparation

From postmarketOS Wiki
  • Search the Devices page for your device to avoid duplicate work. Also search the wiki for your device, and check for links to existing branches. If your target device has an x86-64 CPU, you may be able to use the generic x64 UEFI device port.
  • Identify what SoC (System on a Chip) the device has and check if it's in Supported SoCs in mainline list. If SoC is supported by a (close to) mainline Linux kernel, it is preferable to port it using that kernel. You will be able to achieve greater hardware support (GPU, modem, and so on) while also having more up-to-date software. In some cases, it can even be easier.

If your device isn't well-supported by any (close to) mainline kernel, keep reading this guide.

For help, connect to #main and #porting Matrix/IRC channels and ask your question. People are happy to answer your questions!

Requirements

Development environment

Note See pmbootstrap's system requirements and install dependencies if needed.

To set up a development environment, you will need a Linux system capable of making builds and running pmbootstrap, our development and installation tool. If you don't have a Linux-based OS installed, you may want to set up a virtual machine with VirtualBox first.

It is recommended to install pmbootstrap from Git, as distributions often include outdated versions of pmbootstrap.

Knowledge

It is recommended that you at least somewhat know how to use Linux distributions, how to build software, how APKBUILDs work, and also know how to use the shell, as the porting process is slightly harder than just running a few commands.

Target Device

If your target device has an ARM processor, it must have a floating-point unit (FPU). If the device has at least an ARMv7 CPU, it should have an FPU; however, only some ARMv6 CPUs have one.

Most smartphones have an FPU. Of the first 80+ ports that we started, only two phones lacked an FPU: the HTC Wildfire from 2010 (#1203) and the Vodafone 858 Smart from 2011 (#1592)). Both phones use the MSM7225, an ARMv6 SoC. If your phone was made before 2012, make sure it has an FPU.

This guide assumes you are going to port postmarketOS to a device named wiki-example.

My device runs the Linux kernel (e.g. Android), but the vendor does not provide the source

  1. Ask kindly via e-mail.
  2. If they don't provide the source, team up with gpl-violations.org. You have the legal right to get the source, because the Linux kernel is under the GPLv2!
  3. Consider building generic kernel for your device.
  4. Another option is using prebuilt kernels

Proprietary blobs

Many devices require proprietary blobs for enabling certain peripherals (wifi/bluetooth/cellular/GPS). These repositories appear to contain blobs for a large percentage of devices out there.

Tips

To get more information about a specific command available in pmbootstrap, run:

$ pmbootstrap {command} --help