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 23extern "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 */ 34typedef 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 */ 43typedef 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 */ 58ssize_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 */ 67ssize_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 */ 75ssize_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 */ 83void 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 */ 91void 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 */ 98void free_backtrace_symbols(backtrace_symbol_t* backtrace_symbols, size_t frames); 99 100enum { 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 */ 108void 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