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/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 kInvalidDate = -1;
39 :
40 : // Used to indicate that a symbol has not been imported.
41 : static const size_t kInvalidImportIndex = -1;
42 :
43 : // The modes in which the transform will treat a symbol.
44 : enum TransformMode {
45 : // Will search for the imported symbol and explicitly add an import entry
46 : // for it if it doesn't already exist.
47 : kAlwaysImport,
48 : // Will search for the imported symbol, ignoring it if not found.
49 : kFindOnly,
50 : };
51 :
52 : // Construct an empty module with the specified name, that initially
53 : // specifies no symbol to import.
54 : //
55 : // @param module_name the name of the module to import.
56 : explicit ImportedModule(const base::StringPiece& module_name)
57 : : name_(module_name.begin(), module_name.end()),
58 : date_(kInvalidDate),
59 : imported_(false),
60 : mode_(kFindOnly),
61 E : added_(false) {
62 E : }
63 :
64 : // Construct an empty module with the specified name and date, that
65 : // initially specifies no symbol to import.
66 : //
67 : // If not kInvalidDate, @p date specifies a version time stamp to be
68 : // associated with the imported module, the exact meaning of which, if
69 : // any, is dependent on the format.
70 : //
71 : // @param module_name the name of the module to import.
72 : // @param date the version time stamp.
73 : ImportedModule(const base::StringPiece& module_name, uint32 date)
74 : : name_(module_name.begin(), module_name.end()),
75 : date_(date),
76 : imported_(false),
77 : mode_(kFindOnly),
78 E : added_(false) {
79 E : }
80 :
81 : // @returns the name of the module to import.
82 E : const std::string& name() const { return name_; }
83 :
84 : // @returns the version date/time stamp of the module to import.
85 E : uint32 date() const { return date_; }
86 :
87 : // @returns the mode of the transform.
88 E : TransformMode mode() const { return mode_; }
89 :
90 : // After a successful transform, retrieve whether the module is imported.
91 : //
92 : // @returns true if there is an import entry for this module, false otherwise.
93 E : bool ModuleIsImported() const { return imported_; }
94 :
95 : // After a successful transform, retrieve whether the module has been added.
96 : //
97 : // @returns true if the module was added, false otherwise.
98 E : bool ModuleWasAdded() const { return added_; }
99 :
100 : // Add a symbol to be imported, returning its index. If the symbol already
101 : // exists this will return the existing index rather than adding it a second
102 : // time.
103 : //
104 : // @param symbol_name the symbol to be added.
105 : // @param mode the transform mode.
106 : // @returns the index of the symbol in this module, to be used for querying
107 : // information about the symbol.
108 : size_t AddSymbol(const base::StringPiece& symbol_name,
109 : TransformMode mode);
110 :
111 : // @returns the number of symbols that are to be imported from this module.
112 E : size_t size() const { return symbols_by_index_.size(); }
113 :
114 : // Retrieve the name of a symbol to import.
115 : //
116 : // @param index the index of the symbol to fetch.
117 : // @returns the name of the symbol.
118 E : const std::string& GetSymbolName(size_t index) const {
119 E : DCHECK_GT(symbols_by_index_.size(), index);
120 E : return symbols_by_index_[index]->name;
121 E : }
122 :
123 : // Retrieve the transform mode of a symbol to import.
124 : //
125 : // @param index the index of the symbol to query.
126 : // @returns the mode of the symbol.
127 E : TransformMode GetSymbolMode(size_t index) const {
128 E : DCHECK_GT(symbols_by_index_.size(), index);
129 E : return symbols_by_index_[index]->mode;
130 E : }
131 :
132 : // After a successful transform, retrieve whether the specified symbol is
133 : // effectively imported. If the symbol mode is kAlwaysImport, true will
134 : // always be returned; if it is kFindOnly, the import state of the symbol
135 : // is returned.
136 : //
137 : // @param index the index of the symbol to query.
138 : // @returns true if the symbol @p index has an import entry.
139 E : bool SymbolIsImported(size_t index) const {
140 E : DCHECK_GT(symbols_by_index_.size(), index);
141 E : return symbols_by_index_[index]->import_index != kInvalidImportIndex;
142 E : }
143 :
144 : // After a successful transform, retrieve whether the specified symbol was
145 : // added by the transform. If the symbol mode is kFindOnly, false will
146 : // always be returned; if it is kAlwaysImport, true is returned if adding
147 : // a symbol entry was necessary.
148 : //
149 : // @param index the index of the symbol to fetch.
150 : // @returns true if the symbol was added, false otherwise.
151 E : bool SymbolWasAdded(size_t index) const {
152 E : DCHECK_GT(symbols_by_index_.size(), index);
153 E : return symbols_by_index_[index]->added;
154 E : }
155 :
156 : // After a successful transform, retrieve the index of the symbol
157 : // entry. If the symbol mode is kFindOnly and the symbol was not found,
158 : // the default index kInvalidImportIndex is returned.
159 : //
160 : // @param index the index of the symbol to query.
161 : // @returns the index of the symbol entry, the meaning of which is
162 : // dependent on the underlying import table representation, but is
163 : // guaranteed to be distinct for distinct symbols.
164 E : size_t GetSymbolImportIndex(size_t index) const {
165 E : DCHECK_GT(symbols_by_index_.size(), index);
166 E : return symbols_by_index_[index]->import_index;
167 E : }
168 :
169 : // After a successful transform, retrieve an absolute reference to the
170 : // imported symbol. The returned reference may either be used as
171 : // a reference to the imported entity (if @p is_ptr is set to false), or
172 : // a reference to a pointer to the imported entity (if @p is_ptr is set to
173 : // true).
174 : //
175 : // The returned reference is only valid while no new symbols are imported,
176 : // and must be used or discarded before applying other transforms that may
177 : // add or remove symbols.
178 : //
179 : // Once a reference is used and inserted in a block, the imports may be
180 : // further modified and reference tracking will ensure things are kept up
181 : // to date; until then, @p reference is left dangling.
182 : //
183 : // @param index the index of the symbol to fetch.
184 : // @param ref the reference to populate.
185 : // @param is_ptr set to true if the reference is to a pointer instead of
186 : // the actual imported entity.
187 : // @returns true on success, false otherwise.
188 : bool GetSymbolReference(size_t index,
189 : block_graph::BlockGraph::Reference* ref,
190 : bool* is_ptr) const;
191 :
192 : // Legacy GetSymbolReference() method.
193 : //
194 : // @see GetSymbolReference(size_t,block_graph::BlockGraph::Reference*,bool*)
195 : bool GetSymbolReference(size_t index,
196 E : block_graph::BlockGraph::Reference* ref) const {
197 E : bool is_ptr = false;
198 E : return GetSymbolReference(index, ref, &is_ptr);
199 E : }
200 :
201 : protected:
202 : friend class PECoffAddImportsTransform;
203 :
204 : // A symbol imported from a module, by name.
205 : struct Symbol {
206 : // The name of the symbol to import.
207 : std::string name;
208 : // The ID of this symbol wrt to this imported module. This is an index into
209 : // symbols_by_index_.
210 : size_t symbol_index;
211 : // The index of the imported symbol in the symbol or import table. This
212 : // is left as kInvalidImportIndex if this symbol's mode is kFindOnly and
213 : // the import does not exist.
214 : size_t import_index;
215 : // The transform mode for this symbol.
216 : TransformMode mode;
217 : // If this is true then the symbol was added by the transform.
218 : bool added;
219 : // The reference to the imported symbol.
220 : block_graph::BlockGraph::Reference ref;
221 : // Whether the import symbol reference is to a pointer (true), or
222 : // directly to the object or function (false).
223 : bool is_ptr;
224 :
225 : // A comparison functor. This compares symbols by their names, ensuring
226 : // uniqueness.
227 E : bool operator<(const Symbol& other) const {
228 E : return name < other.name;
229 E : }
230 : };
231 :
232 : typedef std::set<Symbol> SymbolSet;
233 :
234 : // The name of the module to be imported.
235 : std::string name_;
236 :
237 : // A version time stamp associated with the module.
238 : uint32 date_;
239 :
240 : // The symbols to be imported, sorted by name. This ensures that symbols are
241 : // stored uniquely.
242 : SymbolSet symbols_by_name_;
243 :
244 : // A mapping from symbol indices to symbol objects.
245 : std::vector<Symbol*> symbols_by_index_;
246 :
247 : // Set to true if this module was added or found by the transform.
248 : bool imported_;
249 :
250 : // Transform mode for the whole module. Is kFindOnly if all symbols in this
251 : // module are kFindOnly, otherwise is kAlwaysImport.
252 : TransformMode mode_;
253 :
254 : // Set to true if this module was added to image by the transform.
255 : bool added_;
256 :
257 : private:
258 : DISALLOW_COPY_AND_ASSIGN(ImportedModule);
259 : };
260 :
261 : // Common base class for transforms that add imported modules/symbols to
262 : // a given block graph, for both PE and COFF formats.
263 : class PECoffAddImportsTransform {
264 : public:
265 : // Construct an empty PECoffAddImportsTransform, that imports nothing
266 : // initially.
267 E : PECoffAddImportsTransform() : modules_added_(0), symbols_added_(0) {}
268 :
269 : // Add the given module and its symbols to the list of modules and symbols
270 : // to import.
271 : //
272 : // @param imported_module the module to import.
273 E : void AddModule(ImportedModule* imported_module) {
274 E : DCHECK(imported_module != NULL);
275 E : imported_modules_.push_back(imported_module);
276 E : }
277 :
278 : // @returns the number of imported modules that were added to the image.
279 E : size_t modules_added() const { return modules_added_; }
280 :
281 : // @returns the number of imported symbols that were added to the image.
282 E : size_t symbols_added() const { return symbols_added_; }
283 :
284 : protected:
285 : // Update the import state of the specified module.
286 : //
287 : // @param imported whether the module is imported.
288 : // @param added whether the module has been added by the transform.
289 : // @param imported_module the module to update.
290 : static void UpdateModule(bool imported,
291 : bool added,
292 : ImportedModule* imported_module);
293 :
294 : // Update the import index of the specified symbol.
295 : //
296 : // @param index the index of the symbol to update.
297 : // @param import_index the import index to associate with the symbol.
298 : // @param added whether an entry was added for this symbol.
299 : // @param imported_module the module to update.
300 : static void UpdateModuleSymbolIndex(
301 : size_t index,
302 : size_t import_index,
303 : bool added,
304 : ImportedModule* imported_module);
305 :
306 : // Update the import reference of the specified symbol.
307 : //
308 : // @param index the index of the symbol to update.
309 : // @param ref the import reference to associate with the symbol.
310 : // @param is_ptr whether the reference is to a pointer or the actual thing.
311 : // @param imported_module the module to update.
312 : static void UpdateModuleSymbolReference(
313 : size_t index,
314 : block_graph::BlockGraph::Reference ref,
315 : bool is_ptr,
316 : ImportedModule* imported_module);
317 :
318 : // A collection of modules (and symbols from them) to be imported. This
319 : // must be populated prior to calling TransformBlockGraph().
320 : std::vector<ImportedModule*> imported_modules_;
321 :
322 : // Statistics regarding the completed transform.
323 : size_t modules_added_;
324 : size_t symbols_added_;
325 :
326 : private:
327 : DISALLOW_COPY_AND_ASSIGN(PECoffAddImportsTransform);
328 : };
329 :
330 : } // namespace transforms
331 : } // namespace pe
332 :
333 : #endif // SYZYGY_PE_TRANSFORMS_PE_COFF_ADD_IMPORTS_TRANSFORM_H_
|