minidump.h
1 // Copyright 2010 Google LLC 2 // 3 // Redistribution and use in source and binary forms, with or without 4 // modification, are permitted provided that the following conditions are 5 // met: 6 // 7 // * Redistributions of source code must retain the above copyright 8 // notice, this list of conditions and the following disclaimer. 9 // * Redistributions in binary form must reproduce the above 10 // copyright notice, this list of conditions and the following disclaimer 11 // in the documentation and/or other materials provided with the 12 // distribution. 13 // * Neither the name of Google LLC nor the names of its 14 // contributors may be used to endorse or promote products derived from 15 // this software without specific prior written permission. 16 // 17 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28 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 78 #ifndef GOOGLE_BREAKPAD_PROCESSOR_MINIDUMP_H__ 79 #define GOOGLE_BREAKPAD_PROCESSOR_MINIDUMP_H__ 80 81 #include <stdint.h> 82 83 #ifndef _WIN32 84 #include <unistd.h> 85 #endif 86 87 #include <iostream> 88 #include <map> 89 #include <string> 90 #include <vector> 91 92 #include "common/using_std_string.h" 93 #include "google_breakpad/processor/code_module.h" 94 #include "google_breakpad/processor/code_modules.h" 95 #include "google_breakpad/processor/dump_context.h" 96 #include "google_breakpad/processor/dump_object.h" 97 #include "google_breakpad/processor/memory_region.h" 98 #include "google_breakpad/processor/proc_maps_linux.h" 99 100 101 namespace google_breakpad { 102 103 104 using std::map; 105 using std::vector; 106 107 108 class Minidump; 109 template<typename AddressType, typename EntryType> class RangeMap; 110 111 112 // MinidumpObject is the base of all Minidump* objects except for Minidump 113 // itself. 114 class MinidumpObject : public DumpObject { 115 public: 116 virtual ~MinidumpObject() = default; 117 118 protected: 119 explicit MinidumpObject(Minidump* minidump); 120 121 // Refers to the Minidump object that is the ultimate parent of this 122 // Some MinidumpObjects are owned by other MinidumpObjects, but at the 123 // root of the ownership tree is always a Minidump. The Minidump object 124 // is kept here for access to its seeking and reading facilities, and 125 // for access to data about the minidump file itself, such as whether 126 // it should be byte-swapped. 127 Minidump* minidump_; 128 }; 129 130 131 // This class exists primarily to provide a virtual destructor in a base 132 // class common to all objects that might be stored in 133 // Minidump::mStreamObjects. Some object types will never be stored in 134 // Minidump::mStreamObjects, but are represented as streams and adhere to the 135 // same interface, and may be derived from this class. 136 class MinidumpStream : public MinidumpObject { 137 public: 138 MinidumpStream(const MinidumpStream&) = delete; 139 void operator=(const MinidumpStream&) = delete; 140 ~MinidumpStream() override = default; 141 142 protected: 143 explicit MinidumpStream(Minidump* minidump); 144 145 private: 146 // Populate (and validate) the MinidumpStream. minidump_ is expected 147 // to be positioned at the beginning of the stream, so that the next 148 // read from the minidump will be at the beginning of the stream. 149 // expected_size should be set to the stream's length as contained in 150 // the MDRawDirectory record or other identifying record. A class 151 // that implements MinidumpStream can compare expected_size to a 152 // known size as an integrity check. 153 virtual bool Read(uint32_t expected_size) = 0; 154 }; 155 156 157 // MinidumpContext carries a CPU-specific MDRawContext structure, which 158 // contains CPU context such as register states. Each thread has its 159 // own context, and the exception record, if present, also has its own 160 // context. Note that if the exception record is present, the context it 161 // refers to is probably what the user wants to use for the exception 162 // thread, instead of that thread's own context. The exception thread's 163 // context (as opposed to the exception record's context) will contain 164 // context for the exception handler (which performs minidump generation), 165 // and not the context that caused the exception (which is probably what the 166 // user wants). 167 class MinidumpContext : public DumpContext { 168 public: 169 MinidumpContext(const MinidumpContext&) = delete; 170 void operator=(const MinidumpContext&) = delete; 171 ~MinidumpContext() override; 172 173 protected: 174 explicit MinidumpContext(Minidump* minidump); 175 176 private: 177 friend class MinidumpThread; 178 friend class MinidumpException; 179 180 bool Read(uint32_t expected_size); 181 182 // If the minidump contains a SYSTEM_INFO_STREAM, makes sure that the 183 // system info stream gives an appropriate CPU type matching the context 184 // CPU type in context_cpu_type. Returns false if the CPU type does not 185 // match. Returns true if the CPU type matches or if the minidump does 186 // not contain a system info stream. 187 bool CheckAgainstSystemInfo(uint32_t context_cpu_type); 188 189 // Refers to the Minidump object that is the ultimate parent of this 190 // Some MinidumpObjects are owned by other MinidumpObjects, but at the 191 // root of the ownership tree is always a Minidump. The Minidump object 192 // is kept here for access to its seeking and reading facilities, and 193 // for access to data about the minidump file itself, such as whether 194 // it should be byte-swapped. 195 Minidump* minidump_; 196 }; 197 198 199 // MinidumpMemoryRegion does not wrap any MDRaw structure, and only contains 200 // a reference to an MDMemoryDescriptor. This object is intended to wrap 201 // portions of a minidump file that contain memory dumps. In normal 202 // minidumps, each MinidumpThread owns a MinidumpMemoryRegion corresponding 203 // to the thread's stack memory. MinidumpMemoryList also gives access to 204 // memory regions in its list as MinidumpMemoryRegions. This class 205 // adheres to MemoryRegion so that it may be used as a data provider to 206 // the Stackwalker family of classes. 207 class MinidumpMemoryRegion : public MinidumpObject, 208 public MemoryRegion { 209 public: 210 ~MinidumpMemoryRegion() override; 211 212 static void set_max_bytes(uint32_t max_bytes) { max_bytes_ = max_bytes; } 213 static uint32_t max_bytes() { return max_bytes_; } 214 215 // Returns a pointer to the base of the memory region. Returns the 216 // cached value if available, otherwise, reads the minidump file and 217 // caches the memory region. 218 const uint8_t* GetMemory() const; 219 220 // The address of the base of the memory region. 221 uint64_t GetBase() const override; 222 223 // The size, in bytes, of the memory region. 224 uint32_t GetSize() const override; 225 226 // Frees the cached memory region, if cached. 227 void FreeMemory(); 228 229 // Obtains the value of memory at the pointer specified by address. 230 bool GetMemoryAtAddress(uint64_t address, uint8_t* value) const override; 231 bool GetMemoryAtAddress(uint64_t address, uint16_t* value) const override; 232 bool GetMemoryAtAddress(uint64_t address, uint32_t* value) const override; 233 bool GetMemoryAtAddress(uint64_t address, uint64_t* value) const override; 234 235 // Print a human-readable representation of the object to stdout. 236 void Print() const override; 237 void SetPrintMode(bool hexdump, unsigned int width); 238 239 protected: 240 explicit MinidumpMemoryRegion(Minidump* minidump); 241 242 private: 243 friend class MinidumpThread; 244 friend class MinidumpMemoryList; 245 246 // Identify the base address and size of the memory region, and the 247 // location it may be found in the minidump file. 248 void SetDescriptor(MDMemoryDescriptor* descriptor); 249 250 // Implementation for GetMemoryAtAddress 251 template<typename T> bool GetMemoryAtAddressInternal(uint64_t address, 252 T* value) const; 253 254 // Knobs for controlling display of memory printing. 255 bool hexdump_; 256 unsigned int hexdump_width_; 257 258 // The largest memory region that will be read from a minidump. 259 static uint32_t max_bytes_; 260 261 // Base address and size of the memory region, and its position in the 262 // minidump file. 263 MDMemoryDescriptor* descriptor_; 264 265 // Cached memory. 266 mutable vector<uint8_t>* memory_; 267 }; 268 269 270 // MinidumpThread contains information about a thread of execution, 271 // including a snapshot of the thread's stack and CPU context. For 272 // the thread that caused an exception, the context carried by 273 // MinidumpException is probably desired instead of the CPU context 274 // provided here. 275 // Note that a MinidumpThread may be valid() even if it does not 276 // contain a memory region or context. 277 class MinidumpThread : public MinidumpObject { 278 public: 279 ~MinidumpThread() override; 280 281 const MDRawThread* thread() const { return valid_ ? &thread_ : nullptr; } 282 // GetMemory may return NULL even if the MinidumpThread is valid, 283 // if the thread memory cannot be read. 284 virtual MinidumpMemoryRegion* GetMemory(); 285 // GetContext may return NULL even if the MinidumpThread is valid. 286 virtual MinidumpContext* GetContext(); 287 288 // The thread ID is used to determine if a thread is the exception thread, 289 // so a special getter is provided to retrieve this data from the 290 // MDRawThread structure. Returns false if the thread ID cannot be 291 // determined. 292 virtual bool GetThreadID(uint32_t* thread_id) const; 293 294 // Print a human-readable representation of the object to stdout. 295 void Print(); 296 297 // Returns the start address of the thread stack memory region. Returns 0 if 298 // MinidumpThread is invalid. Note that this method can be called even when 299 // the thread memory cannot be read and GetMemory returns NULL. 300 virtual uint64_t GetStartOfStackMemoryRange() const; 301 302 protected: 303 explicit MinidumpThread(Minidump* minidump); 304 305 private: 306 // These objects are managed by MinidumpThreadList. 307 friend class MinidumpThreadList; 308 309 // This works like MinidumpStream::Read, but is driven by 310 // MinidumpThreadList. No size checking is done, because 311 // MinidumpThreadList handles that directly. 312 bool Read(); 313 314 MDRawThread thread_; 315 MinidumpMemoryRegion* memory_; 316 MinidumpContext* context_; 317 }; 318 319 320 // MinidumpThreadList contains all of the threads (as MinidumpThreads) in 321 // a process. 322 class MinidumpThreadList : public MinidumpStream { 323 public: 324 MinidumpThreadList(const MinidumpThreadList&) = delete; 325 void operator=(const MinidumpThreadList&) = delete; 326 ~MinidumpThreadList() override; 327 328 static void set_max_threads(uint32_t max_threads) { 329 max_threads_ = max_threads; 330 } 331 static uint32_t max_threads() { return max_threads_; } 332 333 virtual unsigned int thread_count() const { 334 return valid_ ? thread_count_ : 0; 335 } 336 337 // Sequential access to threads. 338 virtual MinidumpThread* GetThreadAtIndex(unsigned int index) const; 339 340 // Random access to threads. 341 MinidumpThread* GetThreadByID(uint32_t thread_id); 342 343 // Print a human-readable representation of the object to stdout. 344 void Print(); 345 346 protected: 347 explicit MinidumpThreadList(Minidump* aMinidump); 348 349 private: 350 friend class Minidump; 351 352 typedef map<uint32_t, MinidumpThread*> IDToThreadMap; 353 typedef vector<MinidumpThread> MinidumpThreads; 354 355 static const uint32_t kStreamType = MD_THREAD_LIST_STREAM; 356 357 bool Read(uint32_t aExpectedSize) override; 358 359 // The largest number of threads that will be read from a minidump. The 360 // default is 256. 361 static uint32_t max_threads_; 362 363 // Access to threads using the thread ID as the key. 364 IDToThreadMap id_to_thread_map_; 365 366 // The list of threads. 367 MinidumpThreads* threads_; 368 uint32_t thread_count_; 369 }; 370 371 // MinidumpThreadName contains the name of a thread. 372 class MinidumpThreadName : public MinidumpObject { 373 public: 374 ~MinidumpThreadName() override; 375 376 const MDRawThreadName* thread_name() const { 377 return valid_ ? &thread_name_ : nullptr; 378 } 379 380 // Gets the thread ID. 381 virtual bool GetThreadID(uint32_t* thread_id) const; 382 383 // Print a human-readable representation of the object to stdout. 384 void Print(); 385 386 // Returns the name of the thread. 387 virtual std::string GetThreadName() const; 388 389 protected: 390 explicit MinidumpThreadName(Minidump* minidump); 391 392 private: 393 // These objects are managed by MinidumpThreadNameList. 394 friend class MinidumpThreadNameList; 395 396 // This works like MinidumpStream::Read, but is driven by 397 // MinidumpThreadNameList. No size checking is done, because 398 // MinidumpThreadNameList handles that directly. 399 bool Read(); 400 401 // Reads indirectly-referenced data, including the thread name. 402 bool ReadAuxiliaryData(); 403 404 // True after a successful Read. This is different from valid_, which is not 405 // set true until ReadAuxiliaryData also completes successfully. 406 // thread_name_valid_ is only used by ReadAuxiliaryData and the functions it 407 // calls to determine whether the object is ready for auxiliary data to be 408 // read. 409 bool thread_name_valid_; 410 411 MDRawThreadName thread_name_; 412 413 // Cached thread name. 414 const string* name_; 415 }; 416 417 // MinidumpThreadNameList contains all of the names of the threads (as 418 // MinidumpThreadNames) in a process. 419 class MinidumpThreadNameList : public MinidumpStream { 420 public: 421 MinidumpThreadNameList(const MinidumpThreadNameList&) = delete; 422 void operator=(const MinidumpThreadNameList&) = delete; 423 ~MinidumpThreadNameList() override; 424 425 virtual unsigned int thread_name_count() const { 426 return valid_ ? thread_name_count_ : 0; 427 } 428 429 // Sequential access to thread names. 430 virtual MinidumpThreadName* GetThreadNameAtIndex(unsigned int index) const; 431 432 // Print a human-readable representation of the object to stdout. 433 void Print(); 434 435 protected: 436 explicit MinidumpThreadNameList(Minidump* aMinidump); 437 438 private: 439 friend class Minidump; 440 441 typedef vector<MinidumpThreadName> MinidumpThreadNames; 442 443 static const uint32_t kStreamType = MD_THREAD_NAME_LIST_STREAM; 444 445 bool Read(uint32_t aExpectedSize) override; 446 447 // The list of thread names. 448 MinidumpThreadNames* thread_names_; 449 uint32_t thread_name_count_; 450 }; 451 452 // MinidumpModule wraps MDRawModule, which contains information about loaded 453 // code modules. Access is provided to various data referenced indirectly 454 // by MDRawModule, such as the module's name and a specification for where 455 // to locate debugging information for the module. 456 class MinidumpModule : public MinidumpObject, 457 public CodeModule { 458 public: 459 ~MinidumpModule() override; 460 461 static void set_max_cv_bytes(uint32_t max_cv_bytes) { 462 max_cv_bytes_ = max_cv_bytes; 463 } 464 static uint32_t max_cv_bytes() { return max_cv_bytes_; } 465 466 static void set_max_misc_bytes(uint32_t max_misc_bytes) { 467 max_misc_bytes_ = max_misc_bytes; 468 } 469 static uint32_t max_misc_bytes() { return max_misc_bytes_; } 470 471 const MDRawModule* module() const { return valid_ ? &module_ : nullptr; } 472 473 // CodeModule implementation 474 uint64_t base_address() const override { 475 return valid_ ? module_.base_of_image : static_cast<uint64_t>(-1); 476 } 477 uint64_t size() const override { return valid_ ? module_.size_of_image : 0; } 478 string code_file() const override; 479 string code_identifier() const override; 480 string debug_file() const override; 481 string debug_identifier() const override; 482 string version() const override; 483 CodeModule* Copy() const override; 484 bool is_unloaded() const override { return false; } 485 486 // Getter and setter for shrink_down_delta. This is used when the address 487 // range for a module is shrunk down due to address range conflicts with 488 // other modules. The base_address and size fields are not updated and they 489 // should always reflect the original values (reported in the minidump). 490 uint64_t shrink_down_delta() const override; 491 void SetShrinkDownDelta(uint64_t shrink_down_delta) override; 492 493 // The CodeView record, which contains information to locate the module's 494 // debugging information (pdb). This is returned as uint8_t* because 495 // the data can be of types MDCVInfoPDB20* or MDCVInfoPDB70*, or it may be 496 // of a type unknown to Breakpad, in which case the raw data will still be 497 // returned but no byte-swapping will have been performed. Check the 498 // record's signature in the first four bytes to differentiate between 499 // the various types. Current toolchains generate modules which carry 500 // MDCVInfoPDB70 by default. Returns a pointer to the CodeView record on 501 // success, and NULL on failure. On success, the optional |size| argument 502 // is set to the size of the CodeView record. 503 const uint8_t* GetCVRecord(uint32_t* size); 504 505 // The miscellaneous debug record, which is obsolete. Current toolchains 506 // do not generate this type of debugging information (dbg), and this 507 // field is not expected to be present. Returns a pointer to the debugging 508 // record on success, and NULL on failure. On success, the optional |size| 509 // argument is set to the size of the debugging record. 510 const MDImageDebugMisc* GetMiscRecord(uint32_t* size); 511 512 // Print a human-readable representation of the object to stdout. 513 void Print(); 514 515 private: 516 // These objects are managed by MinidumpModuleList. 517 friend class MinidumpModuleList; 518 519 explicit MinidumpModule(Minidump* minidump); 520 521 // This works like MinidumpStream::Read, but is driven by 522 // MinidumpModuleList. No size checking is done, because 523 // MinidumpModuleList handles that directly. 524 bool Read(); 525 526 // Reads indirectly-referenced data, including the module name, CodeView 527 // record, and miscellaneous debugging record. This is necessary to allow 528 // MinidumpModuleList to fully construct MinidumpModule objects without 529 // requiring seeks to read a contiguous set of MinidumpModule objects. 530 // All auxiliary data should be available when Read is called, in order to 531 // allow the CodeModule getters to be const methods. 532 bool ReadAuxiliaryData(); 533 534 // The largest number of bytes that will be read from a minidump for a 535 // CodeView record or miscellaneous debugging record, respectively. The 536 // default for each is 1024. 537 static uint32_t max_cv_bytes_; 538 static uint32_t max_misc_bytes_; 539 540 // True after a successful Read. This is different from valid_, which is 541 // not set true until ReadAuxiliaryData also completes successfully. 542 // module_valid_ is only used by ReadAuxiliaryData and the functions it 543 // calls to determine whether the object is ready for auxiliary data to 544 // be read. 545 bool module_valid_; 546 547 // True if debug info was read from the module. Certain modules 548 // may contain debug records in formats we don't support, 549 // so we can just set this to false to ignore them. 550 bool has_debug_info_; 551 552 MDRawModule module_; 553 554 // Cached module name. 555 const string* name_; 556 557 // Cached CodeView record - this is MDCVInfoPDB20 or (likely) 558 // MDCVInfoPDB70, or possibly something else entirely. Stored as a uint8_t 559 // because the structure contains a variable-sized string and its exact 560 // size cannot be known until it is processed. 561 vector<uint8_t>* cv_record_; 562 563 // If cv_record_ is present, cv_record_signature_ contains a copy of the 564 // CodeView record's first four bytes, for ease of determinining the 565 // type of structure that cv_record_ contains. 566 uint32_t cv_record_signature_; 567 568 // Cached MDImageDebugMisc (usually not present), stored as uint8_t 569 // because the structure contains a variable-sized string and its exact 570 // size cannot be known until it is processed. 571 vector<uint8_t>* misc_record_; 572 }; 573 574 575 // MinidumpModuleList contains all of the loaded code modules for a process 576 // in the form of MinidumpModules. It maintains a map of these modules 577 // so that it may easily provide a code module corresponding to a specific 578 // address. 579 class MinidumpModuleList : public MinidumpStream, 580 public CodeModules { 581 public: 582 MinidumpModuleList(const MinidumpModuleList&) = delete; 583 void operator=(const MinidumpModuleList&) = delete; 584 ~MinidumpModuleList() override; 585 586 static void set_max_modules(uint32_t max_modules) { 587 max_modules_ = max_modules; 588 } 589 static uint32_t max_modules() { return max_modules_; } 590 591 // CodeModules implementation. 592 unsigned int module_count() const override { 593 return valid_ ? module_count_ : 0; 594 } 595 const MinidumpModule* GetModuleForAddress(uint64_t address) const override; 596 const MinidumpModule* GetMainModule() const override; 597 const MinidumpModule* GetModuleAtSequence( 598 unsigned int sequence) const override; 599 const MinidumpModule* GetModuleAtIndex(unsigned int index) const override; 600 const CodeModules* Copy() const override; 601 602 // Returns a vector of all modules which address ranges needed to be shrunk 603 // down due to address range conflicts with other modules. 604 vector<linked_ptr<const CodeModule>> GetShrunkRangeModules() const override; 605 606 // Print a human-readable representation of the object to stdout. 607 void Print(); 608 609 protected: 610 explicit MinidumpModuleList(Minidump* minidump); 611 612 private: 613 friend class Minidump; 614 615 typedef vector<MinidumpModule> MinidumpModules; 616 617 static const uint32_t kStreamType = MD_MODULE_LIST_STREAM; 618 619 bool Read(uint32_t expected_size) override; 620 621 bool StoreRange(const MinidumpModule& module, 622 uint64_t base_address, 623 uint32_t module_index, 624 uint32_t module_count, 625 bool is_android); 626 627 // The largest number of modules that will be read from a minidump. The 628 // default is 1024. 629 static uint32_t max_modules_; 630 631 // Access to modules using addresses as the key. 632 RangeMap<uint64_t, unsigned int>* range_map_; 633 634 MinidumpModules* modules_; 635 uint32_t module_count_; 636 }; 637 638 639 // MinidumpMemoryList corresponds to a minidump's MEMORY_LIST_STREAM stream, 640 // which references the snapshots of all of the memory regions contained 641 // within the minidump. For a normal minidump, this includes stack memory 642 // (also referenced by each MinidumpThread, in fact, the MDMemoryDescriptors 643 // here and in MDRawThread both point to exactly the same data in a 644 // minidump file, conserving space), as well as a 256-byte snapshot of memory 645 // surrounding the instruction pointer in the case of an exception. Other 646 // types of minidumps may contain significantly more memory regions. Full- 647 // memory minidumps contain all of a process' mapped memory. 648 class MinidumpMemoryList : public MinidumpStream { 649 public: 650 MinidumpMemoryList(const MinidumpMemoryList&) = delete; 651 void operator=(const MinidumpMemoryList&) = delete; 652 ~MinidumpMemoryList() override; 653 654 static void set_max_regions(uint32_t max_regions) { 655 max_regions_ = max_regions; 656 } 657 static uint32_t max_regions() { return max_regions_; } 658 659 unsigned int region_count() const { return valid_ ? region_count_ : 0; } 660 661 // Sequential access to memory regions. 662 MinidumpMemoryRegion* GetMemoryRegionAtIndex(unsigned int index); 663 664 // Random access to memory regions. Returns the region encompassing 665 // the address identified by address. 666 virtual MinidumpMemoryRegion* GetMemoryRegionForAddress(uint64_t address); 667 668 // Print a human-readable representation of the object to stdout. 669 void Print(); 670 671 private: 672 friend class Minidump; 673 friend class MockMinidumpMemoryList; 674 675 typedef vector<MDMemoryDescriptor> MemoryDescriptors; 676 typedef vector<MinidumpMemoryRegion> MemoryRegions; 677 678 static const uint32_t kStreamType = MD_MEMORY_LIST_STREAM; 679 680 explicit MinidumpMemoryList(Minidump* minidump); 681 682 bool Read(uint32_t expected_size) override; 683 684 // The largest number of memory regions that will be read from a minidump. 685 // The default is 256. 686 static uint32_t max_regions_; 687 688 // Access to memory regions using addresses as the key. 689 RangeMap<uint64_t, unsigned int>* range_map_; 690 691 // The list of descriptors. This is maintained separately from the list 692 // of regions, because MemoryRegion doesn't own its MemoryDescriptor, it 693 // maintains a pointer to it. descriptors_ provides the storage for this 694 // purpose. 695 MemoryDescriptors* descriptors_; 696 697 // The list of regions. 698 MemoryRegions* regions_; 699 uint32_t region_count_; 700 }; 701 702 703 // MinidumpException wraps MDRawExceptionStream, which contains information 704 // about the exception that caused the minidump to be generated, if the 705 // minidump was generated in an exception handler called as a result of an 706 // exception. It also provides access to a MinidumpContext object, which 707 // contains the CPU context for the exception thread at the time the exception 708 // occurred. 709 class MinidumpException : public MinidumpStream { 710 public: 711 MinidumpException(const MinidumpException&) = delete; 712 void operator=(const MinidumpException&) = delete; 713 ~MinidumpException() override; 714 715 const MDRawExceptionStream* exception() const { 716 return valid_ ? &exception_ : nullptr; 717 } 718 719 // The thread ID is used to determine if a thread is the exception thread, 720 // so a special getter is provided to retrieve this data from the 721 // MDRawExceptionStream structure. Returns false if the thread ID cannot 722 // be determined. 723 bool GetThreadID(uint32_t* thread_id) const; 724 725 MinidumpContext* GetContext(); 726 727 // Print a human-readable representation of the object to stdout. 728 void Print(); 729 730 private: 731 friend class Minidump; 732 733 static const uint32_t kStreamType = MD_EXCEPTION_STREAM; 734 735 explicit MinidumpException(Minidump* minidump); 736 737 bool Read(uint32_t expected_size) override; 738 739 MDRawExceptionStream exception_; 740 MinidumpContext* context_; 741 }; 742 743 // MinidumpAssertion wraps MDRawAssertionInfo, which contains information 744 // about an assertion that caused the minidump to be generated. 745 class MinidumpAssertion : public MinidumpStream { 746 public: 747 MinidumpAssertion(const MinidumpAssertion&) = delete; 748 void operator=(const MinidumpAssertion&) = delete; 749 ~MinidumpAssertion() override; 750 751 const MDRawAssertionInfo* assertion() const { 752 return valid_ ? &assertion_ : nullptr; 753 } 754 755 string expression() const { 756 return valid_ ? expression_ : ""; 757 } 758 759 string function() const { 760 return valid_ ? function_ : ""; 761 } 762 763 string file() const { 764 return valid_ ? file_ : ""; 765 } 766 767 // Print a human-readable representation of the object to stdout. 768 void Print(); 769 770 private: 771 friend class Minidump; 772 773 static const uint32_t kStreamType = MD_ASSERTION_INFO_STREAM; 774 775 explicit MinidumpAssertion(Minidump* minidump); 776 777 bool Read(uint32_t expected_size) override; 778 779 MDRawAssertionInfo assertion_; 780 string expression_; 781 string function_; 782 string file_; 783 }; 784 785 786 // MinidumpSystemInfo wraps MDRawSystemInfo and provides information about 787 // the system on which the minidump was generated. See also MinidumpMiscInfo. 788 class MinidumpSystemInfo : public MinidumpStream { 789 public: 790 MinidumpSystemInfo(const MinidumpSystemInfo&) = delete; 791 void operator=(const MinidumpSystemInfo&) = delete; 792 ~MinidumpSystemInfo() override; 793 794 const MDRawSystemInfo* system_info() const { 795 return valid_ ? &system_info_ : nullptr; 796 } 797 798 // GetOS and GetCPU return textual representations of the operating system 799 // and CPU that produced the minidump. Unlike most other Minidump* methods, 800 // they return string objects, not weak pointers. Defined values for 801 // GetOS() are "mac", "windows", and "linux". Defined values for GetCPU 802 // are "x86" and "ppc". These methods return an empty string when their 803 // values are unknown. 804 string GetOS(); 805 string GetCPU(); 806 807 // I don't know what CSD stands for, but this field is documented as 808 // returning a textual representation of the OS service pack. On other 809 // platforms, this provides additional information about an OS version 810 // level beyond major.minor.micro. Returns NULL if unknown. 811 const string* GetCSDVersion(); 812 813 // If a CPU vendor string can be determined, returns a pointer to it, 814 // otherwise, returns NULL. CPU vendor strings can be determined from 815 // x86 CPUs with CPUID 0. 816 const string* GetCPUVendor(); 817 818 // Print a human-readable representation of the object to stdout. 819 void Print(); 820 821 protected: 822 explicit MinidumpSystemInfo(Minidump* minidump); 823 MDRawSystemInfo system_info_; 824 825 // Textual representation of the OS service pack, for minidumps produced 826 // by MiniDumpWriteDump on Windows. 827 const string* csd_version_; 828 829 private: 830 friend class Minidump; 831 832 static const uint32_t kStreamType = MD_SYSTEM_INFO_STREAM; 833 834 bool Read(uint32_t expected_size) override; 835 836 // A string identifying the CPU vendor, if known. 837 const string* cpu_vendor_; 838 }; 839 840 841 // MinidumpUnloadedModule wraps MDRawUnloadedModule 842 class MinidumpUnloadedModule : public MinidumpObject, 843 public CodeModule { 844 public: 845 ~MinidumpUnloadedModule() override; 846 847 const MDRawUnloadedModule* module() const { 848 return valid_ ? &unloaded_module_ : nullptr; 849 } 850 851 // CodeModule implementation 852 uint64_t base_address() const override { 853 return valid_ ? unloaded_module_.base_of_image : 0; 854 } 855 uint64_t size() const override { 856 return valid_ ? unloaded_module_.size_of_image : 0; 857 } 858 string code_file() const override; 859 string code_identifier() const override; 860 string debug_file() const override; 861 string debug_identifier() const override; 862 string version() const override; 863 CodeModule* Copy() const override; 864 bool is_unloaded() const override { return true; } 865 uint64_t shrink_down_delta() const override; 866 void SetShrinkDownDelta(uint64_t shrink_down_delta) override; 867 868 protected: 869 explicit MinidumpUnloadedModule(Minidump* minidump); 870 871 private: 872 // These objects are managed by MinidumpUnloadedModuleList 873 friend class MinidumpUnloadedModuleList; 874 875 // This works like MinidumpStream::Read, but is driven by 876 // MinidumpUnloadedModuleList. 877 bool Read(uint32_t expected_size); 878 879 // Reads the module name. This is done separately from Read to 880 // allow contiguous reading of code modules by MinidumpUnloadedModuleList. 881 bool ReadAuxiliaryData(); 882 883 // True after a successful Read. This is different from valid_, which 884 // is not set true until ReadAuxiliaryData also completes successfully. 885 // module_valid_ is only used by ReadAuxiliaryData and the functions it 886 // calls to determine whether the object is ready for auxiliary data to 887 // be read. 888 bool module_valid_; 889 890 MDRawUnloadedModule unloaded_module_; 891 892 // Cached module name 893 const string* name_; 894 }; 895 896 897 // MinidumpUnloadedModuleList contains all the unloaded code modules for a 898 // process in the form of MinidumpUnloadedModules. It maintains a map of 899 // these modules so that it may easily provide a code module corresponding 900 // to a specific address. If multiple modules in the list have identical 901 // ranges, only the first module encountered is recorded in the range map. 902 class MinidumpUnloadedModuleList : public MinidumpStream, 903 public CodeModules { 904 public: 905 MinidumpUnloadedModuleList(const MinidumpUnloadedModuleList&) = delete; 906 void operator=(const MinidumpUnloadedModuleList&) = delete; 907 ~MinidumpUnloadedModuleList() override; 908 909 static void set_max_modules(uint32_t max_modules) { 910 max_modules_ = max_modules; 911 } 912 static uint32_t max_modules() { return max_modules_; } 913 914 // CodeModules implementation. 915 unsigned int module_count() const override { 916 return valid_ ? module_count_ : 0; 917 } 918 const MinidumpUnloadedModule* 919 GetModuleForAddress(uint64_t address) const override; 920 const MinidumpUnloadedModule* GetMainModule() const override; 921 const MinidumpUnloadedModule* 922 GetModuleAtSequence(unsigned int sequence) const override; 923 const MinidumpUnloadedModule* 924 GetModuleAtIndex(unsigned int index) const override; 925 const CodeModules* Copy() const override; 926 vector<linked_ptr<const CodeModule>> GetShrunkRangeModules() const override; 927 928 protected: 929 explicit MinidumpUnloadedModuleList(Minidump* minidump_); 930 931 private: 932 friend class Minidump; 933 934 typedef vector<MinidumpUnloadedModule> MinidumpUnloadedModules; 935 936 static const uint32_t kStreamType = MD_UNLOADED_MODULE_LIST_STREAM; 937 938 bool Read(uint32_t expected_size_) override; 939 940 // The largest number of modules that will be read from a minidump. The 941 // default is 1024. 942 static uint32_t max_modules_; 943 944 // Access to module indices using addresses as the key. 945 RangeMap<uint64_t, unsigned int>* range_map_; 946 947 MinidumpUnloadedModules* unloaded_modules_; 948 uint32_t module_count_; 949 }; 950 951 952 // MinidumpMiscInfo wraps MDRawMiscInfo and provides information about 953 // the process that generated the minidump, and optionally additional system 954 // information. See also MinidumpSystemInfo. 955 class MinidumpMiscInfo : public MinidumpStream { 956 public: 957 MinidumpMiscInfo(const MinidumpMiscInfo&) = delete; 958 void operator=(const MinidumpMiscInfo&) = delete; 959 960 const MDRawMiscInfo* misc_info() const { 961 return valid_ ? &misc_info_ : nullptr; 962 } 963 964 // Print a human-readable representation of the object to stdout. 965 void Print(); 966 967 private: 968 friend class Minidump; 969 friend class TestMinidumpMiscInfo; 970 971 static const uint32_t kStreamType = MD_MISC_INFO_STREAM; 972 973 explicit MinidumpMiscInfo(Minidump* minidump_); 974 975 bool Read(uint32_t expected_size_) override; 976 977 MDRawMiscInfo misc_info_; 978 979 // Populated by Read. Contains the converted strings from the corresponding 980 // UTF-16 fields in misc_info_ 981 string standard_name_; 982 string daylight_name_; 983 string build_string_; 984 string dbg_bld_str_; 985 }; 986 987 988 // MinidumpBreakpadInfo wraps MDRawBreakpadInfo, which is an optional stream in 989 // a minidump that provides additional information about the process state 990 // at the time the minidump was generated. 991 class MinidumpBreakpadInfo : public MinidumpStream { 992 public: 993 MinidumpBreakpadInfo(const MinidumpBreakpadInfo&) = delete; 994 void operator=(const MinidumpBreakpadInfo&) = delete; 995 996 const MDRawBreakpadInfo* breakpad_info() const { 997 return valid_ ? &breakpad_info_ : nullptr; 998 } 999 1000 // These thread IDs are used to determine if threads deserve special 1001 // treatment, so special getters are provided to retrieve this data from 1002 // the MDRawBreakpadInfo structure. The getters return false if the thread 1003 // IDs cannot be determined. 1004 bool GetDumpThreadID(uint32_t* thread_id) const; 1005 bool GetRequestingThreadID(uint32_t* thread_id) const; 1006 1007 // Print a human-readable representation of the object to stdout. 1008 void Print(); 1009 1010 private: 1011 friend class Minidump; 1012 1013 static const uint32_t kStreamType = MD_BREAKPAD_INFO_STREAM; 1014 1015 explicit MinidumpBreakpadInfo(Minidump* minidump_); 1016 1017 bool Read(uint32_t expected_size_) override; 1018 1019 MDRawBreakpadInfo breakpad_info_; 1020 }; 1021 1022 // MinidumpMemoryInfo wraps MDRawMemoryInfo, which provides information 1023 // about mapped memory regions in a process, including their ranges 1024 // and protection. 1025 class MinidumpMemoryInfo : public MinidumpObject { 1026 public: 1027 const MDRawMemoryInfo* info() const { 1028 return valid_ ? &memory_info_ : nullptr; 1029 } 1030 1031 // The address of the base of the memory region. 1032 uint64_t GetBase() const { return valid_ ? memory_info_.base_address : 0; } 1033 1034 // The size, in bytes, of the memory region. 1035 uint64_t GetSize() const { return valid_ ? memory_info_.region_size : 0; } 1036 1037 // Return true if the memory protection allows execution. 1038 bool IsExecutable() const; 1039 1040 // Return true if the memory protection allows writing. 1041 bool IsWritable() const; 1042 1043 // Print a human-readable representation of the object to stdout. 1044 void Print(); 1045 1046 private: 1047 // These objects are managed by MinidumpMemoryInfoList. 1048 friend class MinidumpMemoryInfoList; 1049 1050 explicit MinidumpMemoryInfo(Minidump* minidump_); 1051 1052 // This works like MinidumpStream::Read, but is driven by 1053 // MinidumpMemoryInfoList. No size checking is done, because 1054 // MinidumpMemoryInfoList handles that directly. 1055 bool Read(); 1056 1057 MDRawMemoryInfo memory_info_; 1058 }; 1059 1060 // MinidumpMemoryInfoList contains a list of information about 1061 // mapped memory regions for a process in the form of MDRawMemoryInfo. 1062 // It maintains a map of these structures so that it may easily provide 1063 // info corresponding to a specific address. 1064 class MinidumpMemoryInfoList : public MinidumpStream { 1065 public: 1066 MinidumpMemoryInfoList(const MinidumpMemoryInfoList&) = delete; 1067 void operator=(const MinidumpMemoryInfoList&) = delete; 1068 ~MinidumpMemoryInfoList() override; 1069 1070 unsigned int info_count() const { return valid_ ? info_count_ : 0; } 1071 1072 const MinidumpMemoryInfo* GetMemoryInfoForAddress(uint64_t address) const; 1073 const MinidumpMemoryInfo* GetMemoryInfoAtIndex(unsigned int index) const; 1074 1075 // Print a human-readable representation of the object to stdout. 1076 void Print(); 1077 1078 private: 1079 friend class Minidump; 1080 1081 typedef vector<MinidumpMemoryInfo> MinidumpMemoryInfos; 1082 1083 static const uint32_t kStreamType = MD_MEMORY_INFO_LIST_STREAM; 1084 1085 explicit MinidumpMemoryInfoList(Minidump* minidump_); 1086 1087 bool Read(uint32_t expected_size) override; 1088 1089 // Access to memory info using addresses as the key. 1090 RangeMap<uint64_t, unsigned int>* range_map_; 1091 1092 MinidumpMemoryInfos* infos_; 1093 uint32_t info_count_; 1094 }; 1095 1096 // MinidumpLinuxMaps wraps information about a single mapped memory region 1097 // from /proc/self/maps. 1098 class MinidumpLinuxMaps : public MinidumpObject { 1099 public: 1100 MinidumpLinuxMaps(const MinidumpLinuxMaps&) = delete; 1101 void operator=(const MinidumpLinuxMaps&) = delete; 1102 1103 // The memory address of the base of the mapped region. 1104 uint64_t GetBase() const { return valid_ ? region_.start : 0; } 1105 // The size of the mapped region. 1106 uint64_t GetSize() const { return valid_ ? region_.end - region_.start : 0; } 1107 1108 // The permissions of the mapped region. 1109 bool IsReadable() const { 1110 return valid_ ? region_.permissions & MappedMemoryRegion::READ : false; 1111 } 1112 bool IsWriteable() const { 1113 return valid_ ? region_.permissions & MappedMemoryRegion::WRITE : false; 1114 } 1115 bool IsExecutable() const { 1116 return valid_ ? region_.permissions & MappedMemoryRegion::EXECUTE : false; 1117 } 1118 bool IsPrivate() const { 1119 return valid_ ? region_.permissions & MappedMemoryRegion::PRIVATE : false; 1120 } 1121 1122 // The offset of the mapped region. 1123 uint64_t GetOffset() const { return valid_ ? region_.offset : 0; } 1124 1125 // The major device number. 1126 uint8_t GetMajorDevice() const { return valid_ ? region_.major_device : 0; } 1127 // The minor device number. 1128 uint8_t GetMinorDevice() const { return valid_ ? region_.minor_device : 0; } 1129 1130 // The inode of the mapped region. 1131 uint64_t GetInode() const { return valid_ ? region_.inode : 0; } 1132 1133 // The pathname of the mapped region. 1134 const string GetPathname() const { return valid_ ? region_.path : ""; } 1135 1136 // Print the contents of this mapping. 1137 void Print() const; 1138 1139 private: 1140 // These objects are managed by MinidumpLinuxMapsList. 1141 friend class MinidumpLinuxMapsList; 1142 1143 // This caller owns the pointer. 1144 explicit MinidumpLinuxMaps(Minidump* minidump); 1145 1146 // The memory region struct that this class wraps. 1147 MappedMemoryRegion region_; 1148 }; 1149 1150 // MinidumpLinuxMapsList corresponds to the Linux-exclusive MD_LINUX_MAPS 1151 // stream, which contains the contents of /prod/self/maps, which contains 1152 // the mapped memory regions and their access permissions. 1153 class MinidumpLinuxMapsList : public MinidumpStream { 1154 public: 1155 MinidumpLinuxMapsList(const MinidumpLinuxMapsList&) = delete; 1156 void operator=(const MinidumpLinuxMapsList&) = delete; 1157 ~MinidumpLinuxMapsList() override; 1158 1159 // Get number of mappings. 1160 unsigned int get_maps_count() const { return valid_ ? maps_count_ : 0; } 1161 1162 // Get mapping at the given memory address. The caller owns the pointer. 1163 const MinidumpLinuxMaps* GetLinuxMapsForAddress(uint64_t address) const; 1164 // Get mapping at the given index. The caller owns the pointer. 1165 const MinidumpLinuxMaps* GetLinuxMapsAtIndex(unsigned int index) const; 1166 1167 // Print the contents of /proc/self/maps to stdout. 1168 void Print() const; 1169 1170 private: 1171 friend class Minidump; 1172 1173 typedef vector<MinidumpLinuxMaps*> MinidumpLinuxMappings; 1174 1175 static const uint32_t kStreamType = MD_LINUX_MAPS; 1176 1177 // The caller owns the pointer. 1178 explicit MinidumpLinuxMapsList(Minidump* minidump); 1179 1180 // Read and load the contents of the process mapping data. 1181 // The stream should have data in the form of /proc/self/maps. 1182 // This method returns whether the stream was read successfully. 1183 bool Read(uint32_t expected_size) override; 1184 1185 // The list of individual mappings. 1186 MinidumpLinuxMappings* maps_; 1187 // The number of mappings. 1188 uint32_t maps_count_; 1189 }; 1190 1191 // MinidumpCrashpadInfo wraps MDRawCrashpadInfo, which is an optional stream in 1192 // a minidump that provides additional information about the process state 1193 // at the time the minidump was generated. 1194 class MinidumpCrashpadInfo : public MinidumpStream { 1195 public: 1196 struct AnnotationObject { 1197 uint16_t type; 1198 std::string name; 1199 std::vector<uint8_t> value; 1200 }; 1201 1202 const MDRawCrashpadInfo* crashpad_info() const { 1203 return valid_ ? &crashpad_info_ : nullptr; 1204 } 1205 1206 const std::vector<std::vector<AnnotationObject>>* 1207 GetModuleCrashpadInfoAnnotationObjects() const { 1208 return valid_ ? &module_crashpad_info_annotation_objects_ : nullptr; 1209 } 1210 1211 // Print a human-readable representation of the object to stdout. 1212 void Print(); 1213 1214 private: 1215 friend class Minidump; 1216 1217 static const uint32_t kStreamType = MD_CRASHPAD_INFO_STREAM; 1218 1219 explicit MinidumpCrashpadInfo(Minidump* minidump_); 1220 1221 bool Read(uint32_t expected_size); 1222 1223 MDRawCrashpadInfo crashpad_info_; 1224 std::vector<uint32_t> module_crashpad_info_links_; 1225 std::vector<MDRawModuleCrashpadInfo> module_crashpad_info_; 1226 std::vector<std::vector<std::string>> module_crashpad_info_list_annotations_; 1227 std::vector<std::map<std::string, std::string>> 1228 module_crashpad_info_simple_annotations_; 1229 std::vector<std::vector<AnnotationObject>> 1230 module_crashpad_info_annotation_objects_; 1231 1232 std::map<std::string, std::string> simple_annotations_; 1233 }; 1234 1235 1236 // Minidump is the user's interface to a minidump file. It wraps MDRawHeader 1237 // and provides access to the minidump's top-level stream directory. 1238 class Minidump { 1239 public: 1240 // path is the pathname of a file containing the minidump. 1241 explicit Minidump(const string& path, 1242 bool hexdump=false, 1243 unsigned int hexdump_width=16); 1244 // input is an istream wrapping minidump data. Minidump holds a 1245 // weak pointer to input, and the caller must ensure that the stream 1246 // is valid as long as the Minidump object is. 1247 explicit Minidump(std::istream& input); 1248 1249 Minidump(const Minidump&) = delete; 1250 void operator=(const Minidump&) = delete; 1251 1252 virtual ~Minidump(); 1253 1254 // path may be empty if the minidump was not opened from a file 1255 virtual string path() const { 1256 return path_; 1257 } 1258 static void set_max_streams(uint32_t max_streams) { 1259 max_streams_ = max_streams; 1260 } 1261 static uint32_t max_streams() { return max_streams_; } 1262 1263 static void set_max_string_length(uint32_t max_string_length) { 1264 max_string_length_ = max_string_length; 1265 } 1266 static uint32_t max_string_length() { return max_string_length_; } 1267 1268 virtual const MDRawHeader* header() const { 1269 return valid_ ? &header_ : nullptr; 1270 } 1271 1272 // Reads the CPU information from the system info stream and generates the 1273 // appropriate CPU flags. The returned context_cpu_flags are the same as 1274 // if the CPU type bits were set in the context_flags of a context record. 1275 // On success, context_cpu_flags will have the flags that identify the CPU. 1276 // If a system info stream is missing, context_cpu_flags will be 0. 1277 // Returns true if the current position in the stream was not changed. 1278 // Returns false when the current location in the stream was changed and the 1279 // attempt to restore the original position failed. 1280 bool GetContextCPUFlagsFromSystemInfo(uint32_t* context_cpu_flags); 1281 1282 // Reads the minidump file's header and top-level stream directory. 1283 // The minidump is expected to be positioned at the beginning of the 1284 // header. Read() sets up the stream list and map, and validates the 1285 // Minidump object. 1286 virtual bool Read(); 1287 1288 // The next set of methods are stubs that call GetStream. They exist to 1289 // force code generation of the templatized API within the module, and 1290 // to avoid exposing an ugly API (GetStream needs to accept a garbage 1291 // parameter). 1292 virtual MinidumpThreadList* GetThreadList(); 1293 virtual MinidumpThreadNameList* GetThreadNameList(); 1294 virtual MinidumpModuleList* GetModuleList(); 1295 virtual MinidumpMemoryList* GetMemoryList(); 1296 virtual MinidumpException* GetException(); 1297 virtual MinidumpAssertion* GetAssertion(); 1298 virtual MinidumpSystemInfo* GetSystemInfo(); 1299 virtual MinidumpUnloadedModuleList* GetUnloadedModuleList(); 1300 virtual MinidumpMiscInfo* GetMiscInfo(); 1301 virtual MinidumpBreakpadInfo* GetBreakpadInfo(); 1302 virtual MinidumpMemoryInfoList* GetMemoryInfoList(); 1303 MinidumpCrashpadInfo* GetCrashpadInfo(); 1304 1305 // The next method also calls GetStream, but is exclusive for Linux dumps. 1306 virtual MinidumpLinuxMapsList* GetLinuxMapsList(); 1307 1308 // The next set of methods are provided for users who wish to access 1309 // data in minidump files directly, while leveraging the rest of 1310 // this class and related classes to handle the basic minidump 1311 // structure and known stream types. 1312 1313 unsigned int GetDirectoryEntryCount() const { 1314 return valid_ ? header_.stream_count : 0; 1315 } 1316 const MDRawDirectory* GetDirectoryEntryAtIndex(unsigned int index) const; 1317 1318 // The next 2 methods are lower-level I/O routines. They use fd_. 1319 1320 // Reads count bytes from the minidump at the current position into 1321 // the storage area pointed to by bytes. bytes must be of sufficient 1322 // size. After the read, the file position is advanced by count. 1323 bool ReadBytes(void* bytes, size_t count); 1324 1325 // Sets the position of the minidump file to offset. 1326 bool SeekSet(off_t offset); 1327 1328 // Returns the current position of the minidump file. 1329 off_t Tell(); 1330 1331 // Medium-level I/O routines. 1332 1333 // ReadString returns a string which is owned by the caller! offset 1334 // specifies the offset that a length-encoded string is stored at in the 1335 // minidump file. 1336 string* ReadString(off_t offset); 1337 1338 bool ReadUTF8String(off_t offset, string* string_utf8); 1339 1340 bool ReadStringList(off_t offset, std::vector<std::string>* string_list); 1341 1342 bool ReadSimpleStringDictionary( 1343 off_t offset, 1344 std::map<std::string, std::string>* simple_string_dictionary); 1345 1346 bool ReadCrashpadAnnotationsList( 1347 off_t offset, 1348 std::vector<MinidumpCrashpadInfo::AnnotationObject>* annotations_list); 1349 1350 // SeekToStreamType positions the file at the beginning of a stream 1351 // identified by stream_type, and informs the caller of the stream's 1352 // length by setting *stream_length. Because stream_map maps each stream 1353 // type to only one stream in the file, this might mislead the user into 1354 // thinking that the stream that this seeks to is the only stream with 1355 // type stream_type. That can't happen for streams that these classes 1356 // deal with directly, because they're only supposed to be present in the 1357 // file singly, and that's verified when stream_map_ is built. Users who 1358 // are looking for other stream types should be aware of this 1359 // possibility, and consider using GetDirectoryEntryAtIndex (possibly 1360 // with GetDirectoryEntryCount) if expecting multiple streams of the same 1361 // type in a single minidump file. 1362 bool SeekToStreamType(uint32_t stream_type, uint32_t* stream_length); 1363 1364 bool swap() const { return valid_ ? swap_ : false; } 1365 1366 bool is_big_endian() const { return valid_ ? is_big_endian_ : false; } 1367 1368 // Print a human-readable representation of the object to stdout. 1369 void Print(); 1370 1371 // Is the OS Android. 1372 bool IsAndroid(); 1373 1374 // Determines the platform where the minidump was produced. |platform| is 1375 // valid iff this method returns true. 1376 bool GetPlatform(MDOSPlatform* platform); 1377 1378 // Get current hexdump display settings. 1379 unsigned int HexdumpMode() const { return hexdump_ ? hexdump_width_ : 0; } 1380 1381 private: 1382 // MinidumpStreamInfo is used in the MinidumpStreamMap. It lets 1383 // the Minidump object locate interesting streams quickly, and 1384 // provides a convenient place to stash MinidumpStream objects. 1385 struct MinidumpStreamInfo { 1386 MinidumpStreamInfo() : stream_index(0), stream(nullptr) {} 1387 ~MinidumpStreamInfo() { delete stream; } 1388 1389 // Index into the MinidumpDirectoryEntries vector 1390 unsigned int stream_index; 1391 1392 // Pointer to the stream if cached, or NULL if not yet populated 1393 MinidumpStream* stream; 1394 }; 1395 1396 typedef vector<MDRawDirectory> MinidumpDirectoryEntries; 1397 typedef map<uint32_t, MinidumpStreamInfo> MinidumpStreamMap; 1398 1399 template<typename T> T* GetStream(T** stream); 1400 1401 // Opens the minidump file, or if already open, seeks to the beginning. 1402 bool Open(); 1403 1404 // The largest number of top-level streams that will be read from a minidump. 1405 // Note that streams are only read (and only consume memory) as needed, 1406 // when directed by the caller. The default is 128. 1407 static uint32_t max_streams_; 1408 1409 // The maximum length of a UTF-16 string that will be read from a minidump 1410 // in 16-bit words. The default is 1024. UTF-16 strings are converted 1411 // to UTF-8 when stored in memory, and each UTF-16 word will be represented 1412 // by as many as 3 bytes in UTF-8. 1413 static unsigned int max_string_length_; 1414 1415 MDRawHeader header_; 1416 1417 // The list of streams. 1418 MinidumpDirectoryEntries* directory_; 1419 1420 // Access to streams using the stream type as the key. 1421 MinidumpStreamMap* stream_map_; 1422 1423 // The pathname of the minidump file to process, set in the constructor. 1424 // This may be empty if the minidump was opened directly from a stream. 1425 const string path_; 1426 1427 // The stream for all file I/O. Used by ReadBytes and SeekSet. 1428 // Set based on the path in Open, or directly in the constructor. 1429 std::istream* stream_; 1430 1431 // swap_ is true if the minidump file should be byte-swapped. If the 1432 // minidump was produced by a CPU that is other-endian than the CPU 1433 // processing the minidump, this will be true. If the two CPUs are 1434 // same-endian, this will be false. 1435 bool swap_; 1436 1437 // true if the minidump was produced by a big-endian cpu. 1438 bool is_big_endian_; 1439 1440 // Validity of the Minidump structure, false immediately after 1441 // construction or after a failed Read(); true following a successful 1442 // Read(). 1443 bool valid_; 1444 1445 // Knobs for controlling display of memory printing. 1446 bool hexdump_; 1447 unsigned int hexdump_width_; 1448 }; 1449 1450 1451 } // namespace google_breakpad 1452 1453 1454 #endif // GOOGLE_BREAKPAD_PROCESSOR_MINIDUMP_H__