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