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 // module.h: Define google_breakpad::Module. A Module holds debugging 35 // information, and can write that information out as a Breakpad 36 // symbol file. 37 38 #ifndef COMMON_LINUX_MODULE_H__ 39 #define COMMON_LINUX_MODULE_H__ 40 41 #include <iostream> 42 #include <map> 43 #include <set> 44 #include <string> 45 #include <vector> 46 47 #include "common/symbol_data.h" 48 #include "common/using_std_string.h" 49 #include "google_breakpad/common/breakpad_types.h" 50 51 namespace google_breakpad { 52 53 using std::set; 54 using std::vector; 55 using std::map; 56 57 // A Module represents the contents of a module, and supports methods 58 // for adding information produced by parsing STABS or DWARF data 59 // --- possibly both from the same file --- and then writing out the 60 // unified contents as a Breakpad-format symbol file. 61 class Module { 62 public: 63 // The type of addresses and sizes in a symbol table. 64 typedef uint64_t Address; 65 struct File; 66 struct Function; 67 struct Line; 68 struct Extern; 69 70 // Addresses appearing in File, Function, and Line structures are 71 // absolute, not relative to the the module's load address. That 72 // is, if the module were loaded at its nominal load address, the 73 // addresses would be correct. 74 75 // A source file. 76 struct File { FileFile77 explicit File(const string &name_input) : name(name_input), source_id(0) {} 78 79 // The name of the source file. 80 const string name; 81 82 // The file's source id. The Write member function clears this 83 // field and assigns source ids a fresh, so any value placed here 84 // before calling Write will be lost. 85 int source_id; 86 }; 87 88 // An address range. 89 struct Range { RangeRange90 Range(const Address address_input, const Address size_input) : 91 address(address_input), size(size_input) { } 92 93 Address address; 94 Address size; 95 }; 96 97 // A function. 98 struct Function { FunctionFunction99 Function(const string &name_input, const Address &address_input) : 100 name(name_input), address(address_input), parameter_size(0) {} 101 102 // For sorting by address. (Not style-guide compliant, but it's 103 // stupid not to put this in the struct.) CompareByAddressFunction104 static bool CompareByAddress(const Function *x, const Function *y) { 105 return x->address < y->address; 106 } 107 108 // The function's name. 109 string name; 110 111 // The start address and the address ranges covered by the function. 112 const Address address; 113 vector<Range> ranges; 114 115 // The function's parameter size. 116 Address parameter_size; 117 118 // Source lines belonging to this function, sorted by increasing 119 // address. 120 vector<Line> lines; 121 }; 122 123 // A source line. 124 struct Line { 125 // For sorting by address. (Not style-guide compliant, but it's 126 // stupid not to put this in the struct.) CompareByAddressLine127 static bool CompareByAddress(const Module::Line &x, const Module::Line &y) { 128 return x.address < y.address; 129 } 130 131 Address address, size; // The address and size of the line's code. 132 File *file; // The source file. 133 int number; // The source line number. 134 }; 135 136 // An exported symbol. 137 struct Extern { ExternExtern138 explicit Extern(const Address &address_input) : address(address_input) {} 139 const Address address; 140 string name; 141 }; 142 143 // A map from register names to postfix expressions that recover 144 // their their values. This can represent a complete set of rules to 145 // follow at some address, or a set of changes to be applied to an 146 // extant set of rules. 147 typedef map<string, string> RuleMap; 148 149 // A map from addresses to RuleMaps, representing changes that take 150 // effect at given addresses. 151 typedef map<Address, RuleMap> RuleChangeMap; 152 153 // A range of 'STACK CFI' stack walking information. An instance of 154 // this structure corresponds to a 'STACK CFI INIT' record and the 155 // subsequent 'STACK CFI' records that fall within its range. 156 struct StackFrameEntry { 157 // The starting address and number of bytes of machine code this 158 // entry covers. 159 Address address, size; 160 161 // The initial register recovery rules, in force at the starting 162 // address. 163 RuleMap initial_rules; 164 165 // A map from addresses to rule changes. To find the rules in 166 // force at a given address, start with initial_rules, and then 167 // apply the changes given in this map for all addresses up to and 168 // including the address you're interested in. 169 RuleChangeMap rule_changes; 170 }; 171 172 struct FunctionCompare { operatorFunctionCompare173 bool operator() (const Function *lhs, 174 const Function *rhs) const { 175 if (lhs->address == rhs->address) 176 return lhs->name < rhs->name; 177 return lhs->address < rhs->address; 178 } 179 }; 180 181 struct ExternCompare { operatorExternCompare182 bool operator() (const Extern *lhs, 183 const Extern *rhs) const { 184 return lhs->address < rhs->address; 185 } 186 }; 187 188 struct StackFrameEntryCompare { operatorStackFrameEntryCompare189 bool operator() (const StackFrameEntry* lhs, 190 const StackFrameEntry* rhs) const { 191 return lhs->address < rhs->address; 192 } 193 }; 194 195 // Create a new module with the given name, operating system, 196 // architecture, and ID string. 197 Module(const string &name, const string &os, const string &architecture, 198 const string &id, const string &code_id = ""); 199 ~Module(); 200 201 // Set the module's load address to LOAD_ADDRESS; addresses given 202 // for functions and lines will be written to the Breakpad symbol 203 // file as offsets from this address. Construction initializes this 204 // module's load address to zero: addresses written to the symbol 205 // file will be the same as they appear in the Function, Line, and 206 // StackFrameEntry structures. 207 // 208 // Note that this member function has no effect on addresses stored 209 // in the data added to this module; the Write member function 210 // simply subtracts off the load address from addresses before it 211 // prints them. Only the last load address given before calling 212 // Write is used. 213 void SetLoadAddress(Address load_address); 214 215 // Sets address filtering on elements added to the module. This allows 216 // libraries with extraneous debug symbols to generate symbol files containing 217 // only relevant symbols. For example, an LLD-generated partition library may 218 // contain debug information pertaining to all partitions derived from a 219 // single "combined" library. Filtering applies only to elements added after 220 // this method is called. 221 void SetAddressRanges(const vector<Range>& ranges); 222 223 // Add FUNCTION to the module. FUNCTION's name must not be empty. 224 // This module owns all Function objects added with this function: 225 // destroying the module destroys them as well. 226 void AddFunction(Function *function); 227 228 // Add all the functions in [BEGIN,END) to the module. 229 // This module owns all Function objects added with this function: 230 // destroying the module destroys them as well. 231 void AddFunctions(vector<Function *>::iterator begin, 232 vector<Function *>::iterator end); 233 234 // Add STACK_FRAME_ENTRY to the module. 235 // This module owns all StackFrameEntry objects added with this 236 // function: destroying the module destroys them as well. 237 void AddStackFrameEntry(StackFrameEntry *stack_frame_entry); 238 239 // Add PUBLIC to the module. 240 // This module owns all Extern objects added with this function: 241 // destroying the module destroys them as well. 242 void AddExtern(Extern *ext); 243 244 // If this module has a file named NAME, return a pointer to it. If 245 // it has none, then create one and return a pointer to the new 246 // file. This module owns all File objects created using these 247 // functions; destroying the module destroys them as well. 248 File *FindFile(const string &name); 249 File *FindFile(const char *name); 250 251 // If this module has a file named NAME, return a pointer to it. 252 // Otherwise, return NULL. 253 File *FindExistingFile(const string &name); 254 255 // Insert pointers to the functions added to this module at I in 256 // VEC. The pointed-to Functions are still owned by this module. 257 // (Since this is effectively a copy of the function list, this is 258 // mostly useful for testing; other uses should probably get a more 259 // appropriate interface.) 260 void GetFunctions(vector<Function *> *vec, vector<Function *>::iterator i); 261 262 // Insert pointers to the externs added to this module at I in 263 // VEC. The pointed-to Externs are still owned by this module. 264 // (Since this is effectively a copy of the extern list, this is 265 // mostly useful for testing; other uses should probably get a more 266 // appropriate interface.) 267 void GetExterns(vector<Extern *> *vec, vector<Extern *>::iterator i); 268 269 // Clear VEC and fill it with pointers to the Files added to this 270 // module, sorted by name. The pointed-to Files are still owned by 271 // this module. (Since this is effectively a copy of the file list, 272 // this is mostly useful for testing; other uses should probably get 273 // a more appropriate interface.) 274 void GetFiles(vector<File *> *vec); 275 276 // Clear VEC and fill it with pointers to the StackFrameEntry 277 // objects that have been added to this module. (Since this is 278 // effectively a copy of the stack frame entry list, this is mostly 279 // useful for testing; other uses should probably get 280 // a more appropriate interface.) 281 void GetStackFrameEntries(vector<StackFrameEntry *> *vec) const; 282 283 // If this module has a StackFrameEntry whose address range covers 284 // ADDRESS, return it. Otherwise return NULL. 285 StackFrameEntry* FindStackFrameEntryByAddress(Address address); 286 287 // Find those files in this module that are actually referred to by 288 // functions' line number data, and assign them source id numbers. 289 // Set the source id numbers for all other files --- unused by the 290 // source line data --- to -1. We do this before writing out the 291 // symbol file, at which point we omit any unused files. 292 void AssignSourceIds(); 293 294 // Call AssignSourceIds, and write this module to STREAM in the 295 // breakpad symbol format. Return true if all goes well, or false if 296 // an error occurs. This method writes out: 297 // - a header based on the values given to the constructor, 298 // If symbol_data is not ONLY_CFI then: 299 // - the source files added via FindFile, 300 // - the functions added via AddFunctions, each with its lines, 301 // - all public records, 302 // If symbol_data is not NO_CFI then: 303 // - all CFI records. 304 // Addresses in the output are all relative to the load address 305 // established by SetLoadAddress. 306 bool Write(std::ostream &stream, SymbolData symbol_data); 307 name()308 string name() const { return name_; } os()309 string os() const { return os_; } architecture()310 string architecture() const { return architecture_; } identifier()311 string identifier() const { return id_; } code_identifier()312 string code_identifier() const { return code_id_; } 313 314 private: 315 // Report an error that has occurred writing the symbol file, using 316 // errno to find the appropriate cause. Return false. 317 static bool ReportError(); 318 319 // Write RULE_MAP to STREAM, in the form appropriate for 'STACK CFI' 320 // records, without a final newline. Return true if all goes well; 321 // if an error occurs, return false, and leave errno set. 322 static bool WriteRuleMap(const RuleMap &rule_map, std::ostream &stream); 323 324 // Returns true of the specified address resides with an specified address 325 // range, or if no ranges have been specified. 326 bool AddressIsInModule(Address address) const; 327 328 // Module header entries. 329 string name_, os_, architecture_, id_, code_id_; 330 331 // The module's nominal load address. Addresses for functions and 332 // lines are absolute, assuming the module is loaded at this 333 // address. 334 Address load_address_; 335 336 // The set of valid address ranges of the module. If specified, attempts to 337 // add elements residing outside these ranges will be silently filtered. 338 vector<Range> address_ranges_; 339 340 // Relation for maps whose keys are strings shared with some other 341 // structure. 342 struct CompareStringPtrs { operatorCompareStringPtrs343 bool operator()(const string *x, const string *y) const { return *x < *y; } 344 }; 345 346 // A map from filenames to File structures. The map's keys are 347 // pointers to the Files' names. 348 typedef map<const string *, File *, CompareStringPtrs> FileByNameMap; 349 350 // A set containing Function structures, sorted by address. 351 typedef set<Function *, FunctionCompare> FunctionSet; 352 353 // A set containing Extern structures, sorted by address. 354 typedef set<Extern *, ExternCompare> ExternSet; 355 356 // A set containing StackFrameEntry structures, sorted by address. 357 typedef set<StackFrameEntry*, StackFrameEntryCompare> StackFrameEntrySet; 358 359 // The module owns all the files and functions that have been added 360 // to it; destroying the module frees the Files and Functions these 361 // point to. 362 FileByNameMap files_; // This module's source files. 363 FunctionSet functions_; // This module's functions. 364 365 // The module owns all the call frame info entries that have been 366 // added to it. 367 StackFrameEntrySet stack_frame_entries_; 368 369 // The module owns all the externs that have been added to it; 370 // destroying the module frees the Externs these point to. 371 ExternSet externs_; 372 }; 373 374 } // namespace google_breakpad 375 376 #endif // COMMON_LINUX_MODULE_H__ 377