Android ndk-stack tool

Android ndk-stack tool
----------------------

Introduction:
-------------

This document describes the 'ndk-stack' tool that is distributed
The Android NDK, since release r6.

Overview:
---------

'Ndk-stack' is a simple tool that allows you to filter stack traces as they
Appear in the output of 'adb logcat' and replace any address inside a shared
Library with the corresponding <source-file>: <line-number> values.

In a nutshell, it will translate something like:

I/DEBUG (31 ): **************************************** ********
I/DEBUG (31): Build fingerprint: 'generic/google_sdk/generic/: 2.2/FRF91/43546: eng/test-keys'
I/DEBUG (31): pid: 351, tid: 351% gt; % gt;/data/local/ndk-tests/crasher <
I/DEBUG (31): signal 11 (SIGSEGV), fault addr 0d9f00d8
I/DEBUG (31): r0 1_af88 r1 1_a008 r2 baadf00d r3 0d9f00d8
I/DEBUG (31): r4 00000004 r5 g0a008 r6 g0af88 r7 00013c44
I/DEBUG (31): r8 00000000 r9 00000000 10 00000000 fp 00000000
I/DEBUG (31): ip Route 959c sp be956cc8 lr 00008403 pc route 841e cpsr 60000030
I/DEBUG (31): #00 pc route 841e/data/local/ndk-tests/crasher
I/DEBUG (31): #01 pc route 83fe/data/local/ndk-tests/crasher
I/DEBUG (31): #02 pc route 83f6/data/local/ndk-tests/crasher
I/DEBUG (31): #03 pc 000191ac/system/lib/libc. so
I/DEBUG (31): #04 pc route 83ea/data/local/ndk-tests/crasher
I/DEBUG (31): #05 pc 00008458/data/local/ndk-tests/crasher
I/DEBUG (31): #06 pc release dashboard/system/lib/libc. so
I/DEBUG (31 ):

Into the more readable output:

* ******** Crash dump :**********
Build fingerprint: 'generic/google_sdk/generic/: 2.2/FRF91/43546: eng/test-keys'
Pid: 351, tid: 351 >>>/data/local/ndk-tests/crasher <
Signal 11 (SIGSEGV), fault addr 0d9f00d8
Stack frame #00 pc route 841e/data/local/ndk-tests/crasher: Routine zoo in/tmp/foo/crasher/jni/zoo. c: 13
Stack frame #01 pc route 83fe/data/local/ndk-tests/crasher: Routine bar in/tmp/foo/crasher/jni/bar. c: 5
Stack frame #02 pc route 83f6/data/local/ndk-tests/crasher: Routine my_comparison in/tmp/foo/crasher/jni/foo. c: 9
Stack frame #03 pc 000191ac/system/lib/libc. so
Stack frame #04 pc route 83ea/data/local/ndk-tests/crasher: Routine foo in/tmp/foo/crasher/jni/foo. c: 14
Stack frame #05 pc 00008458/data/local/ndk-tests/crasher: Routine main in/tmp/foo/crasher/jni/main. c: 19
Stack frame #06 pc release dashboard/system/lib/libc. so

Usage:
------

To do this, you will first need a directory containing symbolic versions of your
Application's shared libraries. If you use the NDK build system (I. e. ndk-build ),
Then these are always located under $ PROJECT_PATH/obj/local/<AB>, where
<AB> stands for your device's ABI (I. e. 'armeabi 'by default ).

You can feed the logcat text either as direct input to the program, e.g .:

Adb logcat | $ NDK/ndk-stack-sym $ PROJECT_PATH/obj/local/armeabi

Or you can use the-dump option to specify the logcat as an input file, e.g .:

Adb logcat>/tmp/foo.txt
$ NDK/ndk-stack-sym $ PROJECT_PATH/obj/local/armeabi-dump foo.txt

** IMPORTANT **:

The tool looks for the initial line containing starts in the logcat output,
I. e. something that looks like:

**************************************** ********

When copy/pasting traces, don't forget this line from the traces, or
Ndk-stack won't work correctly.

TODO:
-----

A future version of 'ndk-stack' will try to launch 'adb logcat' and select
Library path automatically. For now, you'll have to do these steps manually.

As of now, ndk-stack doesn't handle libraries that don't have debug information
In them. It may be useful to try to detect the nearest function entry point
A given PC address (e.g. as in the libc. so example above ).
 

From androidme