Project

General

Profile

PortingGuideS5PC110

This guide assumes your phone has a S5PC110/Exynos 3110 SoC

Prerequisites

Before porting your device to Replicant, you must make sure it complies with the following:
  • Already supported by CyanogenMod (or, worst-case scenario, by a non-official CyanogenMod port)
  • CyanogenMod support for this device is available for one of Replicant versions (pick the latest)
  • The phone is GSM: Replicant doesn't support CDMA phones yet
  • It is likely to be usable without blobs nor firmwares and with Replicant replacements

Investigating the phone hardware

Before doing anything, you will need to know the codename of the device. You can find it out on CyanogenMod Wiki or on CyanogenMod download page.
For instance, the Nexus S codename is: crespo.

One very important step is to find out if the device is Tivoized: that means that even though the manufacturer releases the kernel source code for the device, the bootloader checks the kernel signature and will refuse to start it if it's not properly signed by the manufacturer. In other words, if you build the kernel yourself, the device will refuse to run it since it's not signed by the manufacturer. Since the Linux kernel is released under the GPLv2, there are no specific dispositions to counter Tivoization, and so porting the device to Replicant is pointless as it will require a prebuilt and signed kernel from the manufacturer.

First thing to consider before starting a port, when all of the above is assumed, is to see how many non-free components are required by CyanogenMod.
The easiest way to do this is to spot the device repository in CyanogenMod repos and look for the extract-files.sh or proprietary-blobs.txt file.
For instance, the list of non-free components for the Nexus S is extract-files.sh

From that list, spot what is related to what hardware component (audio, camera, sensors, gps, modem, etc): that gives an idea of the amount of work required to add support for the phone.

During the port, you might need to find precise infos about the hardware that is in the phone. A good to do this is by looking at the kernel defconfig for the device, another way is to download the Service Manual for the device.

Getting everything ready

In order to prepare everything for the Replicant port:

Cloning the device files

Once your Replicant tree is ready, you can start by adding the necessary repos for your device.
That means cloning the necessary repos in the right place. These repos are:
  • A device-specific repo. On CyanogenMod, it is usually called: android_device_vendor_device.
  • Sometimes one or more common repo(s), usually called: android_device_vendor_devices-common.
    Some devices don't need any common repo, but some do.
  • A kernel repo. On CyanogenMod, it is usually called: android_kernel_samsung_devices.
    The kernel repo can be shared across a family of devices (for instance, on kernel repo for Samsung Exynos, one for Samsung OMAP, etc).
    If there are different branches in the kernel repo, be sure to use the one that will match userspace: if you are porting to ICS, take the branch called ics or ask the people who know which branch to use.
    Generally speaking, the following kernel versions match the given userspaces:
Android version CyanogenMod version Kernel version
Android 2.3 CM 7.x 2.6.35
Android 4.0 CM 9.x 3.0.8
Android 4.1 CM 10 3.0.31
Android 4.2 CM 10.1 3.4
Sometimes, these repos aren't held in CyanogenMod repos but instead in some other projects repos, such as:

Generally speaking, it is a good idea to ask the members of the CyanogenMod community where to find what (especially for kernel sources and for which branch to use).

Clone these repos in the correct locations and remove the prefix (e.g. android_device_samsung_crespo must be cloned in device/samsung/ and renamed to crespo).

Creating the kernel repo

If the kernel repo is nowhere to be found, you'll need to get the kernel source directly from the vendor, especially if your device is supported by a 3rd party CyanogenMod fork.
Keep in mind that the Linux kernel is GPLv2, so vendors have the legal obligation to release the modified kernel sources as soon as they sell you the device.
That means the kernel sources will be available online. Here are some websites where such releases are done:

Once you have the kernel sources, read the instructions to find out which defconfig to use.

Since manufacturers usually don't release the git history along with the files, you'll need to recreate a git repo:
  • Clone the mainline kernel in the same version as the Makefile from the sources you just obtained
  • Remove the cloned files except the .git directory
  • Move the manufacturer kernel tree at the place of the files you just removed
  • Add all the files in git (git add -A) and commit (git commit) with a message explaining what you just imported (e.g. "GT-I9000 GB Opensource Update 2")

Now that you have a git repo, you can move it to the Replicant code tree, under the name: kernel/vendor/devices (e.g. kernel/samsung/aries).
Make sure to make the devices name match the devices in android_device_vendor_devices-common if the kernel is shared across these devices or to match the device in android_device_vendor_device.

In case of a prebuilt kernel

Some devices are still using a prebuilt kernel. Even though the CyanogenMod team is trying to avoid that, it remains in many repos.
For such devices, you will need to remove the prebuilt binaries and the instructions to copy the prebuilt kernel and its modules.

In the device repository (device/vendor/device) and common repository for your device (if any), remove the prebuilt kernel and modules (usually called kernel and module.ko (replace module with the name of a module) or a modules directory).
Remove the instructions to copy these prebuilts on the makefiles. Remove instructions such as:

PRODUCT_COPY_FILES += \
    $(LOCAL_KERNEL):kernel

LOCAL_KERNEL := $(LOCAL_PATH)/kernel

and anything regarding TARGET_PREBUILT_KERNEL as well as the instructions to copy the prebuilt modules.

The BoardConfig.mk (or BoardConfigCommon.mk in the common directory for your device) will most likely hold a line like:

