2
* Copyright (C) 2013 The Android Open Source Project
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
8
* http://www.apache.org/licenses/LICENSE-2.0
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.
17
#ifndef _BACKTRACE_BACKTRACE_H
18
#define _BACKTRACE_BACKTRACE_H
26
#include <backtrace/backtrace_constants.h>
27
#include <backtrace/BacktraceMap.h>
30
#define PRIPTR "016" PRIx64
31
typedef uint64_t word_t;
33
#define PRIPTR "08" PRIx64
34
typedef uint32_t word_t;
37
enum 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,
71
struct BacktraceUnwindError {
72
enum BacktraceUnwindErrorCode error_code;
75
// for BACKTRACE_UNWIND_ERROR_ACCESS_MEM_FAILED
77
// for BACKTRACE_UNWIND_ERROR_ACCESS_REG_FAILED
81
BacktraceUnwindError() : error_code(BACKTRACE_UNWIND_NO_ERROR) {}
84
struct 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
96
struct backtrace_stackinfo_t {
102
namespace unwindstack {
108
enum ArchEnum : uint8_t {
115
static void SetGlobalElfCache(bool enable);
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);
129
virtual ~Backtrace();
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;
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);
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);
144
// Fill in the map data associated with the given pc.
145
virtual void FillInMap(uint64_t pc, backtrace_map_t* map);
147
// Read the data at a specific address.
148
virtual bool ReadWord(uint64_t ptr, word_t* out_value) = 0;
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;
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);
161
pid_t Pid() const { return pid_; }
162
pid_t Tid() const { return tid_; }
163
size_t NumFrames() const { return frames_.size(); }
165
const backtrace_frame_data_t* GetFrame(size_t frame_num) {
166
if (frame_num >= frames_.size()) {
169
return &frames_[frame_num];
172
typedef std::vector<backtrace_frame_data_t>::iterator iterator;
173
iterator begin() { return frames_.begin(); }
174
iterator end() { return frames_.end(); }
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(); }
180
BacktraceMap* GetMap() { return map_; }
182
BacktraceUnwindError GetError() { return error_; }
184
std::string GetErrorString(BacktraceUnwindError error);
186
// Set whether to skip frames in libbacktrace/libunwindstack when doing a local unwind.
187
void SetSkipFrames(bool skip_frames) { skip_frames_ = skip_frames; }
190
Backtrace(pid_t pid, pid_t tid, BacktraceMap* map);
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;
196
virtual bool VerifyReadWordArgs(uint64_t ptr, word_t* out_value);
206
std::vector<backtrace_frame_data_t> frames_;
208
// Skip frames in libbacktrace/libunwindstack when doing a local unwind.
209
bool skip_frames_ = true;
211
BacktraceUnwindError error_;
214
#endif // _BACKTRACE_BACKTRACE_H