Setting Up Android Mobile Phone to Use ARM Streamline for Profiling

This is an article describing the steps how to set up your Android Phone to run ARM Streamline Performance Analyzer. It was originally posted on 8 March 2012 on blogs.arm.com

ARM Streamline Performance Analyzer is a system-wide visualizer and profiler for targets running ARM Linux or Android native applications and libraries. Combining an ARM Linux kernel module, target daemon, and a graphical user interface, it transforms system trace and sampling data into reports that present the data in both visual and statistical forms.

Streamline supports Cortex™-A8, Cortex-A9, Cortex-A15, ARM9™, and ARM11™ processors running ARM Linux or Android. In this article, the target ARM device is HTC Sensation 4G Android mobile phone. Some necessary information is listed below before the start.

• Streamline Version 5.7. Streamline is a component of ARM Development Studio 5. So download ARM DS-5 Professional, Basic or the free Android targeted DS-5 Community Edition to get it.
• Target ARM Device, HTC Sensation 4G
  • Qualcomm® Snapdragon™ 1.2-GHz dual-core processor, ARMv7 architecture
  • Android Version 2.3.4
  • Linux Kernel Version 2.6.35.13

1 Preparation

First, let’s do some preparations.

1.1 Backup Android Phone

BE VERY CAREFUL! It is my responsibility to caution you that the all contents in this article are dangers for your Android phone. The worst case is bricking your phone.

Before continuing, please think twice and backup your data in Android phone first!

1.2 Check and Unlock Android Phone

In order to carry out our work, a suitable Android mobile phone is used as target ARM device. For example, I selected HTC Sensation 4G Android mobile phone.

The First and essential step is to disable fast booting if it is enabled in HTC phone. To do that: Go to Android setting > Power > Fast boot (uncheck the box).

The Second step is to boot into HBOOT (bootloader): Power off the phone. After ensuring the phone is completely off, hold <POWER> + <VOL-DOWN> buttons together until white HBOOT screen appears as following Figure 1.

Figure 1 HBOOT Screen

In HBOOT screen, some necessary information should be confirmed.

• The internal code for HTC phone. For HTC sensation 4G, it is PYRAMID marked by red box in Figure. The internal code is a key to search correct Linux kernel source package released by HTC for your HTC Android mobile phone.
• The status of security lock. For my phone, it is S-OFF (security off) marked by the red box in Figure 1. The security lock is very important for this article’s objective. S-OFF means that NAND Flash ROM of the device is unlocked and writable, which means that you could update certain partitions of the Android system bypassing the signature check; for example, the boot partition with your customized image. The default setting for HTC’s devices is S-ON, which means you may only update system with HTC’s official firmware image because of signature check enabled.

If your HTC phone’s status of security lock is S-ON, don’t worry about it. You can access HTC’s official website Unlock Bootloader. Following this web page, you could unlock your HTC phone.

1.3 Download and install ARM DS-5

Since Streamline is a component of ARM Development Studio 5, you can download a free Community Edition version of ARM DS-5 to install it. Of course, I assume the Eclipse has been installed in advance (as of this writing, DS-5 CE is only supported by Windows and 32-bit Linux JVM versions of Eclipse).

1.4 Download Linux Kernel Source Code

Streamline uses hardware performance counters with kernel metrics to provide an accurate representation of system resources. You must enable certain Linux kernel configurations to run Streamline on an Android system. A copy of Linux kernel source code is necessary for next step. For HTC Sensation 4G, the Linux kernel source code could be download from HTC’s website Kernel Source Code and you can find the correct package “HTC Sensation 4G – MR – 2.6.35 kernel source code (2.6.35.13)” by matching the HTC internal code PYRAMID from a long list.

1.5 Setting up Android Development Environment

The final preparation is setting up Android development environment. This is not for common Android application development but special for Android and Linux kernel development. I have listed my environment for reference:

• 64bit Ubuntu 10.10 running on x86 PC
• The GNU ARM Toolchain under Linux, I used CodeSourcery ARM GNU/Linux Toolchain downloaded from Mentor Graphics.
• Android SDK r16-linux downloaded from Android developers website.
• Android SDK Platform-tools downloaded by Android SDK r16-linux
• A USB cable – USB Type A plug to Micro-USB Type B plug
• An empty SD Card with 1GB or more capacity.
• Configuring USB Access to HTC Android phone on a Linux PC as following:

