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