TARGET_PREBUILT_KERNEL := device/samsung/p5/kernel

you must remove this line.

Now that the device repository has no prebuilt instructions, you can add the instructions to build the kernel. In the BoardConfig.mk file, add the following lines:

TARGET_KERNEL_SOURCE := kernel/samsung/p3
TARGET_KERNEL_CONFIG := samsung_p5_defconfig

and make sure to replace the location and defconfig by the correct values for your devices (being the location of the device kernel tree and the appropriate defconfig).

Building the correct kernel image format

There are different types of kernel images:
  • Android image: that is a zImage, without a separate initramfs
  • zImage: that is a zImage, with a built-in initramfs
  • uImage: that is an image for the u-boot bootloader, with a built-in initramfs

You need to find out which type of kernel image your device uses. Asking people who know about that is the best idea.

Android image

This is the easiest case to handle: just make sure the CONFIG_INITRAMFS_SOURCE option in the kernel defonfig is left blank or undefined:

CONFIG_INITRAMFS_SOURCE="" 

zImage with built-in initramfs

Building a zImage with a built-in initramfs requires the following steps:
In the kernel defconfig, define the CONFIG_INITRAMFS_SOURCE option that way:

CONFIG_INITRAMFS_SOURCE="../../root" 

Once this is done, duplicate the defconfig and add the _recovery prefix before the _defconfig ending (e.g. herring_recovery_defconfig), edit that file and replace CONFIG_INITRAMFS_SOURCE with:

CONFIG_INITRAMFS_SOURCE="../../recovery/root" 

Back to the device repository, edit the BoardConfig.mk file and add the following line:

TARGET_KERNEL_RECOVERY_CONFIG := samsung_p5_recovery_defconfig

and make sure to replace the defconfig by the appropriate defconfig you just cloned (the one with the _recovery_defconfig ending).

Still in the device repository, create a bootimg.mk file containing the following:

LOCAL_PATH := $(call my-dir)

$(INSTALLED_BOOTIMAGE_TARGET): $(INSTALLED_KERNEL_TARGET)
    $(ACP) $(INSTALLED_KERNEL_TARGET) $@

$(INSTALLED_RECOVERYIMAGE_TARGET): $(INSTALLED_RECOVERY_KERNEL_TARGET)
    $(ACP) $(INSTALLED_RECOVERY_KERNEL_TARGET) $@

Edit the BoardConfig.mk file and add the following line:

BOARD_CUSTOM_BOOTIMG_MK := device/vendor/device/bootimg.mk

and make sure to replace device/vendor/device/ to the correct path to your device's repository.

uImage with built-in initramfs

Follow the previous instructions (zImage with built-in initramfs) and set the BOARD_USES_UBOOT variable in the BoardConfig.mk file:

BOARD_USES_UBOOT := true

Adding the device to the build targets

Now that the repos are cloned, you need to modify some makefiles to cope with Replicant paths.
In the device repository (device/vendor/device), modify the file called cm.mk and replace the vendor/cm/ occurrences by vendor/replicant/. Other makefiles may need that as well (in any case, build will fail very early if you missed one). In that same cm.mk file, change the PRODUCT_NAME variable by repalcing the cm prefix with replicant (e.g. change PRODUCT_NAME := cm_crespo to PRODUCT_NAME := replicant_crespo).

Now that your device files are ready, you can declare a new build target: these are held in vendor/replicant/jenkins-build-targets.
Modify that file and add a line (at the end) with the PRODUCT_NAME you set and the -eng suffix (e.g. replicant_crespo-eng).

Setting up the build environment

From now on, everything should be ready to start a build. To check for errors or missed occurrences, start a terminal in the Replicant tree root and lunch:

source build/envsetup.sh
lunch replicant_device-eng

Adapt replicant_device-eng from what you added to the jenkins-build-target (e.g. replicant_crespo-eng).
If an error occurs, it will explicitly report it and you'll need to fix it before doing anything.
If everything works correctly, you should see something like:

============================================
PLATFORM_VERSION_CODENAME=REL
PLATFORM_VERSION=4.0.4
TARGET_PRODUCT=replicant_crespo
TARGET_BUILD_VARIANT=eng
TARGET_BUILD_TYPE=release
TARGET_BUILD_APPS=
TARGET_ARCH=arm
TARGET_ARCH_VARIANT=armv7-a
HOST_ARCH=x86
HOST_OS=linux
HOST_BUILD_TYPE=release
BUILD_ID=IMM76L
============================================

You must repeat these steps everytime before building anything on a freshly-opened terminal.
Remember:

source build/envsetup.sh
lunch replicant_device-eng

(make sure to replace device by your device's product name).

Building the kernel

Once the devices repos are in place and the build target is configured, you are now able to start building things and the first thing to build is obviously the kernel.

Once your terminal is correctly setup (the lunch command worked correctly), you can start building the kernel:

make -j9 bootimage

It will take a couple of minutes, depending on how fast your setup is. At the end, it should create a boot.img file in out/target/product/device (replace device with your device's product name).
If not, an error will be shown and you'll have to fix it.

Building recovery

Building the kernel with success is a great step, but it is hard to make any use of it (unless your userspace matches the initramfs, but that's not always the case).
That's why you'll have to build recovery next. Furthermore, some devices only allow flashing via recovery, so this is fundamental.

Various hardware and software fixes to get things working.

To get software video decoding (OMX stuff):