ROM Android: Porting

Beberapa tip untuk porting CyanogenMod ke device lain

Kemungkinan kita akan menemui telepon / tablet / apapun yang belum tersedia di CM.

Kemungkinan anda sebelumnya sudah perlu membuat CyanogenMod di komputer anda untuk satu atau dua device, dan anda merasa nyaman dengan proses compile-nya. Bahkan, anda masih mempunyai source code yang siap untuk menangani proyek yang besar.

Tampaknya ini adalah kesempatan besar anda :) ...

Catatan: Untuk keperluan tutorial ini, semua directory yang akan digunakan akan mengacu pada directory root source code (yaitu, tempat dimana kita menjalankan perintah "repo init"). Semua nama folder akan mengacu relatif pada roor source code.

Kebutuhan

Porting CyanogenMod ke device yang baru kemungkinan akan amat sangat mudah sekali, atau amat sangat sukar sekali, tergantung pada device tersebut, apakah dia menjalankan versi android yang terbaru atau tidak, dan tentunya keterampilan kita sebagai developer.

Akan sangat sukar melakukan porting tanpa mempunyai pengalaman membuat CyanogenMod (atau recovery) untuk device lain. Jadi sarannya, jika anda sama sekali belum pernah membuat / build CyanogenMod maka coba lah.

Selanjutnya, anda sebaiknya mulai membuat diri anda familiar dengan source code Cyanogenmod. Kemungkinan besar, sebagian besar yang kita butuhkan ada pada folder:

/device/[vendor]/[codename]
/vendor/[vendor]/[codename]
/kernel/[vendor]/[codename]

Ada baiknya kita mempelajari seluruh struktur folder yang ada di CyanogenMod karena akan sangat bermanfaat saat kita melakukan porting.

Collect information about your device

Before you begin your port, you will want to collect as much information about your device as you can. Go to wikipedia and identify the product name, code name, architecture, memory size, internal storage size, and platform architecture. Put this information in a file for easy retrieval. Try to learn as much about the device, including any similarities it may have to other devices.

Much of the information you need may be available online, but assuming the device is already running a non-CyanogenMod version Android, you may also get some of that information from the device itself. To view the files containing this information, the device may need to be rooted. However, sometimes you can find a stock firmware update package online, and can view the files from the .zip archive file.

Look at the device's current /system/build.prop

Assuming the device is already running a version of Android, there should be a file, /system/build.prop, on the device which may contain useful information that will come into play as you do your port. This file contains definitions for various parameters and settings used by Android.

So, if you have previously installed adb onto your computer, you can use the following command to pull this file to your computer:

adb pull /system/build.prop

If you receive an error relating to permissions, the device may need to be rooted to gain access to this file. However, there are other ways to locate this file. For example, it may be included in any stock firmware "upgrade" package online.

Once you have the file...

• Write down the value of the ro.product.manufacturer parameter. This will be your vendor name. The [vendor] is the name of the manufacturer/vendor of the device. CM has established naming conventions for most major vendors, such as samsung, htc, lge, etc. Note that in these directory names, the vendor is always lowercase and contains no spaces.
• Write down the value of the ro.product.device parameter. This will be your device codename. The [codename] corresponds to the project code name of the device itself. This is almost never the sales name of the device. If you have built CM before (and again, you better have!), you should be familiar with the concept of a code name for each device. Like the vendor name, the codename is always lowercase and contains no spaces.

Keep the build.prop file handy, as you may refer to it later.

Examine boot.img and recovery.img

As stated, when doing your port, you may wish to use an existing pre-built kernel that you know works instead of building one from source code. Depending on your device, you may need to extract this kernel file from the device. The kernel may exist as a single file (as it does on many OMAP devices) or may be wrapped up along with the ramdisk in a boot or recovery partition.

Similarly, the contents of the stock ramdisk may be extremely helpful and can often be extracted and reviewed. It may be the case that a device requires specific files from the stock ramdisk in order to boot properly, load a module, etc. In most cases you can view files in the ramdisk from the device itself, but it you may prefer to look at the full directory.

You can frequently extract the boot and recovery images (to a file you name boot.img and recovery.img) on a rooted Android device using dd. Or, if you have access to an update .zip file from the vendor, you can often find those files within.

Collect any available existing source code

The manufacturer or vender of any device using Android will minimally need to make the source code available for all GPL components upon request, including (and especially) the kernel. You definitely want to request a copy of the kernel source and keep it handy.

Determine the partition scheme

The primary long-term storage portion of your mobile device-- usually an "emmc" (embedded multimedia card)-- is much like a computer hard drive in that it is prepared in a particular way to identify and isolate different areas of data. These unique areas are called partitions and they can have any kind of data stored there. Some partitions contain raw data-- firmware, kernels, ramdisks, etc. More often, a partition is formatted to use a particular file system that the kernel will recognize so that individual files and directories can be read and written there.

