1 | // -*- mode: c++ -*- |
2 | |
3 | // Copyright (c) 2010 Google Inc. |
4 | // All rights reserved. |
5 | // |
6 | // Redistribution and use in source and binary forms, with or without |
7 | // modification, are permitted provided that the following conditions are |
8 | // met: |
9 | // |
10 | // * Redistributions of source code must retain the above copyright |
11 | // notice, this list of conditions and the following disclaimer. |
12 | // * Redistributions in binary form must reproduce the above |
13 | // copyright notice, this list of conditions and the following disclaimer |
14 | // in the documentation and/or other materials provided with the |
15 | // distribution. |
16 | // * Neither the name of Google Inc. nor the names of its |
17 | // contributors may be used to endorse or promote products derived from |
18 | // this software without specific prior written permission. |
19 | // |
20 | // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
21 | // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
22 | // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
23 | // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
24 | // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
25 | // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
26 | // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
27 | // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
28 | // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
29 | // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
30 | // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
31 | |
32 | // Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com> |
33 | |
34 | // Add DWARF debugging information to a Breakpad symbol file. This |
35 | // file defines the DwarfCUToModule class, which accepts parsed DWARF |
36 | // data and populates a google_breakpad::Module with the results; the |
37 | // Module can then write its contents as a Breakpad symbol file. |
38 | |
39 | #ifndef COMMON_LINUX_DWARF_CU_TO_MODULE_H__ |
40 | #define COMMON_LINUX_DWARF_CU_TO_MODULE_H__ |
41 | |
42 | #include <stdint.h> |
43 | |
44 | #include <string> |
45 | |
46 | #include "common/language.h" |
47 | #include "common/module.h" |
48 | #include "common/dwarf/dwarf2diehandler.h" |
49 | #include "common/dwarf/dwarf2reader.h" |
50 | #include "common/scoped_ptr.h" |
51 | #include "common/using_std_string.h" |
52 | |
53 | namespace google_breakpad { |
54 | |
55 | // Populate a google_breakpad::Module with DWARF debugging information. |
56 | // |
57 | // An instance of this class can be provided as a handler to a |
58 | // DIEDispatcher, which can in turn be a handler for a |
59 | // CompilationUnit DWARF parser. The handler uses the results |
60 | // of parsing to populate a google_breakpad::Module with source file, |
61 | // function, and source line information. |
62 | class DwarfCUToModule: public RootDIEHandler { |
63 | struct FilePrivate; |
64 | public: |
65 | // Information global to the DWARF-bearing file we are processing, |
66 | // for use by DwarfCUToModule. Each DwarfCUToModule instance deals |
67 | // with a single compilation unit within the file, but information |
68 | // global to the whole file is held here. The client is responsible |
69 | // for filling it in appropriately (except for the 'file_private' |
70 | // field, which the constructor and destructor take care of), and |
71 | // then providing it to the DwarfCUToModule instance for each |
72 | // compilation unit we process in that file. Set HANDLE_INTER_CU_REFS |
73 | // to true to handle debugging symbols with DW_FORM_ref_addr entries. |
74 | class FileContext { |
75 | public: |
76 | FileContext(const string& filename, |
77 | Module* module, |
78 | bool handle_inter_cu_refs); |
79 | ~FileContext(); |
80 | |
81 | // Add CONTENTS of size LENGTH to the section map as NAME. |
82 | void AddSectionToSectionMap(const string& name, |
83 | const uint8_t* contents, |
84 | uint64_t length); |
85 | |
86 | // Clear the section map for testing. |
87 | void ClearSectionMapForTest(); |
88 | |
89 | const SectionMap& section_map() const; |
90 | |
91 | private: |
92 | friend class DwarfCUToModule; |
93 | |
94 | // Clears all the Specifications if HANDLE_INTER_CU_REFS_ is false. |
95 | void ClearSpecifications(); |
96 | |
97 | // Given an OFFSET and a CU that starts at COMPILATION_UNIT_START, returns |
98 | // true if this is an inter-compilation unit reference that is not being |
99 | // handled. |
100 | bool IsUnhandledInterCUReference(uint64_t offset, |
101 | uint64_t compilation_unit_start) const; |
102 | |
103 | // The name of this file, for use in error messages. |
104 | const string filename_; |
105 | |
106 | // A map of this file's sections, used for finding other DWARF |
107 | // sections that the .debug_info section may refer to. |
108 | SectionMap section_map_; |
109 | |
110 | // The Module to which we're contributing definitions. |
111 | Module* module_; |
112 | |
113 | // True if we are handling references between compilation units. |
114 | const bool handle_inter_cu_refs_; |
115 | |
116 | // Inter-compilation unit data used internally by the handlers. |
117 | scoped_ptr<FilePrivate> file_private_; |
118 | }; |
119 | |
120 | // An abstract base class for handlers that handle DWARF range lists for |
121 | // DwarfCUToModule. |
122 | class RangesHandler { |
123 | public: |
124 | RangesHandler() { } |
125 | virtual ~RangesHandler() { } |
126 | |
127 | // Called when finishing a function to populate the function's ranges. |
128 | // The entries are read according to the form and data. |
129 | virtual bool ReadRanges( |
130 | enum DwarfForm form, uint64_t data, |
131 | RangeListReader::CURangesInfo* cu_info, |
132 | vector<Module::Range>* ranges) = 0; |
133 | }; |
134 | |
135 | // An abstract base class for handlers that handle DWARF line data |
136 | // for DwarfCUToModule. DwarfCUToModule could certainly just use |
137 | // LineInfo itself directly, but decoupling things |
138 | // this way makes unit testing a little easier. |
139 | class LineToModuleHandler { |
140 | public: |
141 | LineToModuleHandler() { } |
142 | virtual ~LineToModuleHandler() { } |
143 | |
144 | // Called at the beginning of a new compilation unit, prior to calling |
145 | // ReadProgram(). compilation_dir will indicate the path that the |
146 | // current compilation unit was compiled in, consistent with the |
147 | // DW_AT_comp_dir DIE. |
148 | virtual void StartCompilationUnit(const string& compilation_dir) = 0; |
149 | |
150 | // Populate MODULE and LINES with source file names and code/line |
151 | // mappings, given a pointer to some DWARF line number data |
152 | // PROGRAM, and an overestimate of its size. Add no zero-length |
153 | // lines to LINES. |
154 | virtual void ReadProgram(const uint8_t* program, uint64_t length, |
155 | const uint8_t* string_section, |
156 | uint64_t string_section_length, |
157 | const uint8_t* line_string_section, |
158 | uint64_t line_string_length, |
159 | Module* module, vector<Module::Line>* lines, |
160 | map<uint32_t, Module::File*>* files) = 0; |
161 | }; |
162 | |
163 | // The interface DwarfCUToModule uses to report warnings. The member |
164 | // function definitions for this class write messages to stderr, but |
165 | // you can override them if you'd like to detect or report these |
166 | // conditions yourself. |
167 | class WarningReporter { |
168 | public: |
169 | // Warn about problems in the DWARF file FILENAME, in the |
170 | // compilation unit at OFFSET. |
171 | WarningReporter(const string& filename, uint64_t cu_offset) |
172 | : filename_(filename), cu_offset_(cu_offset), printed_cu_header_(false), |
173 | printed_unpaired_header_(false), |
174 | uncovered_warnings_enabled_(false) { } |
175 | virtual ~WarningReporter() { } |
176 | |
177 | // Set the name of the compilation unit we're processing to NAME. |
178 | virtual void SetCUName(const string& name) { cu_name_ = name; } |
179 | |
180 | // Accessor and setter for uncovered_warnings_enabled_. |
181 | // UncoveredFunction and UncoveredLine only report a problem if that is |
182 | // true. By default, these warnings are disabled, because those |
183 | // conditions occur occasionally in healthy code. |
184 | virtual bool uncovered_warnings_enabled() const { |
185 | return uncovered_warnings_enabled_; |
186 | } |
187 | virtual void set_uncovered_warnings_enabled(bool value) { |
188 | uncovered_warnings_enabled_ = value; |
189 | } |
190 | |
191 | // A DW_AT_specification in the DIE at OFFSET refers to a DIE we |
192 | // haven't processed yet, or that wasn't marked as a declaration, |
193 | // at TARGET. |
194 | virtual void UnknownSpecification(uint64_t offset, uint64_t target); |
195 | |
196 | // A DW_AT_abstract_origin in the DIE at OFFSET refers to a DIE we |
197 | // haven't processed yet, or that wasn't marked as inline, at TARGET. |
198 | virtual void UnknownAbstractOrigin(uint64_t offset, uint64_t target); |
199 | |
200 | // We were unable to find the DWARF section named SECTION_NAME. |
201 | virtual void MissingSection(const string& section_name); |
202 | |
203 | // The CU's DW_AT_stmt_list offset OFFSET is bogus. |
204 | virtual void BadLineInfoOffset(uint64_t offset); |
205 | |
206 | // FUNCTION includes code covered by no line number data. |
207 | virtual void UncoveredFunction(const Module::Function& function); |
208 | |
209 | // Line number NUMBER in LINE_FILE, of length LENGTH, includes code |
210 | // covered by no function. |
211 | virtual void UncoveredLine(const Module::Line& line); |
212 | |
213 | // The DW_TAG_subprogram DIE at OFFSET has no name specified directly |
214 | // in the DIE, nor via a DW_AT_specification or DW_AT_abstract_origin |
215 | // link. |
216 | virtual void UnnamedFunction(uint64_t offset); |
217 | |
218 | // __cxa_demangle() failed to demangle INPUT. |
219 | virtual void DemangleError(const string& input); |
220 | |
221 | // The DW_FORM_ref_addr at OFFSET to TARGET was not handled because |
222 | // FilePrivate did not retain the inter-CU specification data. |
223 | virtual void UnhandledInterCUReference(uint64_t offset, uint64_t target); |
224 | |
225 | // The DW_AT_ranges at offset is malformed (truncated or outside of the |
226 | // .debug_ranges section's bound). |
227 | virtual void MalformedRangeList(uint64_t offset); |
228 | |
229 | // A DW_AT_ranges attribute was encountered but the no .debug_ranges |
230 | // section was found. |
231 | virtual void MissingRanges(); |
232 | |
233 | uint64_t cu_offset() const { |
234 | return cu_offset_; |
235 | } |
236 | |
237 | protected: |
238 | const string filename_; |
239 | const uint64_t cu_offset_; |
240 | string cu_name_; |
241 | bool ; |
242 | bool ; |
243 | bool uncovered_warnings_enabled_; |
244 | |
245 | private: |
246 | // Print a per-CU heading, once. |
247 | void CUHeading(); |
248 | // Print an unpaired function/line heading, once. |
249 | void UncoveredHeading(); |
250 | }; |
251 | |
252 | // Create a DWARF debugging info handler for a compilation unit |
253 | // within FILE_CONTEXT. This uses information received from the |
254 | // CompilationUnit DWARF parser to populate |
255 | // FILE_CONTEXT->module. Use LINE_READER to handle the compilation |
256 | // unit's line number data. Use REPORTER to report problems with the |
257 | // data we find. |
258 | DwarfCUToModule(FileContext* file_context, |
259 | LineToModuleHandler* line_reader, |
260 | RangesHandler* ranges_handler, |
261 | WarningReporter* reporter, |
262 | bool handle_inline = false); |
263 | ~DwarfCUToModule(); |
264 | |
265 | void ProcessAttributeSigned(enum DwarfAttribute attr, |
266 | enum DwarfForm form, |
267 | int64_t data); |
268 | void ProcessAttributeUnsigned(enum DwarfAttribute attr, |
269 | enum DwarfForm form, |
270 | uint64_t data); |
271 | void ProcessAttributeString(enum DwarfAttribute attr, |
272 | enum DwarfForm form, |
273 | const string& data); |
274 | bool EndAttributes(); |
275 | DIEHandler* FindChildHandler(uint64_t offset, enum DwarfTag tag); |
276 | |
277 | // Assign all our source Lines to the Functions that cover their |
278 | // addresses, and then add them to module_. |
279 | void Finish(); |
280 | |
281 | bool StartCompilationUnit(uint64_t offset, uint8_t address_size, |
282 | uint8_t offset_size, uint64_t cu_length, |
283 | uint8_t dwarf_version); |
284 | bool StartRootDIE(uint64_t offset, enum DwarfTag tag); |
285 | |
286 | private: |
287 | // Used internally by the handler. Full definitions are in |
288 | // dwarf_cu_to_module.cc. |
289 | struct CUContext; |
290 | struct DIEContext; |
291 | struct Specification; |
292 | class GenericDIEHandler; |
293 | class FuncHandler; |
294 | class InlineHandler; |
295 | class NamedScopeHandler; |
296 | |
297 | // A map from section offsets to specifications. |
298 | typedef map<uint64_t, Specification> SpecificationByOffset; |
299 | |
300 | // Set this compilation unit's source language to LANGUAGE. |
301 | void SetLanguage(DwarfLanguage language); |
302 | |
303 | // Read source line information at OFFSET in the .debug_line |
304 | // section. Record source files in module_, but record source lines |
305 | // in lines_; we apportion them to functions in |
306 | // AssignLinesToFunctions. |
307 | void ReadSourceLines(uint64_t offset); |
308 | |
309 | // Assign the lines in lines_ to the individual line lists of the |
310 | // functions in functions_. (DWARF line information maps an entire |
311 | // compilation unit at a time, and gives no indication of which |
312 | // lines belong to which functions, beyond their addresses.) |
313 | void AssignLinesToFunctions(); |
314 | |
315 | void AssignFilesToInlines(); |
316 | |
317 | // The only reason cu_context_ and child_context_ are pointers is |
318 | // that we want to keep their definitions private to |
319 | // dwarf_cu_to_module.cc, instead of listing them all here. They are |
320 | // owned by this DwarfCUToModule: the constructor sets them, and the |
321 | // destructor deletes them. |
322 | |
323 | // The handler to use to handle line number data. |
324 | LineToModuleHandler* line_reader_; |
325 | |
326 | // This compilation unit's context. |
327 | scoped_ptr<CUContext> cu_context_; |
328 | |
329 | // A context for our children. |
330 | scoped_ptr<DIEContext> child_context_; |
331 | |
332 | // True if this compilation unit has source line information. |
333 | bool has_source_line_info_; |
334 | |
335 | // The offset of this compilation unit's line number information in |
336 | // the .debug_line section. |
337 | uint64_t source_line_offset_; |
338 | |
339 | // The line numbers we have seen thus far. We accumulate these here |
340 | // during parsing. Then, in Finish, we call AssignLinesToFunctions |
341 | // to dole them out to the appropriate functions. |
342 | vector<Module::Line> lines_; |
343 | |
344 | // The map from file index to File* in this CU. |
345 | std::map<uint32_t, Module::File*> files_; |
346 | }; |
347 | |
348 | } // namespace google_breakpad |
349 | |
350 | #endif // COMMON_LINUX_DWARF_CU_TO_MODULE_H__ |
351 | |