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 defined(__LP64__)
30#define PRIPTR "016" PRIx64
31typedef uint64_t word_t;
32#else
33#define PRIPTR "08" PRIx64
34typedef uint32_t word_t;
35#endif
36
37enum BacktraceUnwindErrorCode : uint32_t {
38  BACKTRACE_UNWIND_NO_ERROR,
39  // Something failed while trying to perform the setup to begin the unwind.
40  BACKTRACE_UNWIND_ERROR_SETUP_FAILED,
41  // There is no map information to use with the unwind.
42  BACKTRACE_UNWIND_ERROR_MAP_MISSING,
43  // An error occurred that indicates a programming error.
44  BACKTRACE_UNWIND_ERROR_INTERNAL,
45  // The thread to unwind has disappeared before the unwind can begin.
46  BACKTRACE_UNWIND_ERROR_THREAD_DOESNT_EXIST,
47  // The thread to unwind has not responded to a signal in a timely manner.
48  BACKTRACE_UNWIND_ERROR_THREAD_TIMEOUT,
49  // Attempt to do an unsupported operation.
50  BACKTRACE_UNWIND_ERROR_UNSUPPORTED_OPERATION,
51  // Attempt to do an offline unwind without a context.
52  BACKTRACE_UNWIND_ERROR_NO_CONTEXT,
53  // The count of frames exceed MAX_BACKTRACE_FRAMES.
54  BACKTRACE_UNWIND_ERROR_EXCEED_MAX_FRAMES_LIMIT,
55  // Failed to read memory.
56  BACKTRACE_UNWIND_ERROR_ACCESS_MEM_FAILED,
57  // Failed to read registers.
58  BACKTRACE_UNWIND_ERROR_ACCESS_REG_FAILED,
59  // Failed to find a function in debug sections.
60  BACKTRACE_UNWIND_ERROR_FIND_PROC_INFO_FAILED,
61  // Failed to execute dwarf instructions in debug sections.
62  BACKTRACE_UNWIND_ERROR_EXECUTE_DWARF_INSTRUCTION_FAILED,
63  // Unwind information is incorrect.
64  BACKTRACE_UNWIND_ERROR_UNWIND_INFO,
65  // Unwind information stopped due to sp/pc repeating.
66  BACKTRACE_UNWIND_ERROR_REPEATED_FRAME,
67  // Unwind information stopped due to invalid elf.
68  BACKTRACE_UNWIND_ERROR_INVALID_ELF,
69};
70
71struct BacktraceUnwindError {
72  enum BacktraceUnwindErrorCode error_code;
73
74  union {
75    // for BACKTRACE_UNWIND_ERROR_ACCESS_MEM_FAILED
76    uint64_t addr;
77    // for BACKTRACE_UNWIND_ERROR_ACCESS_REG_FAILED
78    uint64_t regno;
79  } error_info;
80
81  BacktraceUnwindError() : error_code(BACKTRACE_UNWIND_NO_ERROR) {}
82};
83
84struct backtrace_frame_data_t {
85  size_t num;             // The current fame number.
86  uint64_t pc;            // The absolute pc.
87  uint64_t rel_pc;        // The relative pc.
88  uint64_t sp;            // The top of the stack.
89  size_t stack_size;      // The size of the stack, zero indicate an unknown stack size.
90  backtrace_map_t map;    // The map associated with the given pc.
91  std::string func_name;  // The function name associated with this pc, NULL if not found.
92  uint64_t func_offset;  // pc relative to the start of the function, only valid if func_name is not
93                         // NULL.
94};
95
96struct backtrace_stackinfo_t {
97  uint64_t start;
98  uint64_t end;
99  const uint8_t* data;
100};
101
102namespace unwindstack {
103class Regs;
104}
105
106class Backtrace {
107 public:
108  enum ArchEnum : uint8_t {
109    ARCH_ARM,
110    ARCH_ARM64,
111    ARCH_X86,
112    ARCH_X86_64,
113  };
114
115  static void SetGlobalElfCache(bool enable);
116
117  // Create the correct Backtrace object based on what is to be unwound.
118  // If pid < 0 or equals the current pid, then the Backtrace object
119  // corresponds to the current process.
120  // If pid < 0 or equals the current pid and tid >= 0, then the Backtrace
121  // object corresponds to a thread in the current process.
122  // If pid >= 0 and tid < 0, then the Backtrace object corresponds to a
123  // different process.
124  // Tracing a thread in a different process is not supported.
125  // If map is NULL, then create the map and manage it internally.
126  // If map is not NULL, the map is still owned by the caller.
127  static Backtrace* Create(pid_t pid, pid_t tid, BacktraceMap* map = nullptr);
128
129  virtual ~Backtrace();
130
131  // Get the current stack trace and store in the backtrace_ structure.
132  virtual bool Unwind(size_t num_ignore_frames, void* context = nullptr) = 0;
133
134  static bool Unwind(unwindstack::Regs* regs, BacktraceMap* back_map,
135                     std::vector<backtrace_frame_data_t>* frames, size_t num_ignore_frames,
136                     std::vector<std::string>* skip_names, BacktraceUnwindError* error = nullptr);
137
138  // Get the function name and offset into the function given the pc.
139  // If the string is empty, then no valid function name was found,
140  // or the pc is not in any valid map.
141  virtual std::string GetFunctionName(uint64_t pc, uint64_t* offset,
142                                      const backtrace_map_t* map = nullptr);
143
144  // Fill in the map data associated with the given pc.
145  virtual void FillInMap(uint64_t pc, backtrace_map_t* map);
146
147  // Read the data at a specific address.
148  virtual bool ReadWord(uint64_t ptr, word_t* out_value) = 0;
149
150  // Read arbitrary data from a specific address. If a read request would
151  // span from one map to another, this call only reads up until the end
152  // of the current map.
153  // Returns the total number of bytes actually read.
154  virtual size_t Read(uint64_t addr, uint8_t* buffer, size_t bytes) = 0;
155
156  // Create a string representing the formatted line of backtrace information
157  // for a single frame.
158  virtual std::string FormatFrameData(size_t frame_num);
159  static std::string FormatFrameData(const backtrace_frame_data_t* frame);
160
161  pid_t Pid() const { return pid_; }
162  pid_t Tid() const { return tid_; }
163  size_t NumFrames() const { return frames_.size(); }
164
165  const backtrace_frame_data_t* GetFrame(size_t frame_num) {
166    if (frame_num >= frames_.size()) {
167      return nullptr;
168    }
169    return &frames_[frame_num];
170  }
171
172  typedef std::vector<backtrace_frame_data_t>::iterator iterator;
173  iterator begin() { return frames_.begin(); }
174  iterator end() { return frames_.end(); }
175
176  typedef std::vector<backtrace_frame_data_t>::const_iterator const_iterator;
177  const_iterator begin() const { return frames_.begin(); }
178  const_iterator end() const { return frames_.end(); }
179
180  BacktraceMap* GetMap() { return map_; }
181
182  BacktraceUnwindError GetError() { return error_; }
183
184  std::string GetErrorString(BacktraceUnwindError error);
185
186  // Set whether to skip frames in libbacktrace/libunwindstack when doing a local unwind.
187  void SetSkipFrames(bool skip_frames) { skip_frames_ = skip_frames; }
188
189 protected:
190  Backtrace(pid_t pid, pid_t tid, BacktraceMap* map);
191
192  // The name returned is not demangled, GetFunctionName() takes care of
193  // demangling the name.
194  virtual std::string GetFunctionNameRaw(uint64_t pc, uint64_t* offset) = 0;
195
196  virtual bool VerifyReadWordArgs(uint64_t ptr, word_t* out_value);
197
198  bool BuildMap();
199
200  pid_t pid_;
201  pid_t tid_;
202
203  BacktraceMap* map_;
204  bool map_shared_;
205
206  std::vector<backtrace_frame_data_t> frames_;
207
208  // Skip frames in libbacktrace/libunwindstack when doing a local unwind.
209  bool skip_frames_ = true;
210
211  BacktraceUnwindError error_;
212};
213
214#endif // _BACKTRACE_BACKTRACE_H
215