[Motorola Droid RAZR] dtrail1:
INTRODUCTION INTO KERNEL DEVELOPMENT

PREPARATION

This guide is NOT a full development tutorial! For development of kernels you should be familiar with C. I cannot teach you full C - would be too much for me - but I can show you how to prepare a build environment especially for RAZR Kexec Kernel building! At the end you will find some first steps about how to develop a kernel.

As soon as you have a full dev setup you will be motivated to proceed with learning C - hopefully :D

For me it worked!

The reason is that I would like to see more people giving it a shot! Kexec is wondeful and it would be great if there are some more people working on kernels.

Please leave me some credits if this tutorial helped you wherever you provide your work! THX!

OVERVIEW

1. Install Linux

2. Setup build environment

3. Initialize Kernel Source

3.1 Branches

3.2 How to compile a kernel

4. Create your first development branch (Add a new Governor)

5. Git Commands

I will tell you the way I started once and guide you through the preparation.

It's important to know how to setup a build environment! The best way to learn about kernel development is to learn by practice!

How to setup a build environment

1. INSTALL LINUX

I suggest Linux Mint 15 Cinnamon (or Linux Mint 15 Mate is good for older for low-spec Systems) - it's free and very easy to install near Windows 7 (dual boot). After the installation you will have a very Windows-like desktop environment which is easy to handle also for beginners. Then you need to learn the Linux Shell!

*of course you can install any other Linux, like Ubuntu. Linux Mint is based on Ubuntu 13.04 and I use it as well.

If your CPU supports 64 bit you should install the 64 bit version! This is impossible also later when it comes to install libraires for development, etc. There are mostly two versions, whether for x32 or x64.

After the installation of Linux you need to imstall related software and depencies.

2. SETUP BUILD ENVIRONMENT

Now, Linux is installed, we begin to setup the build environment.

First install Git which is the main part for using services like Github, etc..

We will install also adb and fastboot!

Let's start!

Open a shell (terminal) and type:

sudo apt-get install git android-tools-adb android-tools-fastboot

