ClangExpressionDeclMap.h revision 45690fe3b8b4efb101dd31085413381021a69c2f
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// Other libraries and framework includes 21// Project includes 22#include "lldb/Core/ClangForward.h" 23#include "lldb/Core/Value.h" 24#include "lldb/Expression/ClangExpressionVariable.h" 25#include "lldb/Symbol/TaggedASTType.h" 26 27namespace llvm { 28 class Type; 29 class Value; 30} 31 32namespace lldb_private { 33 34class ClangExpressionVariables; 35class ClangPersistentVariables; 36class Error; 37class Function; 38class NameSearchContext; 39class Variable; 40 41//---------------------------------------------------------------------- 42/// @class ClangExpressionDeclMap ClangExpressionDeclMap.h "lldb/Expression/ClangExpressionDeclMap.h" 43/// @brief Manages named entities that are defined in LLDB's debug information. 44/// 45/// The Clang parser uses the ClangASTSource as an interface to request named 46/// entities from outside an expression. The ClangASTSource reports back, listing 47/// all possible objects corresponding to a particular name. But it in turn 48/// relies on ClangExpressionDeclMap, which performs several important functions. 49/// 50/// First, it records what variables and functions were looked up and what Decls 51/// were returned for them. 52/// 53/// Second, it constructs a struct on behalf of IRForTarget, recording which 54/// variables should be placed where and relaying this information back so that 55/// IRForTarget can generate context-independent code. 56/// 57/// Third, it "materializes" this struct on behalf of the expression command, 58/// finding the current values of each variable and placing them into the 59/// struct so that it can be passed to the JITted version of the IR. 60/// 61/// Fourth and finally, it "dematerializes" the struct after the JITted code has 62/// has executed, placing the new values back where it found the old ones. 63//---------------------------------------------------------------------- 64class ClangExpressionDeclMap 65{ 66public: 67 //------------------------------------------------------------------ 68 /// Constructor 69 /// 70 /// Initializes class variabes. 71 /// 72 /// @param[in] exe_ctx 73 /// The execution context to use when finding types for variables. 74 /// Also used to find a "scratch" AST context to store result types. 75 //------------------------------------------------------------------ 76 ClangExpressionDeclMap(ExecutionContext *exe_ctx); 77 78 //------------------------------------------------------------------ 79 /// Destructor 80 //------------------------------------------------------------------ 81 ~ClangExpressionDeclMap(); 82 83 //------------------------------------------------------------------ 84 /// [Used by IRForTarget] Get a new result variable name of the form 85 /// $n, where n is a natural number starting with 0. 86 /// 87 /// @param[in] name 88 /// The std::string to place the name into. 89 //------------------------------------------------------------------ 90 void GetPersistentResultName (std::string &name); 91 92 //------------------------------------------------------------------ 93 /// [Used by IRForTarget] Add a variable to the list of persistent 94 /// variables for the process. 95 /// 96 /// @param[in] decl 97 /// The Clang declaration for the persistent variable, used for 98 /// lookup during parsing. 99 /// 100 /// @param[in] name 101 /// The name of the persistent variable, usually $something. 102 /// 103 /// @param[in] type 104 /// The type of the variable, in the Clang parser's context. 105 /// 106 /// @return 107 /// True on success; false otherwise. 108 //------------------------------------------------------------------ 109 bool AddPersistentVariable (const clang::NamedDecl *decl, 110 const char *name, 111 TypeFromParser type); 112 113 //------------------------------------------------------------------ 114 /// [Used by IRForTarget] Add a variable to the struct that needs to 115 /// be materialized each time the expression runs. 116 /// 117 /// @param[in] decl 118 /// The Clang declaration for the variable. 119 /// 120 /// @param[in] name 121 /// The name of the variable. 122 /// 123 /// @param[in] value 124 /// The LLVM IR value for this variable. 125 /// 126 /// @param[in] size 127 /// The size of the variable in bytes. 128 /// 129 /// @param[in] alignment 130 /// The required alignment of the variable in bytes. 131 /// 132 /// @return 133 /// True on success; false otherwise. 134 //------------------------------------------------------------------ 135 bool AddValueToStruct (const clang::NamedDecl *decl, 136 const char *name, 137 llvm::Value *value, 138 size_t size, 139 off_t alignment); 140 141 //------------------------------------------------------------------ 142 /// [Used by IRForTarget] Finalize the struct, laying out the position 143 /// of each object in it. 144 /// 145 /// @return 146 /// True on success; false otherwise. 147 //------------------------------------------------------------------ 148 bool DoStructLayout (); 149 150 //------------------------------------------------------------------ 151 /// [Used by IRForTarget] Get general information about the laid-out 152 /// struct after DoStructLayout() has been called. 153 /// 154 /// @param[out] num_elements 155 /// The number of elements in the struct. 156 /// 157 /// @param[out] size 158 /// The size of the struct, in bytes. 159 /// 160 /// @param[out] alignment 161 /// The alignment of the struct, in bytes. 162 /// 163 /// @return 164 /// True if the information could be retrieved; false otherwise. 165 //------------------------------------------------------------------ 166 bool GetStructInfo (uint32_t &num_elements, 167 size_t &size, 168 off_t &alignment); 169 170 //------------------------------------------------------------------ 171 /// [Used by IRForTarget] Get specific information about one field 172 /// of the laid-out struct after DoStructLayout() has been called. 173 /// 174 /// @param[out] decl 175 /// The parsed Decl for the field, as generated by ClangASTSource 176 /// on ClangExpressionDeclMap's behalf. In the case of the result 177 /// value, this will have the name ___clang_result even if the 178 /// result value ends up having the name $1. This is an 179 /// implementation detail of IRForTarget. 180 /// 181 /// @param[out] value 182 /// The IR value for the field (usually a GlobalVariable). In 183 /// the case of the result value, this will have the correct 184 /// name ($1, for instance). This is an implementation detail 185 /// of IRForTarget. 186 /// 187 /// @param[out] offset 188 /// The offset of the field from the beginning of the struct. 189 /// As long as the struct is aligned according to its required 190 /// alignment, this offset will align the field correctly. 191 /// 192 /// @param[out] name 193 /// The name of the field as used in materialization. 194 /// 195 /// @param[in] index 196 /// The index of the field about which information is requested. 197 /// 198 /// @return 199 /// True if the information could be retrieved; false otherwise. 200 //------------------------------------------------------------------ 201 bool GetStructElement (const clang::NamedDecl *&decl, 202 llvm::Value *&value, 203 off_t &offset, 204 const char *&name, 205 uint32_t index); 206 207 //------------------------------------------------------------------ 208 /// [Used by IRForTarget] Get information about a function given its 209 /// Decl. 210 /// 211 /// @param[in] decl 212 /// The parsed Decl for the Function, as generated by ClangASTSource 213 /// on ClangExpressionDeclMap's behalf. 214 /// 215 /// @param[out] value 216 /// A pointer to the address where a Value for the function's address 217 /// can be stored. IRForTarget typically places a ConstantExpr here. 218 /// 219 /// @param[out] ptr 220 /// The absolute address of the function in the target. 221 /// 222 /// @return 223 /// True if the information could be retrieved; false otherwise. 224 //------------------------------------------------------------------ 225 bool GetFunctionInfo (const clang::NamedDecl *decl, 226 llvm::Value**& value, 227 uint64_t &ptr); 228 229 //------------------------------------------------------------------ 230 /// [Used by IRForTarget] Get the address of a function given nothing 231 /// but its name. Some functions are needed but didn't get Decls made 232 /// during parsing -- specifically, sel_registerName is never called 233 /// in the generated IR but we need to call it nonetheless. 234 /// 235 /// @param[in] name 236 /// The name of the function. 237 /// 238 /// @param[out] ptr 239 /// The absolute address of the function in the target. 240 /// 241 /// @return 242 /// True if the address could be retrieved; false otherwise. 243 //------------------------------------------------------------------ 244 bool GetFunctionAddress (const char *name, 245 uint64_t &ptr); 246 247 //------------------------------------------------------------------ 248 /// [Used by CommandObjectExpression] Materialize the entire struct 249 /// at a given address, which should be aligned as specified by 250 /// GetStructInfo(). 251 /// 252 /// @param[in] exe_ctx 253 /// The execution context at which to dump the struct. 254 /// 255 /// @param[in] struct_address 256 /// The address at which the struct should be written. 257 /// 258 /// @param[in] error 259 /// An Error to populate with any messages related to 260 /// materializing the struct. 261 /// 262 /// @return 263 /// True on success; false otherwise. 264 //------------------------------------------------------------------ 265 bool Materialize(ExecutionContext *exe_ctx, 266 lldb::addr_t &struct_address, 267 Error &error); 268 269 //------------------------------------------------------------------ 270 /// [Used by CommandObjectExpression] Pretty-print a materialized 271 /// struct, which must have been materialized by Materialize(), 272 /// byte for byte on a given stream. 273 /// 274 /// @param[in] exe_ctx 275 /// The execution context from which to read the struct. 276 /// 277 /// @param[in] s 278 /// The stream on which to write the pretty-printed output. 279 /// 280 /// @param[in] error 281 /// An Error to populate with any messages related to 282 /// pretty-printing the struct. 283 /// 284 /// @return 285 /// True on success; false otherwise. 286 //------------------------------------------------------------------ 287 bool DumpMaterializedStruct(ExecutionContext *exe_ctx, 288 Stream &s, 289 Error &error); 290 291 //------------------------------------------------------------------ 292 /// [Used by CommandObjectExpression] Deaterialize the entire struct. 293 /// 294 /// @param[in] exe_ctx 295 /// The execution context from which to read the struct. 296 /// 297 /// @param[out] result 298 /// A ClangExpressionVariable containing the result of the 299 /// expression, for potential re-use. 300 /// 301 /// @param[in] error 302 /// An Error to populate with any messages related to 303 /// dematerializing the struct. 304 /// 305 /// @return 306 /// True on success; false otherwise. 307 //------------------------------------------------------------------ 308 bool Dematerialize(ExecutionContext *exe_ctx, 309 ClangExpressionVariable *&result, 310 Error &error); 311 312 //------------------------------------------------------------------ 313 /// [Used by ClangASTSource] Find all entities matching a given name, 314 /// using a NameSearchContext to make Decls for them. 315 /// 316 /// @param[in] context 317 /// The NameSearchContext that can construct Decls for this name. 318 /// 319 /// @param[in] name 320 /// The name as a plain C string. The NameSearchContext contains 321 /// a DeclarationName for the name so at first the name may seem 322 /// redundant, but ClangExpressionDeclMap operates in RTTI land so 323 /// it can't access DeclarationName. 324 /// 325 /// @return 326 /// True on success; false otherwise. 327 //------------------------------------------------------------------ 328 void GetDecls (NameSearchContext &context, 329 const char *name); 330private: 331 ClangExpressionVariableStore m_found_entities; ///< All entities that were looked up for the parser. 332 ClangExpressionVariableList m_struct_members; ///< All entities that need to be placed in the struct. 333 334 ExecutionContext *m_exe_ctx; ///< The execution context where this expression was first defined. It determines types for all the external variables, even if the expression is re-used. 335 SymbolContext *m_sym_ctx; ///< [owned by ClangExpressionDeclMap] The symbol context where this expression was first defined. 336 ClangPersistentVariables *m_persistent_vars; ///< The list of persistent variables to use when resolving symbols in the expression and when creating new ones (like the result). 337 off_t m_struct_alignment; ///< The alignment of the struct in bytes. 338 size_t m_struct_size; ///< The size of the struct in bytes. 339 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). 340 lldb::addr_t m_allocated_area; ///< The base of the memory allocated for the struct. Starts on a potentially unaligned address and may therefore be larger than the struct. 341 lldb::addr_t m_materialized_location; ///< The address at which the struct is placed. Falls inside the allocated area. 342 std::string m_result_name; ///< The name of the result variable ($1, for example) 343 344 //------------------------------------------------------------------ 345 /// Given a symbol context, find a variable that matches the given 346 /// name and type. We need this for expression re-use; we may not 347 /// always get the same lldb::Variable back, and we want the expression 348 /// to work wherever it can. Returns the variable defined in the 349 /// tightest scope. 350 /// 351 /// @param[in] sym_ctx 352 /// The SymbolContext to search for the variable. 353 /// 354 /// @param[in] name 355 /// The name as a plain C string. 356 /// 357 /// @param[in] type 358 /// The required type for the variable. This function may be called 359 /// during parsing, in which case we don't know its type; hence the 360 /// default. 361 /// 362 /// @return 363 /// The LLDB Variable found, or NULL if none was found. 364 //------------------------------------------------------------------ 365 Variable *FindVariableInScope(const SymbolContext &sym_ctx, 366 const char *name, 367 TypeFromUser *type = NULL); 368 369 //------------------------------------------------------------------ 370 /// Get the value of a variable in a given execution context and return 371 /// the associated Types if needed. 372 /// 373 /// @param[in] exe_ctx 374 /// The execution context to look for the variable in. 375 /// 376 /// @param[in] var 377 /// The variable to evaluate. 378 /// 379 /// @param[in] parser_ast_context 380 /// The AST context of the parser, to store the found type in. 381 /// 382 /// @param[out] found_type 383 /// The type of the found value, as it was found in the user process. 384 /// This is only useful when the variable is being inspected on behalf 385 /// of the parser, hence the default. 386 /// 387 /// @param[out] parser_type 388 /// The type of the found value, as it was copied into the parser's 389 /// AST context. This is only useful when the variable is being 390 /// inspected on behalf of the parser, hence the default. 391 /// 392 /// @param[in] decl 393 /// The Decl to be looked up. 394 /// 395 /// @return 396 /// The LLDB Value for the variable. 397 //------------------------------------------------------------------ 398 Value *GetVariableValue(ExecutionContext &exe_ctx, 399 Variable *var, 400 clang::ASTContext *parser_ast_context, 401 TypeFromUser *found_type = NULL, 402 TypeFromParser *parser_type = NULL); 403 404 //------------------------------------------------------------------ 405 /// Use the NameSearchContext to generate a Decl for the given LLDB 406 /// Variable, and put it in the Tuple list. 407 /// 408 /// @param[in] context 409 /// The NameSearchContext to use when constructing the Decl. 410 /// 411 /// @param[in] var 412 /// The LLDB Variable that needs a Decl. 413 //------------------------------------------------------------------ 414 void AddOneVariable(NameSearchContext &context, Variable *var); 415 416 //------------------------------------------------------------------ 417 /// Use the NameSearchContext to generate a Decl for the given 418 /// persistent variable, and put it in the Tuple list. 419 /// 420 /// @param[in] context 421 /// The NameSearchContext to use when constructing the Decl. 422 /// 423 /// @param[in] pvar 424 /// The persistent variable that needs a Decl. 425 //------------------------------------------------------------------ 426 void AddOneVariable(NameSearchContext &context, ClangExpressionVariable *pvar); 427 428 //------------------------------------------------------------------ 429 /// Use the NameSearchContext to generate a Decl for the given 430 /// function. (Functions are not placed in the Tuple list.) Can 431 /// handle both fully typed functions and generic functions. 432 /// 433 /// @param[in] context 434 /// The NameSearchContext to use when constructing the Decl. 435 /// 436 /// @param[in] fun 437 /// The Function that needs to be created. If non-NULL, this is 438 /// a fully-typed function. 439 /// 440 /// @param[in] sym 441 /// The Symbol that corresponds to a function that needs to be 442 /// created with generic type (unitptr_t foo(...)). 443 //------------------------------------------------------------------ 444 void AddOneFunction(NameSearchContext &context, Function *fun, Symbol *sym); 445 446 //------------------------------------------------------------------ 447 /// Use the NameSearchContext to generate a Decl for the given 448 /// type. (Types are not placed in the Tuple list.) 449 /// 450 /// @param[in] context 451 /// The NameSearchContext to use when constructing the Decl. 452 /// 453 /// @param[in] type 454 /// The LLDB Type that needs to be created. 455 //------------------------------------------------------------------ 456 void AddOneType(NameSearchContext &context, Type *type); 457 458 //------------------------------------------------------------------ 459 /// Actually do the task of materializing or dematerializing the struct. 460 /// Since both tasks are very similar, although ClangExpressionDeclMap 461 /// exposes two functions to the outside, both call DoMaterialize. 462 /// 463 /// @param[in] dematerialize 464 /// True if the struct is to be dematerialized; false if it is to 465 /// be materialized. 466 /// 467 /// @param[in] exe_ctx 468 /// The execution context to use. 469 /// 470 /// @param[out] result 471 /// If the struct is being dematerialized, a pointer into which the 472 /// location of the result persistent variable is placed. If not, 473 /// NULL. 474 /// 475 /// @param[in] err 476 /// An Error to populate with any messages related to 477 /// (de)materializing the struct. 478 /// 479 /// @return 480 /// True on success; false otherwise. 481 //------------------------------------------------------------------ 482 bool DoMaterialize (bool dematerialize, 483 ExecutionContext *exe_ctx, 484 ClangExpressionVariable **result, 485 Error &err); 486 487 //------------------------------------------------------------------ 488 /// Actually do the task of materializing or dematerializing a persistent 489 /// variable. 490 /// 491 /// @param[in] dematerialize 492 /// True if the variable is to be dematerialized; false if it is to 493 /// be materialized. 494 /// 495 /// @param[in] exe_ctx 496 /// The execution context to use. 497 /// 498 /// @param[in] name 499 /// The name of the persistent variable. 500 /// 501 /// @param[in] addr 502 /// The address at which to materialize the variable. 503 /// 504 /// @param[in] err 505 /// An Error to populate with any messages related to 506 /// (de)materializing the persistent variable. 507 /// 508 /// @return 509 /// True on success; false otherwise. 510 //------------------------------------------------------------------ 511 bool DoMaterializeOnePersistentVariable(bool dematerialize, 512 ExecutionContext &exe_ctx, 513 const char *name, 514 lldb::addr_t addr, 515 Error &err); 516 517 //------------------------------------------------------------------ 518 /// Actually do the task of materializing or dematerializing a 519 /// variable. 520 /// 521 /// @param[in] dematerialize 522 /// True if the variable is to be dematerialized; false if it is to 523 /// be materialized. 524 /// 525 /// @param[in] exe_ctx 526 /// The execution context to use. 527 /// 528 /// @param[in] sym_ctx 529 /// The symbol context to use (for looking the variable up). 530 /// 531 /// @param[in] name 532 /// The name of the variable (for looking the variable up). 533 /// 534 /// @param[in] type 535 /// The required type of the variable (for looking the variable up). 536 /// 537 /// @param[in] addr 538 /// The address at which to materialize the variable. 539 /// 540 /// @param[in] err 541 /// An Error to populate with any messages related to 542 /// (de)materializing the persistent variable. 543 /// 544 /// @return 545 /// True on success; false otherwise. 546 //------------------------------------------------------------------ 547 bool DoMaterializeOneVariable(bool dematerialize, 548 ExecutionContext &exe_ctx, 549 const SymbolContext &sym_ctx, 550 const char *name, 551 TypeFromUser type, 552 lldb::addr_t addr, 553 Error &err); 554}; 555 556} // namespace lldb_private 557 558#endif // liblldb_ClangExpressionDeclMap_h_ 559