LLDB mainline
IRForTarget.h
Go to the documentation of this file.
1//===-- IRForTarget.h ---------------------------------------------*- C++
2//-*-===//
3//
4// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
5// See https://llvm.org/LICENSE.txt for license information.
6// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_IRFORTARGET_H
11#define LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_IRFORTARGET_H
12
15#include "lldb/Utility/Status.h"
16#include "lldb/Utility/Stream.h"
18#include "lldb/lldb-public.h"
19#include "llvm/IR/DerivedTypes.h"
20#include "llvm/Pass.h"
21
22#include <functional>
23#include <map>
24
25namespace llvm {
26class BasicBlock;
27class CallInst;
28class Constant;
29class ConstantInt;
30class Function;
31class GlobalValue;
32class GlobalVariable;
33class Instruction;
34class Module;
35class StoreInst;
36class DataLayout;
37class Value;
38}
39
40namespace clang {
41class NamedDecl;
42}
43
44namespace lldb_private {
45class ClangExpressionDeclMap;
46class IRExecutionUnit;
47class IRMemoryMap;
48}
49
50/// \class IRForTarget IRForTarget.h "lldb/Expression/IRForTarget.h"
51/// Transforms the IR for a function to run in the target
52///
53/// Once an expression has been parsed and converted to IR, it can run in two
54/// contexts: interpreted by LLDB as a DWARF location expression, or compiled
55/// by the JIT and inserted into the target process for execution.
56///
57/// IRForTarget makes the second possible, by applying a series of
58/// transformations to the IR which make it relocatable. These
59/// transformations are discussed in more detail next to their relevant
60/// functions.
62public:
63 enum class LookupResult { Success, Fail, Ignore };
64
65 /// Constructor
66 ///
67 /// \param[in] decl_map
68 /// The list of externally-referenced variables for the expression,
69 /// for use in looking up globals and allocating the argument
70 /// struct. See the documentation for ClangExpressionDeclMap.
71 ///
72 /// \param[in] resolve_vars
73 /// True if the external variable references (including persistent
74 /// variables) should be resolved. If not, only external functions
75 /// are resolved.
76 ///
77 /// \param[in] execution_unit
78 /// The holder for raw data associated with the expression.
79 ///
80 /// \param[in] error_stream
81 /// If non-NULL, a stream on which errors can be printed.
82 ///
83 /// \param[in] func_name
84 /// The name of the function to prepare for execution in the target.
85 IRForTarget(lldb_private::ClangExpressionDeclMap *decl_map, bool resolve_vars,
86 lldb_private::IRExecutionUnit &execution_unit,
87 lldb_private::Stream &error_stream,
88 const char *func_name = "$__lldb_expr");
89
90 /// Run this IR transformer on a single module
91 ///
92 /// Implementation of the llvm::ModulePass::runOnModule() function.
93 ///
94 /// \param[in] llvm_module
95 /// The module to run on. This module is searched for the function
96 /// $__lldb_expr, and that function is passed to the passes one by
97 /// one.
98 ///
99 /// \return
100 /// True on success; false otherwise
101 bool runOnModule(llvm::Module &llvm_module);
102
103private:
104 /// Ensures that the current function's linkage is set to external.
105 /// Otherwise the JIT may not return an address for it.
106 ///
107 /// \param[in] llvm_function
108 /// The function whose linkage is to be fixed.
109 ///
110 /// \return
111 /// True on success; false otherwise.
112 bool FixFunctionLinkage(llvm::Function &llvm_function);
113
114 /// A module-level pass to replace all function pointers with their
115 /// integer equivalents.
116
117 /// The top-level pass implementation
118 ///
119 /// \param[in] llvm_function
120 /// The function currently being processed.
121 ///
122 /// \return
123 /// True on success; false otherwise.
124 bool HasSideEffects(llvm::Function &llvm_function);
125
126 /// A function-level pass to check whether the function has side
127 /// effects.
128
129 /// Get the address of a function, and a location to put the complete Value
130 /// of the function if one is available.
131 ///
132 /// \param[in] function
133 /// The function to find the location of.
134 ///
135 /// \param[out] ptr
136 /// The location of the function in the target.
137 ///
138 /// \param[out] name
139 /// The resolved name of the function (matters for intrinsics).
140 ///
141 /// \param[out] value_ptr
142 /// A variable to put the function's completed Value* in, or NULL
143 /// if the Value* shouldn't be stored anywhere.
144 ///
145 /// \return
146 /// The pointer.
147 LookupResult GetFunctionAddress(llvm::Function *function, uint64_t &ptr,
149 llvm::Constant **&value_ptr);
150
151 /// A function-level pass to take the generated global value
152 /// $__lldb_expr_result and make it into a persistent variable. Also see
153 /// ASTResultSynthesizer.
154
155 /// Find the NamedDecl corresponding to a Value. This interface is exposed
156 /// for the IR interpreter.
157 ///
158 /// \param[in] global_val
159 /// The global entity to search for
160 ///
161 /// \param[in] module
162 /// The module containing metadata to search
163 ///
164 /// \return
165 /// The corresponding variable declaration
166public:
167 static clang::NamedDecl *DeclForGlobal(const llvm::GlobalValue *global_val,
168 llvm::Module *module);
169
170private:
171 clang::NamedDecl *DeclForGlobal(llvm::GlobalValue *global);
172
173 /// Set the constant result variable m_const_result to the provided
174 /// constant, assuming it can be evaluated. The result variable will be
175 /// reset to NULL later if the expression has side effects.
176 ///
177 /// \param[in] initializer
178 /// The constant initializer for the variable.
179 ///
180 /// \param[in] name
181 /// The name of the result variable.
182 ///
183 /// \param[in] type
184 /// The Clang type of the result variable.
185 void MaybeSetConstantResult(llvm::Constant *initializer,
188
189 /// If the IR represents a cast of a variable, set m_const_result to the
190 /// result of the cast. The result variable will be reset to
191 /// NULL latger if the expression has side effects.
192 ///
193 /// \param[in] type
194 /// The Clang type of the result variable.
196
197 /// The top-level pass implementation
198 ///
199 /// \param[in] llvm_function
200 /// The function currently being processed.
201 ///
202 /// \return
203 /// True on success; false otherwise
204 bool CreateResultVariable(llvm::Function &llvm_function);
205
206 /// A module-level pass to find Objective-C constant strings and
207 /// transform them to calls to CFStringCreateWithBytes.
208
209 /// Rewrite a single Objective-C constant string.
210 ///
211 /// \param[in] NSStr
212 /// The constant NSString to be transformed
213 ///
214 /// \param[in] CStr
215 /// The constant C string inside the NSString. This will be
216 /// passed as the bytes argument to CFStringCreateWithBytes.
217 ///
218 /// \return
219 /// True on success; false otherwise
220 bool RewriteObjCConstString(llvm::GlobalVariable *NSStr,
221 llvm::GlobalVariable *CStr);
222
223 /// The top-level pass implementation
224 ///
225 /// \return
226 /// True on success; false otherwise
228
229 /// A basic block-level pass to find all Objective-C method calls and
230 /// rewrite them to use sel_registerName instead of statically allocated
231 /// selectors. The reason is that the selectors are created on the
232 /// assumption that the Objective-C runtime will scan the appropriate
233 /// section and prepare them. This doesn't happen when code is copied into
234 /// the target, though, and there's no easy way to induce the runtime to
235 /// scan them. So instead we get our selectors from sel_registerName.
236
237 /// Replace a single selector reference
238 ///
239 /// \param[in] selector_load
240 /// The load of the statically-allocated selector.
241 ///
242 /// \return
243 /// True on success; false otherwise
244 bool RewriteObjCSelector(llvm::Instruction *selector_load);
245
246 /// The top-level pass implementation
247 ///
248 /// \param[in] basic_block
249 /// The basic block currently being processed.
250 ///
251 /// \return
252 /// True on success; false otherwise
253 bool RewriteObjCSelectors(llvm::BasicBlock &basic_block);
254
255 /// A basic block-level pass to find all Objective-C class references that
256 /// use the old-style Objective-C runtime and rewrite them to use
257 /// class_getClass instead of statically allocated class references.
258
259 /// Replace a single old-style class reference
260 ///
261 /// \param[in] class_load
262 /// The load of the statically-allocated selector.
263 ///
264 /// \return
265 /// True on success; false otherwise
266 bool RewriteObjCClassReference(llvm::Instruction *class_load);
267
268 /// The top-level pass implementation
269 ///
270 /// \param[in] basic_block
271 /// The basic block currently being processed.
272 ///
273 /// \return
274 /// True on success; false otherwise
275 bool RewriteObjCClassReferences(llvm::BasicBlock &basic_block);
276
277 /// A basic block-level pass to find all newly-declared persistent
278 /// variables and register them with the ClangExprDeclMap. This allows them
279 /// to be materialized and dematerialized like normal external variables.
280 /// Before transformation, these persistent variables look like normal
281 /// locals, so they have an allocation. This pass excises these allocations
282 /// and makes references look like external references where they will be
283 /// resolved -- like all other external references -- by ResolveExternals().
284
285 /// Handle a single allocation of a persistent variable
286 ///
287 /// \param[in] persistent_alloc
288 /// The allocation of the persistent variable.
289 ///
290 /// \return
291 /// True on success; false otherwise
292 bool RewritePersistentAlloc(llvm::Instruction *persistent_alloc);
293
294 /// The top-level pass implementation
295 ///
296 /// \param[in] basic_block
297 /// The basic block currently being processed.
298 bool RewritePersistentAllocs(llvm::BasicBlock &basic_block);
299
300 /// A function-level pass to find all external variables and functions
301 /// used in the IR. Each found external variable is added to the struct,
302 /// and each external function is resolved in place, its call replaced with
303 /// a call to a function pointer whose value is the address of the function
304 /// in the target process.
305
306 /// Handle a single externally-defined variable
307 ///
308 /// \param[in] value
309 /// The variable.
310 ///
311 /// \return
312 /// True on success; false otherwise
313 bool MaybeHandleVariable(llvm::Value *value);
314
315 /// Handle a single externally-defined symbol
316 ///
317 /// \param[in] symbol
318 /// The symbol.
319 ///
320 /// \return
321 /// True on success; false otherwise
322 bool HandleSymbol(llvm::Value *symbol);
323
324 /// Handle a single externally-defined Objective-C class
325 ///
326 /// \param[in] classlist_reference
327 /// The reference, usually "01L_OBJC_CLASSLIST_REFERENCES_$_n"
328 /// where n (if present) is an index.
329 ///
330 /// \return
331 /// True on success; false otherwise
332 bool HandleObjCClass(llvm::Value *classlist_reference);
333
334 /// Handle all the arguments to a function call
335 ///
336 /// \param[in] call_inst
337 /// The call instruction.
338 ///
339 /// \return
340 /// True on success; false otherwise
341 bool MaybeHandleCallArguments(llvm::CallInst *call_inst);
342
343 /// Resolve variable references in calls to external functions
344 ///
345 /// \param[in] basic_block
346 /// The basic block currently being processed.
347 ///
348 /// \return
349 /// True on success; false otherwise
350 bool ResolveCalls(llvm::BasicBlock &basic_block);
351
352 /// Remove calls to __cxa_atexit, which should never be generated by
353 /// expressions.
354 ///
355 /// \param[in] basic_block
356 /// The basic block currently being processed.
357 ///
358 /// \return
359 /// True if the scan was successful; false if some operation
360 /// failed
361 bool RemoveCXAAtExit(llvm::BasicBlock &basic_block);
362
363 /// The top-level pass implementation
364 ///
365 /// \param[in] llvm_function
366 /// The function currently being processed.
367 ///
368 /// \return
369 /// True on success; false otherwise
370 bool ResolveExternals(llvm::Function &llvm_function);
371
372 /// A basic block-level pass to excise guard variables from the code.
373 /// The result for the function is passed through Clang as a static
374 /// variable. Static variables normally have guard variables to ensure that
375 /// they are only initialized once.
376
377 /// Rewrite a load to a guard variable to return constant 0.
378 ///
379 /// \param[in] guard_load
380 /// The load instruction to zero out.
381 void TurnGuardLoadIntoZero(llvm::Instruction *guard_load);
382
383 /// The top-level pass implementation
384 ///
385 /// \param[in] basic_block
386 /// The basic block currently being processed.
387 ///
388 /// \return
389 /// True on success; false otherwise
390 bool RemoveGuards(llvm::BasicBlock &basic_block);
391
392 /// A function-level pass to make all external variable references
393 /// point at the correct offsets from the void* passed into the function.
394 /// ClangExpressionDeclMap::DoStructLayout() must be called beforehand, so
395 /// that the offsets are valid.
396
397 /// The top-level pass implementation
398 ///
399 /// \param[in] llvm_function
400 /// The function currently being processed.
401 ///
402 /// \return
403 /// True on success; false otherwise
404 bool ReplaceVariables(llvm::Function &llvm_function);
405
406 /// True if external variable references and persistent variable references
407 /// should be resolved
409 /// The name of the function to translate
411 /// The name of the result variable ($0, $1, ...)
413 /// The type of the result variable.
415 /// The module being processed, or NULL if that has not been determined yet.
416 llvm::Module *m_module = nullptr;
417 /// The target data for the module being processed, or NULL if there is no
418 /// module.
419 std::unique_ptr<llvm::DataLayout> m_target_data;
420 /// The DeclMap containing the Decls
422 /// The address of the function CFStringCreateWithBytes, cast to the
423 /// appropriate function pointer type
424 llvm::FunctionCallee m_CFStringCreateWithBytes;
425 /// The address of the function sel_registerName, cast to the appropriate
426 /// function pointer type.
427 llvm::FunctionCallee m_sel_registerName;
428 /// The address of the function objc_getClass, cast to the appropriate
429 /// function pointer type.
430 llvm::FunctionCallee m_objc_getClass;
431 /// The type of an integer large enough to hold a pointer.
432 llvm::IntegerType *m_intptr_ty = nullptr;
433 /// The stream on which errors should be printed.
435 /// The execution unit containing the IR being created.
437 /// If non-NULL, the store instruction that writes to the result variable. If
438 /// m_has_side_effects is true, this is NULL.
439 llvm::StoreInst *m_result_store = nullptr;
440 /// True if the function's result in the AST is a pointer (see comments in
441 /// ASTResultSynthesizer::SynthesizeBodyResult)
443 /// A placeholder that will be replaced by a pointer to the final location of
444 /// the static allocation.
445 llvm::GlobalVariable *m_reloc_placeholder = nullptr;
446
448 public:
449 typedef std::function<llvm::Value *(llvm::Function *)> Maker;
450
451 FunctionValueCache(Maker const &maker);
453 llvm::Value *GetValue(llvm::Function *function);
454
455 private:
457 typedef std::map<llvm::Function *, llvm::Value *> FunctionValueMap;
459 };
460
462
463 /// UnfoldConstant operates on a constant [Old] which has just been replaced
464 /// with a value [New]. We assume that new_value has been properly placed
465 /// early in the function, in front of the first instruction in the entry
466 /// basic block [FirstEntryInstruction].
467 ///
468 /// UnfoldConstant reads through the uses of Old and replaces Old in those
469 /// uses with New. Where those uses are constants, the function generates
470 /// new instructions to compute the result of the new, non-constant
471 /// expression and places them before FirstEntryInstruction. These
472 /// instructions replace the constant uses, so UnfoldConstant calls itself
473 /// recursively for those.
474 ///
475 /// \return
476 /// True on success; false otherwise
477 static bool UnfoldConstant(llvm::Constant *old_constant,
478 llvm::Function *llvm_function,
479 FunctionValueCache &value_maker,
480 FunctionValueCache &entry_instruction_finder,
481 lldb_private::Stream &error_stream);
482
483 /// Commit the allocation in m_data_allocator and use its final location to
484 /// replace m_reloc_placeholder.
485 ///
486 /// \return
487 /// True on success; false otherwise
489};
490
491#endif // LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_IRFORTARGET_H
llvm::Value * GetValue(llvm::Function *function)
Definition: IRForTarget.cpp:56
std::function< llvm::Value *(llvm::Function *)> Maker
Definition: IRForTarget.h:449
std::map< llvm::Function *, llvm::Value * > FunctionValueMap
Definition: IRForTarget.h:457
Transforms the IR for a function to run in the target.
Definition: IRForTarget.h:61
std::unique_ptr< llvm::DataLayout > m_target_data
The target data for the module being processed, or NULL if there is no module.
Definition: IRForTarget.h:419
llvm::FunctionCallee m_objc_getClass
The address of the function objc_getClass, cast to the appropriate function pointer type.
Definition: IRForTarget.h:430
llvm::StoreInst * m_result_store
If non-NULL, the store instruction that writes to the result variable.
Definition: IRForTarget.h:439
lldb_private::ConstString m_func_name
The name of the function to translate.
Definition: IRForTarget.h:410
bool CompleteDataAllocation()
Commit the allocation in m_data_allocator and use its final location to replace m_reloc_placeholder.
bool MaybeHandleVariable(llvm::Value *value)
A function-level pass to find all external variables and functions used in the IR.
llvm::GlobalVariable * m_reloc_placeholder
A placeholder that will be replaced by a pointer to the final location of the static allocation.
Definition: IRForTarget.h:445
bool FixFunctionLinkage(llvm::Function &llvm_function)
Ensures that the current function's linkage is set to external.
lldb_private::IRExecutionUnit & m_execution_unit
The execution unit containing the IR being created.
Definition: IRForTarget.h:436
void MaybeSetConstantResult(llvm::Constant *initializer, lldb_private::ConstString name, lldb_private::TypeFromParser type)
Set the constant result variable m_const_result to the provided constant, assuming it can be evaluate...
bool RewriteObjCClassReference(llvm::Instruction *class_load)
A basic block-level pass to find all Objective-C class references that use the old-style Objective-C ...
bool CreateResultVariable(llvm::Function &llvm_function)
The top-level pass implementation.
llvm::Module * m_module
The module being processed, or NULL if that has not been determined yet.
Definition: IRForTarget.h:416
clang::NamedDecl * DeclForGlobal(llvm::GlobalValue *global)
bool HandleSymbol(llvm::Value *symbol)
Handle a single externally-defined symbol.
bool RewriteObjCConstStrings()
The top-level pass implementation.
bool ResolveCalls(llvm::BasicBlock &basic_block)
Resolve variable references in calls to external functions.
bool m_result_is_pointer
True if the function's result in the AST is a pointer (see comments in ASTResultSynthesizer::Synthesi...
Definition: IRForTarget.h:442
void MaybeSetCastResult(lldb_private::TypeFromParser type)
If the IR represents a cast of a variable, set m_const_result to the result of the cast.
bool RewriteObjCConstString(llvm::GlobalVariable *NSStr, llvm::GlobalVariable *CStr)
A module-level pass to find Objective-C constant strings and transform them to calls to CFStringCreat...
bool RemoveGuards(llvm::BasicBlock &basic_block)
The top-level pass implementation.
lldb_private::Stream & m_error_stream
The stream on which errors should be printed.
Definition: IRForTarget.h:434
bool HandleObjCClass(llvm::Value *classlist_reference)
Handle a single externally-defined Objective-C class.
bool m_resolve_vars
True if external variable references and persistent variable references should be resolved.
Definition: IRForTarget.h:408
static clang::NamedDecl * DeclForGlobal(const llvm::GlobalValue *global_val, llvm::Module *module)
A function-level pass to take the generated global value $__lldb_expr_result and make it into a persi...
LookupResult GetFunctionAddress(llvm::Function *function, uint64_t &ptr, lldb_private::ConstString &name, llvm::Constant **&value_ptr)
A function-level pass to check whether the function has side effects.
lldb_private::TypeFromParser m_result_type
The type of the result variable.
Definition: IRForTarget.h:414
llvm::FunctionCallee m_CFStringCreateWithBytes
The address of the function CFStringCreateWithBytes, cast to the appropriate function pointer type.
Definition: IRForTarget.h:424
bool MaybeHandleCallArguments(llvm::CallInst *call_inst)
Handle all the arguments to a function call.
bool runOnModule(llvm::Module &llvm_module)
Run this IR transformer on a single module.
bool RewriteObjCSelectors(llvm::BasicBlock &basic_block)
The top-level pass implementation.
lldb_private::ConstString m_result_name
The name of the result variable ($0, $1, ...)
Definition: IRForTarget.h:412
bool HasSideEffects(llvm::Function &llvm_function)
A module-level pass to replace all function pointers with their integer equivalents.
lldb_private::ClangExpressionDeclMap * m_decl_map
The DeclMap containing the Decls.
Definition: IRForTarget.h:421
bool RewriteObjCClassReferences(llvm::BasicBlock &basic_block)
The top-level pass implementation.
bool RemoveCXAAtExit(llvm::BasicBlock &basic_block)
Remove calls to __cxa_atexit, which should never be generated by expressions.
bool RewritePersistentAllocs(llvm::BasicBlock &basic_block)
The top-level pass implementation.
bool RewritePersistentAlloc(llvm::Instruction *persistent_alloc)
A basic block-level pass to find all newly-declared persistent variables and register them with the C...
void TurnGuardLoadIntoZero(llvm::Instruction *guard_load)
A basic block-level pass to excise guard variables from the code.
FunctionValueCache m_entry_instruction_finder
Definition: IRForTarget.h:461
llvm::FunctionCallee m_sel_registerName
The address of the function sel_registerName, cast to the appropriate function pointer type.
Definition: IRForTarget.h:427
llvm::IntegerType * m_intptr_ty
The type of an integer large enough to hold a pointer.
Definition: IRForTarget.h:432
bool RewriteObjCSelector(llvm::Instruction *selector_load)
A basic block-level pass to find all Objective-C method calls and rewrite them to use sel_registerNam...
bool ResolveExternals(llvm::Function &llvm_function)
The top-level pass implementation.
bool ReplaceVariables(llvm::Function &llvm_function)
A function-level pass to make all external variable references point at the correct offsets from the ...
static bool UnfoldConstant(llvm::Constant *old_constant, llvm::Function *llvm_function, FunctionValueCache &value_maker, FunctionValueCache &entry_instruction_finder, lldb_private::Stream &error_stream)
UnfoldConstant operates on a constant [Old] which has just been replaced with a value [New].
"lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are defined in LLDB's debug in...
A uniqued constant string class.
Definition: ConstString.h:39
"lldb/Expression/IRExecutionUnit.h" Contains the IR and, optionally, JIT- compiled code for a module.
A stream class that can stream formatted output to a file.
Definition: Stream.h:28
A class that represents a running process on the host machine.
Definition: SBAttachInfo.h:14
TaggedASTType< 0 > TypeFromParser
Definition: TaggedASTType.h:40
Definition: Debugger.h:52