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