bbbb1e7588e43a3dddf902b7905c779fb853f476
[folly.git] / folly / experimental / symbolizer / Symbolizer.h
1 /*
2  * Copyright 2016 Facebook, Inc.
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 #pragma once
18
19 #include <array>
20 #include <cstdint>
21 #include <memory>
22 #include <string>
23
24 #include <folly/FBString.h>
25 #include <folly/Range.h>
26 #include <folly/String.h>
27 #include <folly/io/IOBuf.h>
28 #include <folly/experimental/symbolizer/Elf.h>
29 #include <folly/experimental/symbolizer/ElfCache.h>
30 #include <folly/experimental/symbolizer/Dwarf.h>
31 #include <folly/experimental/symbolizer/StackTrace.h>
32
33 namespace folly {
34 namespace symbolizer {
35
36 class Symbolizer;
37
38 /**
39  * Frame information: symbol name and location.
40  */
41 struct SymbolizedFrame {
42   SymbolizedFrame() { }
43
44   void set(const std::shared_ptr<ElfFile>& file, uintptr_t address);
45   void clear() { *this = SymbolizedFrame(); }
46
47   bool found = false;
48   const char* name = nullptr;
49   Dwarf::LocationInfo location;
50
51   /**
52    * Demangle the name and return it. Not async-signal-safe; allocates memory.
53    */
54   fbstring demangledName() const {
55     return name ? demangle(name) : fbstring();
56   }
57  private:
58   std::shared_ptr<ElfFile> file_;
59 };
60
61 template <size_t N>
62 struct FrameArray {
63   FrameArray() { }
64
65   size_t frameCount = 0;
66   uintptr_t addresses[N];
67   SymbolizedFrame frames[N];
68 };
69
70 /**
71  * Get stack trace into a given FrameArray, return true on success (and
72  * set frameCount to the actual frame count, which may be > N) and false
73  * on failure.
74  */
75 namespace detail {
76 template <size_t N>
77 bool fixFrameArray(FrameArray<N>& fa, ssize_t n) {
78   if (n != -1) {
79     fa.frameCount = n;
80     for (size_t i = 0; i < fa.frameCount; ++i) {
81       fa.frames[i].found = false;
82     }
83     return true;
84   } else {
85     fa.frameCount = 0;
86     return false;
87   }
88 }
89 }  // namespace detail
90
91 // Always inline these functions; they don't do much, and unittests rely
92 // on them never showing up in a stack trace.
93 template <size_t N>
94 FOLLY_ALWAYS_INLINE bool getStackTrace(FrameArray<N>& fa);
95
96 template <size_t N>
97 inline bool getStackTrace(FrameArray<N>& fa) {
98   return detail::fixFrameArray(fa, getStackTrace(fa.addresses, N));
99 }
100 template <size_t N>
101 FOLLY_ALWAYS_INLINE bool getStackTraceSafe(FrameArray<N>& fa);
102
103 template <size_t N>
104 inline bool getStackTraceSafe(FrameArray<N>& fa) {
105   return detail::fixFrameArray(fa, getStackTraceSafe(fa.addresses, N));
106 }
107
108 class Symbolizer {
109  public:
110   explicit Symbolizer(ElfCacheBase* cache = nullptr);
111
112   /**
113    * Symbolize given addresses.
114    */
115   void symbolize(const uintptr_t* addresses,
116                  SymbolizedFrame* frames,
117                  size_t frameCount);
118
119   template <size_t N>
120   void symbolize(FrameArray<N>& fa) {
121     symbolize(fa.addresses, fa.frames, fa.frameCount);
122   }
123
124   /**
125    * Shortcut to symbolize one address.
126    */
127   bool symbolize(uintptr_t address, SymbolizedFrame& frame) {
128     symbolize(&address, &frame, 1);
129     return frame.found;
130   }
131
132  private:
133   ElfCacheBase* const cache_ = nullptr;
134 };
135
136 /**
137  * Format one address in the way it's usually printed by SymbolizePrinter.
138  * Async-signal-safe.
139  */
140 class AddressFormatter {
141  public:
142   AddressFormatter();
143
144   /**
145    * Format the address. Returns an internal buffer.
146    */
147   StringPiece format(uintptr_t address);
148
149  private:
150   static constexpr char bufTemplate[] = "    @ 0000000000000000";
151   char buf_[sizeof(bufTemplate)];
152 };
153
154 /**
155  * Print a list of symbolized addresses. Base class.
156  */
157 class SymbolizePrinter {
158  public:
159   /**
160    * Print one address, no ending newline.
161    */
162   void print(uintptr_t address, const SymbolizedFrame& frame);
163
164   /**
165    * Print one address with ending newline.
166    */
167   void println(uintptr_t address, const SymbolizedFrame& frame);
168
169   /**
170    * Print multiple addresses on separate lines.
171    */
172   void println(const uintptr_t* addresses,
173                const SymbolizedFrame* frames,
174                size_t frameCount);
175
176   /**
177    * Print a string, no endling newline.
178    */
179   void print(StringPiece sp) { doPrint(sp); }
180
181   /**
182    * Print multiple addresses on separate lines, skipping the first
183    * skip addresses.
184    */
185   template <size_t N>
186   void println(const FrameArray<N>& fa, size_t skip=0) {
187     if (skip < fa.frameCount) {
188       println(fa.addresses + skip, fa.frames + skip, fa.frameCount - skip);
189     }
190   }
191
192   virtual ~SymbolizePrinter() { }
193
194   enum Options {
195     // Skip file and line information
196     NO_FILE_AND_LINE = 1 << 0,
197
198     // As terse as it gets: function name if found, address otherwise
199     TERSE = 1 << 1,
200
201     // Always colorize output (ANSI escape code)
202     COLOR = 1 << 2,
203
204     // Colorize output only if output is printed to a TTY (ANSI escape code)
205     COLOR_IF_TTY = 1 << 3,
206
207     // Skip frame address information
208     NO_FRAME_ADDRESS = 1 << 4,
209   };
210
211   // NOTE: enum values used as indexes in kColorMap.
212   enum Color { DEFAULT, RED, GREEN, YELLOW, BLUE, CYAN, WHITE, PURPLE, NUM };
213   void color(Color c);
214
215  protected:
216   explicit SymbolizePrinter(int options, bool isTty = false)
217     : options_(options),
218       isTty_(isTty) {
219   }
220
221   const int options_;
222   const bool isTty_;
223
224  private:
225   void printTerse(uintptr_t address, const SymbolizedFrame& frame);
226   virtual void doPrint(StringPiece sp) = 0;
227
228   static constexpr std::array<const char*, Color::NUM> kColorMap = {{
229       "\x1B[0m",
230       "\x1B[31m",
231       "\x1B[32m",
232       "\x1B[33m",
233       "\x1B[34m",
234       "\x1B[36m",
235       "\x1B[37m",
236       "\x1B[35m",
237   }};
238 };
239
240 /**
241  * Print a list of symbolized addresses to a stream.
242  * Not reentrant. Do not use from signal handling code.
243  */
244 class OStreamSymbolizePrinter : public SymbolizePrinter {
245  public:
246   explicit OStreamSymbolizePrinter(std::ostream& out, int options=0);
247  private:
248   void doPrint(StringPiece sp) override;
249   std::ostream& out_;
250 };
251
252 /**
253  * Print a list of symbolized addresses to a file descriptor.
254  * Ignores errors. Async-signal-safe.
255  */
256 class FDSymbolizePrinter : public SymbolizePrinter {
257  public:
258   explicit FDSymbolizePrinter(int fd, int options=0,
259                               size_t bufferSize=0);
260   ~FDSymbolizePrinter();
261   void flush();
262  private:
263   void doPrint(StringPiece sp) override;
264
265   const int fd_;
266   std::unique_ptr<IOBuf> buffer_;
267 };
268
269 /**
270  * Print a list of symbolized addresses to a FILE*.
271  * Ignores errors. Not reentrant. Do not use from signal handling code.
272  */
273 class FILESymbolizePrinter : public SymbolizePrinter {
274  public:
275   explicit FILESymbolizePrinter(FILE* file, int options=0);
276  private:
277   void doPrint(StringPiece sp) override;
278   FILE* const file_ = nullptr;
279 };
280
281 /**
282  * Print a list of symbolized addresses to a std::string.
283  * Not reentrant. Do not use from signal handling code.
284  */
285 class StringSymbolizePrinter : public SymbolizePrinter {
286  public:
287   explicit StringSymbolizePrinter(int options=0) : SymbolizePrinter(options) { }
288
289   std::string str() const { return buf_.toStdString(); }
290   const fbstring& fbstr() const { return buf_; }
291   fbstring moveFbString() { return std::move(buf_); }
292
293  private:
294   void doPrint(StringPiece sp) override;
295   fbstring buf_;
296 };
297
298 }  // namespace symbolizer
299 }  // namespace folly