/thirdparty/breakpad/common/module.h

http://github.com/tomahawk-player/tomahawk · C Header · 321 lines · 102 code · 54 blank · 165 comment · 2 complexity · 4997679f5d699b0a6c0aed4bcfe8e321 MD5 · raw file

  1. // -*- mode: c++ -*-
  2. // Copyright (c) 2010 Google Inc.
  3. // All rights reserved.
  4. //
  5. // Redistribution and use in source and binary forms, with or without
  6. // modification, are permitted provided that the following conditions are
  7. // met:
  8. //
  9. // * Redistributions of source code must retain the above copyright
  10. // notice, this list of conditions and the following disclaimer.
  11. // * Redistributions in binary form must reproduce the above
  12. // copyright notice, this list of conditions and the following disclaimer
  13. // in the documentation and/or other materials provided with the
  14. // distribution.
  15. // * Neither the name of Google Inc. nor the names of its
  16. // contributors may be used to endorse or promote products derived from
  17. // this software without specific prior written permission.
  18. //
  19. // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20. // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21. // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  22. // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  23. // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  24. // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  25. // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26. // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27. // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28. // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  29. // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30. // Original author: Jim Blandy <jimb@mozilla.com> <jimb@red-bean.com>
  31. // module.h: Define google_breakpad::Module. A Module holds debugging
  32. // information, and can write that information out as a Breakpad
  33. // symbol file.
  34. #ifndef COMMON_LINUX_MODULE_H__
  35. #define COMMON_LINUX_MODULE_H__
  36. #include <iostream>
  37. #include <map>
  38. #include <set>
  39. #include <string>
  40. #include <vector>
  41. #include "google_breakpad/common/breakpad_types.h"
  42. namespace google_breakpad {
  43. using std::set;
  44. using std::string;
  45. using std::vector;
  46. using std::map;
  47. // A Module represents the contents of a module, and supports methods
  48. // for adding information produced by parsing STABS or DWARF data
  49. // --- possibly both from the same file --- and then writing out the
  50. // unified contents as a Breakpad-format symbol file.
  51. class Module {
  52. public:
  53. // The type of addresses and sizes in a symbol table.
  54. typedef u_int64_t Address;
  55. struct File;
  56. struct Function;
  57. struct Line;
  58. struct Extern;
  59. // Addresses appearing in File, Function, and Line structures are
  60. // absolute, not relative to the the module's load address. That
  61. // is, if the module were loaded at its nominal load address, the
  62. // addresses would be correct.
  63. // A source file.
  64. struct File {
  65. // The name of the source file.
  66. string name;
  67. // The file's source id. The Write member function clears this
  68. // field and assigns source ids a fresh, so any value placed here
  69. // before calling Write will be lost.
  70. int source_id;
  71. };
  72. // A function.
  73. struct Function {
  74. // For sorting by address. (Not style-guide compliant, but it's
  75. // stupid not to put this in the struct.)
  76. static bool CompareByAddress(const Function *x, const Function *y) {
  77. return x->address < y->address;
  78. }
  79. // The function's name.
  80. string name;
  81. // The start address and length of the function's code.
  82. Address address, size;
  83. // The function's parameter size.
  84. Address parameter_size;
  85. // Source lines belonging to this function, sorted by increasing
  86. // address.
  87. vector<Line> lines;
  88. };
  89. // A source line.
  90. struct Line {
  91. // For sorting by address. (Not style-guide compliant, but it's
  92. // stupid not to put this in the struct.)
  93. static bool CompareByAddress(const Module::Line &x, const Module::Line &y) {
  94. return x.address < y.address;
  95. }
  96. Address address, size; // The address and size of the line's code.
  97. File *file; // The source file.
  98. int number; // The source line number.
  99. };
  100. // An exported symbol.
  101. struct Extern {
  102. Address address;
  103. string name;
  104. };
  105. // A map from register names to postfix expressions that recover
  106. // their their values. This can represent a complete set of rules to
  107. // follow at some address, or a set of changes to be applied to an
  108. // extant set of rules.
  109. typedef map<string, string> RuleMap;
  110. // A map from addresses to RuleMaps, representing changes that take
  111. // effect at given addresses.
  112. typedef map<Address, RuleMap> RuleChangeMap;
  113. // A range of 'STACK CFI' stack walking information. An instance of
  114. // this structure corresponds to a 'STACK CFI INIT' record and the
  115. // subsequent 'STACK CFI' records that fall within its range.
  116. struct StackFrameEntry {
  117. // The starting address and number of bytes of machine code this
  118. // entry covers.
  119. Address address, size;
  120. // The initial register recovery rules, in force at the starting
  121. // address.
  122. RuleMap initial_rules;
  123. // A map from addresses to rule changes. To find the rules in
  124. // force at a given address, start with initial_rules, and then
  125. // apply the changes given in this map for all addresses up to and
  126. // including the address you're interested in.
  127. RuleChangeMap rule_changes;
  128. };
  129. struct FunctionCompare {
  130. bool operator() (const Function *lhs,
  131. const Function *rhs) const {
  132. if (lhs->address == rhs->address)
  133. return lhs->name < rhs->name;
  134. return lhs->address < rhs->address;
  135. }
  136. };
  137. struct ExternCompare {
  138. bool operator() (const Extern *lhs,
  139. const Extern *rhs) const {
  140. return lhs->address < rhs->address;
  141. }
  142. };
  143. // Create a new module with the given name, operating system,
  144. // architecture, and ID string.
  145. Module(const string &name, const string &os, const string &architecture,
  146. const string &id);
  147. ~Module();
  148. // Set the module's load address to LOAD_ADDRESS; addresses given
  149. // for functions and lines will be written to the Breakpad symbol
  150. // file as offsets from this address. Construction initializes this
  151. // module's load address to zero: addresses written to the symbol
  152. // file will be the same as they appear in the Function, Line, and
  153. // StackFrameEntry structures.
  154. //
  155. // Note that this member function has no effect on addresses stored
  156. // in the data added to this module; the Write member function
  157. // simply subtracts off the load address from addresses before it
  158. // prints them. Only the last load address given before calling
  159. // Write is used.
  160. void SetLoadAddress(Address load_address);
  161. // Add FUNCTION to the module. FUNCTION's name must not be empty.
  162. // This module owns all Function objects added with this function:
  163. // destroying the module destroys them as well.
  164. void AddFunction(Function *function);
  165. // Add all the functions in [BEGIN,END) to the module.
  166. // This module owns all Function objects added with this function:
  167. // destroying the module destroys them as well.
  168. void AddFunctions(vector<Function *>::iterator begin,
  169. vector<Function *>::iterator end);
  170. // Add STACK_FRAME_ENTRY to the module.
  171. // This module owns all StackFrameEntry objects added with this
  172. // function: destroying the module destroys them as well.
  173. void AddStackFrameEntry(StackFrameEntry *stack_frame_entry);
  174. // Add PUBLIC to the module.
  175. // This module owns all Extern objects added with this function:
  176. // destroying the module destroys them as well.
  177. void AddExtern(Extern *ext);
  178. // If this module has a file named NAME, return a pointer to it. If
  179. // it has none, then create one and return a pointer to the new
  180. // file. This module owns all File objects created using these
  181. // functions; destroying the module destroys them as well.
  182. File *FindFile(const string &name);
  183. File *FindFile(const char *name);
  184. // If this module has a file named NAME, return a pointer to it.
  185. // Otherwise, return NULL.
  186. File *FindExistingFile(const string &name);
  187. // Insert pointers to the functions added to this module at I in
  188. // VEC. The pointed-to Functions are still owned by this module.
  189. // (Since this is effectively a copy of the function list, this is
  190. // mostly useful for testing; other uses should probably get a more
  191. // appropriate interface.)
  192. void GetFunctions(vector<Function *> *vec, vector<Function *>::iterator i);
  193. // Insert pointers to the externs added to this module at I in
  194. // VEC. The pointed-to Externs are still owned by this module.
  195. // (Since this is effectively a copy of the extern list, this is
  196. // mostly useful for testing; other uses should probably get a more
  197. // appropriate interface.)
  198. void GetExterns(vector<Extern *> *vec, vector<Extern *>::iterator i);
  199. // Clear VEC and fill it with pointers to the Files added to this
  200. // module, sorted by name. The pointed-to Files are still owned by
  201. // this module. (Since this is effectively a copy of the file list,
  202. // this is mostly useful for testing; other uses should probably get
  203. // a more appropriate interface.)
  204. void GetFiles(vector<File *> *vec);
  205. // Clear VEC and fill it with pointers to the StackFrameEntry
  206. // objects that have been added to this module. (Since this is
  207. // effectively a copy of the stack frame entry list, this is mostly
  208. // useful for testing; other uses should probably get
  209. // a more appropriate interface.)
  210. void GetStackFrameEntries(vector<StackFrameEntry *> *vec);
  211. // Find those files in this module that are actually referred to by
  212. // functions' line number data, and assign them source id numbers.
  213. // Set the source id numbers for all other files --- unused by the
  214. // source line data --- to -1. We do this before writing out the
  215. // symbol file, at which point we omit any unused files.
  216. void AssignSourceIds();
  217. // Call AssignSourceIds, and write this module to STREAM in the
  218. // breakpad symbol format. Return true if all goes well, or false if
  219. // an error occurs. This method writes out:
  220. // - a header based on the values given to the constructor,
  221. // - the source files added via FindFile,
  222. // - the functions added via AddFunctions, each with its lines,
  223. // - all public records,
  224. // - and if CFI is true, all CFI records.
  225. // Addresses in the output are all relative to the load address
  226. // established by SetLoadAddress.
  227. bool Write(std::ostream &stream, bool cfi);
  228. private:
  229. // Report an error that has occurred writing the symbol file, using
  230. // errno to find the appropriate cause. Return false.
  231. static bool ReportError();
  232. // Write RULE_MAP to STREAM, in the form appropriate for 'STACK CFI'
  233. // records, without a final newline. Return true if all goes well;
  234. // if an error occurs, return false, and leave errno set.
  235. static bool WriteRuleMap(const RuleMap &rule_map, std::ostream &stream);
  236. // Module header entries.
  237. string name_, os_, architecture_, id_;
  238. // The module's nominal load address. Addresses for functions and
  239. // lines are absolute, assuming the module is loaded at this
  240. // address.
  241. Address load_address_;
  242. // Relation for maps whose keys are strings shared with some other
  243. // structure.
  244. struct CompareStringPtrs {
  245. bool operator()(const string *x, const string *y) { return *x < *y; }
  246. };
  247. // A map from filenames to File structures. The map's keys are
  248. // pointers to the Files' names.
  249. typedef map<const string *, File *, CompareStringPtrs> FileByNameMap;
  250. // A set containing Function structures, sorted by address.
  251. typedef set<Function *, FunctionCompare> FunctionSet;
  252. // A set containing Extern structures, sorted by address.
  253. typedef set<Extern *, ExternCompare> ExternSet;
  254. // The module owns all the files and functions that have been added
  255. // to it; destroying the module frees the Files and Functions these
  256. // point to.
  257. FileByNameMap files_; // This module's source files.
  258. FunctionSet functions_; // This module's functions.
  259. // The module owns all the call frame info entries that have been
  260. // added to it.
  261. vector<StackFrameEntry *> stack_frame_entries_;
  262. // The module owns all the externs that have been added to it;
  263. // destroying the module frees the Externs these point to.
  264. ExternSet externs_;
  265. };
  266. } // namespace google_breakpad
  267. #endif // COMMON_LINUX_MODULE_H__