1 //===-- ClangExpressionDeclMap.h --------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_ClangExpressionDeclMap_h_
11 #define liblldb_ClangExpressionDeclMap_h_
20 // Other libraries and framework includes
22 #include "llvm/ADT/APInt.h"
23 #include "llvm/ADT/DenseMap.h"
24 #include "clang/AST/Decl.h"
25 #include "lldb/lldb-public.h"
26 #include "lldb/Core/ClangForward.h"
27 #include "lldb/Core/Value.h"
28 #include "lldb/Expression/ClangASTSource.h"
29 #include "lldb/Expression/ClangExpressionVariable.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"
35 namespace lldb_private {
37 //----------------------------------------------------------------------
38 /// @class ClangExpressionDeclMap ClangExpressionDeclMap.h "lldb/Expression/ClangExpressionDeclMap.h"
39 /// @brief Manages named entities that are defined in LLDB's debug information.
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.
46 /// First, it records what variables and functions were looked up and what Decls
47 /// were returned for them.
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.
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.
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 :
64 //------------------------------------------------------------------
67 /// Initializes class variables.
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
74 /// @param[in] exe_ctx
75 /// The execution context to use when parsing.
76 //------------------------------------------------------------------
77 ClangExpressionDeclMap (bool keep_result_in_memory,
78 ExecutionContext &exe_ctx);
80 //------------------------------------------------------------------
82 //------------------------------------------------------------------
83 ~ClangExpressionDeclMap ();
85 //------------------------------------------------------------------
86 /// Enable the state needed for parsing and IR transformation.
88 /// @param[in] exe_ctx
89 /// The execution context to use when finding types for variables.
90 /// Also used to find a "scratch" AST context to store result types.
92 /// @param[in] materializer
93 /// If non-NULL, the materializer to populate with information about
94 /// the variables to use
97 /// True if parsing is possible; false if it is unsafe to continue.
98 //------------------------------------------------------------------
100 WillParse (ExecutionContext &exe_ctx,
101 Materializer *materializer);
103 //------------------------------------------------------------------
104 /// [Used by ClangExpressionParser] For each variable that had an unknown
105 /// type at the beginning of parsing, determine its final type now.
108 /// True on success; false otherwise.
109 //------------------------------------------------------------------
111 ResolveUnknownTypes();
113 //------------------------------------------------------------------
114 /// Disable the state needed for parsing and IR transformation.
115 //------------------------------------------------------------------
119 //------------------------------------------------------------------
120 /// [Used by IRForTarget] Add a variable to the list of persistent
121 /// variables for the process.
124 /// The Clang declaration for the persistent variable, used for
125 /// lookup during parsing.
128 /// The name of the persistent variable, usually $something.
131 /// The type of the variable, in the Clang parser's context.
134 /// True on success; false otherwise.
135 //------------------------------------------------------------------
137 AddPersistentVariable (const clang::NamedDecl *decl,
138 const ConstString &name,
143 //------------------------------------------------------------------
144 /// [Used by IRForTarget] Add a variable to the struct that needs to
145 /// be materialized each time the expression runs.
148 /// The Clang declaration for the variable.
151 /// The name of the variable.
154 /// The LLVM IR value for this variable.
157 /// The size of the variable in bytes.
159 /// @param[in] alignment
160 /// The required alignment of the variable in bytes.
163 /// True on success; false otherwise.
164 //------------------------------------------------------------------
166 AddValueToStruct (const clang::NamedDecl *decl,
167 const ConstString &name,
172 //------------------------------------------------------------------
173 /// [Used by IRForTarget] Finalize the struct, laying out the position
174 /// of each object in it.
177 /// True on success; false otherwise.
178 //------------------------------------------------------------------
182 //------------------------------------------------------------------
183 /// [Used by IRForTarget] Get general information about the laid-out
184 /// struct after DoStructLayout() has been called.
186 /// @param[out] num_elements
187 /// The number of elements in the struct.
190 /// The size of the struct, in bytes.
192 /// @param[out] alignment
193 /// The alignment of the struct, in bytes.
196 /// True if the information could be retrieved; false otherwise.
197 //------------------------------------------------------------------
199 GetStructInfo (uint32_t &num_elements,
203 //------------------------------------------------------------------
204 /// [Used by IRForTarget] Get specific information about one field
205 /// of the laid-out struct after DoStructLayout() has been called.
208 /// The parsed Decl for the field, as generated by ClangASTSource
209 /// on ClangExpressionDeclMap's behalf. In the case of the result
210 /// value, this will have the name $__lldb_result even if the
211 /// result value ends up having the name $1. This is an
212 /// implementation detail of IRForTarget.
214 /// @param[out] value
215 /// The IR value for the field (usually a GlobalVariable). In
216 /// the case of the result value, this will have the correct
217 /// name ($1, for instance). This is an implementation detail
220 /// @param[out] offset
221 /// The offset of the field from the beginning of the struct.
222 /// As long as the struct is aligned according to its required
223 /// alignment, this offset will align the field correctly.
226 /// The name of the field as used in materialization.
229 /// The index of the field about which information is requested.
232 /// True if the information could be retrieved; false otherwise.
233 //------------------------------------------------------------------
235 GetStructElement (const clang::NamedDecl *&decl,
241 //------------------------------------------------------------------
242 /// [Used by IRForTarget] Get information about a function given its
246 /// The parsed Decl for the Function, as generated by ClangASTSource
247 /// on ClangExpressionDeclMap's behalf.
250 /// The absolute address of the function in the target.
253 /// True if the information could be retrieved; false otherwise.
254 //------------------------------------------------------------------
256 GetFunctionInfo (const clang::NamedDecl *decl,
259 //------------------------------------------------------------------
260 /// [Used by IRForTarget] Get the address of a function given nothing
261 /// but its name. Some functions are needed but didn't get Decls made
262 /// during parsing -- specifically, sel_registerName is never called
263 /// in the generated IR but we need to call it nonetheless.
266 /// The name of the function.
269 /// The absolute address of the function in the target.
272 /// True if the address could be retrieved; false otherwise.
273 //------------------------------------------------------------------
275 GetFunctionAddress (const ConstString &name,
278 //------------------------------------------------------------------
279 /// [Used by IRForTarget] Get the address of a symbol given nothing
282 /// @param[in] target
283 /// The target to find the symbol in. If not provided,
284 /// then the current parsing context's Target.
286 /// @param[in] process
287 /// The process to use. For Objective-C symbols, the process's
288 /// Objective-C language runtime may be queried if the process
292 /// The name of the symbol.
295 /// Valid load address for the symbol
296 //------------------------------------------------------------------
298 GetSymbolAddress (Target &target,
300 const ConstString &name,
301 lldb::SymbolType symbol_type);
304 GetSymbolAddress (const ConstString &name,
305 lldb::SymbolType symbol_type);
307 //------------------------------------------------------------------
308 /// [Used by IRInterpreter] Get basic target information.
310 /// @param[out] byte_order
311 /// The byte order of the target.
313 /// @param[out] address_byte_size
314 /// The size of a pointer in bytes.
317 /// True if the information could be determined; false
319 //------------------------------------------------------------------
322 lldb::ByteOrder byte_order;
323 size_t address_byte_size;
326 byte_order(lldb::eByteOrderInvalid),
333 return (byte_order != lldb::eByteOrderInvalid &&
334 address_byte_size != 0);
337 TargetInfo GetTargetInfo();
339 //------------------------------------------------------------------
340 /// [Used by ClangASTSource] Find all entities matching a given name,
341 /// using a NameSearchContext to make Decls for them.
343 /// @param[in] context
344 /// The NameSearchContext that can construct Decls for this name.
347 /// True on success; false otherwise.
348 //------------------------------------------------------------------
350 FindExternalVisibleDecls (NameSearchContext &context);
352 //------------------------------------------------------------------
353 /// Find all entities matching a given name in a given module/namespace,
354 /// using a NameSearchContext to make Decls for them.
356 /// @param[in] context
357 /// The NameSearchContext that can construct Decls for this name.
359 /// @param[in] module
360 /// If non-NULL, the module to query.
362 /// @param[in] namespace_decl
363 /// If valid and module is non-NULL, the parent namespace.
366 /// The name as a plain C string. The NameSearchContext contains
367 /// a DeclarationName for the name so at first the name may seem
368 /// redundant, but ClangExpressionDeclMap operates in RTTI land so
369 /// it can't access DeclarationName.
371 /// @param[in] current_id
372 /// The ID for the current FindExternalVisibleDecls invocation,
373 /// for logging purposes.
376 /// True on success; false otherwise.
377 //------------------------------------------------------------------
379 FindExternalVisibleDecls (NameSearchContext &context,
380 lldb::ModuleSP module,
381 ClangNamespaceDecl &namespace_decl,
382 unsigned int current_id);
384 ClangExpressionVariableList m_found_entities; ///< All entities that were looked up for the parser.
385 ClangExpressionVariableList m_struct_members; ///< All entities that need to be placed in the struct.
386 bool m_keep_result_in_memory; ///< True if result persistent variables generated by this expression should stay in memory.
388 //----------------------------------------------------------------------
389 /// The following values should not live beyond parsing
390 //----------------------------------------------------------------------
394 ParserVars(ClangExpressionDeclMap &decl_map) :
397 m_persistent_vars(NULL),
398 m_enable_lookups(false),
399 m_materializer(NULL),
407 if (m_exe_ctx.GetTargetPtr())
408 return m_exe_ctx.GetTargetPtr();
409 else if (m_sym_ctx.target_sp)
410 m_sym_ctx.target_sp.get();
414 ExecutionContext m_exe_ctx; ///< The execution context to use when parsing.
415 SymbolContext m_sym_ctx; ///< The symbol context to use in finding variables and types.
416 ClangPersistentVariables *m_persistent_vars; ///< The persistent variables for the process.
417 bool m_enable_lookups; ///< Set to true during parsing if we have found the first "$__lldb" name.
418 TargetInfo m_target_info; ///< Basic information about the target.
419 Materializer *m_materializer; ///< If non-NULL, the materializer to use when reporting used variables.
421 ClangExpressionDeclMap &m_decl_map;
422 DISALLOW_COPY_AND_ASSIGN (ParserVars);
425 std::unique_ptr<ParserVars> m_parser_vars;
427 //----------------------------------------------------------------------
428 /// Activate parser-specific variables
429 //----------------------------------------------------------------------
433 if (!m_parser_vars.get())
434 m_parser_vars.reset(new ParserVars(*this));
437 //----------------------------------------------------------------------
438 /// Deallocate parser-specific variables
439 //----------------------------------------------------------------------
443 m_parser_vars.reset();
446 //----------------------------------------------------------------------
447 /// The following values contain layout information for the materialized
448 /// struct, but are not specific to a single materialization
449 //----------------------------------------------------------------------
452 m_struct_alignment(0),
454 m_struct_laid_out(false),
456 m_object_pointer_type(NULL, NULL)
460 off_t m_struct_alignment; ///< The alignment of the struct in bytes.
461 size_t m_struct_size; ///< The size of the struct in bytes.
462 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).
463 ConstString m_result_name; ///< The name of the result variable ($1, for example)
464 TypeFromUser m_object_pointer_type; ///< The type of the "this" variable, if one exists
467 std::unique_ptr<StructVars> m_struct_vars;
469 //----------------------------------------------------------------------
470 /// Activate struct variables
471 //----------------------------------------------------------------------
475 if (!m_struct_vars.get())
476 m_struct_vars.reset(new struct StructVars);
479 //----------------------------------------------------------------------
480 /// Deallocate struct variables
481 //----------------------------------------------------------------------
485 m_struct_vars.reset();
488 //----------------------------------------------------------------------
489 /// Get this parser's ID for use in extracting parser- and JIT-specific
490 /// data from persistent variables.
491 //----------------------------------------------------------------------
495 return (uint64_t)this;
498 //------------------------------------------------------------------
499 /// Given a target, find a data symbol that has the given name.
501 /// @param[in] target
502 /// The target to use as the basis for the search.
505 /// The name as a plain C string.
508 /// The LLDB Symbol found, or NULL if none was found.
509 //---------------------------------------------------------
511 FindGlobalDataSymbol (Target &target,
512 const ConstString &name);
514 //------------------------------------------------------------------
515 /// Given a target, find a variable that matches the given name and
518 /// @param[in] target
519 /// The target to use as a basis for finding the variable.
521 /// @param[in] module
522 /// If non-NULL, the module to search.
525 /// The name as a plain C string.
527 /// @param[in] namespace_decl
528 /// If non-NULL and module is non-NULL, the parent namespace.
531 /// The required type for the variable. This function may be called
532 /// during parsing, in which case we don't know its type; hence the
536 /// The LLDB Variable found, or NULL if none was found.
537 //------------------------------------------------------------------
539 FindGlobalVariable (Target &target,
540 lldb::ModuleSP &module,
541 const ConstString &name,
542 ClangNamespaceDecl *namespace_decl,
543 TypeFromUser *type = NULL);
545 //------------------------------------------------------------------
546 /// Get the value of a variable in a given execution context and return
547 /// the associated Types if needed.
550 /// The variable to evaluate.
552 /// @param[out] var_location
553 /// The variable location value to fill in
555 /// @param[out] found_type
556 /// The type of the found value, as it was found in the user process.
557 /// This is only useful when the variable is being inspected on behalf
558 /// of the parser, hence the default.
560 /// @param[out] parser_type
561 /// The type of the found value, as it was copied into the parser's
562 /// AST context. This is only useful when the variable is being
563 /// inspected on behalf of the parser, hence the default.
566 /// The Decl to be looked up.
569 /// Return true if the value was successfully filled in.
570 //------------------------------------------------------------------
572 GetVariableValue (lldb::VariableSP &var,
573 lldb_private::Value &var_location,
574 TypeFromUser *found_type = NULL,
575 TypeFromParser *parser_type = NULL);
577 //------------------------------------------------------------------
578 /// Use the NameSearchContext to generate a Decl for the given LLDB
579 /// Variable, and put it in the Tuple list.
581 /// @param[in] context
582 /// The NameSearchContext to use when constructing the Decl.
585 /// The LLDB Variable that needs a Decl.
587 /// @param[in] valobj
588 /// The LLDB ValueObject for that variable.
589 //------------------------------------------------------------------
591 AddOneVariable (NameSearchContext &context,
592 lldb::VariableSP var,
593 lldb::ValueObjectSP valobj,
594 unsigned int current_id);
596 //------------------------------------------------------------------
597 /// Use the NameSearchContext to generate a Decl for the given
598 /// persistent variable, and put it in the list of found entities.
600 /// @param[in] context
601 /// The NameSearchContext to use when constructing the Decl.
604 /// The persistent variable that needs a Decl.
606 /// @param[in] current_id
607 /// The ID of the current invocation of FindExternalVisibleDecls
608 /// for logging purposes.
609 //------------------------------------------------------------------
611 AddOneVariable (NameSearchContext &context,
612 lldb::ClangExpressionVariableSP &pvar_sp,
613 unsigned int current_id);
615 //------------------------------------------------------------------
616 /// Use the NameSearchContext to generate a Decl for the given LLDB
617 /// symbol (treated as a variable), and put it in the list of found
620 /// @param[in] context
621 /// The NameSearchContext to use when constructing the Decl.
624 /// The LLDB Variable that needs a Decl.
625 //------------------------------------------------------------------
627 AddOneGenericVariable (NameSearchContext &context,
628 const Symbol &symbol,
629 unsigned int current_id);
631 //------------------------------------------------------------------
632 /// Use the NameSearchContext to generate a Decl for the given
633 /// function. (Functions are not placed in the Tuple list.) Can
634 /// handle both fully typed functions and generic functions.
636 /// @param[in] context
637 /// The NameSearchContext to use when constructing the Decl.
640 /// The Function that needs to be created. If non-NULL, this is
641 /// a fully-typed function.
644 /// The Symbol that corresponds to a function that needs to be
645 /// created with generic type (unitptr_t foo(...)).
646 //------------------------------------------------------------------
648 AddOneFunction (NameSearchContext &context,
651 unsigned int current_id);
653 //------------------------------------------------------------------
654 /// Use the NameSearchContext to generate a Decl for the given
657 /// @param[in] context
658 /// The NameSearchContext to use when constructing the Decl.
660 /// @param[in] reg_info
661 /// The information corresponding to that register.
662 //------------------------------------------------------------------
664 AddOneRegister (NameSearchContext &context,
665 const RegisterInfo *reg_info,
666 unsigned int current_id);
668 //------------------------------------------------------------------
669 /// Use the NameSearchContext to generate a Decl for the given
670 /// type. (Types are not placed in the Tuple list.)
672 /// @param[in] context
673 /// The NameSearchContext to use when constructing the Decl.
676 /// The type that needs to be created.
677 //------------------------------------------------------------------
679 AddOneType (NameSearchContext &context,
681 unsigned int current_id);
683 //------------------------------------------------------------------
684 /// Copy a C++ class type into the parser's AST context and add a
685 /// member function declaration to it for the expression.
688 /// The type that needs to be created.
689 //------------------------------------------------------------------
692 CopyClassType(TypeFromUser &type,
693 unsigned int current_id);
696 } // namespace lldb_private
698 #endif // liblldb_ClangExpressionDeclMap_h_