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