/thirdparty/breakpad/google_breakpad/processor/minidump.h

http://github.com/tomahawk-player/tomahawk · C Header · 1032 lines · 407 code · 235 blank · 390 comment · 0 complexity · c23e277420a3625b955668c5d6b41a03 MD5 · raw file

  1. // Copyright (c) 2010 Google Inc.
  2. // All rights reserved.
  3. //
  4. // Redistribution and use in source and binary forms, with or without
  5. // modification, are permitted provided that the following conditions are
  6. // met:
  7. //
  8. // * Redistributions of source code must retain the above copyright
  9. // notice, this list of conditions and the following disclaimer.
  10. // * Redistributions in binary form must reproduce the above
  11. // copyright notice, this list of conditions and the following disclaimer
  12. // in the documentation and/or other materials provided with the
  13. // distribution.
  14. // * Neither the name of Google Inc. nor the names of its
  15. // contributors may be used to endorse or promote products derived from
  16. // this software without specific prior written permission.
  17. //
  18. // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19. // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20. // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21. // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22. // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23. // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  24. // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25. // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26. // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27. // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  28. // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. // minidump.h: A minidump reader.
  30. //
  31. // The basic structure of this module tracks the structure of the minidump
  32. // file itself. At the top level, a minidump file is represented by a
  33. // Minidump object. Like most other classes in this module, Minidump
  34. // provides a Read method that initializes the object with information from
  35. // the file. Most of the classes in this file are wrappers around the
  36. // "raw" structures found in the minidump file itself, and defined in
  37. // minidump_format.h. For example, each thread is represented by a
  38. // MinidumpThread object, whose parameters are specified in an MDRawThread
  39. // structure. A properly byte-swapped MDRawThread can be obtained from a
  40. // MinidumpThread easily by calling its thread() method.
  41. //
  42. // Most of the module lazily reads only the portion of the minidump file
  43. // necessary to fulfill the user's request. Calling Minidump::Read
  44. // only reads the minidump's directory. The thread list is not read until
  45. // it is needed, and even once it's read, the memory regions for each
  46. // thread's stack aren't read until they're needed. This strategy avoids
  47. // unnecessary file input, and allocating memory for data in which the user
  48. // has no interest. Note that although memory allocations for a typical
  49. // minidump file are not particularly large, it is possible for legitimate
  50. // minidumps to be sizable. A full-memory minidump, for example, contains
  51. // a snapshot of the entire mapped memory space. Even a normal minidump,
  52. // with stack memory only, can be large if, for example, the dump was
  53. // generated in response to a crash that occurred due to an infinite-
  54. // recursion bug that caused the stack's limits to be exceeded. Finally,
  55. // some users of this library will unfortunately find themselves in the
  56. // position of having to process potentially-hostile minidumps that might
  57. // attempt to cause problems by forcing the minidump processor to over-
  58. // allocate memory.
  59. //
  60. // Memory management in this module is based on a strict
  61. // you-don't-own-anything policy. The only object owned by the user is
  62. // the top-level Minidump object, the creation and destruction of which
  63. // must be the user's own responsibility. All other objects obtained
  64. // through interaction with this module are ultimately owned by the
  65. // Minidump object, and will be freed upon the Minidump object's destruction.
  66. // Because memory regions can potentially involve large allocations, a
  67. // FreeMemory method is provided by MinidumpMemoryRegion, allowing the user
  68. // to release data when it is no longer needed. Use of this method is
  69. // optional but recommended. If freed data is later required, it will
  70. // be read back in from the minidump file again.
  71. //
  72. // There is one exception to this memory management policy:
  73. // Minidump::ReadString will return a string object to the user, and the user
  74. // is responsible for its deletion.
  75. //
  76. // Author: Mark Mentovai
  77. #ifndef GOOGLE_BREAKPAD_PROCESSOR_MINIDUMP_H__
  78. #define GOOGLE_BREAKPAD_PROCESSOR_MINIDUMP_H__
  79. #ifndef _WIN32
  80. #include <unistd.h>
  81. #endif
  82. #include <iostream>
  83. #include <map>
  84. #include <string>
  85. #include <vector>
  86. #include "google_breakpad/common/minidump_format.h"
  87. #include "google_breakpad/processor/code_module.h"
  88. #include "google_breakpad/processor/code_modules.h"
  89. #include "google_breakpad/processor/memory_region.h"
  90. namespace google_breakpad {
  91. using std::map;
  92. using std::string;
  93. using std::vector;
  94. class Minidump;
  95. template<typename AddressType, typename EntryType> class RangeMap;
  96. // MinidumpObject is the base of all Minidump* objects except for Minidump
  97. // itself.
  98. class MinidumpObject {
  99. public:
  100. virtual ~MinidumpObject() {}
  101. bool valid() const { return valid_; }
  102. protected:
  103. explicit MinidumpObject(Minidump* minidump);
  104. // Refers to the Minidump object that is the ultimate parent of this
  105. // Some MinidumpObjects are owned by other MinidumpObjects, but at the
  106. // root of the ownership tree is always a Minidump. The Minidump object
  107. // is kept here for access to its seeking and reading facilities, and
  108. // for access to data about the minidump file itself, such as whether
  109. // it should be byte-swapped.
  110. Minidump* minidump_;
  111. // MinidumpObjects are not valid when created. When a subclass populates
  112. // its own fields, it can set valid_ to true. Accessors and mutators may
  113. // wish to consider or alter the valid_ state as they interact with
  114. // objects.
  115. bool valid_;
  116. };
  117. // This class exists primarily to provide a virtual destructor in a base
  118. // class common to all objects that might be stored in
  119. // Minidump::mStreamObjects. Some object types (MinidumpContext) will
  120. // never be stored in Minidump::mStreamObjects, but are represented as
  121. // streams and adhere to the same interface, and may be derived from
  122. // this class.
  123. class MinidumpStream : public MinidumpObject {
  124. public:
  125. virtual ~MinidumpStream() {}
  126. protected:
  127. explicit MinidumpStream(Minidump* minidump);
  128. private:
  129. // Populate (and validate) the MinidumpStream. minidump_ is expected
  130. // to be positioned at the beginning of the stream, so that the next
  131. // read from the minidump will be at the beginning of the stream.
  132. // expected_size should be set to the stream's length as contained in
  133. // the MDRawDirectory record or other identifying record. A class
  134. // that implements MinidumpStream can compare expected_size to a
  135. // known size as an integrity check.
  136. virtual bool Read(u_int32_t expected_size) = 0;
  137. };
  138. // MinidumpContext carries a CPU-specific MDRawContext structure, which
  139. // contains CPU context such as register states. Each thread has its
  140. // own context, and the exception record, if present, also has its own
  141. // context. Note that if the exception record is present, the context it
  142. // refers to is probably what the user wants to use for the exception
  143. // thread, instead of that thread's own context. The exception thread's
  144. // context (as opposed to the exception record's context) will contain
  145. // context for the exception handler (which performs minidump generation),
  146. // and not the context that caused the exception (which is probably what the
  147. // user wants).
  148. class MinidumpContext : public MinidumpStream {
  149. public:
  150. virtual ~MinidumpContext();
  151. // Returns an MD_CONTEXT_* value such as MD_CONTEXT_X86 or MD_CONTEXT_PPC
  152. // identifying the CPU type that the context was collected from. The
  153. // returned value will identify the CPU only, and will have any other
  154. // MD_CONTEXT_* bits masked out. Returns 0 on failure.
  155. u_int32_t GetContextCPU() const;
  156. // Returns raw CPU-specific context data for the named CPU type. If the
  157. // context data does not match the CPU type or does not exist, returns
  158. // NULL.
  159. const MDRawContextAMD64* GetContextAMD64() const;
  160. const MDRawContextARM* GetContextARM() const;
  161. const MDRawContextPPC* GetContextPPC() const;
  162. const MDRawContextSPARC* GetContextSPARC() const;
  163. const MDRawContextX86* GetContextX86() const;
  164. // Print a human-readable representation of the object to stdout.
  165. void Print();
  166. private:
  167. friend class MinidumpThread;
  168. friend class MinidumpException;
  169. explicit MinidumpContext(Minidump* minidump);
  170. bool Read(u_int32_t expected_size);
  171. // Free the CPU-specific context structure.
  172. void FreeContext();
  173. // If the minidump contains a SYSTEM_INFO_STREAM, makes sure that the
  174. // system info stream gives an appropriate CPU type matching the context
  175. // CPU type in context_cpu_type. Returns false if the CPU type does not
  176. // match. Returns true if the CPU type matches or if the minidump does
  177. // not contain a system info stream.
  178. bool CheckAgainstSystemInfo(u_int32_t context_cpu_type);
  179. // Store this separately because of the weirdo AMD64 context
  180. u_int32_t context_flags_;
  181. // The CPU-specific context structure.
  182. union {
  183. MDRawContextBase* base;
  184. MDRawContextX86* x86;
  185. MDRawContextPPC* ppc;
  186. MDRawContextAMD64* amd64;
  187. // on Solaris SPARC, sparc is defined as a numeric constant,
  188. // so variables can NOT be named as sparc
  189. MDRawContextSPARC* ctx_sparc;
  190. MDRawContextARM* arm;
  191. } context_;
  192. };
  193. // MinidumpMemoryRegion does not wrap any MDRaw structure, and only contains
  194. // a reference to an MDMemoryDescriptor. This object is intended to wrap
  195. // portions of a minidump file that contain memory dumps. In normal
  196. // minidumps, each MinidumpThread owns a MinidumpMemoryRegion corresponding
  197. // to the thread's stack memory. MinidumpMemoryList also gives access to
  198. // memory regions in its list as MinidumpMemoryRegions. This class
  199. // adheres to MemoryRegion so that it may be used as a data provider to
  200. // the Stackwalker family of classes.
  201. class MinidumpMemoryRegion : public MinidumpObject,
  202. public MemoryRegion {
  203. public:
  204. virtual ~MinidumpMemoryRegion();
  205. static void set_max_bytes(u_int32_t max_bytes) { max_bytes_ = max_bytes; }
  206. static u_int32_t max_bytes() { return max_bytes_; }
  207. // Returns a pointer to the base of the memory region. Returns the
  208. // cached value if available, otherwise, reads the minidump file and
  209. // caches the memory region.
  210. const u_int8_t* GetMemory() const;
  211. // The address of the base of the memory region.
  212. u_int64_t GetBase() const;
  213. // The size, in bytes, of the memory region.
  214. u_int32_t GetSize() const;
  215. // Frees the cached memory region, if cached.
  216. void FreeMemory();
  217. // Obtains the value of memory at the pointer specified by address.
  218. bool GetMemoryAtAddress(u_int64_t address, u_int8_t* value) const;
  219. bool GetMemoryAtAddress(u_int64_t address, u_int16_t* value) const;
  220. bool GetMemoryAtAddress(u_int64_t address, u_int32_t* value) const;
  221. bool GetMemoryAtAddress(u_int64_t address, u_int64_t* value) const;
  222. // Print a human-readable representation of the object to stdout.
  223. void Print();
  224. private:
  225. friend class MinidumpThread;
  226. friend class MinidumpMemoryList;
  227. explicit MinidumpMemoryRegion(Minidump* minidump);
  228. // Identify the base address and size of the memory region, and the
  229. // location it may be found in the minidump file.
  230. void SetDescriptor(MDMemoryDescriptor* descriptor);
  231. // Implementation for GetMemoryAtAddress
  232. template<typename T> bool GetMemoryAtAddressInternal(u_int64_t address,
  233. T* value) const;
  234. // The largest memory region that will be read from a minidump. The
  235. // default is 1MB.
  236. static u_int32_t max_bytes_;
  237. // Base address and size of the memory region, and its position in the
  238. // minidump file.
  239. MDMemoryDescriptor* descriptor_;
  240. // Cached memory.
  241. mutable vector<u_int8_t>* memory_;
  242. };
  243. // MinidumpThread contains information about a thread of execution,
  244. // including a snapshot of the thread's stack and CPU context. For
  245. // the thread that caused an exception, the context carried by
  246. // MinidumpException is probably desired instead of the CPU context
  247. // provided here.
  248. class MinidumpThread : public MinidumpObject {
  249. public:
  250. virtual ~MinidumpThread();
  251. const MDRawThread* thread() const { return valid_ ? &thread_ : NULL; }
  252. MinidumpMemoryRegion* GetMemory();
  253. MinidumpContext* GetContext();
  254. // The thread ID is used to determine if a thread is the exception thread,
  255. // so a special getter is provided to retrieve this data from the
  256. // MDRawThread structure. Returns false if the thread ID cannot be
  257. // determined.
  258. bool GetThreadID(u_int32_t *thread_id) const;
  259. // Print a human-readable representation of the object to stdout.
  260. void Print();
  261. private:
  262. // These objects are managed by MinidumpThreadList.
  263. friend class MinidumpThreadList;
  264. explicit MinidumpThread(Minidump* minidump);
  265. // This works like MinidumpStream::Read, but is driven by
  266. // MinidumpThreadList. No size checking is done, because
  267. // MinidumpThreadList handles that directly.
  268. bool Read();
  269. MDRawThread thread_;
  270. MinidumpMemoryRegion* memory_;
  271. MinidumpContext* context_;
  272. };
  273. // MinidumpThreadList contains all of the threads (as MinidumpThreads) in
  274. // a process.
  275. class MinidumpThreadList : public MinidumpStream {
  276. public:
  277. virtual ~MinidumpThreadList();
  278. static void set_max_threads(u_int32_t max_threads) {
  279. max_threads_ = max_threads;
  280. }
  281. static u_int32_t max_threads() { return max_threads_; }
  282. unsigned int thread_count() const {
  283. return valid_ ? thread_count_ : 0;
  284. }
  285. // Sequential access to threads.
  286. MinidumpThread* GetThreadAtIndex(unsigned int index) const;
  287. // Random access to threads.
  288. MinidumpThread* GetThreadByID(u_int32_t thread_id);
  289. // Print a human-readable representation of the object to stdout.
  290. void Print();
  291. private:
  292. friend class Minidump;
  293. typedef map<u_int32_t, MinidumpThread*> IDToThreadMap;
  294. typedef vector<MinidumpThread> MinidumpThreads;
  295. static const u_int32_t kStreamType = MD_THREAD_LIST_STREAM;
  296. explicit MinidumpThreadList(Minidump* aMinidump);
  297. bool Read(u_int32_t aExpectedSize);
  298. // The largest number of threads that will be read from a minidump. The
  299. // default is 256.
  300. static u_int32_t max_threads_;
  301. // Access to threads using the thread ID as the key.
  302. IDToThreadMap id_to_thread_map_;
  303. // The list of threads.
  304. MinidumpThreads* threads_;
  305. u_int32_t thread_count_;
  306. };
  307. // MinidumpModule wraps MDRawModule, which contains information about loaded
  308. // code modules. Access is provided to various data referenced indirectly
  309. // by MDRawModule, such as the module's name and a specification for where
  310. // to locate debugging information for the module.
  311. class MinidumpModule : public MinidumpObject,
  312. public CodeModule {
  313. public:
  314. virtual ~MinidumpModule();
  315. static void set_max_cv_bytes(u_int32_t max_cv_bytes) {
  316. max_cv_bytes_ = max_cv_bytes;
  317. }
  318. static u_int32_t max_cv_bytes() { return max_cv_bytes_; }
  319. static void set_max_misc_bytes(u_int32_t max_misc_bytes) {
  320. max_misc_bytes_ = max_misc_bytes;
  321. }
  322. static u_int32_t max_misc_bytes() { return max_misc_bytes_; }
  323. const MDRawModule* module() const { return valid_ ? &module_ : NULL; }
  324. // CodeModule implementation
  325. virtual u_int64_t base_address() const {
  326. return valid_ ? module_.base_of_image : static_cast<u_int64_t>(-1);
  327. }
  328. virtual u_int64_t size() const { return valid_ ? module_.size_of_image : 0; }
  329. virtual string code_file() const;
  330. virtual string code_identifier() const;
  331. virtual string debug_file() const;
  332. virtual string debug_identifier() const;
  333. virtual string version() const;
  334. virtual const CodeModule* Copy() const;
  335. // The CodeView record, which contains information to locate the module's
  336. // debugging information (pdb). This is returned as u_int8_t* because
  337. // the data can be of types MDCVInfoPDB20* or MDCVInfoPDB70*, or it may be
  338. // of a type unknown to Breakpad, in which case the raw data will still be
  339. // returned but no byte-swapping will have been performed. Check the
  340. // record's signature in the first four bytes to differentiate between
  341. // the various types. Current toolchains generate modules which carry
  342. // MDCVInfoPDB70 by default. Returns a pointer to the CodeView record on
  343. // success, and NULL on failure. On success, the optional |size| argument
  344. // is set to the size of the CodeView record.
  345. const u_int8_t* GetCVRecord(u_int32_t* size);
  346. // The miscellaneous debug record, which is obsolete. Current toolchains
  347. // do not generate this type of debugging information (dbg), and this
  348. // field is not expected to be present. Returns a pointer to the debugging
  349. // record on success, and NULL on failure. On success, the optional |size|
  350. // argument is set to the size of the debugging record.
  351. const MDImageDebugMisc* GetMiscRecord(u_int32_t* size);
  352. // Print a human-readable representation of the object to stdout.
  353. void Print();
  354. private:
  355. // These objects are managed by MinidumpModuleList.
  356. friend class MinidumpModuleList;
  357. explicit MinidumpModule(Minidump* minidump);
  358. // This works like MinidumpStream::Read, but is driven by
  359. // MinidumpModuleList. No size checking is done, because
  360. // MinidumpModuleList handles that directly.
  361. bool Read();
  362. // Reads indirectly-referenced data, including the module name, CodeView
  363. // record, and miscellaneous debugging record. This is necessary to allow
  364. // MinidumpModuleList to fully construct MinidumpModule objects without
  365. // requiring seeks to read a contiguous set of MinidumpModule objects.
  366. // All auxiliary data should be available when Read is called, in order to
  367. // allow the CodeModule getters to be const methods.
  368. bool ReadAuxiliaryData();
  369. // The largest number of bytes that will be read from a minidump for a
  370. // CodeView record or miscellaneous debugging record, respectively. The
  371. // default for each is 1024.
  372. static u_int32_t max_cv_bytes_;
  373. static u_int32_t max_misc_bytes_;
  374. // True after a successful Read. This is different from valid_, which is
  375. // not set true until ReadAuxiliaryData also completes successfully.
  376. // module_valid_ is only used by ReadAuxiliaryData and the functions it
  377. // calls to determine whether the object is ready for auxiliary data to
  378. // be read.
  379. bool module_valid_;
  380. // True if debug info was read from the module. Certain modules
  381. // may contain debug records in formats we don't support,
  382. // so we can just set this to false to ignore them.
  383. bool has_debug_info_;
  384. MDRawModule module_;
  385. // Cached module name.
  386. const string* name_;
  387. // Cached CodeView record - this is MDCVInfoPDB20 or (likely)
  388. // MDCVInfoPDB70, or possibly something else entirely. Stored as a u_int8_t
  389. // because the structure contains a variable-sized string and its exact
  390. // size cannot be known until it is processed.
  391. vector<u_int8_t>* cv_record_;
  392. // If cv_record_ is present, cv_record_signature_ contains a copy of the
  393. // CodeView record's first four bytes, for ease of determinining the
  394. // type of structure that cv_record_ contains.
  395. u_int32_t cv_record_signature_;
  396. // Cached MDImageDebugMisc (usually not present), stored as u_int8_t
  397. // because the structure contains a variable-sized string and its exact
  398. // size cannot be known until it is processed.
  399. vector<u_int8_t>* misc_record_;
  400. };
  401. // MinidumpModuleList contains all of the loaded code modules for a process
  402. // in the form of MinidumpModules. It maintains a map of these modules
  403. // so that it may easily provide a code module corresponding to a specific
  404. // address.
  405. class MinidumpModuleList : public MinidumpStream,
  406. public CodeModules {
  407. public:
  408. virtual ~MinidumpModuleList();
  409. static void set_max_modules(u_int32_t max_modules) {
  410. max_modules_ = max_modules;
  411. }
  412. static u_int32_t max_modules() { return max_modules_; }
  413. // CodeModules implementation.
  414. virtual unsigned int module_count() const {
  415. return valid_ ? module_count_ : 0;
  416. }
  417. virtual const MinidumpModule* GetModuleForAddress(u_int64_t address) const;
  418. virtual const MinidumpModule* GetMainModule() const;
  419. virtual const MinidumpModule* GetModuleAtSequence(
  420. unsigned int sequence) const;
  421. virtual const MinidumpModule* GetModuleAtIndex(unsigned int index) const;
  422. virtual const CodeModules* Copy() const;
  423. // Print a human-readable representation of the object to stdout.
  424. void Print();
  425. private:
  426. friend class Minidump;
  427. typedef vector<MinidumpModule> MinidumpModules;
  428. static const u_int32_t kStreamType = MD_MODULE_LIST_STREAM;
  429. explicit MinidumpModuleList(Minidump* minidump);
  430. bool Read(u_int32_t expected_size);
  431. // The largest number of modules that will be read from a minidump. The
  432. // default is 1024.
  433. static u_int32_t max_modules_;
  434. // Access to modules using addresses as the key.
  435. RangeMap<u_int64_t, unsigned int> *range_map_;
  436. MinidumpModules *modules_;
  437. u_int32_t module_count_;
  438. };
  439. // MinidumpMemoryList corresponds to a minidump's MEMORY_LIST_STREAM stream,
  440. // which references the snapshots of all of the memory regions contained
  441. // within the minidump. For a normal minidump, this includes stack memory
  442. // (also referenced by each MinidumpThread, in fact, the MDMemoryDescriptors
  443. // here and in MDRawThread both point to exactly the same data in a
  444. // minidump file, conserving space), as well as a 256-byte snapshot of memory
  445. // surrounding the instruction pointer in the case of an exception. Other
  446. // types of minidumps may contain significantly more memory regions. Full-
  447. // memory minidumps contain all of a process' mapped memory.
  448. class MinidumpMemoryList : public MinidumpStream {
  449. public:
  450. virtual ~MinidumpMemoryList();
  451. static void set_max_regions(u_int32_t max_regions) {
  452. max_regions_ = max_regions;
  453. }
  454. static u_int32_t max_regions() { return max_regions_; }
  455. unsigned int region_count() const { return valid_ ? region_count_ : 0; }
  456. // Sequential access to memory regions.
  457. MinidumpMemoryRegion* GetMemoryRegionAtIndex(unsigned int index);
  458. // Random access to memory regions. Returns the region encompassing
  459. // the address identified by address.
  460. MinidumpMemoryRegion* GetMemoryRegionForAddress(u_int64_t address);
  461. // Print a human-readable representation of the object to stdout.
  462. void Print();
  463. private:
  464. friend class Minidump;
  465. typedef vector<MDMemoryDescriptor> MemoryDescriptors;
  466. typedef vector<MinidumpMemoryRegion> MemoryRegions;
  467. static const u_int32_t kStreamType = MD_MEMORY_LIST_STREAM;
  468. explicit MinidumpMemoryList(Minidump* minidump);
  469. bool Read(u_int32_t expected_size);
  470. // The largest number of memory regions that will be read from a minidump.
  471. // The default is 256.
  472. static u_int32_t max_regions_;
  473. // Access to memory regions using addresses as the key.
  474. RangeMap<u_int64_t, unsigned int> *range_map_;
  475. // The list of descriptors. This is maintained separately from the list
  476. // of regions, because MemoryRegion doesn't own its MemoryDescriptor, it
  477. // maintains a pointer to it. descriptors_ provides the storage for this
  478. // purpose.
  479. MemoryDescriptors *descriptors_;
  480. // The list of regions.
  481. MemoryRegions *regions_;
  482. u_int32_t region_count_;
  483. };
  484. // MinidumpException wraps MDRawExceptionStream, which contains information
  485. // about the exception that caused the minidump to be generated, if the
  486. // minidump was generated in an exception handler called as a result of
  487. // an exception. It also provides access to a MinidumpContext object,
  488. // which contains the CPU context for the exception thread at the time
  489. // the exception occurred.
  490. class MinidumpException : public MinidumpStream {
  491. public:
  492. virtual ~MinidumpException();
  493. const MDRawExceptionStream* exception() const {
  494. return valid_ ? &exception_ : NULL;
  495. }
  496. // The thread ID is used to determine if a thread is the exception thread,
  497. // so a special getter is provided to retrieve this data from the
  498. // MDRawExceptionStream structure. Returns false if the thread ID cannot
  499. // be determined.
  500. bool GetThreadID(u_int32_t *thread_id) const;
  501. MinidumpContext* GetContext();
  502. // Print a human-readable representation of the object to stdout.
  503. void Print();
  504. private:
  505. friend class Minidump;
  506. static const u_int32_t kStreamType = MD_EXCEPTION_STREAM;
  507. explicit MinidumpException(Minidump* minidump);
  508. bool Read(u_int32_t expected_size);
  509. MDRawExceptionStream exception_;
  510. MinidumpContext* context_;
  511. };
  512. // MinidumpAssertion wraps MDRawAssertionInfo, which contains information
  513. // about an assertion that caused the minidump to be generated.
  514. class MinidumpAssertion : public MinidumpStream {
  515. public:
  516. virtual ~MinidumpAssertion();
  517. const MDRawAssertionInfo* assertion() const {
  518. return valid_ ? &assertion_ : NULL;
  519. }
  520. string expression() const {
  521. return valid_ ? expression_ : "";
  522. }
  523. string function() const {
  524. return valid_ ? function_ : "";
  525. }
  526. string file() const {
  527. return valid_ ? file_ : "";
  528. }
  529. // Print a human-readable representation of the object to stdout.
  530. void Print();
  531. private:
  532. friend class Minidump;
  533. static const u_int32_t kStreamType = MD_ASSERTION_INFO_STREAM;
  534. explicit MinidumpAssertion(Minidump* minidump);
  535. bool Read(u_int32_t expected_size);
  536. MDRawAssertionInfo assertion_;
  537. string expression_;
  538. string function_;
  539. string file_;
  540. };
  541. // MinidumpSystemInfo wraps MDRawSystemInfo and provides information about
  542. // the system on which the minidump was generated. See also MinidumpMiscInfo.
  543. class MinidumpSystemInfo : public MinidumpStream {
  544. public:
  545. virtual ~MinidumpSystemInfo();
  546. const MDRawSystemInfo* system_info() const {
  547. return valid_ ? &system_info_ : NULL;
  548. }
  549. // GetOS and GetCPU return textual representations of the operating system
  550. // and CPU that produced the minidump. Unlike most other Minidump* methods,
  551. // they return string objects, not weak pointers. Defined values for
  552. // GetOS() are "mac", "windows", and "linux". Defined values for GetCPU
  553. // are "x86" and "ppc". These methods return an empty string when their
  554. // values are unknown.
  555. string GetOS();
  556. string GetCPU();
  557. // I don't know what CSD stands for, but this field is documented as
  558. // returning a textual representation of the OS service pack. On other
  559. // platforms, this provides additional information about an OS version
  560. // level beyond major.minor.micro. Returns NULL if unknown.
  561. const string* GetCSDVersion();
  562. // If a CPU vendor string can be determined, returns a pointer to it,
  563. // otherwise, returns NULL. CPU vendor strings can be determined from
  564. // x86 CPUs with CPUID 0.
  565. const string* GetCPUVendor();
  566. // Print a human-readable representation of the object to stdout.
  567. void Print();
  568. private:
  569. friend class Minidump;
  570. static const u_int32_t kStreamType = MD_SYSTEM_INFO_STREAM;
  571. explicit MinidumpSystemInfo(Minidump* minidump);
  572. bool Read(u_int32_t expected_size);
  573. MDRawSystemInfo system_info_;
  574. // Textual representation of the OS service pack, for minidumps produced
  575. // by MiniDumpWriteDump on Windows.
  576. const string* csd_version_;
  577. // A string identifying the CPU vendor, if known.
  578. const string* cpu_vendor_;
  579. };
  580. // MinidumpMiscInfo wraps MDRawMiscInfo and provides information about
  581. // the process that generated the minidump, and optionally additional system
  582. // information. See also MinidumpSystemInfo.
  583. class MinidumpMiscInfo : public MinidumpStream {
  584. public:
  585. const MDRawMiscInfo* misc_info() const {
  586. return valid_ ? &misc_info_ : NULL;
  587. }
  588. // Print a human-readable representation of the object to stdout.
  589. void Print();
  590. private:
  591. friend class Minidump;
  592. static const u_int32_t kStreamType = MD_MISC_INFO_STREAM;
  593. explicit MinidumpMiscInfo(Minidump* minidump_);
  594. bool Read(u_int32_t expected_size_);
  595. MDRawMiscInfo misc_info_;
  596. };
  597. // MinidumpBreakpadInfo wraps MDRawBreakpadInfo, which is an optional stream in
  598. // a minidump that provides additional information about the process state
  599. // at the time the minidump was generated.
  600. class MinidumpBreakpadInfo : public MinidumpStream {
  601. public:
  602. const MDRawBreakpadInfo* breakpad_info() const {
  603. return valid_ ? &breakpad_info_ : NULL;
  604. }
  605. // These thread IDs are used to determine if threads deserve special
  606. // treatment, so special getters are provided to retrieve this data from
  607. // the MDRawBreakpadInfo structure. The getters return false if the thread
  608. // IDs cannot be determined.
  609. bool GetDumpThreadID(u_int32_t *thread_id) const;
  610. bool GetRequestingThreadID(u_int32_t *thread_id) const;
  611. // Print a human-readable representation of the object to stdout.
  612. void Print();
  613. private:
  614. friend class Minidump;
  615. static const u_int32_t kStreamType = MD_BREAKPAD_INFO_STREAM;
  616. explicit MinidumpBreakpadInfo(Minidump* minidump_);
  617. bool Read(u_int32_t expected_size_);
  618. MDRawBreakpadInfo breakpad_info_;
  619. };
  620. // MinidumpMemoryInfo wraps MDRawMemoryInfo, which provides information
  621. // about mapped memory regions in a process, including their ranges
  622. // and protection.
  623. class MinidumpMemoryInfo : public MinidumpObject {
  624. public:
  625. const MDRawMemoryInfo* info() const { return valid_ ? &memory_info_ : NULL; }
  626. // The address of the base of the memory region.
  627. u_int64_t GetBase() const { return valid_ ? memory_info_.base_address : 0; }
  628. // The size, in bytes, of the memory region.
  629. u_int32_t GetSize() const { return valid_ ? memory_info_.region_size : 0; }
  630. // Return true if the memory protection allows execution.
  631. bool IsExecutable() const;
  632. // Return true if the memory protection allows writing.
  633. bool IsWritable() const;
  634. // Print a human-readable representation of the object to stdout.
  635. void Print();
  636. private:
  637. // These objects are managed by MinidumpMemoryInfoList.
  638. friend class MinidumpMemoryInfoList;
  639. explicit MinidumpMemoryInfo(Minidump* minidump);
  640. // This works like MinidumpStream::Read, but is driven by
  641. // MinidumpMemoryInfoList. No size checking is done, because
  642. // MinidumpMemoryInfoList handles that directly.
  643. bool Read();
  644. MDRawMemoryInfo memory_info_;
  645. };
  646. // MinidumpMemoryInfoList contains a list of information about
  647. // mapped memory regions for a process in the form of MDRawMemoryInfo.
  648. // It maintains a map of these structures so that it may easily provide
  649. // info corresponding to a specific address.
  650. class MinidumpMemoryInfoList : public MinidumpStream {
  651. public:
  652. virtual ~MinidumpMemoryInfoList();
  653. unsigned int info_count() const { return valid_ ? info_count_ : 0; }
  654. const MinidumpMemoryInfo* GetMemoryInfoForAddress(u_int64_t address) const;
  655. const MinidumpMemoryInfo* GetMemoryInfoAtIndex(unsigned int index) const;
  656. // Print a human-readable representation of the object to stdout.
  657. void Print();
  658. private:
  659. friend class Minidump;
  660. typedef vector<MinidumpMemoryInfo> MinidumpMemoryInfos;
  661. static const u_int32_t kStreamType = MD_MEMORY_INFO_LIST_STREAM;
  662. explicit MinidumpMemoryInfoList(Minidump* minidump);
  663. bool Read(u_int32_t expected_size);
  664. // Access to memory info using addresses as the key.
  665. RangeMap<u_int64_t, unsigned int> *range_map_;
  666. MinidumpMemoryInfos* infos_;
  667. u_int32_t info_count_;
  668. };
  669. // Minidump is the user's interface to a minidump file. It wraps MDRawHeader
  670. // and provides access to the minidump's top-level stream directory.
  671. class Minidump {
  672. public:
  673. // path is the pathname of a file containing the minidump.
  674. explicit Minidump(const string& path);
  675. // input is an istream wrapping minidump data. Minidump holds a
  676. // weak pointer to input, and the caller must ensure that the stream
  677. // is valid as long as the Minidump object is.
  678. explicit Minidump(std::istream& input);
  679. virtual ~Minidump();
  680. // path may be empty if the minidump was not opened from a file
  681. virtual string path() const {
  682. return path_;
  683. }
  684. static void set_max_streams(u_int32_t max_streams) {
  685. max_streams_ = max_streams;
  686. }
  687. static u_int32_t max_streams() { return max_streams_; }
  688. static void set_max_string_length(u_int32_t max_string_length) {
  689. max_string_length_ = max_string_length;
  690. }
  691. static u_int32_t max_string_length() { return max_string_length_; }
  692. virtual const MDRawHeader* header() const { return valid_ ? &header_ : NULL; }
  693. // Reads the minidump file's header and top-level stream directory.
  694. // The minidump is expected to be positioned at the beginning of the
  695. // header. Read() sets up the stream list and map, and validates the
  696. // Minidump object.
  697. virtual bool Read();
  698. // The next set of methods are stubs that call GetStream. They exist to
  699. // force code generation of the templatized API within the module, and
  700. // to avoid exposing an ugly API (GetStream needs to accept a garbage
  701. // parameter).
  702. virtual MinidumpThreadList* GetThreadList();
  703. MinidumpModuleList* GetModuleList();
  704. MinidumpMemoryList* GetMemoryList();
  705. MinidumpException* GetException();
  706. MinidumpAssertion* GetAssertion();
  707. MinidumpSystemInfo* GetSystemInfo();
  708. MinidumpMiscInfo* GetMiscInfo();
  709. MinidumpBreakpadInfo* GetBreakpadInfo();
  710. MinidumpMemoryInfoList* GetMemoryInfoList();
  711. // The next set of methods are provided for users who wish to access
  712. // data in minidump files directly, while leveraging the rest of
  713. // this class and related classes to handle the basic minidump
  714. // structure and known stream types.
  715. unsigned int GetDirectoryEntryCount() const {
  716. return valid_ ? header_.stream_count : 0;
  717. }
  718. const MDRawDirectory* GetDirectoryEntryAtIndex(unsigned int index) const;
  719. // The next 2 methods are lower-level I/O routines. They use fd_.
  720. // Reads count bytes from the minidump at the current position into
  721. // the storage area pointed to by bytes. bytes must be of sufficient
  722. // size. After the read, the file position is advanced by count.
  723. bool ReadBytes(void* bytes, size_t count);
  724. // Sets the position of the minidump file to offset.
  725. bool SeekSet(off_t offset);
  726. // Returns the current position of the minidump file.
  727. off_t Tell();
  728. // The next 2 methods are medium-level I/O routines.
  729. // ReadString returns a string which is owned by the caller! offset
  730. // specifies the offset that a length-encoded string is stored at in the
  731. // minidump file.
  732. string* ReadString(off_t offset);
  733. // SeekToStreamType positions the file at the beginning of a stream
  734. // identified by stream_type, and informs the caller of the stream's
  735. // length by setting *stream_length. Because stream_map maps each stream
  736. // type to only one stream in the file, this might mislead the user into
  737. // thinking that the stream that this seeks to is the only stream with
  738. // type stream_type. That can't happen for streams that these classes
  739. // deal with directly, because they're only supposed to be present in the
  740. // file singly, and that's verified when stream_map_ is built. Users who
  741. // are looking for other stream types should be aware of this
  742. // possibility, and consider using GetDirectoryEntryAtIndex (possibly
  743. // with GetDirectoryEntryCount) if expecting multiple streams of the same
  744. // type in a single minidump file.
  745. bool SeekToStreamType(u_int32_t stream_type, u_int32_t* stream_length);
  746. bool swap() const { return valid_ ? swap_ : false; }
  747. // Print a human-readable representation of the object to stdout.
  748. void Print();
  749. private:
  750. // MinidumpStreamInfo is used in the MinidumpStreamMap. It lets
  751. // the Minidump object locate interesting streams quickly, and
  752. // provides a convenient place to stash MinidumpStream objects.
  753. struct MinidumpStreamInfo {
  754. MinidumpStreamInfo() : stream_index(0), stream(NULL) {}
  755. ~MinidumpStreamInfo() { delete stream; }
  756. // Index into the MinidumpDirectoryEntries vector
  757. unsigned int stream_index;
  758. // Pointer to the stream if cached, or NULL if not yet populated
  759. MinidumpStream* stream;
  760. };
  761. typedef vector<MDRawDirectory> MinidumpDirectoryEntries;
  762. typedef map<u_int32_t, MinidumpStreamInfo> MinidumpStreamMap;
  763. template<typename T> T* GetStream(T** stream);
  764. // Opens the minidump file, or if already open, seeks to the beginning.
  765. bool Open();
  766. // The largest number of top-level streams that will be read from a minidump.
  767. // Note that streams are only read (and only consume memory) as needed,
  768. // when directed by the caller. The default is 128.
  769. static u_int32_t max_streams_;
  770. // The maximum length of a UTF-16 string that will be read from a minidump
  771. // in 16-bit words. The default is 1024. UTF-16 strings are converted
  772. // to UTF-8 when stored in memory, and each UTF-16 word will be represented
  773. // by as many as 3 bytes in UTF-8.
  774. static unsigned int max_string_length_;
  775. MDRawHeader header_;
  776. // The list of streams.
  777. MinidumpDirectoryEntries* directory_;
  778. // Access to streams using the stream type as the key.
  779. MinidumpStreamMap* stream_map_;
  780. // The pathname of the minidump file to process, set in the constructor.
  781. // This may be empty if the minidump was opened directly from a stream.
  782. const string path_;
  783. // The stream for all file I/O. Used by ReadBytes and SeekSet.
  784. // Set based on the path in Open, or directly in the constructor.
  785. std::istream* stream_;
  786. // swap_ is true if the minidump file should be byte-swapped. If the
  787. // minidump was produced by a CPU that is other-endian than the CPU
  788. // processing the minidump, this will be true. If the two CPUs are
  789. // same-endian, this will be false.
  790. bool swap_;
  791. // Validity of the Minidump structure, false immediately after
  792. // construction or after a failed Read(); true following a successful
  793. // Read().
  794. bool valid_;
  795. };
  796. } // namespace google_breakpad
  797. #endif // GOOGLE_BREAKPAD_PROCESSOR_MINIDUMP_H__