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