The version for Nexus S kernel is obtained from https://github.com/netarchy/nexus-s

• arch
  

In the arch\arm\common folder there is a FIQ handler code. The fiq_debugger.c contains the FIQ handler that is registered as a device driver. The driver’s probe code registers the interrupt routine.

From what I’ve read FIQ is a high priority interrupt where it can’t be interrupted when it is executed. Normal interrupts can still be interrupted but FIQ cannot. This is useful in Linux if for example the kernel hangs because of some interrupt code or some hardware issue. The other thing to remember is that FIQ handler must be implemented in ASM not in C (however, there are few places that I saw the handler is implemented using C, for example, Samsung kernel code is implemented in C). There is a good thread about why writing in ASM is better than C → http://www.spinicst.net/lists/arm-kernel/msg30890.html

This website http://aelmahmoudy.users.sourceforge.net/electronix/arm/chapter3.htm outlines the different interrupts (one of them FIQ) and explains in details the working

ARM vector location for FIQ is at 0xffff001c.

In order to create our own FIQ handler we must make sure that when our interrupt routine is called register housekeeping need to be done beforehand and mostly this is done in ASM. The sample for this housekeeping can be seen at fiq_glue.S from the Samsung code

Following are some links that provides more information to understand how FIQ works in Linux and how it is used in embedded world.

https://lwn.net/Articles/526754/

http://www.spinics.net/lists/newbies/msg45652.html

http://warmcat.com/at91-fiq.patch

http://stackoverflow.com/questions/2962473/problem-calling-linux-c-code-from-fiq-handler

https://geekwentfreak-raviteja.rhcloud.com/2011/01/writing-interrupt-routines-using-gcc-for-arm/

http://www.embedded.com/design/mcus-processors-and-socs/4007119/Building-Bare-Metal-ARM-Systems-with-GNU-Part-1–Getting-Started#

http://www.gnudd.com/sw/fiq-engine.html (library that assist in building our own fiq handler, it provides utility such as print, etc)

In the \arm\include\asm\mach there is  file called mmc.h which is a cut down version from the the plain vanilla kernel that resides inside arch\arm\mach-msm\include\mach

There are few changes in the arch\arm\kernel directory

the biggest changes inside this directory is in the etm.c file. The file contains Macrocell code. Few observations for the other files

1. leds.c → contains code for led notification, it is does as part of sysdev (/sys filesystem)
2. process.c → new code has been added to print out more information about the registers

 The folder mach-s5pv210 contains most of the code to define the processor of the device, in Nexus S case it is the S5PV210 application processor.  Some interesting observation

1. in the cpufreq.c there is a definition called SLEEP_FREQ that defined the speed of the processor when it is in sleep mode, in the code it is specified as 800Mhz
2. the MACHINE_START declaration can be found inside mach-herring.c file
3. there are few interrupts that are being registered such as – UARTs, Timer, ADC, Alarm, RTC, etc inside irq.c in the plat-s5p directory
4. the memory definitions can be seen in file map.h inside arch\arm\mach-s5pv210\include\mach\

GPIO pins configuration can be found inside the file gpio-herring.h inside arch/arm/mach-s5pv210/include/mach. The GPIO pin configuration will show which pin is configured for what and based on that information it is possible to trace through the kernel source code to see where the code specific to a particular functionality lives in. For example the there is a GPIO called GPIO_PHONE_ACTIVE and by searching for that string in the kernel I was able to find a file called dev-herring-phone.c containing code on how it handles phone calls. Most of the processor/phone configuration (GPS, buttons, leds, etc) and how it is handled inside Linux can be found inside in the arch/arm/mach-s5pv210 directory

• drivers

Lots of new and modified code in this directory, which is understandable as the crux of kernel are normally the interfacing with hardware and this directory is where the majority of code lives. The  Android drivers resides in the staging/ directory

• firmware

There is  a binary blob file called samsung_mfc_fw.bin.ihex. The file is a video driver file as can be seen in the Makefile. This is a proprietary driver for video which can only work for a specific kernel version.

• fs

yaffs2 is the default filesystem used inside Android. This filesystem is used to mount the image file so that it can be accessed as normal filesystem.  Not obvious from the code which version of branch it is from, can be explored further from the project website www.yaffs.net

Few files have been modified inside this directory

Most of the changes are very minor except inside the file base.c in the proc directory

• kernel

 Quite a number of changes inside this directory as can be seen in the screenshot below.  There are few new files which are related to wakelock and suspend features. Power management code mostly added inside here

•  mm

 This directory contains the ashmem.c which is the memory management driver for Android.

• net

Lots of changes inside this directory, the following screenshot shows the file that have been modified.

• sound

Contains the sound drivers inside the board. Looking at the code it is using WM8994 (http://www.wolfsonmicro.com/products/audio_hubs/WM8994/) chipset. Memory management for the sound drivers are also available.

My personal observation doing this exercise are as follows

1. Most of Samsung code are readily available in the vanilla kernel, so any additional code that are added are for new features or some bug fixes that have been done in new kernel version but not backported to old version.
2. Most of new code are in the machine configuration – this is the place information about the processor clock, pins configuration, interrupts, etc can be found. This is understandable as each board/machine have their own specific configuration not to mention the different GPIO pins. Due to this it is noticeable that the drivers code take the most chunk of new code added into the Android-ify kernel.

3. Few changes are made to made to the main kernel code to ease debugging by adding new debug log messages.
4. Video is proprietary as this got to do with the GPU

error: Exited sync due to gc errors

This error happens because the script is using the -c parameter which is only available in Git version 1.7.2 and above. To solve this problem upgrade your Git to the latest version or if you are using Ubuntu you can follow this step

# add the ppa repo:
$ sudo apt-add-repository ppa:git-core/ppa

$ sudo nano /etc/apt/sources.list
# add the following lines, then exit (ctrl-X) and save (Y):
deb http://ppa.launchpad.net/git-core/ppa/ubuntu lucid main
deb-src http://ppa.launchpad.net/git-core/ppa/ubuntu lucid main

# add the server’s key:
$ sudo apt-key adv –keyserver keyserver.ubuntu.com –recv-keys E1DF1F24
$ sudo apt-get update

# remove and reinstall:
$ sudo apt-get remove git-core
$ sudo apt-get install git

Android Building Link

Because of my own need and to make my life easier I created a document explaining the different directories inside Android containing simple description what is its contents. At the moment the document contains information for Android 4.0.3_r1, as source code keep on changing I will try to keep it up to date to the latest version that are available in the Android repository.

Click here to view the document

Feel free to leave to comment or correction for the document in this post

This tutorial uses Linux to build and use GCC and the distro flavour used is the Ubuntu distro. This tutorial uses the Xubuntu distro but you can use different kind of Ubuntu distro. If you are not experienced with Linux than it is recommended that you use the same version and distro with this tutorial to save time and pain down the track in troubleshooting problems. The screenshot shows the Linux Kernel and Xubuntu version I’m using for this tutorial, to make it easier I’m outlining the Linux version information here

Linux ubuntu 3.0.0-12-generic #20-Ubuntu SMP … x86_64 GNU/Linux

Toolchain Script Preparation

There are a number of ways you can build GCC from the ground up but most of the scripts that I came across are either out of date, buggy or worse not maintained and out of date. I found the scripts created by Uwe Hermann is the most easiest to use and it is also maintained up to date in github by Piotr Esden-Tempski. Use the latest source from github by checking it out as follows (if you don’t have git installed on your machine follows the instructions in the troubleshooting section)

git clone https://github.com/esden/summon-arm-toolchain.git

The next step, which is the most crucial step in the whole process is to install all the necessary libraries that are required by GCC. Execute the following command to install the libraries

sudo apt-get install flex bison libgmp3-dev libmpfr-dev libncurses5-dev libmpc-dev autoconf texinfo build-essential libftdi-dev zlib1g-dev

Press Y when it asked Do you want to continue. It will take sometime but you will see few lines of messages coming out to inform you about the installation progress. You will get something similar as below

Get:1 http://us.archive.ubuntu.com/ubuntu/ oneiric/main autoconf all 2.68-1ubuntu1 [560 kB]
Get:2 http://us.archive.ubuntu.com/ubuntu/ oneiric/main autotools-dev all 20110511.1 [44.7 kB]
Get:3 http://us.archive.ubuntu.com/ubuntu/ oneiric/main automake all 1:1.11.1-1ubuntu1 [544 kB]
Get:4 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libstdc++6-4.6-dev amd64 4.6.1-9ubuntu3 [1,644 kB]
Get:5 http://us.archive.ubuntu.com/ubuntu/ oneiric/main g++-4.6 amd64 4.6.1-9ubuntu3 [6,970 kB]
Get:6 http://us.archive.ubuntu.com/ubuntu/ oneiric/main g++ amd64 4:4.6.1-2ubuntu5 [1,444 B]
Get:7 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libdpkg-perl all 1.16.0.3ubuntu5 [171 kB]
Get:8 http://us.archive.ubuntu.com/ubuntu/ oneiric/main dpkg-dev all 1.16.0.3ubuntu5 [473 kB]
Get:9 http://us.archive.ubuntu.com/ubuntu/ oneiric/main build-essential amd64 11.5ubuntu1 [5,928 B]
Get:10 http://us.archive.ubuntu.com/ubuntu/ oneiric/main fakeroot amd64 1.17-1 [107 kB]
Get:11 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libalgorithm-diff-perl all 1.19.02-2 [50.7 kB]
Get:12 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libalgorithm-diff-xs-perl amd64 0.04-1build1 [13.4 kB]
Get:13 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libalgorithm-merge-perl all 0.08-2 [12.7 kB]
Get:14 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libgmpxx4ldbl amd64 2:5.0.1+dfsg-7ubuntu2 [10.7 kB]
Get:15 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libgmp-dev amd64 2:5.0.1+dfsg-7ubuntu2 [367 kB]
Get:16 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libgmp3-dev amd64 2:5.0.1+dfsg-7ubuntu2 [3,814 B]
Get:17 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libmpfr-dev amd64 3.0.1-5 [234 kB]
Get:18 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libtinfo-dev amd64 5.9-1ubuntu5 [71.2 kB]
Get:19 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libncurses5-dev amd64 5.9-1ubuntu5 [252 kB]
Get:20 http://us.archive.ubuntu.com/ubuntu/ oneiric/main texinfo amd64 4.13a.dfsg.1-8ubuntu1 [458 kB]
Get:21 http://us.archive.ubuntu.com/ubuntu/ oneiric/main libmpc-dev amd64 0.9-3 [53.1 kB]
Fetched 12.0 MB in 1min 17s (156 kB/s)
Selecting previously deselected package autoconf.
(Reading database … 148533 files and directories currently installed.)
Unpacking autoconf (from …/autoconf_2.68-1ubuntu1_all.deb) …
Selecting previously deselected package autotools-dev.
Unpacking autotools-dev (from …/autotools-dev_20110511.1_all.deb) …
Selecting previously deselected package automake.
Unpacking automake (from …/automake_1%3a1.11.1-1ubuntu1_all.deb) …
Selecting previously deselected package libstdc++6-4.6-dev.
Unpacking libstdc++6-4.6-dev (from …/libstdc++6-4.6-dev_4.6.1-9ubuntu3_amd64.deb) …
Selecting previously deselected package g++-4.6.
Unpacking g++-4.6 (from …/g++-4.6_4.6.1-9ubuntu3_amd64.deb) …
Selecting previously deselected package g++.
Unpacking g++ (from …/g++_4%3a4.6.1-2ubuntu5_amd64.deb) …
Selecting previously deselected package libdpkg-perl.
Unpacking libdpkg-perl (from …/libdpkg-perl_1.16.0.3ubuntu5_all.deb) …
Selecting previously deselected package dpkg-dev.
Unpacking dpkg-dev (from …/dpkg-dev_1.16.0.3ubuntu5_all.deb) …
Selecting previously deselected package build-essential.
Unpacking build-essential (from …/build-essential_11.5ubuntu1_amd64.deb) …
Selecting previously deselected package fakeroot.
Unpacking fakeroot (from …/fakeroot_1.17-1_amd64.deb) …
Selecting previously deselected package libalgorithm-diff-perl.
Unpacking libalgorithm-diff-perl (from …/libalgorithm-diff-perl_1.19.02-2_all.deb) …
Selecting previously deselected package libalgorithm-diff-xs-perl.
Unpacking libalgorithm-diff-xs-perl (from …/libalgorithm-diff-xs-perl_0.04-1build1_amd64.deb) …
Selecting previously deselected package libalgorithm-merge-perl.
Unpacking libalgorithm-merge-perl (from …/libalgorithm-merge-perl_0.08-2_all.deb) …
Selecting previously deselected package libgmpxx4ldbl.
Unpacking libgmpxx4ldbl (from …/libgmpxx4ldbl_2%3a5.0.1+dfsg-7ubuntu2_amd64.deb) …
Selecting previously deselected package libgmp-dev.
Unpacking libgmp-dev (from …/libgmp-dev_2%3a5.0.1+dfsg-7ubuntu2_amd64.deb) …
Selecting previously deselected package libgmp3-dev.
Unpacking libgmp3-dev (from …/libgmp3-dev_2%3a5.0.1+dfsg-7ubuntu2_amd64.deb) …
Selecting previously deselected package libmpfr-dev.
Unpacking libmpfr-dev (from …/libmpfr-dev_3.0.1-5_amd64.deb) …
Selecting previously deselected package libtinfo-dev.
Unpacking libtinfo-dev (from …/libtinfo-dev_5.9-1ubuntu5_amd64.deb) …
Selecting previously deselected package libncurses5-dev.
Unpacking libncurses5-dev (from …/libncurses5-dev_5.9-1ubuntu5_amd64.deb) …
Selecting previously deselected package texinfo.
Unpacking texinfo (from …/texinfo_4.13a.dfsg.1-8ubuntu1_amd64.deb) …
Selecting previously deselected package libmpc-dev.
Unpacking libmpc-dev (from …/libmpc-dev_0.9-3_amd64.deb) …
Processing triggers for man-db …
Processing triggers for doc-base …
Processing 1 added doc-base file…
Registering documents with scrollkeeper…
Processing triggers for install-info …
Setting up autoconf (2.68-1ubuntu1) …
Setting up autotools-dev (20110511.1) …
Setting up automake (1:1.11.1-1ubuntu1) …
update-alternatives: using /usr/bin/automake-1.11 to provide /usr/bin/automake (automake) in auto mode.
Setting up libdpkg-perl (1.16.0.3ubuntu5) …
Setting up dpkg-dev (1.16.0.3ubuntu5) …
Setting up fakeroot (1.17-1) …
update-alternatives: using /usr/bin/fakeroot-sysv to provide /usr/bin/fakeroot (fakeroot) in auto mode.
Setting up libalgorithm-diff-perl (1.19.02-2) …
Setting up libalgorithm-diff-xs-perl (0.04-1build1) …
Setting up libalgorithm-merge-perl (0.08-2) …
Setting up libgmpxx4ldbl (2:5.0.1+dfsg-7ubuntu2) …
Setting up libgmp-dev (2:5.0.1+dfsg-7ubuntu2) …
Setting up libgmp3-dev (2:5.0.1+dfsg-7ubuntu2) …
Setting up libmpfr-dev (3.0.1-5) …
Setting up libtinfo-dev (5.9-1ubuntu5) …
Setting up libncurses5-dev (5.9-1ubuntu5) …
Setting up texinfo (4.13a.dfsg.1-8ubuntu1) …
Setting up libmpc-dev (0.9-3) …
Setting up libstdc++6-4.6-dev (4.6.1-9ubuntu3) …
Setting up g++-4.6 (4.6.1-9ubuntu3) …
Setting up g++ (4:4.6.1-2ubuntu5) …
update-alternatives: using /usr/bin/g++ to provide /usr/bin/c++ (c++) in auto mode.
Setting up build-essential (11.5ubuntu1) …
Processing triggers for libc-bin …
ldconfig deferred processing now taking place

Building Toolchain

This step will guide you on how to build GCC. Change to the directory that contains the checked out scripts and execute the command as follow

You will see the script will start downloading all the necessary dependencies that are required to build GCC. The first dependency is the binutils

Next, the script will download GCC. In this case the script is downloading GCC from Linaro website. This step will take a bit longer than the other steps as this is the core GCC source codes that are being downloaded.

Next, it will download newlib library

Next, it will download gdb debugger

Next, it will download openocd

After completing the download process the script will unpack the source code one by one. The first one will be the binutils and you will see long list of files being extracted out looking something like the following

On completion of the extraction process the compilation process for binutils will kick in and will look as the following

Compilation process will take sometime to complete as it involved quite a lot of files. After completing the binutils compilation the script will move to extract the GCC and newlib source codes followed by the compilation process.

On completion of the GCC and newlib source code the GCC have been compiled and ready to use. The next step after this the script will compile the openocd and gdb source code too.

It is advisable to let the whole script complete before doing anything. At any given point of time if the script stops because of errors check the Appendix section for troubleshooting tips and fixes, once you have done the fix you can re-run the script again.

Checking The New GCC

Once GCC has been compiled successfully you need to test to make sure that it is working, the first and easiest step is to execute it. If you haven’t changed anything from the summon-arm-toolchain script the GCC binaries would have been installed in the /sat directory in your home folder, in my case it is installed in /home/nanik/sat

In order to execute the newly created GCC you need to add it to your PATH environment variable as follows

PATH=$PATH:~/sat/bin

to print out the help menu of GCC type in (Note: help option is with double dash)

arm-none-eabi-gcc –help

you will the output as shown below. The output shown is a printout of the available options in GCC

the other way to check is to print out the supported platform/architecture that GCC can compile the source code to. Execute the following commmand (Note: target-help option is with double dash)

arm-none-eabi-gcc –target-help

if you scroll down the output on your screen you will see something like the following screen

What you are seeing on the output is the ARM CPUs that are supported by the GCC and also the ARM architectures (instruction sets) that are supported.

If you have reached this part of the instruction that means you have successfully compiled and run GCC. Now you can use the GCC as part of your build process.

Troubleshooting

Installing git

If you don’t have git installed on your machine execute the following command

sudo apt-get install git

You will get somewhat similar kind of messages, and once the download and installtion is done you can use git

zlib compilation error

During compilation process if you come across problem such as

fatal error: zlib.h: No such file or directory

install the zlib by using the following command

sudo apt-get install zlib1g-dev

openocd compilation error

During openocd compilation process if you come across error

error: Cannot build & run test program using libftdi

install the libftdi library by using the following command

sudo apt-get install libftdi-dev

Enter Y to continue the installation process, once completed you will something like below

Must have Java 1.6+ installed on your local machine

DS-5 Installation Steps

1. Download Eclipse making sure it’s Eclipse Indigo

2. Download Android SDK

3. Click on the link to download, in my case I downloaded the .zip file (android-sdk_r15-windows.zip)

4. Download the Android NDK (Native Development Kit) from http://developer.android.com/sdk/ndk

5. Unzip both the NDK and SDK .zip files to a directory

6. Unzip Eclipse .zip to a directory

7. Launch Eclipse and specify the workspace

8. Select Install New Software… from the Help menu

9. Enter the repository information in the Name and Location field

10. Select the ARM DS-5 Community Edition by clicking on the tickbox

11. You should see the Eclipse plug-ins for DS-5 Community Edition with all the necessary components shown.

12. Select the radio button for I accept the terms of the license agreements and click on Finish button

13. You will see the progress of the components being installed . Depending on your internet connection it will take few minutes to 15-20min to complete the downloading and installing of the components.

14. Click on Restart Now

15. When Eclipse has started select the Install Community Edition license and click Continue button

Android SDK Configuration

1. Install ADT (Android Development Toolkit) plugin

2. Select the Developer Tools check box to select the components that need to be installed

3. Check to make sure all the necessary components have been selected.

4. Select I accept the terms of the license agreements

5. The installation process will start and wait until it’s completed

6. You will get a Warning message to tell you that the software content is not signed, for this just click Ok button

7. Click on Restart Now

8. Select Window –> Preferences

9. Select Android from the Preferences window and click on Browse… button to select the SDK location

10. You will get Android SDK Verification message box, click on Ok button

11. Exit Eclipse

12. Run SDK Manager.exe

13. Make sure the following are selected

• Android SDK Platform-tools
• Documentation for Android SDK
• SDK Platform
• Samples for SDK
• ARM EABI v7a System Image
• Google APIs by Google Inc.

14. Select Accept All and click Install button

15. Wait until the downloading complete. The download process will take sometime as it’s downloading quite a number of files for the SDK.

16. Click on Yes once you are done

17. Open the AVD Manager by selecting Windows –> AVD Manager

18. Click on New… button

19. Enter the information for creating a new AVD (Android Virtual Device) and click on Create AVD

20. Click on the Start… button to bring up the Launch Options dialog box. Click on Launch button.

21. If everything goes well you should be able to see the following Ice Cream Sandwich (Android 4.0) startup screen.

Once you are able to see the Android home screen your setup is complete

How To Run NDK Sample Application

1. Change to your NDK directory and execute the command ndk-build -C samples/hello-neon in your command prompt as shown below

2. Open up Eclipse and select File –> New –> Project and select Android Project

3. Type in the name of the project and for the Location field select the sample hello-neon and click on Finish button

4. Once the project has been imported double-click on AndroidManifest.xml and select the Application tab. Once it’s opened click on the Application Attributes heading, you will see the Debuggable option and select true . Save the file before moving on to the next steps.

5. Run the application by right clicking on the hello-neon project and select Run As and select Android Application

6. You will see on the Console tab the following messages

7. You will see the application run in the emulator as follows

How To Setup Debugging

1. Open the debug perspective by select Window –> Open Perspective –> Debug

2. Open the debug perspective by select Window –> Open Perspective –> DS-5 Debug.You will see screen similar to the following screen shot

3. Open up the debug configuration by selecting Run –> Debug Configurations

4. Create a new configuration by clicking on the New launch configuration button. Untick the Connect as root and check make sure that your physical device (mobile phone/tablet) is connected properly to the USB and the ID is shown in the Connections drop down box.

If any of the above information are not done properly the tab will have an error on it like so

5. Fill in the following under the Files and click on the Workspace… button to browse for the project and select the hello-neon project. Do the same step for both the Project directory and APK file.

6. Fill in the following under Debugger tab

Using Debugger

1. Switch to DS-5 Debug mode

2. Open up the helloneon.c file and put a break point on line 109 and 113. Double click on the blue line of the left side of the screen to put the breakpoint in (a small blue color circle)

3. To start debugging click on the DS-5 debug icon or go to Run –> Debug Configurations and select the helloNeon under the DS-5 Debugger section. Click on the Debug button on Debug Configurations box.

4. Once the application is running on your device you can see the breakpoint will be hit at the line that you setup from the previous step

5. To connect or disconnect the debugging session use the connect and disconnect button in the Debug Control

Problem and Fixes

1. If your ARM menus from the Help menu does not show up it’s because it cannot find the license key. What you must do is make sure you have the proper location of your eclipse directory in your PATH folder

2. If you are getting the following error meaning that you have not compiled the program to generate the .so file. Follow step 1 from the How To Run NDK Sample Application section.

3. If you are getting the following error this means that the .apk has not been generated

the easiest way to resolve this is to run the application by right clicking on the hello-neon project and select Run As and select Android Application. Once the application has been exported to your phone do the debugging steps again.

4. If your breakpoint is not triggered when the app hit that line that means that most probably the gdbserver that Eclipse is using is not from DS-5 version. This is what you have to do. Go to Help –> ARM Extras

It will open up a folder that contains the gator and gdbserver directories.

Go to the gdbserver/android directory and copy the gdbserver-stat-7.1 file into your project folder, in my case it’s copied into the C:\DS-5\android-ndk-r7-windows\samples\hello-neon\libs\armeabi and C:\DS-5\android-ndk-r7-windows\samples\hello-neon\libs\armeabi-v7a directory. Once copied delete the old gdbserver and rename the copied file from gdbserver-stat-7.1 to gdbserver

Once this step is done you should be able to see your breakpoint hit.

Update 2/March/2012: Added the following video uploaded by ARM

http://www.youtube.com/watch?feature=player_detailpage&v=xfoezJgw7wA