You can create a rule that defines all HTC Phones, All Modes. This is adapted from http://developer.and...ing/device.html. Use root to create or modify /etc/udev/rules.d/51-android.rules. Put the following line in the file:

SUBSYSTEM=="usb", SYSFS{idVendor}=="0bb4", MODE="0666"

Save the file, then change the file permissions to read-all:

$ chmod a+r /etc/udev/rules.d/51-android.rules

2 Pull kernel configuration and Android init.rc from phone

Now, we can begin formal work.

Before building Linux kernel, connect android device to PC via USB cable and pull the kernel configuration as following in a terminal window:

$ cd /path/to/android-sdk/tools

$ ./adb pull /proc/config.gz

$ gunzip ./config.gz

$ cp config /path/to/kernel/.config

Pull init.rc script in to the Android root folder:

$ cd /path/to/android-sdk/tools

$ ./adb pull /init.rc

3 Building Linux kernel and gator module

Next step, extract the Linux kernel source code package to a working folder on your PC. Change directories in to the kernel folder you just extracted and issue this command to enter kernel configuration menu.

$ make ARCH=arm menuconfig

Use the arrow keys to navigate to the desired submenu and press Enter. Each submenu is listed with the action you need to take within it.

• General Setup, make sure the Profiling Support option is enabled.
• Kernel Hacking, in the Kernel Hacking submenu, navigate to the Tracers submenu and press Enter. Make sure the Trace process context switches option is enabled.
• Kernel Features, make sure the High Resolution Timer Support is enabled. Enable Use local timer interrupts if you are using a symmetric multiprocessor (SMP) target.

After saving and exiting configuration menu, you must rebuild kernel and modules as following:

$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- zImage -j4

$ make ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- modules -j4

To use Streamline with your Android target, you also must build the gator kernel module, gator.ko. The gator kernel module sources are located in your DS-5 install folder:

installdir/arm/gator/driver-src/gator-driver.tar.gz

In your DS-5 CE Eclipse install, you can locate the source files with the Help->ARM Extras… menu. Transfer the source package to the working folder and unzip it. Issue the following command to build the gator module:

$ make -C <path/to/kernel/source> M=`pwd` ARCH=arm CROSS_COMPILE=arm-none-linux-gnueabi- modules

To enable Streamline on an Android system, you need run the gator daemon application. The pre-built gatord is located on your DS-5 install folder:

installdir/arm/gator/android/gatord

In DS-5 CE, the source is located by selecting the Help->ARM Extras… menu again. To use it, simply copy gatord to your Android phone and place it in the same directory (e.g. /system/xbin or /system/bin) as the gator driver, gatord.ko, on the Android file system.

(optional) To enable gator service on Android booting, you must modify init.rc script file which has been pulled <a name="OLE_LINK1">from Android device. Add following line in the bottom of file

service ds5_gatord /system/xbin/gatord

exec /system/xbin/gatord &

oneshot

You may also launch gatord after the Android device boots up if you do not wish to incur gatord’s resource utilization at boot. For example, you could use the adb shell command to run /system/xbin/gatord& after boot.

4 Creating an Android update.zip package and Flashing phone

An update.zip is a zip file on an SD Card’s root folder loaded by the Android Recovery System on boot. Normally, it is signed with a vendor’s key and released for system recovery in an emergency or system upgrade. When the Android phone is unlocked, you may update the system with a customized package. Today, I will show you how to create an update.zip package for updating the Linux kernel and init.rc script.

• To speed up work, download a kernel update package as a template. For the HTC Sensation 4G, I found some kernel update packages via Google.
• Extract it to your work folder <workdir>
• Replace the zImage file in <workdir>/kernel with rebuilt kernel zImage.
• Copy init.rc to <workdir>/kernel
• Edit or create mkbooting.sh script in <workdir>/kernel to update the boot image

#!/sbin/sh

# repleace init.rc in ramdisk

mkdir /tmp/newramdisk

cd /tmp/newramdisk

