This article describes how to get Android running on your favourite ARM-based System on Chip (SoC) board. We run through the overall procedure and point out potential pitfalls and other things that you may encounter.
Since the Android software stack was primarily designed around the ARM Architecture, there are not many things that need amending to get it to work on another ARM platform.
We assume that your workstation has Ubuntu (10.10 or later) Operating System installed, and that you have already followed the instructions found at  to be ready to build Android sources. These instructions have been tested with Ubuntu 10.10, but they should be compatible with other GNU/Linux OSes.
For the purposes of this document, we use the following terms.
|Mainline kernel||the kernel that you can get from the mainline (i.e. http://www.kernel.org); implies that no changes have been made to it. Also known as "vanilla kernel".|
|Reference kernel||this is the kernel that you have for your board; that is most likely a vanilla kernel, plus any patches required to support your board.|
|Merged kernel||the kernel that is the result of merging Android patches to the Reference kernel. A Merged kernel should support Android.|
|Android patches||the patches that you extract from the Google Android kernel. These are the changes from the point that a Mainline Kernel version has been imported to the Android Kernel tree. See http://android.git.kernel.org|
|Android kernel||the kernel that you can get from Google's Android Open Source Project repository. It contains Google's changes to the Mainline kernel, to support Android. You can get it from : http://android.git.kernel.org/kernel/common.git|
The procedure is split into two parts:
- Get a Linux kernel that works on your board (Reference kernel)
- Get the matching Android kernel version for the Android release you want use (e.g. Gingerbread) - the Android kernel version is loosely coupled with an Android release.
- Extract the patches for the Android kernel (around 2 MB in size) and merge the Android patches with the Reference Linux kernel for your board - or merge the two kernel trees
- Configure the Merged kernel for use in Android
- Build the Merged kernel
- Userspace - the Android filesystem
- Add the Android build target of your SoC in the devices folder of the Android Source tree
- Build Android for your SoC
- Configure init.rc to fit your booting media
We must stress the importance of doing the "configure" step carefully in both parts of the procedure. If it is not done correctly then it will not be possible to complete the task successfully.
You might want to get Android working on a platform that already has an Android
port available. We provide pre-built kernel binaries, kernel sources and kernel
.config files, for certain ARM boards such as the
ARM Versatile Express.
Please see  for more detail.
Part 1 - Kernel
The following diagram shows the procedure of merging of the Reference with the Android kernel.
a. Known working Linux Reference kernel
Make sure that you have a working kernel and a Linux root filesystem, functional on your board, i.e. you can boot to a GNU/Linux graphical environment.
If this is not possible, there is no point attempting to complete this exercise.
Note : The Linux root filesystem is only required to test the Merged Kernel, not for the Android port to your SoC.
You need a kernel that boots and provides to the system all of the appropriate support required for a windowing system (e.g. graphics drivers for the framebuffer or your graphics chip) as a reference point. This will be called your Reference kernel.
It should be noted here that every Android release after Cupcake requires double buffering and page flipping support from the graphics system. If your Reference kernel does not support this, then Android releases after Cupcake will not work.
The .config file of the Reference kernel will be used as a base for the Merged kernel. Keep a copy of this as a reference for later use.
For the purpose of this article, we assume that you have a 2.6.38-based functional Reference kernel for your board. You may use any kernel revision you wish, but keep in mind that it may result in deviating from the information in this article.
b. Android kernel
Find an Android kernel which has the same revision as your Reference kernel. If it is not possible, use a revision that is closest, as this will simplify the procedure.
Revision mismatch of the two kernels will probably result in spending more time merging and debugging. From experience, merging a Reference kernel and the Android patches of the same revision requires about a day; in the case of revision mismatch, more time may be required.
c - Merge Android Kernel Changes
In this step you can either obtain the Android patches from the Android kernel source, or use git to merge the two kernel trees using their common point in time.
The first approach will produce a patch file that can be applied to the Reference kernel, while using git-merge will produce a single tree that will keep the patching history, and maintain all of the individual commits.Please note that you will have to do either c.i or c.ii, not both!
c - i. Extract Single Patch
The expected size of the patch is about 2MB. To extract the patches, find the point in time (using "git log") where the Mainline kernel was imported to the Android kernel source tree.Go to the top level of the Android kernel source tree and run:
git log --pretty=oneline --format="%Cgreen%h %Creset%s" \ --grep="Linux 2.6." -n 20which will generate 20 one-line log entries that have the expression "Linux 2.6." in the subject or in the commit message. The output should look like:
521cb40 Linux 2.6.38 a5abba9 Linux 2.6.38-rc8 dd9c154 Linux 2.6.38-rc7 f5412be Linux 2.6.38-rc6 85e2efb Linux 2.6.38-rc5 100b33c Linux 2.6.38-rc4 ebf5382 Linux 2.6.38-rc3 1bae4ce Linux 2.6.38-rc2 c56eb8f Linux 2.6.38-rc1 aa0adb1 batman-adv: Use "__attribute__" shortcut macros f5afcd3 drm/i915/crt: Check for a analog monitor in case of DVI-I 3c0eee3 Linux 2.6.37 387c31c Linux 2.6.37-rc8 90a8a73 Linux 2.6.37-rc7 b0c3844 Linux 2.6.37-rc6 cf7d7e5 Linux 2.6.37-rc5 e8a7e48 Linux 2.6.37-rc4 3561d43 Linux 2.6.37-rc3 5bd5a45 x86: Add NX protection for kernel data 64edc8e x86: Fix improper large page preservationSince you need the patches to be on top of the 2.6.38 Mainline kernel release, run the following command:
git diff 521cb40 HEAD > 2.6.38-to-Android.patchThis gives you a patch file (named
2.6.38-to-Android.patch) containing the changes to be merged. Check for merging conflicts, before attempting to perform the actual merge, by running:
git apply --test [path/to/2.6.38-to-Android.patch]which produces a list of merging conflicts (if any). Make sure that you resolve these conflicts and that the patch applies cleanly to your tree before you continue.
c - ii. Use git-mergeThis approach merges the Android kernel tree with your local Reference kernel tree. First, add the Android kernel tree as one of your remote trees:
git remote add [android tree] \ git://android.git.kernel.org/kernel/common.gitwhere
[android tree]is the local name for the remote Android repository. Now enter:
git fetch [android tree]to get all the git information for that tree (such as branch names, commits and tags). To identify the common point where the merge will be based, enter:
git merge-base armdroid-2.6.38 [android tree]/android-2.6.38where armdroid-2.6.38 is the local branch name for your Reference kernel that you wish to merge with the Android kernel tree, and
[android tree]/android-2.6.38is the branch of the 2.6.38 Android Kernel at the remote repository. This returns the hash of the commit at which the two branches diverged. E.g.:
a5abba989deceb731047425812d268daf7536575You can use this to get an estimate of the number and size of changes made from that point in time, to the head of your Reference kernel tree. Then, attempt an automatic merge using:
git merge armdroid-2.6.38 [android tree]/android-2.6.38Any conflicts will be reported - review these using:
git statusFor conflict resolution
git mergetoolcan be quite handy, and it allows you to use your favourite diff tool. For example:
git mergetool --tool=vimdiff kernel/printk.clets you review and resolve the merging conflict for
kernel/printk.cusing vimdiff. When you have resolved the conflicts, commit the changes using:
git commit -a
d. Configure the Merged kernel for Android
In order to get the Merged kernel configured correctly for Android, you must have a known working configuration tested with a Linux root filesystem.
This should be tested by building a kernel image from the merged source tree,
using the known working defconfig or
.config file saved in Part 1a, and checking
that it boots your existing working Linux root filesystem.
Note: Be aware that due to the Android parts in the Merged kernel, you might get asked about some options that were not available in the reference configuration of your Reference kernel.
If it does not boot, take a step back and make sure that what was merged from the Android kernel source tree did not break anything in your Reference kernel. Checking the files in which you have resolved any merge conflicts should be a good place to start.
If it does boot, you can then add options to your working configuration that are required for Android.
- power_management :
- wakelocks :
- ashmem :
- pmem :
- switch class support :
- staging drivers :
- binder :
- logger :
- ram console :
- usb_gadgets with at least adb selected -
- power supply :
Note that the names above are those which can be found in the 2.6.38 Android kernel configuration - be aware that these tend to change from version to version!
We have also found that in multiprocessor systems, CPU hotplugging support is required. You should enable this if your ARM based SoC has more than one core in order to boot a kernel with multiprocessor support.
To get the Merged kernel to work correctly for Android, the above configuration options are the minimum options required.
e. Build the Merged kernel
Build the Merged kernel with:
make ARCH=arm CROSS_COMPILE=[path-to-arm-gcc] uImage
which will produce a kernel Image, uImage and zImage in arch/arm/boot directory
in the Merged kernel source tree. Replace the
[path-to-arm-gcc] with the path to
the latest version of Linaro or CodeSourcery ARM toolchain that you have
installed. For this exercise we used Sourcery G++ Lite 2010.09-50) 4.5.1.
Note that you need the uboot-mkimage package in order to generate a uImage.
If you do not want a U-boot wrapped Linux kernel image, substitute
You now need the Android root filesystem in order to complete your port.
Part 2 - Userspace - The Android filesystem
a. Add a device in the tree
Each build target defines the configuration of the ARM based SoC/board and selects which sources should be built for Android.
The build target directory that the Android build system uses depends on the Android version. In Froyo and Gingerbread the location is:
whereas in Eclair it is:
In this article, we assume that you are using Gingerbread.
a - i. Adding a build target
Below is an example of adding a couple of ARM generic Android build targets, along with a mock target.
Create a directory in [android_root]/device, with the desired name. E.g.:
Enter the new directory and create a
products folder you need an
AndroidProducts.mk file that lists all of
the products that you have under the
arm folder. This should be as
PRODUCT_MAKEFILES := \ $(LOCAL_DIR)/armboards_v7a.mk \ $(LOCAL_DIR)/armboards_v7a_noneon.mk \ $(LOCAL_DIR)/another_product.mk \
As this implies, you also need to have one "Product_Makefile" per product in the
[android_root]/device/arm/products/ folder. Therefore, for our example you need:
Each of these files must contain the following, adapted to match the product and device naming :
$(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk) # # Overrides PRODUCT_NAME := [product_name] PRODUCT_DEVICE := [board_name]
PRODUCT_NAME is the build target name used by the Android build system,
PRODUCT_DEVICE defines the name of the directory that contains the
files which describe the device.
For our example the first product is :
$(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk) # # Overrides PRODUCT_NAME := armboard_v7a PRODUCT_DEVICE := armboard_v7a
Note that the
PRODUCT_NAME does not have to be the same as the
For example, if you were to add support for ARM Versatile Express board, the
contents of the
vexpress.mk file could be :
$(call inherit-product, $(SRC_TARGET_DIR)/product/generic.mk) # # Overrides PRODUCT_NAME := vexpress PRODUCT_DEVICE := cortex-a9
and the files that define/configure that device would be in a "cortex-a9"
directory. You are free to choose the name you wish for your product and device,
limited to the characters allowed. For example, you cannot use minus "-"
because this is used to separate the
PRODUCT prefix and the
test, suffix from the product name in the build command line.
Following the example above, create the required directories:
mkdir [android_root]/device/arm/armboard_v7a/ mkdir [android_root]/device/arm/armboard_v7a_noneon/ mkdir [android_root]/device/arm/another_product/
and populate them accordingly.
Each one of these directories should contain at least the "Android.mk" and "BoardConfig.mk" files. The first one is the makefile for the product and the second, as the name implies, is the config file for the product. The Google guidelines  for what the Android.mk file should contain are :
# make file for new hardware from # LOCAL_PATH := $(call my-dir) # # this is here to use the pre-built kernel ifeq ($(TARGET_PREBUILT_KERNEL),) TARGET_PREBUILT_KERNEL := $(LOCAL_PATH)/kernel endif # file := $(INSTALLED_KERNEL_TARGET) ALL_PREBUILT += $(file) $(file): $(TARGET_PREBUILT_KERNEL) | $(ACP) $(transform-prebuilt-to-target) # # no boot loader, so we don't need any of that stuff.. # LOCAL_PATH := vendor/[company_name]/[board_name] # include $(CLEAR_VARS) # # include more board specific stuff here? Such as Audio parameters. #
which, when adapted to our example, becomes:
# make file for ARMv7-A based SoC # LOCAL_PATH := $(call my-dir) # # this is here to use the pre-built kernel ifeq ($(TARGET_PREBUILT_KERNEL),) TARGET_PREBUILT_KERNEL := $(LOCAL_PATH)/kernel endif # file := $(INSTALLED_KERNEL_TARGET) ALL_PREBUILT += $(file) $(file): $(TARGET_PREBUILT_KERNEL) | $(ACP) $(transform-prebuilt-to-target) # # no boot loader, so we don't need any of that stuff.. # LOCAL_PATH := device/arm/armboard_v7a # include $(CLEAR_VARS) # # include more board specific stuff here? Such as Audio parameters. # PRODUCT_COPY_FILES += \ $(LOCAL_PATH)/armboard_v7a.kl:system/usr/keylayout/armboard_v7a.kl
Note the added line in the
PRODUCT_COPY_FILES definition, that contains two
locations separated by a colon. The first is the location of the keyboard
file in the local Android source tree, and the second is where it will be
installed on the target. This is added because we wanted to have our own,
tweaked, keyboard layout.
BoardConfig.mk file for
armboard_v7a product is:
# These definitions override the defaults in config/config.make for armboard_v7a # # TARGET_NO_BOOTLOADER := false # TARGET_HARDWARE_3D := false # TARGET_CPU_ABI := armeabi-v7a TARGET_CPU_ABI2 := armeabi TARGET_NO_KERNEL := true TARGET_ARCH_VARIANT := armv7-a-neon BOARD_USES_GENERIC_AUDIO := true USE_CAMERA_STUB := true
where you define that you are using the
armeabi-v7a and that the target
architecture variant is ARMv7-A with NEON. *Note the support for 2 ABIs that
was introduced in Froyo*. This allows the distribution to run native ARM
applications built for one specific architecture version (using Android NDK).
For any further system properties configuration, add a system.prop file
containing the things you need, at the same location as the above files
device/arm/[DEVICE_NAME]). Google's guidelines  provide a template
for this :
# system.prop for # This overrides settings in the products/generic/system.prop file # # rild.libpath=/system/lib/libreference-ril.so # rild.libargs=-d /dev/ttyS0
For any other products/device you wish to add, follow the same procedure outlined here (2.a.i).
You should now be ready to build the Android file system for your SoC, with the device folder containing all the necessary configuration and build files. For our example, the device folder should look like this:
arm/ +-- armboard_v7a | +-- Android.mk | +-- armboard_v7a.kl | +-- BoardConfig.mk | \-- system.prop +-- armboard_v7a_noneon | +-- Android.mk | +-- armboard_v7a_noneon.kl | +-- BoardConfig.mk | \-- system.prop +-- another_product | +-- Android.mk | +-- another_product.kl | +-- BoardConfig.mk | \-- system.prop \-- products +-- AndroidProducts.mk +-- armboard_v7a.mk +-- armboard_v7a_noneon.mk \-- another_product.mk
b. Build Android for your SoC
Build the Android filesystem for one of your added targets, by going to the top directory of the Android source tree, and entering:
Note: You do not need to build Android as the root user.
After some time, and if everything was set up correctly, you will get the Android root filesystem and a compressed version of it at:
For our example :
c. Configure the root filesystem
We use the root filesystem over NFS. For that, make sure you have the NFS server set up and serving the location you wish to place the Android root filesystem.
Note: To use a root filesystem on a remote NFS Server, your Reference Kernel
(and therefore your Merged kernel) must support Rootfs over NFS (
The line in the
/etc/exports file should be like:
where the path at the beginning is the Android root filesystem location, and the last part is the NFS configuration string.
Now you need to copy the contents of the
root directory from the
Android source tree to the NFS served location :
$ cp -a [android_root]/out/target/product/armboard_v7a/root/* \ /var/nfs4/android-fs
and the contents of the
system directory from the Android source tree in
system placeholder - now in the NFS served location :
$ cp -a [android_root]/out/target/product/armboard_v7a/system/* \ /var/nfs4/android-fs/system
Use "sudo" at the beginning of each command, if you need to have root privileges to copy things to the defined destination.
Ensure that the ownership and permissions of the files, as they come out of the
build system, have not been modified. -
cp -a should have done this for you.
For this filesystem to work, you also need to make changes in the
[android_root_filesystem]/init.rc file. For Gingerbread you need to do the
- Locate and comment out the following lines
mount rootfs rootfs /ro remount
mount yaffs mtd@system /system
mount yaffs2 mtd@system /system ro remout
mount yaffs2 mtd@userdata /data nosuid nodev
mount yaffs2 mtd@cache /cache nosuid nodev
- To get root privileges in the shell, change:
... service console /system/bin/sh console disabled user shell group log ...to:
... service console /system/bin/sh console disabled user root group log ...
- To get DNS working, add the indicated line
# basic network init ifup lo hostname localhost domainname localdomain ---> setprop net.dns1 [DNS]and replace
[DNS]with your local DNS server.
Note : The instructions in this step can be also used for deploying the Android root filesystem on other media (such as USB sticks or MMC).
Load the kernel on your board, and set the appropriate boot arguments in order boot successfully.
For our example and for the VExpress board that uses U-Boot, we use the following bootargs:
root=/dev/nfs \ nfsroot=[NFS_IP]:/srv/nfs4/android-fs,nolock,wsize=1024,rsize=1024 rw \ ip=dhcp console=ttyAMA init=init noinitrd mem=1024M user_debug=31
Android should come up shortly. Note that the first boot will take longer since Android is optimizing the .dex files (this is known as the dexopt operation). See  for more details on dexopt.
Should any minor issues appear, experiment a bit more with the kernel options
init.rc configuration, based on the information you get from Android's
logcat and the system's dmesg.
Vasileios Laganakos, Staff Embedded Software Engineer, ARM. Vasileios is an undercover Physicist in the Computing Industry. During his undergrad studies was involved with FreeBSD & Linux and was thrilled with what the coding community can achieve. Came over to the UK for his MSc in Advanced Computer Science, where he focused in High Performance Computing, Micro-Kernel operation and principles, and got addicted to Embedded Systems - stayed there ever since, working on that in ARM! He is very curious about almost every tech subject in the field, and loves finding better ways to code "that thing".
29 Comments On This Entry
Please log in above to add a comment or register for an account
Search My Blog
Coding Using NEON Technology
on Yesterday, 08:57 AM
on May 08 2013 06:15 PM
New Platform Bring-Up with ARM® Development Studio 5 (DS-5™)
on Apr 30 2013 09:55 AM
如何利用全志安卓4.0 HDMI Dongle进行ARM DS-5 Streamline性能分析
on Apr 26 2013 10:50 AM
DS-5 Streamline Performance Analyzer on Allwinner Android 4.0 HDMI Dongle
on Apr 25 2013 04:58 PM