Porting Guide

Preetam D'Souza edited this page May 2, 2017 · 12 revisions

Interesting in porting Maru OS to a new device? This guide will help walk you through the process.

Overview

At a high-level, your porting flow will look like this:

  1. Announce your desired port on @chevdroid's device port thread
  2. Create a porting thread for your device where you can ask questions during the porting process and share knowledge. Here are some example threads:
  3. Hack on your port, ask questions, share your builds for others to test, etc. on your thread until it's pretty stable
  4. Submit your port to The Maru OS Project and fix any issues found during review
  5. Celebrate when your device port rolls out with the latest official builds!

How do I get started on a port?

Adding a device port to Maru OS is nearly the same as adding a port to the Android Open Source Project (AOSP). You will need to provide three new repositories for your device:

  1. device_<vendor>_<codename>: your device-specific configuration
  2. device_<vendor>_<codename>_kernel: kernel source for your device
  3. device_<vendor>_<codename>-kernel: prebuilt kernel image for your device

Create these repos on your personal GitHub account with the prefix maruos_. This way it's obvious that these repos are intended to be part of the Maru OS Project, and others can easily find your repos if they'd like to collaborate. During your early bringup phase, you can hack on your device port and push up to these repos to share your work.

Once your port is stable and is ready to be submitted, a maruos org member will re-create them under the official maruos org and you can submit your work as a PR.

Now, let's take a closer look at these three.

device_<vendor>_<codename>

Example: https://github.com/pdsouza/maruos_device_lge_bullhead

This is the hardware-specific configuration for your device. Ideally, your device vendor has an open-source repository that you can use as a starting point, like with the Nexus devices. If not, you'll have to use a similar device repo and tweak things to make it work.

Customizations needed: You will need to create a new product configuration and lunch option for your device called maru_<codename> that will make your device "maru-aware". See this patch that adds the maru_bullhead product for bullhead (Nexus 5X) as an example.

device_<vendor>_<codename>_kernel

Example: https://github.com/pdsouza/maruos_device_lge_bullhead_kernel

This is the actual Linux kernel source for your device. The kernel source is under the GPL license, so your device vendor should make it available somewhere on their website.

Customizations needed: You will need to create a new defconfig that enables some kernel options that Maru OS requires. See this patch for bullhead as an example. Read Kernel for more details.

device_<vendor>_<codename>-kernel

Example: https://github.com/pdsouza/maruos_device_lge_bullhead-kernel

This is just the prebuilt kernel image binary that you get when you build device_<vendor>_<codename>_kernel.

How do I get my port accepted as an official device?

Before your port can be accepted as an official device, it must be tested by at least a few people and confirmed to work pretty well. "Works pretty well" means that all the hardware (graphics, audio, cellular, wifi, etc.) works and that Maru Desktop works. Your porting thread is a good place to share your builds and get feedback.

Once you're confident your port works well, and you can commit to being a device maintainer, you can kick off the process to get your port included in Maru OS:

  1. Get in touch with one of the maruos members on the forums or our gitter who can help guide you through the process
  2. Once we check out your thread and confirm that it works well, we'll re-create your device repos on the org
  3. Send over your work via a PR to the freshly created device repos on maruos, and work with us to fix any issues found in your PR (all commits signed off as per contribution guidelines, etc.)
  4. We'll merge your PR and give you write access to these repos
  5. Send us a PR to add the new device repos to the Maru OS manifest

Known Porting Issues

Container login failures

Kernels before 3.15, especially 3.10, cause PAM errors that prevent user authentication in secondary namespaces--even with correct credentials! This is known to affect the Nexus 5X and Nexus 6P. Note that this does not affect the 3.4 kernel for the Nexus 5 or Nexus 7.

Fix: apply this backported 3.15 kernel patch https://github.com/maruos/android_kernel_msm/commit/86406af61755852d74d23b051d4327565528a506

Related threads:

More info:

No desktop output on HDMI screen with arm64 devices (https://github.com/maruos/blueprints/issues/5)

If porting to an arm64 device and you are using the prebuilt armhf desktop container image, note that mclient (graphics bridge for the desktop) will crash. This is because mclient is only packaged as an armhf 32-bit binary and it has issues dealing with a 64-bit mflinger.

Fix: Please build an arm64 desktop container with the master branch of https://github.com/maruos/blueprints and use that for your builds:

$ ./build.sh -n jessie -- -a arm64

Related threads: