1 : // Copyright 2013 Google Inc. All Rights Reserved.
2 : //
3 : // Licensed under the Apache License, Version 2.0 (the "License");
4 : // you may not use this file except in compliance with the License.
5 : // You may obtain a copy of the License at
6 : //
7 : // http://www.apache.org/licenses/LICENSE-2.0
8 : //
9 : // Unless required by applicable law or agreed to in writing, software
10 : // distributed under the License is distributed on an "AS IS" BASIS,
11 : // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 : // See the License for the specific language governing permissions and
13 : // limitations under the License.
14 : //
15 : // Definitions of the PECoffAddImportsTransform base class, and auxiliary
16 : // ImportedModule class. PECoffAddImportsTransform is the base class common
17 : // to both PE and COFF transforms that add external (imported) symbols to
18 : // a block graph.
19 : //
20 : // The base class provides helper routines and definitions, as well as part
21 : // of the common interface, through the ImportedModule class and AddModule()
22 : // method.
23 :
24 : #ifndef SYZYGY_PE_TRANSFORMS_PE_COFF_ADD_IMPORTS_TRANSFORM_H_
25 : #define SYZYGY_PE_TRANSFORMS_PE_COFF_ADD_IMPORTS_TRANSFORM_H_
26 :
27 : #include "base/strings/string_piece.h"
28 : #include "syzygy/block_graph/block_graph.h"
29 :
30 : namespace pe {
31 : namespace transforms {
32 :
33 : // A list of symbols to be imported from a module.
34 : class ImportedModule {
35 : public:
36 : // Used to indicate that the date/time stamp for the module should not be
37 : // updated.
38 : static const uint32_t kInvalidDate = UINT32_MAX;
39 :
40 : // The modes in which the transform will treat a symbol.
41 : enum TransformMode {
42 : // Will search for the imported symbol and explicitly add an import entry
43 : // for it if it doesn't already exist.
44 : kAlwaysImport,
45 : // Will search for the imported symbol, ignoring it if not found.
46 : kFindOnly,
47 : };
48 :
49 : // Construct an empty module with the specified name, that initially
50 : // specifies no symbol to import.
51 : //
52 : // @param module_name the name of the module to import.
53 : explicit ImportedModule(const base::StringPiece& module_name)
54 E : : name_(module_name.begin(), module_name.end()),
55 E : date_(kInvalidDate),
56 E : imported_(false),
57 E : mode_(kFindOnly),
58 E : added_(false) {
59 E : }
60 :
61 : // Construct an empty module with the specified name and date, that
62 : // initially specifies no symbol to import.
63 : //
64 : // If not kInvalidDate, @p date specifies a version time stamp to be
65 : // associated with the imported module, the exact meaning of which, if
66 : // any, is dependent on the format.
67 : //
68 : // @param module_name the name of the module to import.
69 : // @param date the version time stamp.
70 : ImportedModule(const base::StringPiece& module_name, uint32_t date)
71 E : : name_(module_name.begin(), module_name.end()),
72 E : date_(date),
73 E : imported_(false),
74 E : mode_(kFindOnly),
75 E : added_(false) {}
76 :
77 : // @returns the name of the module to import.
78 E : const std::string& name() const { return name_; }
79 :
80 : // @returns the version date/time stamp of the module to import.
81 E : uint32_t date() const { return date_; }
82 :
83 : // @returns the mode of the transform.
84 E : TransformMode mode() const { return mode_; }
85 :
86 : // After a successful transform, retrieve whether the module is imported.
87 : //
88 : // @returns true if there is an import entry for this module, false otherwise.
89 E : bool ModuleIsImported() const { return imported_; }
90 :
91 : // After a successful transform, retrieve whether the module has been added.
92 : //
93 : // @returns true if the module was added, false otherwise.
94 E : bool ModuleWasAdded() const { return added_; }
95 :
96 : // Add a symbol to be imported, returning its index. If the symbol already
97 : // exists this will return the existing index rather than adding it a second
98 : // time.
99 : //
100 : // @param symbol_name the symbol to be added.
101 : // @param mode the transform mode.
102 : // @returns the index of the symbol in this module, to be used for querying
103 : // information about the symbol.
104 : size_t AddSymbol(const base::StringPiece& symbol_name,
105 : TransformMode mode);
106 :
107 : // @returns the number of symbols that are to be imported from this module.
108 E : size_t size() const { return symbols_by_index_.size(); }
109 :
110 : // Retrieve the name of a symbol to import.
111 : //
112 : // @param index the index of the symbol to fetch.
113 : // @returns the name of the symbol.
114 E : const std::string& GetSymbolName(size_t index) const {
115 E : DCHECK_GT(symbols_by_index_.size(), index);
116 E : return symbols_by_index_[index]->name;
117 E : }
118 :
119 : // Retrieve the transform mode of a symbol to import.
120 : //
121 : // @param index the index of the symbol to query.
122 : // @returns the mode of the symbol.
123 E : TransformMode GetSymbolMode(size_t index) const {
124 E : DCHECK_GT(symbols_by_index_.size(), index);
125 E : return symbols_by_index_[index]->mode;
126 E : }
127 :
128 : // After a successful transform, retrieve whether the specified symbol is
129 : // effectively imported. If the symbol mode is kAlwaysImport, true will
130 : // always be returned; if it is kFindOnly, the import state of the symbol
131 : // is returned.
132 : //
133 : // @param index the index of the symbol to query.
134 : // @returns true if the symbol @p index has an import entry.
135 E : bool SymbolIsImported(size_t index) const {
136 E : DCHECK_GT(symbols_by_index_.size(), index);
137 E : return symbols_by_index_[index]->imported;
138 E : }
139 :
140 : // After a successful transform, retrieve whether the specified symbol was
141 : // added by the transform. If the symbol mode is kFindOnly, false will
142 : // always be returned; if it is kAlwaysImport, true is returned if adding
143 : // a symbol entry was necessary.
144 : //
145 : // @param index the index of the symbol to fetch.
146 : // @returns true if the symbol was added, false otherwise.
147 E : bool SymbolWasAdded(size_t index) const {
148 E : DCHECK_GT(symbols_by_index_.size(), index);
149 E : return symbols_by_index_[index]->added;
150 E : }
151 :
152 : // After a successful transform, retrieve an absolute reference to the
153 : // imported symbol. The returned reference may either be used as
154 : // a reference to the imported entity (if @p is_ptr is set to false), or
155 : // a reference to a pointer to the imported entity (if @p is_ptr is set to
156 : // true).
157 : //
158 : // The returned reference is only valid while no new symbols are imported,
159 : // and must be used or discarded before applying other transforms that may
160 : // add or remove symbols.
161 : //
162 : // Once a reference is used and inserted in a block, the imports may be
163 : // further modified and reference tracking will ensure things are kept up
164 : // to date; until then, @p reference is left dangling.
165 : //
166 : // @param index the index of the symbol to fetch.
167 : // @param ref the reference to populate.
168 : // @param is_ptr set to true if the reference is to a pointer instead of
169 : // the actual imported entity.
170 : // @returns true on success, false otherwise.
171 : bool GetSymbolReference(size_t index,
172 : block_graph::BlockGraph::Reference* ref,
173 : bool* is_ptr) const;
174 :
175 : // Legacy GetSymbolReference() method.
176 : //
177 : // @see GetSymbolReference(size_t,block_graph::BlockGraph::Reference*,bool*)
178 : bool GetSymbolReference(size_t index,
179 E : block_graph::BlockGraph::Reference* ref) const {
180 E : bool is_ptr = false;
181 E : return GetSymbolReference(index, ref, &is_ptr);
182 E : }
183 :
184 : protected:
185 : friend class PECoffAddImportsTransform;
186 :
187 : // A symbol imported from a module, by name.
188 : struct Symbol {
189 : // The name of the symbol to import.
190 : std::string name;
191 : // The ID of this symbol wrt to this imported module. This is an index into
192 : // symbols_by_index_.
193 : size_t symbol_index;
194 : // The transform mode for this symbol.
195 : TransformMode mode;
196 : // If this is true then the symbol is imported.
197 : bool imported;
198 : // If this is true then the symbol was added by the transform.
199 : bool added;
200 : // The reference to the imported symbol.
201 : block_graph::BlockGraph::Reference ref;
202 : // Whether the import symbol reference is to a pointer (true), or
203 : // directly to the object or function (false).
204 : bool is_ptr;
205 :
206 : // A comparison functor. This compares symbols by their names, ensuring
207 : // uniqueness.
208 E : bool operator<(const Symbol& other) const {
209 E : return name < other.name;
210 E : }
211 : };
212 :
213 : typedef std::set<Symbol> SymbolSet;
214 :
215 : // The name of the module to be imported.
216 : std::string name_;
217 :
218 : // A version time stamp associated with the module.
219 : uint32_t date_;
220 :
221 : // The symbols to be imported, sorted by name. This ensures that symbols are
222 : // stored uniquely.
223 : SymbolSet symbols_by_name_;
224 :
225 : // A mapping from symbol indices to symbol objects.
226 : std::vector<Symbol*> symbols_by_index_;
227 :
228 : // Set to true if this module was added or found by the transform.
229 : bool imported_;
230 :
231 : // Transform mode for the whole module. Is kFindOnly if all symbols in this
232 : // module are kFindOnly, otherwise is kAlwaysImport.
233 : TransformMode mode_;
234 :
235 : // Set to true if this module was added to image by the transform.
236 : bool added_;
237 :
238 : private:
239 : DISALLOW_COPY_AND_ASSIGN(ImportedModule);
240 : };
241 :
242 : // Common base class for transforms that add imported modules/symbols to
243 : // a given block graph, for both PE and COFF formats.
244 : class PECoffAddImportsTransform {
245 : public:
246 : // Construct an empty PECoffAddImportsTransform, that imports nothing
247 : // initially.
248 E : PECoffAddImportsTransform() : modules_added_(0), symbols_added_(0) {}
249 :
250 : // Add the given module and its symbols to the list of modules and symbols
251 : // to import.
252 : //
253 : // @param imported_module the module to import.
254 E : void AddModule(ImportedModule* imported_module) {
255 E : DCHECK(imported_module != NULL);
256 E : imported_modules_.push_back(imported_module);
257 E : }
258 :
259 : // @returns the number of imported modules that were added to the image.
260 E : size_t modules_added() const { return modules_added_; }
261 :
262 : // @returns the number of imported symbols that were added to the image.
263 E : size_t symbols_added() const { return symbols_added_; }
264 :
265 : protected:
266 : // Update the import state of the specified module.
267 : //
268 : // @param imported whether the module is imported.
269 : // @param added whether the module has been added by the transform.
270 : // @param imported_module the module to update.
271 : static void UpdateModule(bool imported,
272 : bool added,
273 : ImportedModule* imported_module);
274 :
275 : // Update the metadata associated with the imported symbol.
276 : //
277 : // @param index the index of the symbol to update.
278 : // @param imported whether or not the symbol is imported.
279 : // @param added whether an entry was added for this symbol.
280 : // @param imported_module the module to update.
281 : static void UpdateModuleSymbolInfo(
282 : size_t index,
283 : bool imported,
284 : bool added,
285 : ImportedModule* imported_module);
286 :
287 : // Update the import reference of the specified symbol.
288 : //
289 : // @param index the index of the symbol to update.
290 : // @param ref the import reference to associate with the symbol.
291 : // @param is_ptr whether the reference is to a pointer or the actual thing.
292 : // @param imported_module the module to update.
293 : static void UpdateModuleSymbolReference(
294 : size_t index,
295 : block_graph::BlockGraph::Reference ref,
296 : bool is_ptr,
297 : ImportedModule* imported_module);
298 :
299 : // A collection of modules (and symbols from them) to be imported. This
300 : // must be populated prior to calling TransformBlockGraph().
301 : std::vector<ImportedModule*> imported_modules_;
302 :
303 : // Statistics regarding the completed transform.
304 : size_t modules_added_;
305 : size_t symbols_added_;
306 :
307 : private:
308 : DISALLOW_COPY_AND_ASSIGN(PECoffAddImportsTransform);
309 : };
310 :
311 : } // namespace transforms
312 : } // namespace pe
313 :
314 : #endif // SYZYGY_PE_TRANSFORMS_PE_COFF_ADD_IMPORTS_TRANSFORM_H_
|