= Touch/GPU profiling/Mali =

For ARM Mali devices, we have 2 tools available.

 * CPU/GPU profiler - called [[https://developer.arm.com/products/software-development-tools/ds-5-development-studio/streamline/overview|DS-5 Streamline]]
 * GL API tracer & analyser - called [[http://malideveloper.arm.com/resources/tools/mali-graphics-debugger/|Mali Graphics Debugger]]

I'll take each one in turn.

== DS-5 Streamline ==

This tool is great for getting an overall perspective of what your device is doing. It gathers statistics from your device on CPU usage (per application), GPU usage (direct-from-GPU performance stats), Memory, I/O and much more. You can obtain it via here:

https://developer.arm.com/products/software-development-tools/ds-5-development-studio/editions/community-edition

and following the "Download DS-5 Community Edition" link. It will ask you to fill in a form, and you'll get a link to the download in your email.

=== Installation ===

Installation of DS-5 on your laptop/PC is straight forward. First install these packages (64 bit systems):
{{{{
    lib32ncurses5 libusb-0.1-4:i386 libxft2:i386 libxmu6:i386 libxrandr2:i386 libxcursor1:i386
}}}}
Extract the download into a temporary directory, enter it and run
{{{{
    ./install.sh
}}}}
I prefer to not run this as root. Follow the prompts to perform the installation. It will ask you where to install, take note of where you choose, as there are files we'll need later in there.


=== Device Preparation ===

Getting your device ready to be profiled is a little work.

Your device needs to have booted a kernel with a particular configuration - which is not the default. I have built suitable kernels (aka "boot.img") for some Ubuntu Touch devices, and put them here:

http://people.canonical.com/~gerboland/krillin/kernel/

You need to download the "boot.img" file suited to your device.

=== Profiling ===

1. Boot the Krillin with the custom kernel. Have it connected by USB. Reboot it to the bootloader with:
{{{
    adb reboot bootloader
}}}
and then do:
{{{
    fastboot boot path/to/boot.img
}}}
The phone should show you the file transferred, then it will pause for a while (can be up to a minute) before booting.

2. Need to transfer a daemon "gatord" to the phone, and run it. You have a copy of the daemon in the DS-5 install. Mine is here:
{{{
    /path/to/DS-5_v5.24.0/sw/streamline/bin/arm/gatord
}}}
So just adb push it to the phone. Then run it
{{{
    sudo ./gatord
}}}
It might not need to be root. It's not very good at dealing with Ctrl+C either. It has a "-d" flag to enable printing useful debug output in case you have connection issues.

3. Now open DS-5 Streamline. 

There are 2 ways to accomplish this:

i. There is a dedicated application called Streamline now installed on your system, which solely records & visualizes performance statistics. It should be available in the Dash, just search for it.

ii. An alternative is to use the Streamline tool which is embedded in the Eclipe IDE DS-5 installed which was also installed. Just search for "Eclipse for DS-5" in the Dash. To get Eclipse into the Streamline mode we want for profiling, do this:
{{{
    Window->Open Perspective->C/C++
}}}
Now you should have a panel on the left with a "Streamline" tab. Select it.

In either case, on the left is a panel where we configure the profiler.

First, let's make sure Streamline sees your phone. There's a test input box, with an "eye" icon. Click the eye, a dialog should appear which lists any profileable devices either connected by ADB, or over wifi. Hopefully your phone will show up.
If not, might need to forward the port with:
{{{
adb forward tcp:3768 tcp:3768
}}}
Once DS-5 sees your phone, you can profile. The red circle records.

Have a play, especially looking in the "Counter configuration" section (button beside the record button).

I had to study some videos to really get to grips with the tool:
https://www.youtube.com/results?search_query=ds-5+streamline



== Mali Graphics Debugger ==

'''Warning!''' This does not work on the BQ Aquaris e4.5 (aka "Krillin") - following these steps will make your phone unbootable!

An advanced API tracer is available for the Mali chipset. It is able to step through each draw call, and visualize what draws for each step, which is very useful for identifying expensive draw calls. It is available here:

http://malideveloper.arm.com/resources/tools/mali-graphics-debugger/

(Note there was some issue preventing v3.2 working with Ubuntu phone. Version 3.3 and greater work fine however - as did 2.1 and lower). You do not need to register an account to get access to the tool - see the "No thanks" link in the registration form.

There's a PDF manual inside the tarball that you download that is handy.


=== Installation on the Device ===

Extract tarball to your machine. We need to install a daemon & a GL interceptor library on the device. So change to a directory like this:
        ....../Mali_Graphics_Debugger_v4.0.0.169e7ab2_Linux_x64/target/android/arm
and copy the mgddaemon to device with
{{{
	adb push mgddaemon /home/phablet
	adb push armeabi-v7a/libGLES_mgd.so /home/phablet
}}}
Rest of the install steps are on the device:
{{{
	adb shell
}}}

The linux-side interceptor library doesn't play nice with the hybris layer, so need to install it on the Android side.
To get write access to it:
{{{
        mkdir -p temp
	sudo mount /var/lib/lxc/android/system.img temp && cd temp
}}}

You need to be root to work in here
{{{
	sudo bash
}}}

The Android partition is almost totally full, but we need space to copy in the interceptor library. One handy way is to delete some useless large files:
{{{
	rm ~/temp/res/images/*
}}}

Then copy the libGLES_mgd.so file to lib/egl
{{{
	cd lib/egl

	cp ~/libGLES_mgd.so .

	cp egl.cfg egl.cfg.bak

	echo "0 0 mgd" > egl.cfg

        echo "unity8" > processlist.cfg   
}}}
This last command is sadly useless due to a bug in v2.1. The Interceptor has no idea about process names that are non-android! (see "adb shell /system/bin/logcat | ag Interceptor"). So you get data about every application drawing with the GPU :(

Reboot device.


=== Using the Profiler Tool ===
First need to forward a port from the device to your machine: 
{{{
	adb forward tcp:5002 tcp:5002
}}}
Then start the mdgdaemon on the device.

Now on your machine, launch something like
{{{
	Mali_Graphics_Debugger_v2.1.0.8a389e5b_Linux_x64/gui/mgd
}}}
to bring up the profiler UI. Open a Connection to the device. Start an application on the device. You should see data appearing in your UI.