contrib/llvm-project/lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionDeclMap.h

   1 //===-- ClangExpressionDeclMap.h --------------------------------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef liblldb_ClangExpressionDeclMap_h_
  10 #define liblldb_ClangExpressionDeclMap_h_
  11
  12 #include <signal.h>
  13 #include <stdint.h>
  14
  15 #include <vector>
  16
  17 #include "ClangASTSource.h"
  18 #include "ClangExpressionVariable.h"
  19
  20 #include "lldb/Core/ClangForward.h"
  21 #include "lldb/Core/Value.h"
  22 #include "lldb/Expression/Materializer.h"
  23 #include "lldb/Symbol/SymbolContext.h"
  24 #include "lldb/Symbol/TaggedASTType.h"
  25 #include "lldb/Target/ExecutionContext.h"
  26 #include "lldb/lldb-public.h"
  27 #include "clang/AST/Decl.h"
  28 #include "llvm/ADT/DenseMap.h"
  29
  30 namespace lldb_private {
  31
  32 /// \class ClangExpressionDeclMap ClangExpressionDeclMap.h
  33 /// "lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are
  34 /// defined in LLDB's debug information.
  35 ///
  36 /// The Clang parser uses the ClangASTSource as an interface to request named
  37 /// entities from outside an expression.  The ClangASTSource reports back,
  38 /// listing all possible objects corresponding to a particular name.  But it
  39 /// in turn relies on ClangExpressionDeclMap, which performs several important
  40 /// functions.
  41 ///
  42 /// First, it records what variables and functions were looked up and what
  43 /// Decls were returned for them.
  44 ///
  45 /// Second, it constructs a struct on behalf of IRForTarget, recording which
  46 /// variables should be placed where and relaying this information back so
  47 /// that IRForTarget can generate context-independent code.
  48 ///
  49 /// Third, it "materializes" this struct on behalf of the expression command,
  50 /// finding the current values of each variable and placing them into the
  51 /// struct so that it can be passed to the JITted version of the IR.
  52 ///
  53 /// Fourth and finally, it "dematerializes" the struct after the JITted code
  54 /// has has executed, placing the new values back where it found the old ones.
  55 class ClangExpressionDeclMap : public ClangASTSource {
  56 public:
  57   /// Constructor
  58   ///
  59   /// Initializes class variables.
  60   ///
  61   /// \param[in] keep_result_in_memory
  62   ///     If true, inhibits the normal deallocation of the memory for
  63   ///     the result persistent variable, and instead marks the variable
  64   ///     as persisting.
  65   ///
  66   /// \param[in] delegate
  67   ///     If non-NULL, use this delegate to report result values.  This
  68   ///     allows the client ClangUserExpression to report a result.
  69   ///
  70   /// \param[in] exe_ctx
  71   ///     The execution context to use when parsing.
  72   ///
  73   /// \param[in] ctx_obj
  74   ///     If not empty, then expression is evaluated in context of this object.
  75   ///     See the comment to `UserExpression::Evaluate` for details.
  76   ClangExpressionDeclMap(
  77       bool keep_result_in_memory,
  78       Materializer::PersistentVariableDelegate *result_delegate,
  79       ExecutionContext &exe_ctx,
  80       ValueObject *ctx_obj);
  81
  82   /// Destructor
  83   ~ClangExpressionDeclMap() override;
  84
  85   /// Enable the state needed for parsing and IR transformation.
  86   ///
  87   /// \param[in] exe_ctx
  88   ///     The execution context to use when finding types for variables.
  89   ///     Also used to find a "scratch" AST context to store result types.
  90   ///
  91   /// \param[in] materializer
  92   ///     If non-NULL, the materializer to populate with information about
  93   ///     the variables to use
  94   ///
  95   /// \return
  96   ///     True if parsing is possible; false if it is unsafe to continue.
  97   bool WillParse(ExecutionContext &exe_ctx, Materializer *materializer);
  98
  99   void InstallCodeGenerator(clang::ASTConsumer *code_gen);
 100
 101   /// [Used by ClangExpressionParser] For each variable that had an unknown
 102   ///     type at the beginning of parsing, determine its final type now.
 103   ///
 104   /// \return
 105   ///     True on success; false otherwise.
 106   bool ResolveUnknownTypes();
 107
 108   /// Disable the state needed for parsing and IR transformation.
 109   void DidParse();
 110
 111   /// [Used by IRForTarget] Add a variable to the list of persistent
 112   ///     variables for the process.
 113   ///
 114   /// \param[in] decl
 115   ///     The Clang declaration for the persistent variable, used for
 116   ///     lookup during parsing.
 117   ///
 118   /// \param[in] name
 119   ///     The name of the persistent variable, usually $something.
 120   ///
 121   /// \param[in] type
 122   ///     The type of the variable, in the Clang parser's context.
 123   ///
 124   /// \return
 125   ///     True on success; false otherwise.
 126   bool AddPersistentVariable(const clang::NamedDecl *decl,
 127                              ConstString name, TypeFromParser type,
 128                              bool is_result, bool is_lvalue);
 129
 130   /// [Used by IRForTarget] Add a variable to the struct that needs to
 131   ///     be materialized each time the expression runs.
 132   ///
 133   /// \param[in] decl
 134   ///     The Clang declaration for the variable.
 135   ///
 136   /// \param[in] name
 137   ///     The name of the variable.
 138   ///
 139   /// \param[in] value
 140   ///     The LLVM IR value for this variable.
 141   ///
 142   /// \param[in] size
 143   ///     The size of the variable in bytes.
 144   ///
 145   /// \param[in] alignment
 146   ///     The required alignment of the variable in bytes.
 147   ///
 148   /// \return
 149   ///     True on success; false otherwise.
 150   bool AddValueToStruct(const clang::NamedDecl *decl, ConstString name,
 151                         llvm::Value *value, size_t size,
 152                         lldb::offset_t alignment);
 153
 154   /// [Used by IRForTarget] Finalize the struct, laying out the position of
 155   /// each object in it.
 156   ///
 157   /// \return
 158   ///     True on success; false otherwise.
 159   bool DoStructLayout();
 160
 161   /// [Used by IRForTarget] Get general information about the laid-out struct
 162   /// after DoStructLayout() has been called.
 163   ///
 164   /// \param[out] num_elements
 165   ///     The number of elements in the struct.
 166   ///
 167   /// \param[out] size
 168   ///     The size of the struct, in bytes.
 169   ///
 170   /// \param[out] alignment
 171   ///     The alignment of the struct, in bytes.
 172   ///
 173   /// \return
 174   ///     True if the information could be retrieved; false otherwise.
 175   bool GetStructInfo(uint32_t &num_elements, size_t &size,
 176                      lldb::offset_t &alignment);
 177
 178   /// [Used by IRForTarget] Get specific information about one field of the
 179   /// laid-out struct after DoStructLayout() has been called.
 180   ///
 181   /// \param[out] decl
 182   ///     The parsed Decl for the field, as generated by ClangASTSource
 183   ///     on ClangExpressionDeclMap's behalf.  In the case of the result
 184   ///     value, this will have the name $__lldb_result even if the
 185   ///     result value ends up having the name $1.  This is an
 186   ///     implementation detail of IRForTarget.
 187   ///
 188   /// \param[out] value
 189   ///     The IR value for the field (usually a GlobalVariable).  In
 190   ///     the case of the result value, this will have the correct
 191   ///     name ($1, for instance).  This is an implementation detail
 192   ///     of IRForTarget.
 193   ///
 194   /// \param[out] offset
 195   ///     The offset of the field from the beginning of the struct.
 196   ///     As long as the struct is aligned according to its required
 197   ///     alignment, this offset will align the field correctly.
 198   ///
 199   /// \param[out] name
 200   ///     The name of the field as used in materialization.
 201   ///
 202   /// \param[in] index
 203   ///     The index of the field about which information is requested.
 204   ///
 205   /// \return
 206   ///     True if the information could be retrieved; false otherwise.
 207   bool GetStructElement(const clang::NamedDecl *&decl, llvm::Value *&value,
 208                         lldb::offset_t &offset, ConstString &name,
 209                         uint32_t index);
 210
 211   /// [Used by IRForTarget] Get information about a function given its Decl.
 212   ///
 213   /// \param[in] decl
 214   ///     The parsed Decl for the Function, as generated by ClangASTSource
 215   ///     on ClangExpressionDeclMap's behalf.
 216   ///
 217   /// \param[out] ptr
 218   ///     The absolute address of the function in the target.
 219   ///
 220   /// \return
 221   ///     True if the information could be retrieved; false otherwise.
 222   bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr);
 223
 224   /// [Used by IRForTarget] Get the address of a symbol given nothing but its
 225   /// name.
 226   ///
 227   /// \param[in] target
 228   ///     The target to find the symbol in.  If not provided,
 229   ///     then the current parsing context's Target.
 230   ///
 231   /// \param[in] process
 232   ///     The process to use.  For Objective-C symbols, the process's
 233   ///     Objective-C language runtime may be queried if the process
 234   ///     is non-NULL.
 235   ///
 236   /// \param[in] name
 237   ///     The name of the symbol.
 238   ///
 239   /// \param[in] module
 240   ///     The module to limit the search to. This can be NULL
 241   ///
 242   /// \return
 243   ///     Valid load address for the symbol
 244   lldb::addr_t GetSymbolAddress(Target &target, Process *process,
 245                                 ConstString name, lldb::SymbolType symbol_type,
 246                                 Module *module = nullptr);
 247
 248   lldb::addr_t GetSymbolAddress(ConstString name,
 249                                 lldb::SymbolType symbol_type);
 250
 251   /// [Used by IRInterpreter] Get basic target information.
 252   ///
 253   /// \param[out] byte_order
 254   ///     The byte order of the target.
 255   ///
 256   /// \param[out] address_byte_size
 257   ///     The size of a pointer in bytes.
 258   ///
 259   /// \return
 260   ///     True if the information could be determined; false
 261   ///     otherwise.
 262   struct TargetInfo {
 263     lldb::ByteOrder byte_order;
 264     size_t address_byte_size;
 265
 266     TargetInfo() : byte_order(lldb::eByteOrderInvalid), address_byte_size(0) {}
 267
 268     bool IsValid() {
 269       return (byte_order != lldb::eByteOrderInvalid && address_byte_size != 0);
 270     }
 271   };
 272   TargetInfo GetTargetInfo();
 273
 274   /// [Used by ClangASTSource] Find all entities matching a given name, using
 275   /// a NameSearchContext to make Decls for them.
 276   ///
 277   /// \param[in] context
 278   ///     The NameSearchContext that can construct Decls for this name.
 279   ///
 280   /// \return
 281   ///     True on success; false otherwise.
 282   void FindExternalVisibleDecls(NameSearchContext &context) override;
 283
 284   /// Find all entities matching a given name in a given module/namespace,
 285   /// using a NameSearchContext to make Decls for them.
 286   ///
 287   /// \param[in] context
 288   ///     The NameSearchContext that can construct Decls for this name.
 289   ///
 290   /// \param[in] module
 291   ///     If non-NULL, the module to query.
 292   ///
 293   /// \param[in] namespace_decl
 294   ///     If valid and module is non-NULL, the parent namespace.
 295   ///
 296   /// \param[in] current_id
 297   ///     The ID for the current FindExternalVisibleDecls invocation,
 298   ///     for logging purposes.
 299   ///
 300   /// \return
 301   ///     True on success; false otherwise.
 302   void FindExternalVisibleDecls(NameSearchContext &context,
 303                                 lldb::ModuleSP module,
 304                                 CompilerDeclContext &namespace_decl,
 305                                 unsigned int current_id);
 306
 307 private:
 308   ExpressionVariableList
 309       m_found_entities; ///< All entities that were looked up for the parser.
 310   ExpressionVariableList
 311       m_struct_members; ///< All entities that need to be placed in the struct.
 312   bool m_keep_result_in_memory; ///< True if result persistent variables
 313                                 ///generated by this expression should stay in
 314                                 ///memory.
 315   Materializer::PersistentVariableDelegate
 316       *m_result_delegate; ///< If non-NULL, used to report expression results to
 317                           ///ClangUserExpression.
 318   ValueObject *m_ctx_obj; ///< If not empty, then expression is
 319                           ///evaluated in context of this object.
 320                           ///For details see the comment to
 321                           ///`UserExpression::Evaluate`.
 322
 323   /// The following values should not live beyond parsing
 324   class ParserVars {
 325   public:
 326     ParserVars() {}
 327
 328     Target *GetTarget() {
 329       if (m_exe_ctx.GetTargetPtr())
 330         return m_exe_ctx.GetTargetPtr();
 331       else if (m_sym_ctx.target_sp)
 332         m_sym_ctx.target_sp.get();
 333       return nullptr;
 334     }
 335
 336     ExecutionContext m_exe_ctx; ///< The execution context to use when parsing.
 337     SymbolContext m_sym_ctx; ///< The symbol context to use in finding variables
 338                              ///and types.
 339     ClangPersistentVariables *m_persistent_vars =
 340         nullptr; ///< The persistent variables for the process.
 341     bool m_enable_lookups = false; ///< Set to true during parsing if we have
 342                                    ///found the first "$__lldb" name.
 343     TargetInfo m_target_info;      ///< Basic information about the target.
 344     Materializer *m_materializer = nullptr;   ///< If non-NULL, the materializer
 345                                               ///to use when reporting used
 346                                               ///variables.
 347     clang::ASTConsumer *m_code_gen = nullptr; ///< If non-NULL, a code generator
 348                                               ///that receives new top-level
 349                                               ///functions.
 350   private:
 351     DISALLOW_COPY_AND_ASSIGN(ParserVars);
 352   };
 353
 354   std::unique_ptr<ParserVars> m_parser_vars;
 355
 356   /// Activate parser-specific variables
 357   void EnableParserVars() {
 358     if (!m_parser_vars.get())
 359       m_parser_vars = llvm::make_unique<ParserVars>();
 360   }
 361
 362   /// Deallocate parser-specific variables
 363   void DisableParserVars() { m_parser_vars.reset(); }
 364
 365   /// The following values contain layout information for the materialized
 366   /// struct, but are not specific to a single materialization
 367   struct StructVars {
 368     StructVars()
 369         : m_struct_alignment(0), m_struct_size(0), m_struct_laid_out(false),
 370           m_result_name(), m_object_pointer_type(nullptr, nullptr) {}
 371
 372     lldb::offset_t
 373         m_struct_alignment; ///< The alignment of the struct in bytes.
 374     size_t m_struct_size;   ///< The size of the struct in bytes.
 375     bool m_struct_laid_out; ///< True if the struct has been laid out and the
 376                             ///layout is valid (that is, no new fields have been
 377                             ///added since).
 378     ConstString
 379         m_result_name; ///< The name of the result variable ($1, for example)
 380     TypeFromUser m_object_pointer_type; ///< The type of the "this" variable, if
 381                                         ///one exists
 382   };
 383
 384   std::unique_ptr<StructVars> m_struct_vars;
 385
 386   /// Activate struct variables
 387   void EnableStructVars() {
 388     if (!m_struct_vars.get())
 389       m_struct_vars.reset(new struct StructVars);
 390   }
 391
 392   /// Deallocate struct variables
 393   void DisableStructVars() { m_struct_vars.reset(); }
 394
 395   /// Get this parser's ID for use in extracting parser- and JIT-specific data
 396   /// from persistent variables.
 397   uint64_t GetParserID() { return (uint64_t) this; }
 398
 399   /// Given a target, find a variable that matches the given name and type.
 400   ///
 401   /// \param[in] target
 402   ///     The target to use as a basis for finding the variable.
 403   ///
 404   /// \param[in] module
 405   ///     If non-NULL, the module to search.
 406   ///
 407   /// \param[in] name
 408   ///     The name as a plain C string.
 409   ///
 410   /// \param[in] namespace_decl
 411   ///     If non-NULL and module is non-NULL, the parent namespace.
 412   ///
 413   /// \param[in] type
 414   ///     The required type for the variable.  This function may be called
 415   ///     during parsing, in which case we don't know its type; hence the
 416   ///     default.
 417   ///
 418   /// \return
 419   ///     The LLDB Variable found, or NULL if none was found.
 420   lldb::VariableSP FindGlobalVariable(Target &target, lldb::ModuleSP &module,
 421                                       ConstString name,
 422                                       CompilerDeclContext *namespace_decl,
 423                                       TypeFromUser *type = nullptr);
 424
 425   /// Get the value of a variable in a given execution context and return the
 426   /// associated Types if needed.
 427   ///
 428   /// \param[in] var
 429   ///     The variable to evaluate.
 430   ///
 431   /// \param[out] var_location
 432   ///     The variable location value to fill in
 433   ///
 434   /// \param[out] found_type
 435   ///     The type of the found value, as it was found in the user process.
 436   ///     This is only useful when the variable is being inspected on behalf
 437   ///     of the parser, hence the default.
 438   ///
 439   /// \param[out] parser_type
 440   ///     The type of the found value, as it was copied into the parser's
 441   ///     AST context.  This is only useful when the variable is being
 442   ///     inspected on behalf of the parser, hence the default.
 443   ///
 444   /// \param[in] decl
 445   ///     The Decl to be looked up.
 446   ///
 447   /// \return
 448   ///     Return true if the value was successfully filled in.
 449   bool GetVariableValue(lldb::VariableSP &var,
 450                         lldb_private::Value &var_location,
 451                         TypeFromUser *found_type = nullptr,
 452                         TypeFromParser *parser_type = nullptr);
 453
 454   /// Use the NameSearchContext to generate a Decl for the given LLDB
 455   /// Variable, and put it in the Tuple list.
 456   ///
 457   /// \param[in] context
 458   ///     The NameSearchContext to use when constructing the Decl.
 459   ///
 460   /// \param[in] var
 461   ///     The LLDB Variable that needs a Decl.
 462   ///
 463   /// \param[in] valobj
 464   ///     The LLDB ValueObject for that variable.
 465   void AddOneVariable(NameSearchContext &context, lldb::VariableSP var,
 466                       lldb::ValueObjectSP valobj, unsigned int current_id);
 467
 468   /// Use the NameSearchContext to generate a Decl for the given persistent
 469   /// variable, and put it in the list of found entities.
 470   ///
 471   /// \param[in] context
 472   ///     The NameSearchContext to use when constructing the Decl.
 473   ///
 474   /// \param[in] pvar
 475   ///     The persistent variable that needs a Decl.
 476   ///
 477   /// \param[in] current_id
 478   ///     The ID of the current invocation of FindExternalVisibleDecls
 479   ///     for logging purposes.
 480   void AddOneVariable(NameSearchContext &context,
 481                       lldb::ExpressionVariableSP &pvar_sp,
 482                       unsigned int current_id);
 483
 484   /// Use the NameSearchContext to generate a Decl for the given LLDB symbol
 485   /// (treated as a variable), and put it in the list of found entities.
 486   ///
 487   /// \param[in] context
 488   ///     The NameSearchContext to use when constructing the Decl.
 489   ///
 490   /// \param[in] var
 491   ///     The LLDB Variable that needs a Decl.
 492   void AddOneGenericVariable(NameSearchContext &context, const Symbol &symbol,
 493                              unsigned int current_id);
 494
 495   /// Use the NameSearchContext to generate a Decl for the given function.
 496   /// (Functions are not placed in the Tuple list.)  Can handle both fully
 497   /// typed functions and generic functions.
 498   ///
 499   /// \param[in] context
 500   ///     The NameSearchContext to use when constructing the Decl.
 501   ///
 502   /// \param[in] fun
 503   ///     The Function that needs to be created.  If non-NULL, this is
 504   ///     a fully-typed function.
 505   ///
 506   /// \param[in] sym
 507   ///     The Symbol that corresponds to a function that needs to be
 508   ///     created with generic type (unitptr_t foo(...)).
 509   void AddOneFunction(NameSearchContext &context, Function *fun, Symbol *sym,
 510                       unsigned int current_id);
 511
 512   /// Use the NameSearchContext to generate a Decl for the given register.
 513   ///
 514   /// \param[in] context
 515   ///     The NameSearchContext to use when constructing the Decl.
 516   ///
 517   /// \param[in] reg_info
 518   ///     The information corresponding to that register.
 519   void AddOneRegister(NameSearchContext &context, const RegisterInfo *reg_info,
 520                       unsigned int current_id);
 521
 522   /// Use the NameSearchContext to generate a Decl for the given type.  (Types
 523   /// are not placed in the Tuple list.)
 524   ///
 525   /// \param[in] context
 526   ///     The NameSearchContext to use when constructing the Decl.
 527   ///
 528   /// \param[in] type
 529   ///     The type that needs to be created.
 530   void AddOneType(NameSearchContext &context, const TypeFromUser &type,
 531                   unsigned int current_id);
 532
 533   /// Generate a Decl for "*this" and add a member function declaration to it
 534   /// for the expression, then report it.
 535   ///
 536   /// \param[in] context
 537   ///     The NameSearchContext to use when constructing the Decl.
 538   ///
 539   /// \param[in] type
 540   ///     The type for *this.
 541   void AddThisType(NameSearchContext &context, const TypeFromUser &type,
 542                    unsigned int current_id);
 543
 544   /// Move a type out of the current ASTContext into another, but make sure to
 545   /// export all components of the type also.
 546   ///
 547   /// \param[in] target
 548   ///     The ClangASTContext to move to.
 549   /// \param[in] source
 550   ///     The ClangASTContext to move from.  This is assumed to be going away.
 551   /// \param[in] parser_type
 552   ///     The type as it appears in the source context.
 553   ///
 554   /// \return
 555   ///     Returns the moved type, or an empty type if there was a problem.
 556   TypeFromUser DeportType(ClangASTContext &target, ClangASTContext &source,
 557                           TypeFromParser parser_type);
 558
 559   ClangASTContext *GetClangASTContext();
 560 };
 561
 562 } // namespace lldb_private
 563
 564 #endif // liblldb_ClangExpressionDeclMap_h_