Difference between revisions of "Porting Guide"

From WebOS-Ports
Jump to navigation Jump to search
Line 24: Line 24:
  
 
== Building the Android pieces ==
 
== 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 for all java and app layer related components. The tiny Android system will be running in a virtual container (we're using [https://linuxcontainers.org/ LXC]) on the target device to enable LuneOS to access several of the hardware features.
  
 
Setup yourself to be able to build Android with following the steps in [http://source.android.com/source/initializing.html 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 webOS ports.
 
Setup yourself to be able to build Android with following the steps in [http://source.android.com/source/initializing.html 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 webOS ports.
  
Now check out the webOS ports Android tree (which is currently based on CyanogenMod 10.1):
+
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 ~/work/cm-wop-10.1
+
  mkdir ~/work/cm-wop-11.0
  repo init -u https://github.com/webOS-ports/android.git -b wop-10.1
+
  repo init -u https://github.com/webOS-ports/android.git -b wop-11.0
 
  repo sync -j8
 
  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 and add your device layer and kernel tree.
+
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 and add your device layer and kernel tree. 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.
  
 
Building the Android parts is now a matter of
 
Building the Android parts is now a matter of
Line 41: Line 50:
 
  make target-files-package
 
  make target-files-package
  
If the build fails it may required that you modify some parts of the device layer in order to make everything work.
+
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 [[Bug_Report_guidelines|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.  
 
As next step we have to bundle everything into a package we can drop into the OpenEmbedded build process later.  
Line 48: Line 57:
 
  cp `find obj -name filesystem_config.txt` .
 
  cp `find obj -name filesystem_config.txt` .
 
  cp ramdisk.img android-ramdisk.img
 
  cp ramdisk.img android-ramdisk.img
  tar cjf phablet-`date +%Y%m%d`-0-<machine>.tar.gz system symbols android-ramdisk.img filesystem_config.txt
+
  tar cjf cm-wop-11.0-`date +%Y%m%d`-0-<machine>.tar.gz system symbols android-ramdisk.img filesystem_config.txt
  
The resulting tar.gz archive is what you need to take and store somewhere.
+
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 unoffcial ones too. As all packages include properietary binaries
  
 
== Kernel ==
 
== Kernel ==
Line 56: Line 65:
 
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.
 
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 from the webOS userspace, we need to add a few extra kernel configs that are usually not enabled by default for Android.
+
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 do
 +
 
 +
$ make <devicename>_defconfig
 +
$ 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/daisy/scripts/verify_kernel_config
 +
$ chmod +x verify_kernel_config
 +
$ ./verify_kernel_config defconfig
  
* CONFIG_SYSVIPC=y
+
Fix all reported misconfigured entries. Afterwards save the created defconfig file for later.
* CONFIG_NAMESPACES=y
 
* CONFIG_UTS_NS=y
 
* CONFIG_IPC_NS=y
 
* CONFIG_USER_NS=y
 
* CONFIG_PID_NS=y
 
* CONFIG_NET_NS=y
 
* CONFIG_DEVTMPFS=y
 
* CONFIG_DEVTMPFS_MOUNT=y
 
* CONFIG_DEVPTS_MULTIPLE_INSTANCES=y
 
* CONFIG_FSNOTIFY=y
 
* CONFIG_DNOTIFY=y
 
* CONFIG_INOTIFY_USER=y
 
* CONFIG_FANOTIFY=y
 
* CONFIG_FANOTIFY_ACCESS_PERMISSIONS=y
 
* CONFIG_SWAP=y
 
* # CONFIG_ANDROID_PARANOID_NETWORK is not set
 
* CONFIG_VT=y
 
* CONFIG_VT_CONSOLE=y
 
* CONFIG_AUTOFS4_FS=y
 
  
 
== Creating an OpenEmbedded machine layer ==
 
== Creating an OpenEmbedded machine layer ==
  
To build webOS with OpenEmbedded you need to create machine layer for it (also called board support package (BSP)). There are already some available in the [http://git.shr-project.org/git/?p=meta-smartphone.git;a=summary meta-smartphone] layer which can be used as reference. A very good guide on how to create a machine layer is available [https://www.yoctoproject.org/docs/current/bsp-guide/bsp-guide.html here] from the [https://yoctoproject.org/ Yocto Project].
+
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 [https://github.com/webOS-ports/meta-smartphone/tree/webOS-ports/daisy]) but you can start with keeping your meta layer as separate repository.
  
 
== Integration with several webOS components ==
 
== Integration with several webOS components ==

Revision as of 20:55, 16 September 2014

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 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 Ubuntu)
  • OpenGL ES2.0 HAL and drivers
  • Audio/Media HAL and services, to re-use the hardware video decoders
  • RILD for modem support

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

Porting webOS ports to another target device consists of several steps:

  1. Building the Android pieces
  2. Kernel modifications
  3. Creating an OpenEmbedded machine layer
  4. Integration with several 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 for 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.

Setup yourself 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 webOS ports.

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 ~/work/cm-wop-11.0
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 and add your device layer and kernel tree. 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.

Building the Android parts is now a matter of

. build/envsetup.sh
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.gz 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 unoffcial ones too. As all packages include properietary 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 do

$ make <devicename>_defconfig
$ 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/daisy/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 [1]) but you can start with keeping your meta layer as separate repository.

Integration with several webOS components

To integrate an Android based propably with webOS ports some components need to be modified.

nyx-modules

The nyx module are responsible within webOS to support certain hardware features in a device independet manner. We already modified the Open webOS standard implementation so it should work with most Android device. The only thing which need 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 needs 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 [2].

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: