[Acer Iconia A500] ezterry:
Developers Corner

~~~~~ Background

As you may know the linux kernel is considered Free Software under the GPL.

To the creators of the GPL licence this means:

Full text here

This means when Linus Torvalds changed the licensing from "Non-Comercial" use to the GPLv2 he was no longer preventing the kernel from being used in commercial products (as is obvious by its use on all android devices) However requested that anyone who received a copy of the software, get or be offered a copy of the source as well, and to be allowed to modify that source and distribute those changes to someone else, with the only restriction being they must also provide the source so the next person can also make changes.

Mind you this dosn't mean free software is actually free. Countless hours of hard work by countless people make the kernel what it is today.

While we all must provide the source, if something isn't already in the kernel that you want you have only the following options:

1) find someone willing to make the change

2) pay someone to make the change

3) roll up your sleeves and make the change yourself.

Also note one makes you give away changes you write to the linux kernel, you only must give the source to those who already have the binary.

~~~~~ This Guide

This guide will help you build the kernel yourself on your computer from source, this is in hopes that you may take an interest in how both the build system, and kernel its self works.

Instructions will be primarily focused on both linux, and cygwin users; however osx users may also be able to follow this guide with only minor modifications.

If you do make changes you think the public is interested in I will also be happy to review and potentially include it in my future builds, remember however while its polite to credit me for the codebase provided, you may always distribute you modified versions of the kernel as long as you adhere to providing the source per the GPLv2 to those you distribute it to.

~~~~~ Getting Started - Downloading The Toolchain

The toolchain is the compiler used to convert the 'C' code of the kernel into the arm instructions red by your device.

To build this kernel I use a custom android toolchain based on gcc4.6.3;

Pre-built binaries are available for x86 linux, cygwin, and osx:

1) Download the one for your platform

x86 Linux: toolchain-4.6.3.tar.bz2 (Sha1: c8c57aba6ad92e9acddf29ba

Cygwin: toolchain-4.6.3.cygwin.tar.bz2 (Sha1: 6947e1c1ba95195019f542eb8ba0708667b63eca)

OSX: toolchain-4.6.3.darwin.tar.bz2 (Sha1: 9a977f0672863fdd9501383a6ad1e30723281f

Additional details about these files are on my Android Software post:

http://xdaforums.com/showthread.php?t=1686310

All users may wish to look over the cygwin building requirements there to ensure there system has the required packages.

Other information on the post will include information about retrieving the source to the tool chain its self and another overview of building android kernels in general, and not just this specific Acer kernel.

2) Now that you have the toolchain you want to extract it; this can be done anywere but I recommend for the sake of this guide in your posix home directory

this is done by running at your posix prompt (cygwin terminal in windows normal terminal in linux/osx)

mkdir -p ~/android
cd ~/android
tar -xjvf </path/to/>toolchain-4.6.3.cygwin.tar.bz2

substitution '</path/to/>toolchain-4.6.3.cygwin.tar.bz2' with the file you downloaded above

all versions will extract then to '~/android/toolchain-4.6.3/' all the files required to build arm binaries

~~~~~ Getting the source code

This can be done many ways, if you want to build a specific version the tarball may be easiest, however it is recommended that you use the git revision control software if you wish to make changes, as this helps keep track of the changes, and publish them on services such as github. (in addition its easier for other people to take the changes into there own work without you loosing credit)

3) To get the AcerTabKernel source change directory into the ~/android directory used to make the toolchain

cd ~/android

4) run the command to fetch a copy of my git repository

git clone git://github.com/ezterry/AcerTabKernel.git

5) change into that directory

cd AcerTabKernel

~~~~~ GIT only, switching code views

Once you have the source code you can always refresh it with git fetch origin, however more work is required to update the local files

Option A: following a branch (recommended if you want the latest source)

6.A.1) run 'git branch -a'

you will likely see the following:

master - you local version of the master branch

remotes/origin/HEAD -> origin/master -- indication master is the default branch

remotes/origin/master -- the remote version of master (as of the last 'git fetch origin' or 'git pull' command)

remotes/origin/tegra_overclock -- the remote version of tegra_overclock (as of the last 'git fetch origin' or 'git pull' command)

the two branchs of interest are as follows:

master - the acer A100/A500 source including my enhancements w/o overclocking support

tegra_overclock - the full enhancement list with overclocking