busybox gunzip -c /tmp/boot.img-ramdisk.gz | busybox cpio -i

busybox cp /tmp/init.rc /tmp/newramdisk/

chmod 750 /tmp/newramdisk/init.rc

busybox find . | busybox cpio -o -H newc | busybox gzip > /tmp/newramdisk.gz

cd /tmp

rm -r /tmp/newramdisk

# generate createnewboot.sh

echo \#!/sbin/sh > /tmp/createnewboot.sh

echo /tmp/mkbootimg --kernel /tmp/zImage --ramdisk /tmp/newramdisk.gz --cmdline \"$(cat /tmp/boot.img-cmdline)\" --base $(cat /tmp/boot.img-base) --output /tmp/newboot.img >> /tmp/createnewboot.sh

chmod 777 /tmp/createnewboot.sh

/tmp/createnewboot.sh

return $?

• Copy rebuilt kernel modules (wifi drivers) to <workdir>/system/lib/modules
• Copy gator.ko and gatord to <workdir>/system/xbin
• Edit updater-script in <workdir>/META-INF/com/google/android/updater-script. Add the following lines of script to update the system partition and set the file permissions of gatord to executable.

ui_print("Extracting system files...");

package_extract_dir("system", "/system");

set_perm(0, 0, 0755, "/system/xbin/gatord");

unmount("/system");

• Edit updater-script in <workdir>/META-INF/com/google/android/updater-script. Add the following lines of script to update the boot image (kernel and init.rc).

ui_print("Building new boot.img...");

run_program("/tmp/dd", "if=/dev/block/mmcblk0p20", "of=/tmp/boot.img");;

run_program("/tmp/unpackbootimg", "/tmp/boot.img", "/tmp/");

run_program("/tmp/mkbootimg.sh");

• Compress the <workdir> folder to update.zip file. Take care! Don’t include the <workdir> folder itself.
• Copy update.zip file to your target handset’s SD Card root folder.
• BE CAFEFUL! Charge you phone before continuing!!!
• Power off phone and power it on in HBOOT mode. (Press Power and Volume down buttons together)
• Enter the Recovery menu. The system will prompt you and automatically update.
• After restarting, your phone is ready for profiling with Streamline.

5 Profiling Android phone with Streamline

Streamline supports connection to your target using Ethernet. Using the Android Debug Bridge (ADB) utility, it is possible to forward a TCP port from the target to your PC localhost over a USB connection. ADB can also be configured to work over Ethernet or Wi-Fi. For more information about the Android SDK and ADB setup, see the Android website. Once ADB is set up, forward the Streamline port to your localhost using the following command:

adb forward tcp:8080 tcp:8080

Now run DS-5 on your PC and open the Streamline Data View. If it is not visible from the Window->Show View menu, select Window->Show View->Other; find “ARM Streamline” in the dialog box and open “ARM Streamline Data”. Enter the device’s Ethernet address in the Capture Options dialog box of the ARM Streamline Data view in Eclipse or DS-5. If you use the Android Debug Bridge (ADB) over USB to forward the port, enter localhost in the Address field as shown in Figure 2.

Figure 2 Streanline Data Capture Dialog

Finally, following the instructions ARM DS-5 Using ARM Streamline on the ARM website, you can start profiling your Android phone with Streamline. Figure 3 is a screen shot of profiling Android phone with Streamline.

Figure 3 Streamline Profiling Window

6 Conclusion

Streamline is a powerful and cost-efficient solution for system-wide software profiling and performance analysis for ARM Linux and Android platform. I hope this article helps you leverage Streamline to accelerate your Android development work. Once you start using it, you will come to like this tool quickly. If you want to learn more about how to use Streamline, please access the ARM Streamline website and ARM DS-5 info center.

Fang Bao is a Software Engineer for ARM in the Home Software Enabling team. Fang holds a master's degree from Tsinghua University. Prior to joining ARM, Fang accumulated several years of experience working on projects related to the digital home, including Digital STB, PVR-STB, IP-STB, Blu-ray Disc Player, DMP, Android STB and Google TV. He has a deep understanding of DTV and STB products as well as the open source Linux and Android platforms. Fang is inquisitive about all things ARM for the connected home. Fang Bao is based in Shanghai, China.