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