Before you can replace the stock operating system with CyanogenMod, it is therefore important to ascertain the partition scheme of the device. The recovery image you build will need this information to know where to find the various Android directories. Particularly, you want to know which partitions are assigned to /system, /data, /cache, and /sdcard.

You want to know which partitions exist, on what device, how they are mounted, as well as the size of the partitions. This information may be transferred later to the BoardConfig.mk file in your /vendor directory.

If you're lucky, a recovery.fstab file can be located in a recovery.img file, speeding up the process of figuring out what goes where. Also, the init.[codename].rc file in the ramdisk may have the information. Look for the lines near the top where the partitions are mounted.

Also, the command:

$ cat /proc/partitions

from a running device can also help you identify the partitions. Also see /proc/emmc, /proc/mounts or /proc/mtd. You may also get some information from the command mount (run as root).

Also check /cache/recovery.log or /tmp/recovery.log.

Finally, if you have source code to the bootloader (such as the u-boot used by many OMAP-based devices), you will likely find the information there as well.

Set up three new directories

Now that you've gathered information about your device, it's time to generate the folders for your device configuration, located in the following directories, relative to the code source directory.

• device/[vendor]/[codename]/ -- this is where the installation files specific to your device will go. The device/ directory contain 99-100% of the configuration settings and other code for particular devices. You'll get to know this directory pretty well. As mentioned, when starting the folder for this device, it may be a good idea to adapt a directory for an existing device that is architecturally similar to the one you wish to port. Look for a device that is based on the same platform, for example.

• vendor/[vendor]/[codename]/ -- The vendor/ directory contains proprietary, binary "blobs" that are backed up from the original device (or provided by the vendor, such as in the case of Google Nexus devices and some TI graphics blobs).

• kernel/[vendor]/[codename]/ -- the kernel source goes here. When you first start your porting effort, you may wish to simplify things by using a pre-built kernel (such as the one that came with the stock installation) rather than building the kernel from scratch. The trick to that will be extracting the kernel out of the stock system from whatever format it may be in, and then re-packaging it, along with a new ramdisk, into a form that your device can use. This can vary from device-to-device, so it may again be helpful to look at similar devices to yours that use a similar architecture. Building the kernel from source is not strictly necessary for every device, but in the spirit of open source, it is the preferred practice for CyanogenMod. See here for a detailed discussion about how CyanogenMod builds the kernel source from scratch.

There are at least three methods to generate these directories:

Method 1: Use mkvendor.sh to generate skeleton files

Use the mkvendor.sh script in build/tools/device/ to automatically generate the directories.

This script accepts three parameters: vendor, codename, and a boot.img file.

Example usage:

$ ./build/tools/device/mkvendor.sh samsung i9300 ~/Desktop/i9300boot.img

In the above example, samsung represents the vendor, i9300 represents the codename and the last parameter is the path to the boot.img file that was extracted from the boot partition with dd or provided by the vendor in an update .zip as discussed above.

The command above should create a /device/samsung/i9300/ folder within your CyanogenMod source repo structure. And inside the folder, the files AndroidBoard.mk, AndroidProducts.mk, BoardConfig.mk, cm.mk, device_[codename].mk, kernel (the binary), recovery.fstab, etc.

This will not build the kernel/ directory. You will need to do that later, when you are ready to build the kernel.

Method 2: Fork a similar device's git repository

If you've got a GitHub account, you might want to start by forking another, similar device, and then rename it for your device. See the section on setting up github for a discussion on how to name your repository.

Always be sure you're compliant with the license of any repository you fork.

Method 3: create the directories and files manually

You can always start with an empty directory and start creating the files by hand. This is the least recommended and perhaps the most tedious method, but it may be the most instructive. You can look at other devices for reference on what files you need.

Customize the files

There are many files in the device/ folders. We will start by focusing on four files BoardConfig.mk, device_[codename].mk, cm.mk, recovery.fstab, and kernel to get recovery working for your device.

Lets examine each of these files:

BoardConfig.mk

This file contains vital architectual and build information about the architecture of your device's motherboard, CPU, and other hardware. Getting this file right is essential.

To get a basic recovery booting, a few parameters need to be set in this file.

The following parameters must be set properly in BoardConfig to compile a working recovery image:

