lldb/source/Plugins/ExpressionParser/Clang/IRForTarget.h

   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
  13 #include "lldb/Symbol/TaggedASTType.h"
  14 #include "lldb/Utility/ConstString.h"
  15 #include "lldb/Utility/Status.h"
  16 #include "lldb/Utility/Stream.h"
  17 #include "lldb/Utility/StreamString.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
  25 namespace llvm {
  26 class BasicBlock;
  27 class CallInst;
  28 class Constant;
  29 class ConstantInt;
  30 class Function;
  31 class GlobalValue;
  32 class GlobalVariable;
  33 class Instruction;
  34 class Module;
  35 class StoreInst;
  36 class DataLayout;
  37 class Value;
  38 }
  39
  40 namespace clang {
  41 class NamedDecl;
  42 }
  43
  44 namespace lldb_private {
  45 class ClangExpressionDeclMap;
  46 class IRExecutionUnit;
  47 class 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.
  61 class IRForTarget {
  62 public:
  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
 103 private:
 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 function-level pass to take the generated global value
 115   /// $__lldb_expr_result and make it into a persistent variable. Also see
 116   /// ASTResultSynthesizer.
 117
 118   /// Find the NamedDecl corresponding to a Value.  This interface is exposed
 119   /// for the IR interpreter.
 120   ///
 121   /// \param[in] global_val
 122   ///     The global entity to search for
 123   ///
 124   /// \param[in] module
 125   ///     The module containing metadata to search
 126   ///
 127   /// \return
 128   ///     The corresponding variable declaration
 129 public:
 130   static clang::NamedDecl *DeclForGlobal(const llvm::GlobalValue *global_val,
 131                                          llvm::Module *module);
 132
 133 private:
 134   clang::NamedDecl *DeclForGlobal(llvm::GlobalValue *global);
 135
 136   /// The top-level pass implementation
 137   ///
 138   /// \param[in] llvm_function
 139   ///     The function currently being processed.
 140   ///
 141   /// \return
 142   ///     True on success; false otherwise
 143   bool CreateResultVariable(llvm::Function &llvm_function);
 144
 145   /// A module-level pass to find Objective-C constant strings and
 146   /// transform them to calls to CFStringCreateWithBytes.
 147
 148   /// Rewrite a single Objective-C constant string.
 149   ///
 150   /// \param[in] NSStr
 151   ///     The constant NSString to be transformed
 152   ///
 153   /// \param[in] CStr
 154   ///     The constant C string inside the NSString.  This will be
 155   ///     passed as the bytes argument to CFStringCreateWithBytes.
 156   ///
 157   /// \return
 158   ///     True on success; false otherwise
 159   bool RewriteObjCConstString(llvm::GlobalVariable *NSStr,
 160                               llvm::GlobalVariable *CStr);
 161
 162   /// The top-level pass implementation
 163   ///
 164   /// \return
 165   ///     True on success; false otherwise
 166   bool RewriteObjCConstStrings();
 167
 168   /// A basic block-level pass to find all Objective-C method calls and
 169   /// rewrite them to use sel_registerName instead of statically allocated
 170   /// selectors.  The reason is that the selectors are created on the
 171   /// assumption that the Objective-C runtime will scan the appropriate
 172   /// section and prepare them.  This doesn't happen when code is copied into
 173   /// the target, though, and there's no easy way to induce the runtime to
 174   /// scan them.  So instead we get our selectors from sel_registerName.
 175
 176   /// Replace a single selector reference
 177   ///
 178   /// \param[in] selector_load
 179   ///     The load of the statically-allocated selector.
 180   ///
 181   /// \return
 182   ///     True on success; false otherwise
 183   bool RewriteObjCSelector(llvm::Instruction *selector_load);
 184
 185   /// The top-level pass implementation
 186   ///
 187   /// \param[in] basic_block
 188   ///     The basic block currently being processed.
 189   ///
 190   /// \return
 191   ///     True on success; false otherwise
 192   bool RewriteObjCSelectors(llvm::BasicBlock &basic_block);
 193
 194   /// A basic block-level pass to find all newly-declared persistent
 195   /// variables and register them with the ClangExprDeclMap.  This allows them
 196   /// to be materialized and dematerialized like normal external variables.
 197   /// Before transformation, these persistent variables look like normal
 198   /// locals, so they have an allocation. This pass excises these allocations
 199   /// and makes references look like external references where they will be
 200   /// resolved -- like all other external references -- by ResolveExternals().
 201
 202   /// Handle a single allocation of a persistent variable
 203   ///
 204   /// \param[in] persistent_alloc
 205   ///     The allocation of the persistent variable.
 206   ///
 207   /// \return
 208   ///     True on success; false otherwise
 209   bool RewritePersistentAlloc(llvm::Instruction *persistent_alloc);
 210
 211   /// The top-level pass implementation
 212   ///
 213   /// \param[in] basic_block
 214   ///     The basic block currently being processed.
 215   bool RewritePersistentAllocs(llvm::BasicBlock &basic_block);
 216
 217   /// A function-level pass to find all external variables and functions
 218   /// used in the IR.  Each found external variable is added to the struct,
 219   /// and each external function is resolved in place, its call replaced with
 220   /// a call to a function pointer whose value is the address of the function
 221   /// in the target process.
 222
 223   /// Handle a single externally-defined variable
 224   ///
 225   /// \param[in] value
 226   ///     The variable.
 227   ///
 228   /// \return
 229   ///     True on success; false otherwise
 230   bool MaybeHandleVariable(llvm::Value *value);
 231
 232   /// Handle a single externally-defined symbol
 233   ///
 234   /// \param[in] symbol
 235   ///     The symbol.
 236   ///
 237   /// \return
 238   ///     True on success; false otherwise
 239   bool HandleSymbol(llvm::Value *symbol);
 240
 241   /// Handle a single externally-defined Objective-C class
 242   ///
 243   /// \param[in] classlist_reference
 244   ///     The reference, usually "01L_OBJC_CLASSLIST_REFERENCES_$_n"
 245   ///     where n (if present) is an index.
 246   ///
 247   /// \return
 248   ///     True on success; false otherwise
 249   bool HandleObjCClass(llvm::Value *classlist_reference);
 250
 251   /// Handle all the arguments to a function call
 252   ///
 253   /// \param[in] call_inst
 254   ///     The call instruction.
 255   ///
 256   /// \return
 257   ///     True on success; false otherwise
 258   bool MaybeHandleCallArguments(llvm::CallInst *call_inst);
 259
 260   /// Resolve variable references in calls to external functions
 261   ///
 262   /// \param[in] basic_block
 263   ///     The basic block currently being processed.
 264   ///
 265   /// \return
 266   ///     True on success; false otherwise
 267   bool ResolveCalls(llvm::BasicBlock &basic_block);
 268
 269   /// Remove calls to __cxa_atexit, which should never be generated by
 270   /// expressions.
 271   ///
 272   /// \param[in] basic_block
 273   ///     The basic block currently being processed.
 274   ///
 275   /// \return
 276   ///     True if the scan was successful; false if some operation
 277   ///     failed
 278   bool RemoveCXAAtExit(llvm::BasicBlock &basic_block);
 279
 280   /// The top-level pass implementation
 281   ///
 282   /// \param[in] llvm_function
 283   ///     The function currently being processed.
 284   ///
 285   /// \return
 286   ///     True on success; false otherwise
 287   bool ResolveExternals(llvm::Function &llvm_function);
 288
 289   /// A basic block-level pass to excise guard variables from the code.
 290   /// The result for the function is passed through Clang as a static
 291   /// variable.  Static variables normally have guard variables to ensure that
 292   /// they are only initialized once.
 293
 294   /// Rewrite a load to a guard variable to return constant 0.
 295   ///
 296   /// \param[in] guard_load
 297   ///     The load instruction to zero out.
 298   void TurnGuardLoadIntoZero(llvm::Instruction *guard_load);
 299
 300   /// The top-level pass implementation
 301   ///
 302   /// \param[in] basic_block
 303   ///     The basic block currently being processed.
 304   ///
 305   /// \return
 306   ///     True on success; false otherwise
 307   bool RemoveGuards(llvm::BasicBlock &basic_block);
 308
 309   /// A function-level pass to make all external variable references
 310   /// point at the correct offsets from the void* passed into the function.
 311   /// ClangExpressionDeclMap::DoStructLayout() must be called beforehand, so
 312   /// that the offsets are valid.
 313
 314   /// The top-level pass implementation
 315   ///
 316   /// \param[in] llvm_function
 317   ///     The function currently being processed.
 318   ///
 319   /// \return
 320   ///     True on success; false otherwise
 321   bool ReplaceVariables(llvm::Function &llvm_function);
 322
 323   /// True if external variable references and persistent variable references
 324   /// should be resolved
 325   bool m_resolve_vars;
 326   /// The name of the function to translate
 327   lldb_private::ConstString m_func_name;
 328   /// The name of the result variable ($0, $1, ...)
 329   lldb_private::ConstString m_result_name;
 330   /// The type of the result variable.
 331   lldb_private::TypeFromParser m_result_type;
 332   /// The module being processed, or NULL if that has not been determined yet.
 333   llvm::Module *m_module = nullptr;
 334   /// The target data for the module being processed, or NULL if there is no
 335   /// module.
 336   std::unique_ptr<llvm::DataLayout> m_target_data;
 337   /// The DeclMap containing the Decls
 338   lldb_private::ClangExpressionDeclMap *m_decl_map;
 339   /// The address of the function CFStringCreateWithBytes, cast to the
 340   /// appropriate function pointer type
 341   llvm::FunctionCallee m_CFStringCreateWithBytes;
 342   /// The address of the function sel_registerName, cast to the appropriate
 343   /// function pointer type.
 344   llvm::FunctionCallee m_sel_registerName;
 345   /// The type of an integer large enough to hold a pointer.
 346   llvm::IntegerType *m_intptr_ty = nullptr;
 347   /// The stream on which errors should be printed.
 348   lldb_private::Stream &m_error_stream;
 349   /// The execution unit containing the IR being created.
 350   lldb_private::IRExecutionUnit &m_execution_unit;
 351   /// True if the function's result in the AST is a pointer (see comments in
 352   /// ASTResultSynthesizer::SynthesizeBodyResult)
 353   bool m_result_is_pointer = false;
 354
 355   class FunctionValueCache {
 356   public:
 357     typedef std::function<llvm::Value *(llvm::Function *)> Maker;
 358
 359     FunctionValueCache(Maker const &maker);
 360     ~FunctionValueCache();
 361     llvm::Value *GetValue(llvm::Function *function);
 362
 363   private:
 364     Maker const m_maker;
 365     typedef std::map<llvm::Function *, llvm::Value *> FunctionValueMap;
 366     FunctionValueMap m_values;
 367   };
 368
 369   FunctionValueCache m_entry_instruction_finder;
 370
 371   /// UnfoldConstant operates on a constant [Old] which has just been replaced
 372   /// with a value [New].  We assume that new_value has been properly placed
 373   /// early in the function, in front of the first instruction in the entry
 374   /// basic block [FirstEntryInstruction].
 375   ///
 376   /// UnfoldConstant reads through the uses of Old and replaces Old in those
 377   /// uses with New.  Where those uses are constants, the function generates
 378   /// new instructions to compute the result of the new, non-constant
 379   /// expression and places them before FirstEntryInstruction.  These
 380   /// instructions replace the constant uses, so UnfoldConstant calls itself
 381   /// recursively for those.
 382   ///
 383   /// \return
 384   ///     True on success; false otherwise
 385   static bool UnfoldConstant(llvm::Constant *old_constant,
 386                              llvm::Function *llvm_function,
 387                              FunctionValueCache &value_maker,
 388                              FunctionValueCache &entry_instruction_finder,
 389                              lldb_private::Stream &error_stream);
 390 };
 391
 392 #endif // LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_IRFORTARGET_H