1Android ndk-stack tool 2==== 3 4Introduction: 5------------- 6 7This document describes the 'ndk-stack' tool that is distributed with 8the Android NDK, since release r6. 9 10Overview: 11--------- 12 13'ndk-stack' is a simple tool that allows you to filter stack traces as they 14appear in the output of '`adb logcat`' and replace any address inside a shared 15library with the corresponding <source-file>:<line-number> values. 16 17In a nutshell, it will translate something like: 18 19 I/DEBUG ( 31): *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 20 I/DEBUG ( 31): Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys' 21 I/DEBUG ( 31): pid: 351, tid: 351 %gt;%gt;%gt; /data/local/ndk-tests/crasher <<< 22 I/DEBUG ( 31): signal 11 (SIGSEGV), fault addr 0d9f00d8 23 I/DEBUG ( 31): r0 0000af88 r1 0000a008 r2 baadf00d r3 0d9f00d8 24 I/DEBUG ( 31): r4 00000004 r5 0000a008 r6 0000af88 r7 00013c44 25 I/DEBUG ( 31): r8 00000000 r9 00000000 10 00000000 fp 00000000 26 I/DEBUG ( 31): ip 0000959c sp be956cc8 lr 00008403 pc 0000841e cpsr 60000030 27 I/DEBUG ( 31): #00 pc 0000841e /data/local/ndk-tests/crasher 28 I/DEBUG ( 31): #01 pc 000083fe /data/local/ndk-tests/crasher 29 I/DEBUG ( 31): #02 pc 000083f6 /data/local/ndk-tests/crasher 30 I/DEBUG ( 31): #03 pc 000191ac /system/lib/libc.so 31 I/DEBUG ( 31): #04 pc 000083ea /data/local/ndk-tests/crasher 32 I/DEBUG ( 31): #05 pc 00008458 /data/local/ndk-tests/crasher 33 I/DEBUG ( 31): #06 pc 0000d362 /system/lib/libc.so 34 I/DEBUG ( 31): 35 36Into the more readable output: 37 38 ********** Crash dump: ********** 39 Build fingerprint: 'generic/google_sdk/generic/:2.2/FRF91/43546:eng/test-keys' 40 pid: 351, tid: 351 >>> /data/local/ndk-tests/crasher <<< 41 signal 11 (SIGSEGV), fault addr 0d9f00d8 42 Stack frame #00 pc 0000841e /data/local/ndk-tests/crasher : Routine zoo in /tmp/foo/crasher/jni/zoo.c:13 43 Stack frame #01 pc 000083fe /data/local/ndk-tests/crasher : Routine bar in /tmp/foo/crasher/jni/bar.c:5 44 Stack frame #02 pc 000083f6 /data/local/ndk-tests/crasher : Routine my_comparison in /tmp/foo/crasher/jni/foo.c:9 45 Stack frame #03 pc 000191ac /system/lib/libc.so 46 Stack frame #04 pc 000083ea /data/local/ndk-tests/crasher : Routine foo in /tmp/foo/crasher/jni/foo.c:14 47 Stack frame #05 pc 00008458 /data/local/ndk-tests/crasher : Routine main in /tmp/foo/crasher/jni/main.c:19 48 Stack frame #06 pc 0000d362 /system/lib/libc.so 49 50Usage: 51------ 52 53To do this, you will first need a directory containing symbolic versions of your 54application's shared libraries. If you use the NDK build system (i.e. ndk-build), 55then these are always located under `$PROJECT_PATH/obj/local/<abi>`, where 56`<abi>` stands for your device's ABI (i.e. '`armeabi`' by default). 57 58You can feed the logcat text either as direct input to the program, e.g.: 59 60 adb logcat | $NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi 61 62Or you can use the -dump option to specify the logcat as an input file, e.g.: 63 64 adb logcat > /tmp/foo.txt 65 $NDK/ndk-stack -sym $PROJECT_PATH/obj/local/armeabi -dump foo.txt 66 67 68** IMPORTANT **: 69 70> The tool looks for the initial line containing starts in the logcat output, 71 i.e. something that looks like: 72 73 *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** 74 75When copy/pasting traces, don't forget this line from the traces, or 76ndk-stack won't work correctly. 77 78TODO: 79----- 80 81A future version of '`ndk-stack`' will try to launch '`adb logcat`' and select the 82library path automatically. For now, you'll have to do these steps manually. 83 84As of now, ndk-stack doesn't handle libraries that don't have debug information 85in them. It may be useful to try to detect the nearest function entry point to 86a given PC address (e.g. as in the libc.so example above). 87