• TARGET_ARCH: this is the architecture of the device it is usually something like arm or omap3.
• BOARD_KERNEL_CMDLINE: not all devices pass boot parameters however if your device does this must be filled out properly in order to boot successfully. You can find this information in the ramdisk.img.
• BOARD_KERNEL_PAGESIZE: the pagesize of the stock boot.img and must be set properly in order to boot. Typical values for this are 2048 and 4096 and this information can be extracted from the stock kernel.
• BOARD_BOOTIMAGE_PARTITION_SIZE: the number of bytes allocated to the kernel image partition.
• BOARD_RECOVERYIMAGE_PARTITION_SIZE: the number of bytes allocated to the recovery image partition.
• BOARD_SYSTEMIMAGE_PARTITION_SIZE: the number of bytes allocated to the Android system filesystem partition.
• BOARD_USERDATAIMAGE_PARTITION_SIZE: the number of bytes allocated to the Android data filesystem partition.

• BOARD_HAS_NO_SELECT_BUTTON: (optional), use this if your device needs to use its Power button to confirm selections in recovery.
• BOARD_FORCE_RAMDISK_ADDRESS / BOARD_MKBOOTIMG_ARGS: (optional), use these to force a specific address for the ramdisk. This is usually needed on larger partitions in order for the ramdisk to be loaded properly where it's expected to exist. This value can be obtained from the stock kernel. The former is deprecated as of Android 4.2.x and the latter will now be used in 4.2.x and beyond.

device_[codename].mk

The device_codename.mk makefile contains instructions about which Android packages to build, and where to copy specific files and packages, or specific properties to set during your compilation.

This file can be used to copy vital files into the ramdisk at compilation time.

• PRODUCT_COPY_FILES: used to copy files during compilation into the ramdisk, which will be located at $OUT/recovery/root.

Example:

$(LOCAL_PATH)/sbin/offmode_charging:recovery/root/sbin/offmode_charging \

This will copy the file offmode_charging binary into the sbin folder within the ramdisk.

• PRODUCT_NAME / PRODUCT_DEVICE: used for setting the value of your codename. This is the name of the device you load with Lunch.

kernel

This is simply the prebuilt kernel image or a kernel you built yourself used to boot the device. The format of the kernel may be in a zImage or uImage, depending on the requirements of the architecture of your device.

cm.mk

You'll need to make a few changes to this file to integrate with the lunch, brunch, and breakfast commands, so that your device shows up on the list and builds properly. You'll also set some variables (see other devices) to indicate what size splash animation should be used, whether this is a tablet or phone, etc.

Some of these settings aren't used for building just the recovery, but you may as well set them now because once recovery is done and working, the settings here will be important.

Again, take a look at a similar device to yours to get an idea of what the settings here should be. It's fairly intuitive.

recovery.fstab

recovery.fstab defines the file system mount point, file system type, and block device for each of the partitions in your device. It works almost exactly like /etc/fstab in a standard Linux operating system.

Example:

/system		ext4		/dev/block/mmcblk0p32 

This sets the block device at mmcblk0p32 to be mounted on /system as filesystem type ext4

All mountpoints should exist in this file and it is crucial this information be correct or else very bad things can happen, such as a recovery flash writing to the wrong location.

vendorsetup.sh

vendorsetup.sh is called when setupenv.sh is run. It is used to add non-standard lunch combos to the lunch menu.

To add your device to the lunch menu:

add_lunch_combo cm_<codename>-userdebug

Then build a test recovery image

To build only the recovery, set up lunch as with a regular build, and say make recoveryimage

If things break (and they will break), have a look at these tips for dealing with build errors.

Not much needs to be said here, but make sure the recovery is working before you move on to getting CyanogenMod working. A 100%-working and reliable recovery mode is absolutely necessary before you start testing experimental Android builds.

Adjust recovery_ui.cpp if necessary

You may discover that although the recovery image runs, some of the hardware buttons, such as the volume buttons or power buttons, which would normally be used to scroll through the options, don't work.

You may need to adjust the GPIO values to get the buttons to be recognized. Similarly, you may wish to include/exclude options or modify other UI elements.

To do this, you may wish to create and edit the /device/[vendor]/[codename]/recovery/recovery_ui.cpp. You can find ample examples of this file, the associated recovery/Android.mk file that builds it, and how it is used.

Put your device folder in github, and use a local manifest to automatically sync it with repo sync

Once you've started your device folder, create your own GitHub account and set up your folder as a public GitHub repository. This is a great opportunity to learn about git, and also your source can be accessible to others who can collaborate with you.

When naming your repository, use the format android_device_VENDOR_CODENAME, where VENDOR and CODENAME use the new device's values. So, let's say your GitHub account name is "fat-tire" and your device codename is "encore", manufactured by Barnes and Noble. You should call your repository android_device_bn_encore. It would be accessible at https://github.com/fat-tire/android_device_bn_encore. Similarly, the kernel repository would be called android_kernel_bn_encore. It would be accessible at https://github.com/fat-tire/android_kernel_bn_encore.

