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.
294 /// @param[in] module
295 /// The module to limit the search to. This can be NULL
298 /// Valid load address for the symbol
299 //------------------------------------------------------------------
301 GetSymbolAddress (Target &target,
303 const ConstString &name,
304 lldb::SymbolType symbol_type,
305 Module *module = NULL);
308 GetSymbolAddress (const ConstString &name,
309 lldb::SymbolType symbol_type);
311 //------------------------------------------------------------------
312 /// [Used by IRInterpreter] Get basic target information.
314 /// @param[out] byte_order
315 /// The byte order of the target.
317 /// @param[out] address_byte_size
318 /// The size of a pointer in bytes.
321 /// True if the information could be determined; false
323 //------------------------------------------------------------------
326 lldb::ByteOrder byte_order;
327 size_t address_byte_size;
330 byte_order(lldb::eByteOrderInvalid),
337 return (byte_order != lldb::eByteOrderInvalid &&
338 address_byte_size != 0);
341 TargetInfo GetTargetInfo();
343 //------------------------------------------------------------------
344 /// [Used by ClangASTSource] Find all entities matching a given name,
345 /// using a NameSearchContext to make Decls for them.
347 /// @param[in] context
348 /// The NameSearchContext that can construct Decls for this name.
351 /// True on success; false otherwise.
352 //------------------------------------------------------------------
354 FindExternalVisibleDecls (NameSearchContext &context);
356 //------------------------------------------------------------------
357 /// Find all entities matching a given name in a given module/namespace,
358 /// using a NameSearchContext to make Decls for them.
360 /// @param[in] context
361 /// The NameSearchContext that can construct Decls for this name.
363 /// @param[in] module
364 /// If non-NULL, the module to query.
366 /// @param[in] namespace_decl
367 /// If valid and module is non-NULL, the parent namespace.
370 /// The name as a plain C string. The NameSearchContext contains
371 /// a DeclarationName for the name so at first the name may seem
372 /// redundant, but ClangExpressionDeclMap operates in RTTI land so
373 /// it can't access DeclarationName.
375 /// @param[in] current_id
376 /// The ID for the current FindExternalVisibleDecls invocation,
377 /// for logging purposes.
380 /// True on success; false otherwise.
381 //------------------------------------------------------------------
383 FindExternalVisibleDecls (NameSearchContext &context,
384 lldb::ModuleSP module,
385 ClangNamespaceDecl &namespace_decl,
386 unsigned int current_id);
388 ClangExpressionVariableList m_found_entities; ///< All entities that were looked up for the parser.
389 ClangExpressionVariableList m_struct_members; ///< All entities that need to be placed in the struct.
390 bool m_keep_result_in_memory; ///< True if result persistent variables generated by this expression should stay in memory.
392 //----------------------------------------------------------------------
393 /// The following values should not live beyond parsing
394 //----------------------------------------------------------------------
398 ParserVars(ClangExpressionDeclMap &decl_map) :
401 m_persistent_vars(NULL),
402 m_enable_lookups(false),
403 m_materializer(NULL),
411 if (m_exe_ctx.GetTargetPtr())
412 return m_exe_ctx.GetTargetPtr();
413 else if (m_sym_ctx.target_sp)
414 m_sym_ctx.target_sp.get();
418 ExecutionContext m_exe_ctx; ///< The execution context to use when parsing.
419 SymbolContext m_sym_ctx; ///< The symbol context to use in finding variables and types.
420 ClangPersistentVariables *m_persistent_vars; ///< The persistent variables for the process.
421 bool m_enable_lookups; ///< Set to true during parsing if we have found the first "$__lldb" name.
422 TargetInfo m_target_info; ///< Basic information about the target.
423 Materializer *m_materializer; ///< If non-NULL, the materializer to use when reporting used variables.
425 ClangExpressionDeclMap &m_decl_map;
426 DISALLOW_COPY_AND_ASSIGN (ParserVars);
429 std::unique_ptr<ParserVars> m_parser_vars;
431 //----------------------------------------------------------------------
432 /// Activate parser-specific variables
433 //----------------------------------------------------------------------
437 if (!m_parser_vars.get())
438 m_parser_vars.reset(new ParserVars(*this));
441 //----------------------------------------------------------------------
442 /// Deallocate parser-specific variables
443 //----------------------------------------------------------------------
447 m_parser_vars.reset();
450 //----------------------------------------------------------------------
451 /// The following values contain layout information for the materialized
452 /// struct, but are not specific to a single materialization
453 //----------------------------------------------------------------------
456 m_struct_alignment(0),
458 m_struct_laid_out(false),
460 m_object_pointer_type(NULL, NULL)
464 off_t m_struct_alignment; ///< The alignment of the struct in bytes.
465 size_t m_struct_size; ///< The size of the struct in bytes.
466 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).
467 ConstString m_result_name; ///< The name of the result variable ($1, for example)
468 TypeFromUser m_object_pointer_type; ///< The type of the "this" variable, if one exists
471 std::unique_ptr<StructVars> m_struct_vars;
473 //----------------------------------------------------------------------
474 /// Activate struct variables
475 //----------------------------------------------------------------------
479 if (!m_struct_vars.get())
480 m_struct_vars.reset(new struct StructVars);
483 //----------------------------------------------------------------------
484 /// Deallocate struct variables
485 //----------------------------------------------------------------------
489 m_struct_vars.reset();
492 //----------------------------------------------------------------------
493 /// Get this parser's ID for use in extracting parser- and JIT-specific
494 /// data from persistent variables.
495 //----------------------------------------------------------------------
499 return (uint64_t)this;
502 //------------------------------------------------------------------
503 /// Given a target, find a data symbol that has the given name.
505 /// @param[in] target
506 /// The target to use as the basis for the search.
509 /// The name as a plain C string.
511 /// @param[in] module
512 /// The module to limit the search to. This can be NULL
515 /// The LLDB Symbol found, or NULL if none was found.
516 //------------------------------------------------------------------
518 FindGlobalDataSymbol (Target &target,
519 const ConstString &name,
520 Module *module = NULL);
522 //------------------------------------------------------------------
523 /// Given a target, find a variable that matches the given name and
526 /// @param[in] target
527 /// The target to use as a basis for finding the variable.
529 /// @param[in] module
530 /// If non-NULL, the module to search.
533 /// The name as a plain C string.
535 /// @param[in] namespace_decl
536 /// If non-NULL and module is non-NULL, the parent namespace.
539 /// The required type for the variable. This function may be called
540 /// during parsing, in which case we don't know its type; hence the
544 /// The LLDB Variable found, or NULL if none was found.
545 //------------------------------------------------------------------
547 FindGlobalVariable (Target &target,
548 lldb::ModuleSP &module,
549 const ConstString &name,
550 ClangNamespaceDecl *namespace_decl,
551 TypeFromUser *type = NULL);
553 //------------------------------------------------------------------
554 /// Get the value of a variable in a given execution context and return
555 /// the associated Types if needed.
558 /// The variable to evaluate.
560 /// @param[out] var_location
561 /// The variable location value to fill in
563 /// @param[out] found_type
564 /// The type of the found value, as it was found in the user process.
565 /// This is only useful when the variable is being inspected on behalf
566 /// of the parser, hence the default.
568 /// @param[out] parser_type
569 /// The type of the found value, as it was copied into the parser's
570 /// AST context. This is only useful when the variable is being
571 /// inspected on behalf of the parser, hence the default.
574 /// The Decl to be looked up.
577 /// Return true if the value was successfully filled in.
578 //------------------------------------------------------------------
580 GetVariableValue (lldb::VariableSP &var,
581 lldb_private::Value &var_location,
582 TypeFromUser *found_type = NULL,
583 TypeFromParser *parser_type = NULL);
585 //------------------------------------------------------------------
586 /// Use the NameSearchContext to generate a Decl for the given LLDB
587 /// Variable, and put it in the Tuple list.
589 /// @param[in] context
590 /// The NameSearchContext to use when constructing the Decl.
593 /// The LLDB Variable that needs a Decl.
595 /// @param[in] valobj
596 /// The LLDB ValueObject for that variable.
597 //------------------------------------------------------------------
599 AddOneVariable (NameSearchContext &context,
600 lldb::VariableSP var,
601 lldb::ValueObjectSP valobj,
602 unsigned int current_id);
604 //------------------------------------------------------------------
605 /// Use the NameSearchContext to generate a Decl for the given
606 /// persistent variable, and put it in the list of found entities.
608 /// @param[in] context
609 /// The NameSearchContext to use when constructing the Decl.
612 /// The persistent variable that needs a Decl.
614 /// @param[in] current_id
615 /// The ID of the current invocation of FindExternalVisibleDecls
616 /// for logging purposes.
617 //------------------------------------------------------------------
619 AddOneVariable (NameSearchContext &context,
620 lldb::ClangExpressionVariableSP &pvar_sp,
621 unsigned int current_id);
623 //------------------------------------------------------------------
624 /// Use the NameSearchContext to generate a Decl for the given LLDB
625 /// symbol (treated as a variable), and put it in the list of found
628 /// @param[in] context
629 /// The NameSearchContext to use when constructing the Decl.
632 /// The LLDB Variable that needs a Decl.
633 //------------------------------------------------------------------
635 AddOneGenericVariable (NameSearchContext &context,
636 const Symbol &symbol,
637 unsigned int current_id);
639 //------------------------------------------------------------------
640 /// Use the NameSearchContext to generate a Decl for the given
641 /// function. (Functions are not placed in the Tuple list.) Can
642 /// handle both fully typed functions and generic functions.
644 /// @param[in] context
645 /// The NameSearchContext to use when constructing the Decl.
648 /// The Function that needs to be created. If non-NULL, this is
649 /// a fully-typed function.
652 /// The Symbol that corresponds to a function that needs to be
653 /// created with generic type (unitptr_t foo(...)).
654 //------------------------------------------------------------------
656 AddOneFunction (NameSearchContext &context,
659 unsigned int current_id);
661 //------------------------------------------------------------------
662 /// Use the NameSearchContext to generate a Decl for the given
665 /// @param[in] context
666 /// The NameSearchContext to use when constructing the Decl.
668 /// @param[in] reg_info
669 /// The information corresponding to that register.
670 //------------------------------------------------------------------
672 AddOneRegister (NameSearchContext &context,
673 const RegisterInfo *reg_info,
674 unsigned int current_id);
676 //------------------------------------------------------------------
677 /// Use the NameSearchContext to generate a Decl for the given
678 /// type. (Types are not placed in the Tuple list.)
680 /// @param[in] context
681 /// The NameSearchContext to use when constructing the Decl.
684 /// The type that needs to be created.
685 //------------------------------------------------------------------
687 AddOneType (NameSearchContext &context,
689 unsigned int current_id);
691 //------------------------------------------------------------------
692 /// Copy a C++ class type into the parser's AST context and add a
693 /// member function declaration to it for the expression.
696 /// The type that needs to be created.
697 //------------------------------------------------------------------
700 CopyClassType(TypeFromUser &type,
701 unsigned int current_id);
704 } // namespace lldb_private
706 #endif // liblldb_ClangExpressionDeclMap_h_