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