The last thing to do is create a local manifest for other people to use to automatically download and their keep up-to-date with your changes. Here's an example, using the above scenario:

<?xml version="1.0" encoding="UTF-8"?>
<manifest>
  <project name="fat-tire/android_device_bn_encore" path="device/bn/encore" remote="github" revision="cm-10.1" />
  <project name="fat-tire/android_kernel_bn_encore" path="kernel/bn/encore" remote="github" revision="cm-10.1" />
</manifest>

Once you've tested that the local manifest file works, you can pass it on to others, who can then try out your work. At that point you can continue to push your changes to GitHub, and even give other users commit access so that you can work on the device together.

Add the blobs to the vendor/ directory

Once you have a working recovery, it's now time to get CyanogenMod building and working.

The first thing to do is to get all the proprietary, binary blobs into the vendor/ folder, along with a .mk file that will include them in the final build.

This requires three steps:

1. Create extract-files.sh and setup-makefiles.sh scripts to pull those blob files from the device using adb and put them in the right /vendor/ directory. There are plenty of examples available for other devices.
2. Create an .mk Makefile to copy those files to the $OUT folder during the build process and put them in the right place. Again, use other devices as a guide for what this Makefile should look like. An example filename might be BoardConfigVendor.mk
3. Make sure that the Makefile you just created is included from your main BoardConfig.mk via a command such as -include vendor/[vendor]/[codename]/BoardConfigVendor.mk. Again, existing devices can illustrate how this is done.

Now revise the device/ directory

Since you have a working recovery, go back and start modifying the files in the device/ folder. As always, use other similar devices as a reference.

You now have a easy means to do backups and test your builds. So start tweaking the device folder itself, and see if you get it to boot... Once you do, from there its a matter of building and supporting the various parts and peripherals, one-by-one.

Getting help from the manufacturers & vendors

Many of the OEMs (Original Equipment Manufacturers) who make the underlying platform used by your device frequently provide wikis, documentation, and sample code that can assist you in completing your port. You'll find that some companies are more friendly to the development community than others. Here are some of the more common OEMs and vendors, along with web sites and repositories that may help.

(This list is incomplete. Please help add to it)

OEM	Platform	Repositories/Resources
Google	various	Google's Git Repository , Nexus binary blobs
HTC	various	Dev Center
Lenovo	various	Lenovo Smartphones (Search your device)
LG	various	LG Open Source Code Distribution
Motorola	various	Motorola Open Source Center
Nvidia	Tegra	Tegra's GitWeb
Qualcomm	MSM/QSD	Code Aurora Forum
Samsung	various	Samsung Open Source Release Center
Texas Instruments	OMAP	www.omapzoom.com , Omappedia

Sometimes if you have questions you can even reach out to the developers via email or the support forums.

Adding XML Overlays

It's very likely in your device_[codename].mk file, there's a line that looks like this:

DEVICE_PACKAGE_OVERLAYS := \
    device/[vendor]/[codename]/overlay

What this does is set the overlay/ folder to allow you to override any XML file used by Android frameworks or apps, just for this device. To do so, create a directory structure which mirrors the path leading to an XML file, starting from the root of your source. Then replace the file you want to overlay.

Example: Let's say you want to override some standard Android settings. Look at the file in frameworks/base/core/res/res/values/config.xml. Then copy it to device/[vendor]/[codename]/overlay/frameworks/base/core/res/res/values/config.xml. Now YOUR version will be used instead of the other one. You only need to include the settings you wish to override-- not all of them, so you can pare down the file to those few that change from the default.

You can overlay any XML file, affecting layouts, settings, preferences, translations, and more.

Make the kernel and kernel modules build from source

If you have previously used a pre-built kernel, you may at some point want to start building the kernel from scratch.

See the instructions for how to change the BoardConfig.mk file to make CyanogenMod build the kernel and any required kernel modules automatically.

Conclusion

There's no way a single wiki page will tell you everything you need to know to do a port from beginning to end. However, hopefully you now have an understanding of how things are set up and the steps you need to take. You an always ask for help on the forums or on IRC. Others with the same device may jump in to help too.

Hopefully you'll find the process rewarding and educational. And it'll get you some street cred as well.

When you're all done, and your port works better than stock... when it's stable and shiny and marvelous and wonderful...

You may want to contribute your work upstream. Here are the instructions for how to do just that.

Good luck!

See Also

• Android-Porting -- the official Google Group on this topic
• General CyanogenMod Porting Discussion -- a forum post on porting

Referensi

• http://wiki.cyanogenmod.org/w/Doc:_porting_intro
• https://groups.google.com/forum/?fromgroups#!forum/android-porting
• http://forum.cyanogenmod.org/topic/15492-general-cyanogenmod-porting-discussion/