Latest revision as of 22:42, 19 December 2016

Overview

To rapidly support a wide range of devices, our architecture reuses some of the drivers and hardware enablement available for Android.

As a consequence, at the current images you'll find some of the Android services running at the device next to the LuneOS/webOS services.

For quick reference, these are the current components used from Android:

Linux Kernel (stock Android kernel provided by the vendor, with a few changes to support some extra features needed by LuneOS/webOS)
OpenGL ES 2.0 HAL and drivers
Audio/Media HAL and services, to re-use the hardware video decoders
RILD (RIL Daemon) for modem support

Other than the very basic services (needed to re-use the binary blobs already available), the rest is just pure LuneOS/webOS goodness .

Porting LuneOS to another target device consists of several steps:

Building the Android pieces
Kernel modifications
Creating an OpenEmbedded machine layer
Integration with several LuneOS/webOS components

All in all you should try to make each part of your work available for other people and easily to reproduce so other people can start helping with the port.

Building the Android pieces

As first step we have to build a special version of Android which is build on top of the cyanogenmod sources but stripped of all java and app layer related components. The tiny Android system will be running in a virtual container (we're using LXC) on the target device to enable LuneOS to access several of the hardware features.

Set yourself up to be able to build Android with following the steps in Initializing a Build Environment. However you can ignore the steps to install a java environment as it's currently not needed to build the required Android parts for LuneOS/webOS.

AOSP based builds should also work in general, but we haven't tested it. Sony has quite detailed instructions on their website for this to get you started: http://developer.sonymobile.com/open-devices/aosp-build-instructions/how-to-build-aosp-nougat-for-unlocked-xperia-devices/#build-experimental-aosp-nougat-7-1

Basically you need to do the following: Install JDK (Below is for Ubuntu >= 15.04 for steps on Ubuntu 14.04 see [1]

$ sudo apt-get update

For Ubuntu 16.04:

When using CM 10.1/11.0 based builds you'll need Oracle JDK:

$ sudo add-apt-repository ppa:webupd8team/java
$ sudo apt-get update
$ sudo apt-get install oracle-java7-installer

When using CM 12/13 based builds you'll need OpenJDK JDK:

$ sudo add-apt-repository ppa:openjdk-r/ppa
$ sudo apt-get update
$ sudo apt-get install openjdk-7-jdk

For Ubuntu 15.04:

When using CM 10.1/11.0 based builds you'll need Oracle JDK:

$ sudo add-apt-repository ppa:webupd8team/java
$ sudo apt-get update
$ sudo apt-get install oracle-java7-installer

When using CM 12/13 based builds you'll need OpenJDK JDK:

$ sudo add-apt-repository ppa:openjdk-r/ppa
$ sudo apt-get update
$ sudo apt-get install openjdk-7-jdk

Install required packages:

$ sudo apt-get install git-core gnupg flex bison gperf build-essential \
zip curl zlib1g-dev gcc-multilib g++-multilib libc6-dev-i386 \
lib32ncurses5-dev x11proto-core-dev libx11-dev lib32z-dev ccache \
libgl1-mesa-dev libxml2-utils xsltproc unzip schedtool

Next install the repo tool in your home directory, follow the steps here or below:
Make sure you have a bin/ directory in your home directory and that it is included in your path:

$ mkdir ~/bin
$ PATH=~/bin:$PATH

Download the Repo tool and ensure that it is executable

$ curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
$ chmod a+x ~/bin/repo

If you're doing a new port you should based it on cynogenmod 11.x rather than the old 10.x version we're using for some targets (for example the Nexus 4). Now check out the webOS-ports Android tree:

$ mkdir <your-work-directory>
$ cd <your-work-directory>
$ repo init -u https://github.com/webOS-ports/android.git -b wop-11.0
$ repo sync -j8

All official supported devices are already part of the checked out tree. If you want to add a further device you have to change the manifest file (file default.xml) and add your device layer and kernel tree. You'll find the manifest in .repo/manifests. For example for the Nexus 4 it looks like this:

 <project name="webOS-ports/android_device_lge_mako" path="device/lge/mako" remote="github" revision="wop-11.0" />
 <project name="CyanogenMod/android_kernel_google_msm" path="kernel/google/msm" remote="github" />

NOTE: For the Nexus 4 we did some modifications to the device repository and therefore using a fork of the original CyanogenMod repository with a wop-11.0 branch in it to indicate this.

NOTE: Don't forget to extract the properietary blobs for your device. See the CyanogenMod build guide for this.

NOTE: In the manifest file default.xml, "-- target devices --" part, the LuneOS developers use CyanogenMod device codename and not the commercial device name. Codename devices matching : mako for Nexus 4, tuna (maguro) for Galaxy Nexus (GSM) (tuna is a generic codename for Galaxy Nexus with GSM or CDMA), grouper for Nexus 7 (Wifi, 2012 version), tenderloin for HP TouchPad. You can find all the CyanogenMod devices codename here : https://download.cyanogenmod.org/

Building the Android parts is now a matter of

$ . build/envsetup.sh
$ cd vendor/cm
$ ./get-prebuilts
$ cd ../..
$ brunch cm_<machine>-userdebug
$ make target-files-package

If the build fails it is required that you modify some parts of the device layer in order to make everything work. If you find further problems with the build like unsolved dependencies feel free to open a bug report (see Report Bugs) or ask through our communication channels.

As next step we have to bundle everything into a package we can drop into the OpenEmbedded build process later.

$ cd out/target/product/<machine>/
$ cp `find obj -name filesystem_config.txt` .
$ cp ramdisk.img android-ramdisk.img
$ tar cjf cm-wop-11.0-`date +%Y%m%d`-0-<machine>.tar.bz2 system symbols android-ramdisk.img filesystem_config.txt

The resulting tar.gz archive is what you need to take and store somewhere. For the official supported devices all packages are placed on http://build.webos-ports.org/cm-wop-11.0/. However we're not going to store the unofficial ones too. As all packages include proprietary binaries

Kernel

The used kernel is directly based on an Android device kernel without any extra modifications. We will create a recipe in the OpenEmbedded machine layer later.

As a requirement for LuneOS we need to add a few extra kernel configs that are usually not enabled by default for Android.

To generate a config suitable for LuneOS clone the kernel sources for your device. After you switched to the repository (if you included the kernel repository in default.xml above, you should be able to find it in kernel/<manufacturer>/<devicename>/

Then do:

$ make <devicename>_defconfig

In case that doesn't work try:

$ make defconfig

Followed by:

$ cp .config defconfig

That will create a file called .config in the root path of the directory. Now we need to enable all required options for LuneOS. We wrote a simple helper scripts which checks the config file automatically for the required options:

$ wget https://raw.githubusercontent.com/webOS-ports/meta-webos-ports/jethro/meta-luneos/scripts/verify_kernel_config
$ chmod +x verify_kernel_config
$ ./verify_kernel_config defconfig

Fix all reported misconfigured entries. Afterwards save the created defconfig file for later.

Creating an OpenEmbedded machine layer

To build webOS with OpenEmbedded you need to create machine layer for it (also called board support package (BSP)). Normally we place all machine layers within meta-smartphone (see [2]) but you can start with keeping your meta layer as separate repository.

Good starting points for creating the meta layer for the machine are

The yocto reference manual: http://www.yoctoproject.org/docs/1.6.1/bsp-guide/bsp-guide.html
The existing layers: https://github.com/shr-distribution/meta-smartphone/tree/fido

The minimum a meta layer for a new machine must provide are:

the machine configuration file in conf/machine/<machine>.conf
a kernel recipe: recipes-kernel/linux/linux-<vendor>-<machine>.bb
a android system image: recipes-core/android-system-image/android-system-image_<machine>.conf

We will not describe all details here but point out the important points to get everything working for devices based on Android.

The machine config needs to include following things:

<source lang="bash"> require conf/machine/include/bsp-android-hybris.inc

ANDROID_BOARD_BOOTIMAGE_PARTITION = "<name of the boot partition within the Android recovery. for example 'mmcblk0p16'>" ANDROID_BOARD_SYSTEMIMAGE_PARTITION_SIZE = "<Use value from BoardConfig.mk from Android device tree>" ANDROID_BOARD_FLASH_BLOCK_SIZE = "<Use value from BoardConfig.mk from Android device tree>"

Use this when Android part is based on wop-10.1

PREFERRED_PROVIDER_virtual/android-headers = "phablet-headers"

.. and when based on wop-11.0

PREFERRED_PROVIDER_virtual/android-headers = "android-headers" </source>

The recipe for the android-system-image should look like this:

<source lang="bash"> require recipes-core/android-system-image/android-system-image.inc

PV = "<build date>-<build number>" PR = "${INC_PR}.0"

SRC_URI = "http://<url to .tar.gz package created above>" SRC_URI[md5sum] = "<md5 checksum of .tar.gz package>" SRC_URI[sha256sum] = "<sha256 checksum of .tar.gz package>" </source>

The kernel recipe at recipes-kernel/linux/linux-<vendor>-<machine>_git.bb needs to include the following

Values needed to create the fastboot'able kernel image

CMDLINE = "<fill in the same cmdline as found in the BoardConfig.mk of the Android device tree>" KERNEL_RAM_BASE = "<Take value from BoardConfig.mk>" RAMDISK_RAM_BASE = "<Take value from BoardConfig.mk>" SECOND_RAM_BASE = "<Take value from BoardConfig.mk>" TAGS_RAM_BASE = "<Take value from BoardConfig.mk>"

This will make sure the kernel can be flashed with fastboot on the device

inherit kernel_android </source>

Integration with several webOS components

To integrate an Android base with LuneOS some components need to be modified.

nyx-modules

The nyx modules are responsible within webOS/LuneOS to support certain hardware features in a device-independent manner. We already modified the Open webOS standard implementation so it should work with most Android devices. The only thing which needs to be done for a need porting device is to add a device configuration file to the repository (or as patch in your OE machine layer).

The machine configuration file needs to be placed within the src/machine directory of the nyx-modules repository and should look like this:

set(MODULE_SYSTEM_WEBOS_LINUX	YES)
set(MODULE_KEYS_WEBOS_LINUX	YES)
set(MODULE_TOUCHPANEL_WEBOS_LINUX	YES)
set(MODULE_LED_CONTROLLER_WEBOS_LINUX	YES)
set(MODULE_HAPTICS_TIMEDOUTPUT_WEBOS_LINUX	YES)
add_definitions(-DKEYPAD_INPUT_DEVICE=\"/dev/input/event2\")
add_definitions(-DBATTERY_SYSFS_PATH=\"/sys/class/power_supply/battery/\")

The last two lines need to be adjusted to fit your porting device. If you need further assistance you can also look at the already existing configuration files for other machines at [3].

LunaSysMgr

You have to create a machine specific configuration file within the luna-sysmgr repository (see https://github.com/webOS-ports/luna-sysmgr). The file must have the name luna-<machine>.conf and needs to be placed within the conf directory. The file should have the following content:

See the sample file for Mako: https://github.com/webOS-ports/luna-sysmgr/blob/webOS-ports/master/conf/luna-mako.conf

Setting it up as an official build

1. Add the target(s) to https://github.com/webOS-ports/jenkins-jobs/commit/737eeb1b27dda3b0da44d8cec1fd69b8716f4304 2. Create jobs in Jenkins for stable, testing and unstable. You can copy from existing jobs: http://jenkins.nas-admin.org/ 3. Add the layers for the targets (TO BE COMPLETED) 4. Enable builds for new targets in luneos-stable_build, luneos-unstable_build and luneos-testing_build

Difference between revisions of "Porting Guide"