GPU Debugging on Android Devices

Here are some notes on getting the GPU/OpenGL ES debuggers working with devices.

NVidia’s Tegra tool seems the best (even has integrated mesh viewer). Qualcomm’s Adreno tool is also quite good. ARM’s MALI tool is difficult to set up (rooting), but covers the essentials. Intel’s GPA tool is a complete suite, but is only a system usage profiler for Android. Imagination’s PowerVR tools appear good, though I haven’t tested them yet (one tool requires rooting). Vivante provides no tools. Desktop tools not listed.

Before we start

Things you must do (all tools require it):

  1. Add adb.exe to the path. I.e. the Android SDK folder/platform-tools/ will do the trick.
  2. Confirm that your device is connected by doing an “adb devices” from any command prompt or shell.

If it’s not available, and you need a driver, you can hack Google’s USB driver to support your device.

  1. Open up AndroidSDKDir/extras/google/usb_driver/android_winusb.inf in a text editor.
  2. Note the “[Google.NTx86]” and “[Google.NTamd64]” sections. These are where you put stuff for 32bit Windows and 64bit Windows.
  3. Copy and make a new ADB definition for the device you are adding. Something like this:
  4. ;Samsung Galaxy Tab 3
    %SingleAdbInterface% = USB_Install, USB\VID_04E8&PID_6860
    %CompositeAdbInterface% = USB_Install, USB\VID_04E8&PID_6860&MI_03

    ;Lenovo K900
    %SingleAdbInterface% = USB_Install, USB\VID_17EF&PID_75B0
    %CompositeAdbInterface% = USB_Install, USB\VID_17EF&PID_75B0&MI_01

    ;ONDA VX610W
    %SingleAdbInterface% = USB_Install, USB\VID_18D1&PID_0003
    %CompositeAdbInterface% = USB_Install, USB\VID_18D1&PID_0003&MI_01

  5. VID’s and PID’s you get from the Windows Device Manager.
    1. From the Start Menu, Right click Computer and select Properties. Click Device Manager.
    2. Right Click on the ‘broken’ device that doesn’t have a driver, and click Properties.
    3. Click the Details Tab, then select Hardware IDs from the dropdown box.
    4. This is where you find your VID, PID, and MI. Copy those values in to a layout like shown above. If there’s extra data there, you can try it if you want, but what’s important (AFAIK) is the VID, PID, and MI.

    5. Save the file, and now update the driver to use this driver. You should now have a ADB Interface. To test, do an “adb devices” from a command prompt/shell.
  6. If a device is still not working, you may need to add the VID to your adb_usb.ini file. Either open the file (C:\Users\MyName\.android\adb_usb.ini) or do something like the following:
  7. Use the same VID found in the device manager. For example, 2836 is the Ouya’s VID.


Qualcomm Adreno Profiler

Both USB and WiFi debugging.

Download Adreno Profiler (not the SDK):…/gaming-graphics-optimization-adreno

Add the following line to your AndroidManifest.xml file:

If you don’t know where, put it somewhere near the bottom of the file.

This is optional (tool does it automatically), but for reference the following config flag must be set. From a shell do:

Which enables profiling.

FYI Adreno devices only supports GPU debugging if is available.

Do the following to confirm whether the file is on the device.

For me, it’s available on my 2nd gen Nexus 7.

NVidia PerfHud ES Tegra

Supports ADB USB and WiFi debugging.

Download the Tegra Android Development Pack here:

It’s a download installer, so you can deselect the parts you do not want.

Like Adreno, be sure to add the following line to your AndroidManifest.xml file:

The next command has to be run every time you boot/reboot your Android device:

NVidia’s tool, unfortunately, doesn’t do this automatically for you.

Add the following code to your app, somewhere before you create your OpenGL ES context.

The Code above requires the EGL headers in addition to the OpenGL ES headers.

Tested on an original Nexus 7. Haven’t tried the Ouya yet.

ARM MALI Graphics Debugger

NOTE: Requires rooted device.

Supports ADB USB and WiFi Debugging. Tricky setup.

Download is here:

Setup instructions for Android are hidden inside the install folder.

First, browse to the folder above.

Next mount the system folder like so:

Now do the following.

NOTE: My OS lacks a “cp” command. You can alternatively use “cat”. i.e. “cat mgddaemon > /system/bin/mgddaemon”. Don’t forget to redirect!

This installs the daemon and alternative that captures GLES messages (forwarding them to the daemon).

The daemon has one more config option, a file “/system/lib/egl/processlist.cfg”. If you put the name of your app in that file (i.e. if using stock SDL2), then that will the only process traced. Otherwise omitting the file will cause the daemon and library to trace all running GLES apps (which can confuse the debugger).

Shut down all instances of your app, then decide if you want a USB or WiFi connection.

For USB, do the following:

This will make the IP you enter (i.e. localhost) on port 5002.

For WiFi, you’re already ready. Just lookup the devices IP address in either Settings->Networking or About.

Finally, start the daemon.

And you should now be able to punch in the IP address (either the device or localhost) in to the Mali Graphics Debugger App.

Tested on an obscure Chinese tablet called the ONDA VX6010W (Allwinner A10 SOC) running Android 4.1. I also have a GameStick, but I haven’t tried that yet (didn’t want to root it).

To disable the capture library, copy your backup (egl.cfg.bak) to “egl.cfg”.

You might want to keep a copy of the mgd version around, for ease.

Another tip: I made a typo in one of my filenames (egl.cgf). Running the daemon will allow the Mali Graphics Debugger to connect to the device, but if “egl.cfg” isn’t the correct file (the mgd version) then you will get no trace data.

Imagination (PowerVR) PVRTrace and PVRTune

NOTE: PVRTrace requires a rooted device.

Supports ADB USB and WiFi debugging (depending on tool).

Download here, as part of the PowerVR SDK.

Have only done some initial tests with this. As it turns out, none of my PowerVR GPU devices are working with my SDL2 code (both ARM and x86 CPUs), so I can’t really verify if this is working yet (well I can, but I don’t want to).

Intel Graphics Performance Analyzer (GPA) for Android

Supports ADB USB debugging.

Download is here:

Like others, be sure to add the following line to your AndroidManifest.xml file:

After that, Intel GPA System Analyzer will just work. This is a profiler tool with realtime usage graphs.

Unfortunately, this is the only tool in the Intel GPA suite supported by Android.

Tested on a Lenovo K900, and a Samsung Galaxy Tab 3.

OpenGL Extension GL_KHR_debug

This is an interesting extension available on certain GPUs (MALI 600 series GPUs, all OpenGL 4.3+ drivers). It provides far better debug logging of errors and things in OpenGL and OpenGL ES.

Some useful links:…/easier-opengl-es-debugging-on-arm-mali-gpus-with-gl_khr_debug/

The original extension, available on AMD GPUs.