(you will have to enter your password. Keep in mind that you won't see any input when typing passwords in Linux!)

Now you have installed adb, fastboot and Git!

After this you need to create a working space which means you have to download the full Android source to be able to build your kernel later.

Still in Terminal make sure you're in your user root directory (just type "cd" to get back into your root dir). Now you have to create a new directory for Android sources. Therefor we use the "mkdir" command (make directory). We need to create a folder structure, so we create another folder inside of your new folder:

mkdir android
cd android
mkdir system

Now you have install the depencies (libraires, etc, needed for compiling Android). So you are still in your terminal and type:

sudo apt-get install git-core gnupg flex bison gperf libsdl1.2-dev libesd0-dev libwxgtk2.8-dev squashfs-tools build-essential zip curl libncurses5-dev zlib1g-dev openjdk-6-jre openjdk-6-jdk pngcrush schedtool libxml2 libxml2-utils xsltproc

Now we need some additional libs because we are using a 64 bit system. Still in terminal install them by using the apt-get command. I will only show you the package names now, so you can practice and see if you have understood it. Install these:

g++-multilib lib32z1-dev lib32ncurses5-dev lib32readline-gplv2-dev gcc-multilib

Next step is the creation of the repo base directory. It is needed by the repo software which lets you control and use the git repositories on your local machine (your computer). Use the "mkdir" command to create the following directory:

mkdir -p ~/bin

Now you have to install the "repo command". It's a binary file, so you have to make it "executable" (runable) by using the "chmod" command. Chmod is similar to the "set_perm("...")" command used by updater-scripts (EDIFY script language). It just sets the permissions of a file, i.e. to allow the execution of this file or to make sure the file can be accessed by any people or other programs.

Enter the following to download the "repo" binary and make it executable (runnable):

curl https://dl-ssl.google.com/dl/googlesource/git-repo/repo > ~/bin/repo

chmod a+x ~/bin/repo

Now we have to make sure that we can call "repo" from anywhere. This means if you're in terminal in for example: $ /home/Downloads and you type "repo" it will tell you usually that "repo" is an unknown command. To avoid this we need to make it generic by adding "repo" to your static PATH (Path of execution). The command:

export PATH=${PATH}:~/bin

Fine! So far we are prepared! Now we have to download the android source!

Still in terminal, type:

cd ~/android/system/

repo init -u git://github.com/CyanogenMod/android.git -b cm-10.2

.

To start the download of all the source code to your computer:

repo sync

Now, when the download has been finished we have to download the prebuilt apps (like terminal emulator, etc):

cd ~/android/system/vendor/cm

then enter:

./get-prebuilts

Now there are the vendor files needed! There are two ways to do that: The "easy" way and - sometimes it doesn't work, then you have to use - the "harder" way.

Congratulations! You have successfully setup your Android build environment!

Now we need the kernel source!

3. INITIALIZE KERNEL SOURCE

So you learned some basics about Git! Proof that you understand it and clone the kernel source repo to your PC! I'll give you the links but you have to clone it yourself! Use the clone URL you find at the following Github repo. Make sure you are NOT cloning into your Android source dir /android/system!)

The source for our 3.0.8 Kernel:

www.github.com/CyanogenMod/android_kernel_motorola_omap4-common

NOTE

Too hard? Let me help you (You can even copy&paste my stuff - but for real learning experience you should try to make it on your own)

Head into this dir:

cd ~/android

Clone the kernel source:

git clone https://github.com/CyanogenMod/android_kernel_motorola_omap4-common.git

The new folder will be: ~/android/android_kernel_motorola_omap4-common where your kernel source sits.

When done, you have successfully loaded the kernel source! Fine!

3.1 ---> BRANCHES

Now I am going explain you something about "branches" and how to use them!

A "branch" is a part of almost all git repos. It is very important and also very useful to work with branches!

A typical repository looks like that:

[CODE GIT REPO

|

master branch

/ \

/ \

branch: Test branch: Stable

\ /

\ /

\ /

MERGE changes[/CODE]

The repo contains mostly multiple branches. There is always the "master branch" (can have another name of course, branches can be named like you want) and some lower branches.

The "Master branch" is the main branch!

All other branches are custom and mainly used to test new code or sth else.

Let's say we have a kernel repo! This repo contains the JBX-Kernel. The master branch contains the current STABLE Version of the kernel. Now we want to implement a new feature. But when we use the master branch for development (which is sometimes an experiment) we could potentially break the kernel or its source and make it becoming unusable. Therefore we can use a different branch.

NOTE: A branch is always a copy of this branch where you are while creating a new branch! This means when I am currently in the JBX-Kernel master branch, and I create a new branch from there, then I will get a new branch which includes a full copy of my JBX-Kerne master branch. -- But I can work with it without being scared about breaking my repo!

Then many devs are using a "Merge branch". There we could in example copy all changes (which have been tested successfully before) together into a new branch. This process is called "merging".

Let's say we have finished our new feature inside of a test branch. Now the feature is ready to be built in into the Stable Kernel. Then we merge the test branch into the master branch. Thsi results in an updated master branch which now includes our new feature!

Another possibility to use branches can be found if you want to split our repo into different systems, such like the CM kernel source contains branches for CM10.1 and CM10.2. So there is a branch calld "cm-10.1" and another branch called "cm-10.2".

When you look at the part where we initalized the CM repo, you might notice that the repo URL includes this:

repo init -u git://github.com/CyanogenMod/android.git -b cm-10.2

The line marked with red in the URL points to a specific branch, the cm-10.2 branch.

Now we are still in the kernel source dir!

Because you want to build a 4.3 Kernel we need to be in the right branch for this! There are already branches exisiting in the kernel source (like explained above), it's splitted into different versions (4.2.2 and 4.3).

Still in terminal be sure you're inside your kernel source root dir (~/android/android_kernel_motorola_omap4-common), type:

git checkout cm-10.2

The output in the terminal will tell you sth like: "Switched to branch cm-10.2"

(if it's the first time you enter a branch it will download the files first and tell you: "Switched to a new branch cm-10.2". Don't be confused by this. If you try to enter a non-existing branch it will give you an error).

Now you are in the kernel repo, in the 4.3 branch!

Before we start to play with the source code I will show you how to build a kernel! As long as the kernel source is untouched you can be sure that it will work! Also this will make sure you have done everything right so far - as soon as the kernel boots you've built! ;)

3.2 HOW TO COMPILE A KERNEL

To get a first impression about how to build the kernel, please have a deeper look at my personal JBX build script:

https://github.com/RAZR-K-Devs/android_kernel_motorola_omap4-common/blob/JBX_4.3/build.sh

The script is very simple and contains only a few commands which can be used in the terminal as well. For your the script is only interesting until the poiont where it says: "make -j4 TARGET_KERNEL_SOURCE=/home/dtrail/android/android_kernel_motorola_omap4-common/ TARGET_KERNEL_CONFIG=mapphone_OCE_defconfig $OUT/boot.img"

Since the latest Android version and the modified kexec stuff it's not enough anymore to build the kernel only. The PVR source has been moved into the Android source and it must be built together with the kernel in order to get a working (booting) kernel! That's why I don't show you the common way.

In fact you can now build your kernel by taking my build script commands, and enter them - one by one - in your terminal. BUT you have to modify the paths because script was made for use on my computer (so, you probably are not called "dtrail!" :D ). You have to start in your kernel source dir (this is the location where my build script is being executed). To make it easier for you, I have pasted the script here and changed it so it will work for you. I have removed all comments and echo (output) commands so there are only the related build commands left. I just added comments just for you:

# THESE LINES (those beginning with #) ARE COMMENTS!!!

# Be in your kernel source: /android/android_kernel_motorola_omap4-common
# this command cleans all leftover files from prior compile (needed)
make mrproper

# We build the kernel and its modules
# enter the Android source dir
cd /android/system

# This command makes sure to use the additional build cache. It will make all fufutre build processes MUCH faster! (YOu have to install ccache first by using apt-get)
export USE_CCACHE=1

# Clean also the Android source dir
make mrproper
make ARCH=arm distclean

# Tell the compiler that we want to build now
source build/envsetup.sh

# Tell the compiler which device we want to build for
lunch cm_spyder-userdebug

# built kernel & modules (This command includes the full path to the kernel course and the used kernel config)
make -j4 TARGET_KERNEL_SOURCE=/home/YOUR_USERNAME_HERE/android/android_kernel_motorola_omap4-common/ TARGET_KERNEL_CONFIG=mapphone_mmi_defconfig $OUT/boot.img

After you entered this your computer will start building. The first compiling process will take longer! But future bui9lds will be built much faster thanks to the use of CCACHE!

CONGRATULATIONS!! You built your first kernel!!

Now we have to create a flashable zip file and flash the kernel to see if it works. >The advanced Linux users from you should have another look into my build script I linked above, there you can see how it automaticall pushes (copy) the fiules into a prepared folder which includes everything needed for a flashable zip and compresses it to a ready zip file!

Other less experienced users can just download my latest JBX-Kernel, unpack it, delete "logo.bin" and do this:

go to (by using mouse or terminal):

/android/system/out/target/product/spyder

There you will find a file called "kernel" - this is your fresh compiled kernel! Copy it to the unpacked JBX-Kernel folder, into:

.../JBX-Kernel_whatever.../system/etc/kexec

(and overwrite the previous kernel in there)

Now go to:

/android/system/out/target/product/spyder/system/lib/modules

There are all the modules you've just built. Copy them to:

.../JBX-Kernel_whatever.../system/lib/modules

Now compress the folders to a new zip file, copy it to your phone and flash it in recovery!

4. CREATE YOUR FIRST DEVELOPMENT BRANCH (add a new Governor)

to create a new branch locally, be in terminal inside the root of your kernel source, and type:

git checkout -b BRANCH_NAME

Replace BRANCH_NAME with whatever you want!

Now you created and switched to your new branch! Here you can start plaing with the files!

To develop Linux kernel (Android IS Linux!) you will have to learn C! The kernel is developed in pure C which is the best programming language for drivers (machine controlling).

if you're German I can suggest your the "open Book - C von A bis Z" (Galileo Computing, gratis).

Otherwiase just google for free C books or tutorials.

Take your time, this is not easy in the fist place - but as soon as you are more experienced you will find it more easy!

The best way to learn it is to read and browse others Kernel repos! You are always free to watch my JBX-Kernel Repo! Read the commit messages to see what this commit is for and look at the code-side changes! If you read carefully, and learn C at the same time, you will understand the commits, step by step.

Let me give you some more hints:

Set you some smaller goals and start to reach them one by one! Don't set yourself too high goals, otherwise you will make yourself too much pressure!

Small steps are the way to your success!

Some of you might only want to make some minor changes, such like adding new governors, etc. Therefor you can i.e. use google to find related commits. So open Google and type:

github kernel omap add governor

We hope that google will show us some repos where the dev(s) wrote commit messages like "Added XXX governor", etc, etc..

In this example Google will put out this:

https://www.google.com/search?q=github+kernel+omap+add+governor

If you click the link you will find the very first result, which leads us to:

https://github.com/broodplank/glass-omap-xrr02

There click on Commits and you will see a commit "Add SmartassV2 governor". Now open this commit, you will find this:

https://github.com/broodplank/glass-omap-xrr02/commit/f959e0e8c16412319e991b26aaa50d8fe3555a4e

There you can see now the FULL commit with all its details! It shows you exactly how to add a governor! The green parts are ALWAYS insertions on Github, while red parts are deletions! SO you can see exactly:

1. WHICH files have been changed

2. WHAT has been changed in these files

3. WHERE in the files were the changes made

4. HOW were these changes performed

Now, if you study this commit for a while, you might know what has to be done in order to add a new governor!

NOTE: The very long files which are COMPLETELY green are NEW FILES!

Let's say you want to take this SMartassV2 governor into your kernel:

You can do it with different ways.

1. Cherry-Pick

For this weay you have to add the "glass-omap-xrr02" repo as remote to your repo. So you get the clone URL and use the git remote command (in your kernel root dir with terminal):

git remote remove upstream

git remote add upstream https://github.com/broodplank/glass-omap-xrr02.git

Now we must fetch the repos content:

git fetch upstream

Wait until the fetching process is finished.

Now we need the SHA1 sum of the commits. You go to your browser and look at the commit. The SHA1 is a very large number you can find at the upper right.

In this case this is the SHA1 for the commit "add SmartassV2 governor":

f959e0e8c16412319e991b26aaa50d8fe3555a4e

So, we need to cherry-pick this commit by typing in the terminal:

git cherry-pick f959e0e8c16412319e991b26aaa50d8fe3555a4e

Now there are three possibilites! If you see a message about "...conflicts" then it didn't work correctly because your local kernel source files might be a little bit different than those from the remote repo. In this case you open these files with a text editor (gedit) and find the lines with the errors, they are looking like this:

<<<<< HEAD

..some code...

>>>>>> Add SmartassV2 governor

Compare the files to those in the remote commit in your browser qand correct the issues or just this:

git cherry-pick --abort

This reverts your cherry-pick and your files are clean and like they were before the cherry-pick!

YOu can add the governor manually by simply looking the remote commit in the browser and copy the green stuff into your local files. Make sure you insert the codes in the right places!!! When you copy it from the green parts you will have to remove EVERY SINGLE "+" at the beginninf of each line!

There is another view in github for files, called "RAW". This will shows the pure file - but also without green/red marks! But in case you add the SMartassV2 governor, you can just search for the keyword "smartass" in the raw view of the file and then copy all lines which are including "msartass" into your local files

The governor itself is a complete new file, so you canswitch to the raw view, right click --> select all --> copy. Then create as new file in the right location (/kernel_source_dir/drivers/cpufreq/cpufreq.c) with the same name like in the commit (cpufreq_smartassv2.c) and paste the whole code into it, save and close.

Don't forget the rest of the code in the other files!!

At last you have to insert the new governor into your kernel configuration! The kernel config is mostly a "defconfig" file!

ALl the related defconfigs we need are located in:

.../arch(arm/configs

The default defconfig for our RAZR is the:

mapphone_mmi_defconfig

The defconfig file inlcudedes everything which is built into the kernel later. If you search for keyword "GOV" you will see the other governos, like Hotplug, etc.. YOu can see how they are used in the defconfig file, so add your new governor the same way. This should be:

CONFIG_CPU_FREQ_GOV_SMARTASS2=y
# CPU_FREQ_DEFAULT_GOV_SMARTASS2 is not set

*The second line is for setting it as default governor.

Thats was it! Now make sure everything was done the right way, save and close all files. In terminal type:

git status

This shows you info about the current status. In this case it will show you the changed files and the new file(s) in red color.

Now you have to stage your commit:

git add .

Adds all new/changed/untracked files to the commit, then:

git commit -m "Added Smartassv2 governor"

Done! Your new commit is staged to the index and can be uploaded! (Uploading is not part of this at the moment! If you want to learn more about git, use Google) :)

Now repeat the compile process like you did already! See if your new governor is included and working.

For further learning it's a good way to proceed with learning C and read, compare and understand commits from other devs/repos.

Ok, guys! I hope you enjoy the guide and it's helpful for you! I will extend/fix/correct this time by time... for now I'm done!

5. GIT COMMANDS

If you find any mistakes or somethings missing in your mind, PM me or post it here.

Please leave me some credits if this tutorial helped you wherever you provide your work! THX!

CREDITS

*Cyanogenmod - took some single infos from their website

How to build Cyanogenmod for Droid Razr (website):

http://wiki.cyanogenmod.org/w/Build_for_spyder

*Hashcode - for being always helpful and supportive and of course for his great work with dhacker

*Linux, Google, XDA-DEVELOPERS