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