6.A.2) Create a local version of tegra_overclock

run:

git branch tegra_overclock origin/tegra_overclock

6.A.3) Switching branches

you can switch between the branches by calling

git checkout <branch name>

so if you want to build this kernel you will call:

git checkout tegra_overclock

Option B: retrieving a specific tag

6.B.1) If you want the code to a specific kernel you can force the checkout of a tag

git chekout -f [color=gray]<tagname>[/color]

so for the v0.9.9 you can run

git checkout -f ezT20_kernel_v0.9.9

This will fetch the code, however you local branches will not be updated if you make changes, see on screen note for details

~~~~~ Building the kernel

Once you have the code you can build the kernel (or make other changes first)

7) Set up your build enviroment

Most steps above need not be done any time you make a change; however every time you want to build from a new terminal you must set up that terminals environment as follows

A) add the toolchan to your path:

export PATH=$HOME/android/export PATH=$HOME/android/toolchain-4.6.3/bin:$PATH

B) run the following commands to prepare the cross compiler from within the directory with the code (ie 'cd ~/android/AcerTabKernel')

export ARCH=arm;export CROSS_COMPILE=arm-linux-androideabi-;export KERNEL_DIR=`pwd`

*note I make this one line to make it easier to copy and paste all at once

8) Now that the enviroment is set up we can configure the kernel by running

For A500 Kernels:

make picasso_defconfig

For A100 Kernels:

make vangogh_defconfig

This will grab the default configuration for the device (same as /proc/config.gz on the running kernel) in the source tree this is arch/arm/config/picasso_defconfig or arch/arm/config/vangogh_defconfig

9) if you want to change the config (add/remove modules and components or change the kernels name):

make menuconfig

this will provide the kernel configuraiton gui that allows you to update the many kernel options including adding modules.

10) build the binary kernel

make -j5

you should replace the 5 in -j5 with the number of CPU cores in your computer + 1. 5 is ideal for a quadcore CPU.

If the number is lower/higher the kernel will take longer to build. (slightly higher however will have minimal impact)

11) prepare the modules (makes sure the modules are ready for use, they are built in the previous step)

make modules

~~~~~ Packaging the kernel

At this point you can find the kernel in arch/arm/boot/zImage and if you search for files ending in *.ko you will find all the built modules

However here I will describe creating the update.zip installer

Note this may look difficult as the process is mostly manual not automated

12) Download the template (I will assume you are in the directory with the kernel source still)

wget [url]http://android-git.devnull.name/gh/tepl/acer_kernel_tmpl.tar.bz2[/url]

This template contains the update_binary, unpackbootimg and mkbootimg binaries

In addition it has the ufsd.ko acer stok module (a closed source kernel module used for mounting ntfs disks) the updater-script you will use, and a nfo.prop template

koush is to thank for the unpackbootimg source (unpackbootimg/mkbootimg I built using the A500 Public Recovery source tree, updater_binary is from the stock ICS installer)

13) for future use move the template outside your source directory in case you delete/refresh it

mv acer_kernel_tmpl.tar.bz2 ~/android/

14) make the update.zip work directory

tar -xjvf ~/acer_kernel_tmpl.tar.bz2

15) copy over the zImage

cp arch/arm/boot/zImage acer_kernel_tmpl/[color=gray]<kernel_name.zImage>[/color]

the kernel_name can be any name you wish to call the kernel

16) copy in the modules

cp `find | grep ko$ | grep -v ufsd` zImage acer_kernel_tmpl/system/lib/modules/

17) copy in modules.order

cp modules.order acer_kernel_tmpl/system/lib/modules/

18) edit the nfo.prop

update the values as per the comments, this will control the displayed output during install

as well as allow you to specify any name for the zImage to be installed without

touching the edify script

19) generate the installer zip

cd acer_kernel_tmpl
zip -r ../kernel_install.zip .
cd ..

now kernel_install.zip can be flashed from clockworkmod (as an unsigned zip) or you may optionally sign the zip now to publish

~~~~~ What next

What next is up to you, there are many source files to look at some never used for our devices.. and many that I've never looked at.

One important thing however is learning the basics of git revision control, and how to maintain your local mirror and keep it in sync with the version I have on github.

Other interesting git features include remotes allowing you to compare source from other kernel repositories and even cherry-pick individual commits from other users.

If you know how to code, learning this isn't difficult so off to 'git help' and google you go :)