1 // Copyright (c) 2006, 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 
30 // simple_symbol_supplier.h: A simple SymbolSupplier implementation
31 //
32 // SimpleSymbolSupplier is a straightforward implementation of SymbolSupplier
33 // that stores symbol files in a filesystem tree.  A SimpleSymbolSupplier is
34 // created with one or more base directories, which are the root paths for all
35 // symbol files.  Each symbol file contained therein has a directory entry in
36 // the base directory with a name identical to the corresponding debugging
37 // file (pdb).  Within each of these directories, there are subdirectories
38 // named for the debugging file's identifier.  For recent pdb files, this is
39 // a concatenation of the pdb's uuid and age, presented in hexadecimal form,
40 // without any dashes or separators.  The uuid is in uppercase hexadecimal
41 // and the age is in lowercase hexadecimal.  Within that subdirectory,
42 // SimpleSymbolSupplier expects to find the symbol file, which is named
43 // identically to the debug file, but with a .sym extension.  If the original
44 // debug file had a name ending in .pdb, the .pdb extension will be replaced
45 // with .sym.  This sample hierarchy is rooted at the "symbols" base
46 // directory:
47 //
48 // symbols
49 // symbols/test_app.pdb
50 // symbols/test_app.pdb/63FE4780728D49379B9D7BB6460CB42A1
51 // symbols/test_app.pdb/63FE4780728D49379B9D7BB6460CB42A1/test_app.sym
52 // symbols/kernel32.pdb
53 // symbols/kernel32.pdb/BCE8785C57B44245A669896B6A19B9542
54 // symbols/kernel32.pdb/BCE8785C57B44245A669896B6A19B9542/kernel32.sym
55 //
56 // In this case, the uuid of test_app.pdb is
57 // 63fe4780-728d-4937-9b9d-7bb6460cb42a and its age is 1.
58 //
59 // This scheme was chosen to be roughly analogous to the way that
60 // symbol files may be accessed from Microsoft Symbol Server.  A hierarchy
61 // used for Microsoft Symbol Server storage is usable as a hierarchy for
62 // SimpleSymbolServer, provided that the pdb files are transformed to dumped
63 // format using a tool such as dump_syms, and given a .sym extension.
64 //
65 // SimpleSymbolSupplier will iterate over all root paths searching for
66 // a symbol file existing in that path.
67 //
68 // SimpleSymbolSupplier supports any debugging file which can be identified
69 // by a CodeModule object's debug_file and debug_identifier accessors.  The
70 // expected ultimate source of these CodeModule objects are MinidumpModule
71 // objects; it is this class that is responsible for assigning appropriate
72 // values for debug_file and debug_identifier.
73 //
74 // Author: Mark Mentovai
75 
76 #ifndef PROCESSOR_SIMPLE_SYMBOL_SUPPLIER_H__
77 #define PROCESSOR_SIMPLE_SYMBOL_SUPPLIER_H__
78 
79 #include <map>
80 #include <string>
81 #include <vector>
82 
83 #include "common/using_std_string.h"
84 #include "google_breakpad/processor/symbol_supplier.h"
85 
86 namespace google_breakpad {
87 
88 using std::map;
89 using std::vector;
90 
91 class CodeModule;
92 
93 class SimpleSymbolSupplier : public SymbolSupplier {
94  public:
95   // Creates a new SimpleSymbolSupplier, using path as the root path where
96   // symbols are stored.
SimpleSymbolSupplier(const string & path)97   explicit SimpleSymbolSupplier(const string &path) : paths_(1, path) {}
98 
99   // Creates a new SimpleSymbolSupplier, using paths as a list of root
100   // paths where symbols may be stored.
SimpleSymbolSupplier(const vector<string> & paths)101   explicit SimpleSymbolSupplier(const vector<string> &paths) : paths_(paths) {}
102 
~SimpleSymbolSupplier()103   virtual ~SimpleSymbolSupplier() {}
104 
105   // Returns the path to the symbol file for the given module.  See the
106   // description above.
107   virtual SymbolResult GetSymbolFile(const CodeModule *module,
108                                      const SystemInfo *system_info,
109                                      string *symbol_file);
110 
111   virtual SymbolResult GetSymbolFile(const CodeModule *module,
112                                      const SystemInfo *system_info,
113                                      string *symbol_file,
114                                      string *symbol_data);
115 
116   // Allocates data buffer on heap and writes symbol data into buffer.
117   // Symbol supplier ALWAYS takes ownership of the data buffer.
118   virtual SymbolResult GetCStringSymbolData(const CodeModule *module,
119                                             const SystemInfo *system_info,
120                                             string *symbol_file,
121                                             char **symbol_data,
122                                             size_t *symbol_data_size);
123 
124   // Free the data buffer allocated in the above GetCStringSymbolData();
125   virtual void FreeSymbolData(const CodeModule *module);
126 
127  protected:
128   SymbolResult GetSymbolFileAtPathFromRoot(const CodeModule *module,
129                                            const SystemInfo *system_info,
130                                            const string &root_path,
131                                            string *symbol_file);
132 
133  private:
134   map<string, char *> memory_buffers_;
135   vector<string> paths_;
136 };
137 
138 }  // namespace google_breakpad
139 
140 #endif  // PROCESSOR_SIMPLE_SYMBOL_SUPPLIER_H__
141