1  // Copyright 2014 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  // microdump.h: A microdump reader.  Microdump is a minified variant of a
 30  // minidump (see minidump.h for documentation) which contains the minimum
 31  // amount of information required to get a stack trace for the crashing thread.
 32  // The information contained in a microdump is:
 33  // - the crashing thread stack
 34  // - system information (os type / version)
 35  // - cpu context (state of the registers)
 36  // - list of mmaps
 37  
 38  #ifndef GOOGLE_BREAKPAD_PROCESSOR_MICRODUMP_H__
 39  #define GOOGLE_BREAKPAD_PROCESSOR_MICRODUMP_H__
 40  
 41  #include <string>
 42  #include <vector>
 43  
 44  #include "common/scoped_ptr.h"
 45  #include "common/using_std_string.h"
 46  #include "google_breakpad/processor/dump_context.h"
 47  #include "google_breakpad/processor/memory_region.h"
 48  #include "google_breakpad/processor/system_info.h"
 49  #include "processor/basic_code_modules.h"
 50  
 51  namespace google_breakpad {
 52  
 53  // MicrodumpModuleList contains all of the loaded code modules for a process
 54  // in the form of MicrodumpModules.  It maintains a vector of these modules
 55  // and provides access to a code module corresponding to a specific address.
 56  class MicrodumpModules : public BasicCodeModules {
 57   public:
 58    // Takes over ownership of |module|.
 59    void Add(const CodeModule* module);
 60  
 61    // Enables/disables module address range shrink.
 62    void SetEnableModuleShrink(bool is_enabled);
 63  };
 64  
 65  // MicrodumpContext carries a CPU-specific context.
 66  // See dump_context.h for documentation.
 67  class MicrodumpContext : public DumpContext {
 68   public:
 69    virtual void SetContextARM(MDRawContextARM* arm);
 70    virtual void SetContextARM64(MDRawContextARM64* arm64);
 71    virtual void SetContextX86(MDRawContextX86* x86);
 72    virtual void SetContextMIPS(MDRawContextMIPS* mips32);
 73    virtual void SetContextMIPS64(MDRawContextMIPS* mips64);
 74  };
 75  
 76  // This class provides access to microdump memory regions.
 77  // See memory_region.h for documentation.
 78  class MicrodumpMemoryRegion : public MemoryRegion {
 79   public:
 80    MicrodumpMemoryRegion();
 81    virtual ~MicrodumpMemoryRegion() {}
 82  
 83    // Set this region's address and contents. If we have placed an
 84    // instance of this class in a test fixture class, individual tests
 85    // can use this to provide the region's contents.
 86    void Init(uint64_t base_address, const std::vector<uint8_t>& contents);
 87  
 88    virtual uint64_t GetBase() const;
 89    virtual uint32_t GetSize() const;
 90  
 91    virtual bool GetMemoryAtAddress(uint64_t address, uint8_t* value) const;
 92    virtual bool GetMemoryAtAddress(uint64_t address, uint16_t* value) const;
 93    virtual bool GetMemoryAtAddress(uint64_t address, uint32_t* value) const;
 94    virtual bool GetMemoryAtAddress(uint64_t address, uint64_t* value) const;
 95  
 96    // Print a human-readable representation of the object to stdout.
 97    virtual void Print() const;
 98  
 99   private:
100    // Fetch a little-endian value from ADDRESS in contents_ whose size
101    // is BYTES, and store it in *VALUE.  Returns true on success.
102    template<typename ValueType>
103    bool GetMemoryLittleEndian(uint64_t address, ValueType* value) const;
104  
105    uint64_t base_address_;
106    std::vector<uint8_t> contents_;
107  };
108  
109  // Microdump is the user's interface to a microdump file.  It provides access to
110  // the microdump's context, memory regions and modules.
111  class Microdump {
112   public:
113    explicit Microdump(const string& contents);
114    virtual ~Microdump() {}
115  
116    DumpContext* GetContext() { return context_.get(); }
117    MicrodumpMemoryRegion* GetMemory() { return stack_region_.get(); }
118    MicrodumpModules* GetModules() { return modules_.get(); }
119    SystemInfo* GetSystemInfo() { return system_info_.get(); }
120  
121    string GetCrashReason() { return crash_reason_; }
122    uint64_t GetCrashAddress() { return crash_address_; }
123   private:
124    scoped_ptr<MicrodumpContext> context_;
125    scoped_ptr<MicrodumpMemoryRegion> stack_region_;
126    scoped_ptr<MicrodumpModules> modules_;
127    scoped_ptr<SystemInfo> system_info_;
128    string crash_reason_;
129    uint64_t crash_address_;
130  };
131  
132  }  // namespace google_breakpad
133  
134  #endif  // GOOGLE_BREAKPAD_PROCESSOR_MICRODUMP_H__