1  // -*- mode: C++ -*-
  2  
  3  // Copyright 2010 Google LLC
  4  //
  5  // Redistribution and use in source and binary forms, with or without
  6  // modification, are permitted provided that the following conditions are
  7  // met:
  8  //
  9  //     * Redistributions of source code must retain the above copyright
 10  // notice, this list of conditions and the following disclaimer.
 11  //     * Redistributions in binary form must reproduce the above
 12  // copyright notice, this list of conditions and the following disclaimer
 13  // in the documentation and/or other materials provided with the
 14  // distribution.
 15  //     * Neither the name of Google LLC nor the names of its
 16  // contributors may be used to endorse or promote products derived from
 17  // this software without specific prior written permission.
 18  //
 19  // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 20  // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 21  // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 22  // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 23  // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 24  // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 25  // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 26  // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 27  // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 28  // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 29  // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 30  
 31  // Abstract interface to return function/file/line info for a memory address.
 32  
 33  #ifndef GOOGLE_BREAKPAD_PROCESSOR_SOURCE_LINE_RESOLVER_INTERFACE_H__
 34  #define GOOGLE_BREAKPAD_PROCESSOR_SOURCE_LINE_RESOLVER_INTERFACE_H__
 35  
 36  #include <deque>
 37  #include <memory>
 38  #include <string>
 39  #include <vector>
 40  
 41  #include "common/using_std_string.h"
 42  #include "google_breakpad/common/breakpad_types.h"
 43  #include "google_breakpad/processor/code_module.h"
 44  
 45  namespace google_breakpad {
 46  
 47  struct StackFrame;
 48  struct WindowsFrameInfo;
 49  class CFIFrameInfo;
 50  
 51  class SourceLineResolverInterface {
 52   public:
 53    typedef uint64_t MemAddr;
 54  
 55    virtual ~SourceLineResolverInterface() {}
 56  
 57    // Adds a module to this resolver, returning true on success.
 58    //
 59    // module should have at least the code_file, debug_file,
 60    // and debug_identifier members populated.
 61    //
 62    // map_file should contain line/address mappings for this module.
 63    virtual bool LoadModule(const CodeModule* module,
 64                            const string& map_file) = 0;
 65    // Same as above, but takes the contents of a pre-read map buffer
 66    virtual bool LoadModuleUsingMapBuffer(const CodeModule* module,
 67                                          const string& map_buffer) = 0;
 68  
 69    // Add an interface to load symbol using C-String data instead of string.
 70    // This is useful in the optimization design for avoiding unnecessary copying
 71    // of symbol data, in order to improve memory efficiency.
 72    // LoadModuleUsingMemoryBuffer() does NOT take ownership of memory_buffer.
 73    // LoadModuleUsingMemoryBuffer() null terminates the passed in buffer, if
 74    // the last character is not a null terminator.
 75    virtual bool LoadModuleUsingMemoryBuffer(const CodeModule* module,
 76                                             char* memory_buffer,
 77                                             size_t memory_buffer_size) = 0;
 78  
 79    // Return true if the memory buffer should be deleted immediately after
 80    // LoadModuleUsingMemoryBuffer(). Return false if the memory buffer has to be
 81    // alive during the lifetime of the corresponding Module.
 82    virtual bool ShouldDeleteMemoryBufferAfterLoadModule() = 0;
 83  
 84    // Request that the specified module be unloaded from this resolver.
 85    // A resolver may choose to ignore such a request.
 86    virtual void UnloadModule(const CodeModule* module) = 0;
 87  
 88    // Returns true if the module has been loaded.
 89    virtual bool HasModule(const CodeModule* module) = 0;
 90  
 91    // Returns true if the module has been loaded and it is corrupt.
 92    virtual bool IsModuleCorrupt(const CodeModule* module) = 0;
 93  
 94    // Fills in the function_base, function_name, source_file_name,
 95    // and source_line fields of the StackFrame.  The instruction and
 96    // module_name fields must already be filled in. If inlined_frames is not
 97    // nullptr, it will try to construct inlined frames by adding them into
 98    // inlined_frames in an order from outermost frame to inner most frame.
 99    virtual void FillSourceLineInfo(
100        StackFrame* frame,
101        std::deque<std::unique_ptr<StackFrame>>* inlined_frames) = 0;
102  
103    // If Windows stack walking information is available covering
104    // FRAME's instruction address, return a WindowsFrameInfo structure
105    // describing it. If the information is not available, returns NULL.
106    // A NULL return value does not indicate an error. The caller takes
107    // ownership of any returned WindowsFrameInfo object.
108    virtual WindowsFrameInfo* FindWindowsFrameInfo(const StackFrame* frame) = 0;
109  
110    // If CFI stack walking information is available covering ADDRESS,
111    // return a CFIFrameInfo structure describing it. If the information
112    // is not available, return NULL. The caller takes ownership of any
113    // returned CFIFrameInfo object.
114    virtual CFIFrameInfo* FindCFIFrameInfo(const StackFrame* frame) = 0;
115  
116   protected:
117    // SourceLineResolverInterface cannot be instantiated except by subclasses
118    SourceLineResolverInterface() {}
119  };
120  
121  }  // namespace google_breakpad
122  
123  #endif  // GOOGLE_BREAKPAD_PROCESSOR_SOURCE_LINE_RESOLVER_INTERFACE_H__