Jeff Brown | 501edd2 | 2011-10-19 20:35:35 -0700 | [diff] [blame] | 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 { |
Jeff Brown | 19b39f3 | 2011-11-21 21:10:00 -0800 | [diff] [blame] | 44 | uintptr_t relative_pc; /* relative frame PC offset from the start of the library, |
Jeff Brown | 501edd2 | 2011-10-19 20:35:35 -0700 | [diff] [blame] | 45 | or the absolute PC if the library is unknown */ |
Jeff Brown | 19b39f3 | 2011-11-21 21:10:00 -0800 | [diff] [blame] | 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 */ |
Jeff Brown | f0c5872 | 2011-11-03 17:58:44 -0700 | [diff] [blame] | 48 | char* map_name; /* executable or library name, or NULL if unknown */ |
Jeff Brown | 19b39f3 | 2011-11-21 21:10:00 -0800 | [diff] [blame] | 49 | char* symbol_name; /* symbol name, or NULL if unknown */ |
Jeff Brown | 501edd2 | 2011-10-19 20:35:35 -0700 | [diff] [blame] | 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 | |
Jeff Brown | 19b39f3 | 2011-11-21 21:10:00 -0800 | [diff] [blame] | 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 | |
Jeff Brown | 501edd2 | 2011-10-19 20:35:35 -0700 | [diff] [blame] | 111 | #ifdef __cplusplus |
| 112 | } |
| 113 | #endif |
| 114 | |
| 115 | #endif // _CORKSCREW_BACKTRACE_H |