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 <stdio.h> 42 43 #include <map> 44 #include <set> 45 #include <string> 46 #include <vector> 47 48 #include "google_breakpad/common/breakpad_types.h" 49 50 namespace google_breakpad { 51 52 using std::set; 53 using std::string; 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 u_int64_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 { 77 // The name of the source file. 78 string name; 79 80 // The file's source id. The Write member function clears this 81 // field and assigns source ids a fresh, so any value placed here 82 // before calling Write will be lost. 83 int source_id; 84 }; 85 86 // A function. 87 struct Function { 88 // For sorting by address. (Not style-guide compliant, but it's 89 // stupid not to put this in the struct.) CompareByAddressFunction90 static bool CompareByAddress(const Function *x, const Function *y) { 91 return x->address < y->address; 92 } 93 94 // The function's name. 95 string name; 96 97 // The start address and length of the function's code. 98 Address address, size; 99 100 // The function's parameter size. 101 Address parameter_size; 102 103 // Source lines belonging to this function, sorted by increasing 104 // address. 105 vector<Line> lines; 106 }; 107 108 // A source line. 109 struct Line { 110 // For sorting by address. (Not style-guide compliant, but it's 111 // stupid not to put this in the struct.) CompareByAddressLine112 static bool CompareByAddress(const Module::Line &x, const Module::Line &y) { 113 return x.address < y.address; 114 } 115 116 Address address, size; // The address and size of the line's code. 117 File *file; // The source file. 118 int number; // The source line number. 119 }; 120 121 // An exported symbol. 122 struct Extern { 123 Address address; 124 string name; 125 }; 126 127 // A map from register names to postfix expressions that recover 128 // their their values. This can represent a complete set of rules to 129 // follow at some address, or a set of changes to be applied to an 130 // extant set of rules. 131 typedef map<string, string> RuleMap; 132 133 // A map from addresses to RuleMaps, representing changes that take 134 // effect at given addresses. 135 typedef map<Address, RuleMap> RuleChangeMap; 136 137 // A range of 'STACK CFI' stack walking information. An instance of 138 // this structure corresponds to a 'STACK CFI INIT' record and the 139 // subsequent 'STACK CFI' records that fall within its range. 140 struct StackFrameEntry { 141 // The starting address and number of bytes of machine code this 142 // entry covers. 143 Address address, size; 144 145 // The initial register recovery rules, in force at the starting 146 // address. 147 RuleMap initial_rules; 148 149 // A map from addresses to rule changes. To find the rules in 150 // force at a given address, start with initial_rules, and then 151 // apply the changes given in this map for all addresses up to and 152 // including the address you're interested in. 153 RuleChangeMap rule_changes; 154 }; 155 156 struct FunctionCompare { operatorFunctionCompare157 bool operator() (const Function *lhs, 158 const Function *rhs) const { 159 if (lhs->address == rhs->address) 160 return lhs->name < rhs->name; 161 return lhs->address < rhs->address; 162 } 163 }; 164 165 struct ExternCompare { operatorExternCompare166 bool operator() (const Extern *lhs, 167 const Extern *rhs) const { 168 return lhs->address < rhs->address; 169 } 170 }; 171 172 // Create a new module with the given name, operating system, 173 // architecture, and ID string. 174 Module(const string &name, const string &os, const string &architecture, 175 const string &id); 176 ~Module(); 177 178 // Set the module's load address to LOAD_ADDRESS; addresses given 179 // for functions and lines will be written to the Breakpad symbol 180 // file as offsets from this address. Construction initializes this 181 // module's load address to zero: addresses written to the symbol 182 // file will be the same as they appear in the Function, Line, and 183 // StackFrameEntry structures. 184 // 185 // Note that this member function has no effect on addresses stored 186 // in the data added to this module; the Write member function 187 // simply subtracts off the load address from addresses before it 188 // prints them. Only the last load address given before calling 189 // Write is used. 190 void SetLoadAddress(Address load_address); 191 192 // Add FUNCTION to the module. FUNCTION's name must not be empty. 193 // This module owns all Function objects added with this function: 194 // destroying the module destroys them as well. 195 void AddFunction(Function *function); 196 197 // Add all the functions in [BEGIN,END) to the module. 198 // This module owns all Function objects added with this function: 199 // destroying the module destroys them as well. 200 void AddFunctions(vector<Function *>::iterator begin, 201 vector<Function *>::iterator end); 202 203 // Add STACK_FRAME_ENTRY to the module. 204 // This module owns all StackFrameEntry objects added with this 205 // function: destroying the module destroys them as well. 206 void AddStackFrameEntry(StackFrameEntry *stack_frame_entry); 207 208 // Add PUBLIC to the module. 209 // This module owns all Extern objects added with this function: 210 // destroying the module destroys them as well. 211 void AddExtern(Extern *ext); 212 213 // If this module has a file named NAME, return a pointer to it. If 214 // it has none, then create one and return a pointer to the new 215 // file. This module owns all File objects created using these 216 // functions; destroying the module destroys them as well. 217 File *FindFile(const string &name); 218 File *FindFile(const char *name); 219 220 // If this module has a file named NAME, return a pointer to it. 221 // Otherwise, return NULL. 222 File *FindExistingFile(const string &name); 223 224 // Insert pointers to the functions added to this module at I in 225 // VEC. The pointed-to Functions are still owned by this module. 226 // (Since this is effectively a copy of the function list, this is 227 // mostly useful for testing; other uses should probably get a more 228 // appropriate interface.) 229 void GetFunctions(vector<Function *> *vec, vector<Function *>::iterator i); 230 231 // Insert pointers to the externs added to this module at I in 232 // VEC. The pointed-to Externs are still owned by this module. 233 // (Since this is effectively a copy of the extern list, this is 234 // mostly useful for testing; other uses should probably get a more 235 // appropriate interface.) 236 void GetExterns(vector<Extern *> *vec, vector<Extern *>::iterator i); 237 238 // Clear VEC and fill it with pointers to the Files added to this 239 // module, sorted by name. The pointed-to Files are still owned by 240 // this module. (Since this is effectively a copy of the file list, 241 // this is mostly useful for testing; other uses should probably get 242 // a more appropriate interface.) 243 void GetFiles(vector<File *> *vec); 244 245 // Clear VEC and fill it with pointers to the StackFrameEntry 246 // objects that have been added to this module. (Since this is 247 // effectively a copy of the stack frame entry list, this is mostly 248 // useful for testing; other uses should probably get 249 // a more appropriate interface.) 250 void GetStackFrameEntries(vector<StackFrameEntry *> *vec); 251 252 // Find those files in this module that are actually referred to by 253 // functions' line number data, and assign them source id numbers. 254 // Set the source id numbers for all other files --- unused by the 255 // source line data --- to -1. We do this before writing out the 256 // symbol file, at which point we omit any unused files. 257 void AssignSourceIds(); 258 259 // Call AssignSourceIds, and write this module to STREAM in the 260 // breakpad symbol format. Return true if all goes well, or false if 261 // an error occurs. This method writes out: 262 // - a header based on the values given to the constructor, 263 // - the source files added via FindFile, and finally 264 // - the functions added via AddFunctions, each with its lines. 265 // Addresses in the output are all relative to the load address 266 // established by SetLoadAddress. 267 bool Write(FILE *stream); 268 269 private: 270 271 // Report an error that has occurred writing the symbol file, using 272 // errno to find the appropriate cause. Return false. 273 static bool ReportError(); 274 275 // Write RULE_MAP to STREAM, in the form appropriate for 'STACK CFI' 276 // records, without a final newline. Return true if all goes well; 277 // if an error occurs, return false, and leave errno set. 278 static bool WriteRuleMap(const RuleMap &rule_map, FILE *stream); 279 280 // Module header entries. 281 string name_, os_, architecture_, id_; 282 283 // The module's nominal load address. Addresses for functions and 284 // lines are absolute, assuming the module is loaded at this 285 // address. 286 Address load_address_; 287 288 // Relation for maps whose keys are strings shared with some other 289 // structure. 290 struct CompareStringPtrs { operatorCompareStringPtrs291 bool operator()(const string *x, const string *y) { return *x < *y; }; 292 }; 293 294 // A map from filenames to File structures. The map's keys are 295 // pointers to the Files' names. 296 typedef map<const string *, File *, CompareStringPtrs> FileByNameMap; 297 298 // A set containing Function structures, sorted by address. 299 typedef set<Function *, FunctionCompare> FunctionSet; 300 301 // A set containing Extern structures, sorted by address. 302 typedef set<Extern *, ExternCompare> ExternSet; 303 304 // The module owns all the files and functions that have been added 305 // to it; destroying the module frees the Files and Functions these 306 // point to. 307 FileByNameMap files_; // This module's source files. 308 FunctionSet functions_; // This module's functions. 309 310 // The module owns all the call frame info entries that have been 311 // added to it. 312 vector<StackFrameEntry *> stack_frame_entries_; 313 314 // The module owns all the externs that have been added to it; 315 // destroying the module frees the Externs these point to. 316 ExternSet externs_; 317 }; 318 319 } // namespace google_breakpad 320 321 #endif // COMMON_LINUX_MODULE_H__ 322