1 /* 2 * Copyright (C) 2013 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 #ifndef _BACKTRACE_BACKTRACE_H 18 #define _BACKTRACE_BACKTRACE_H 19 20 #include <inttypes.h> 21 #include <stdint.h> 22 23 #include <string> 24 #include <vector> 25 26 #include <backtrace/backtrace_constants.h> 27 #include <backtrace/BacktraceMap.h> 28 29 #if __LP64__ 30 #define PRIPTR "016" PRIxPTR 31 typedef uint64_t word_t; 32 #else 33 #define PRIPTR "08" PRIxPTR 34 typedef uint32_t word_t; 35 #endif 36 37 struct backtrace_frame_data_t { 38 size_t num; // The current fame number. 39 uintptr_t pc; // The absolute pc. 40 uintptr_t sp; // The top of the stack. 41 size_t stack_size; // The size of the stack, zero indicate an unknown stack size. 42 backtrace_map_t map; // The map associated with the given pc. 43 std::string func_name; // The function name associated with this pc, NULL if not found. 44 uintptr_t func_offset; // pc relative to the start of the function, only valid if func_name is not NULL. 45 }; 46 47 #if defined(__APPLE__) 48 struct __darwin_ucontext; 49 typedef __darwin_ucontext ucontext_t; 50 #else 51 struct ucontext; 52 typedef ucontext ucontext_t; 53 #endif 54 55 class Backtrace { 56 public: 57 // Create the correct Backtrace object based on what is to be unwound. 58 // If pid < 0 or equals the current pid, then the Backtrace object 59 // corresponds to the current process. 60 // If pid < 0 or equals the current pid and tid >= 0, then the Backtrace 61 // object corresponds to a thread in the current process. 62 // If pid >= 0 and tid < 0, then the Backtrace object corresponds to a 63 // different process. 64 // Tracing a thread in a different process is not supported. 65 // If map is NULL, then create the map and manage it internally. 66 // If map is not NULL, the map is still owned by the caller. 67 static Backtrace* Create(pid_t pid, pid_t tid, BacktraceMap* map = NULL); 68 69 virtual ~Backtrace(); 70 71 // Get the current stack trace and store in the backtrace_ structure. 72 virtual bool Unwind(size_t num_ignore_frames, ucontext_t* context = NULL) = 0; 73 74 // Get the function name and offset into the function given the pc. 75 // If the string is empty, then no valid function name was found. 76 virtual std::string GetFunctionName(uintptr_t pc, uintptr_t* offset); 77 78 // Fill in the map data associated with the given pc. 79 virtual void FillInMap(uintptr_t pc, backtrace_map_t* map); 80 81 // Read the data at a specific address. 82 virtual bool ReadWord(uintptr_t ptr, word_t* out_value) = 0; 83 84 // Read arbitrary data from a specific address. If a read request would 85 // span from one map to another, this call only reads up until the end 86 // of the current map. 87 // Returns the total number of bytes actually read. 88 virtual size_t Read(uintptr_t addr, uint8_t* buffer, size_t bytes) = 0; 89 90 // Create a string representing the formatted line of backtrace information 91 // for a single frame. 92 virtual std::string FormatFrameData(size_t frame_num); 93 virtual std::string FormatFrameData(const backtrace_frame_data_t* frame); 94 Pid()95 pid_t Pid() const { return pid_; } Tid()96 pid_t Tid() const { return tid_; } NumFrames()97 size_t NumFrames() const { return frames_.size(); } 98 GetFrame(size_t frame_num)99 const backtrace_frame_data_t* GetFrame(size_t frame_num) { 100 if (frame_num >= frames_.size()) { 101 return NULL; 102 } 103 return &frames_[frame_num]; 104 } 105 106 typedef std::vector<backtrace_frame_data_t>::iterator iterator; begin()107 iterator begin() { return frames_.begin(); } end()108 iterator end() { return frames_.end(); } 109 110 typedef std::vector<backtrace_frame_data_t>::const_iterator const_iterator; begin()111 const_iterator begin() const { return frames_.begin(); } end()112 const_iterator end() const { return frames_.end(); } 113 GetMap()114 BacktraceMap* GetMap() { return map_; } 115 116 protected: 117 Backtrace(pid_t pid, pid_t tid, BacktraceMap* map); 118 119 // The name returned is not demangled, GetFunctionName() takes care of 120 // demangling the name. 121 virtual std::string GetFunctionNameRaw(uintptr_t pc, uintptr_t* offset) = 0; 122 123 virtual bool VerifyReadWordArgs(uintptr_t ptr, word_t* out_value); 124 125 bool BuildMap(); 126 127 pid_t pid_; 128 pid_t tid_; 129 130 BacktraceMap* map_; 131 bool map_shared_; 132 133 std::vector<backtrace_frame_data_t> frames_; 134 }; 135 136 #endif // _BACKTRACE_BACKTRACE_H 137