1 /* 2 * Copyright (C) 2011 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 /* A stack unwinder. */ 18 19 #ifndef _CORKSCREW_BACKTRACE_H 20 #define _CORKSCREW_BACKTRACE_H 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 #include <sys/types.h> 27 #include <corkscrew/ptrace.h> 28 #include <corkscrew/map_info.h> 29 #include <corkscrew/symbol_table.h> 30 31 /* 32 * Describes a single frame of a backtrace. 33 */ 34 typedef struct { 35 uintptr_t absolute_pc; /* absolute PC offset */ 36 uintptr_t stack_top; /* top of stack for this frame */ 37 size_t stack_size; /* size of this stack frame */ 38 } backtrace_frame_t; 39 40 /* 41 * Describes the symbols associated with a backtrace frame. 42 */ 43 typedef struct { 44 uintptr_t relative_pc; /* relative frame PC offset from the start of the library, 45 or the absolute PC if the library is unknown */ 46 uintptr_t relative_symbol_addr; /* relative offset of the symbol from the start of the 47 library or 0 if the library is unknown */ 48 char* map_name; /* executable or library name, or NULL if unknown */ 49 char* symbol_name; /* symbol name, or NULL if unknown */ 50 char* demangled_name; /* demangled symbol name, or NULL if unknown */ 51 } backtrace_symbol_t; 52 53 /* 54 * Unwinds the call stack for the current thread of execution. 55 * Populates the backtrace array with the program counters from the call stack. 56 * Returns the number of frames collected, or -1 if an error occurred. 57 */ 58 ssize_t unwind_backtrace(backtrace_frame_t* backtrace, size_t ignore_depth, size_t max_depth); 59 60 /* 61 * Unwinds the call stack for a thread within this process. 62 * Populates the backtrace array with the program counters from the call stack. 63 * Returns the number of frames collected, or -1 if an error occurred. 64 * 65 * The task is briefly suspended while the backtrace is being collected. 66 */ 67 ssize_t unwind_backtrace_thread(pid_t tid, backtrace_frame_t* backtrace, 68 size_t ignore_depth, size_t max_depth); 69 70 /* 71 * Unwinds the call stack of a task within a remote process using ptrace(). 72 * Populates the backtrace array with the program counters from the call stack. 73 * Returns the number of frames collected, or -1 if an error occurred. 74 */ 75 ssize_t unwind_backtrace_ptrace(pid_t tid, const ptrace_context_t* context, 76 backtrace_frame_t* backtrace, size_t ignore_depth, size_t max_depth); 77 78 /* 79 * Gets the symbols for each frame of a backtrace. 80 * The symbols array must be big enough to hold one symbol record per frame. 81 * The symbols must later be freed using free_backtrace_symbols. 82 */ 83 void get_backtrace_symbols(const backtrace_frame_t* backtrace, size_t frames, 84 backtrace_symbol_t* backtrace_symbols); 85 86 /* 87 * Gets the symbols for each frame of a backtrace from a remote process. 88 * The symbols array must be big enough to hold one symbol record per frame. 89 * The symbols must later be freed using free_backtrace_symbols. 90 */ 91 void get_backtrace_symbols_ptrace(const ptrace_context_t* context, 92 const backtrace_frame_t* backtrace, size_t frames, 93 backtrace_symbol_t* backtrace_symbols); 94 95 /* 96 * Frees the storage associated with backtrace symbols. 97 */ 98 void free_backtrace_symbols(backtrace_symbol_t* backtrace_symbols, size_t frames); 99 100 enum { 101 // A hint for how big to make the line buffer for format_backtrace_line 102 MAX_BACKTRACE_LINE_LENGTH = 800, 103 }; 104 105 /** 106 * Formats a line from a backtrace as a zero-terminated string into the specified buffer. 107 */ 108 void format_backtrace_line(unsigned frameNumber, const backtrace_frame_t* frame, 109 const backtrace_symbol_t* symbol, char* buffer, size_t bufferSize); 110 111 #ifdef __cplusplus 112 } 113 #endif 114 115 #endif // _CORKSCREW_BACKTRACE_H 116