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 #include "ClangASTSource.h"
21 #include "ClangExpressionVariable.h"
23 // Other libraries and framework includes
25 #include "lldb/Core/ClangForward.h"
26 #include "lldb/Core/Value.h"
27 #include "lldb/Expression/Materializer.h"
28 #include "lldb/Symbol/SymbolContext.h"
29 #include "lldb/Symbol/TaggedASTType.h"
30 #include "lldb/Target/ExecutionContext.h"
31 #include "lldb/lldb-public.h"
32 #include "clang/AST/Decl.h"
33 #include "llvm/ADT/DenseMap.h"
35 namespace lldb_private {
37 //----------------------------------------------------------------------
38 /// @class ClangExpressionDeclMap ClangExpressionDeclMap.h
39 /// "lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are
40 /// defined in LLDB's debug information.
42 /// The Clang parser uses the ClangASTSource as an interface to request named
43 /// entities from outside an expression. The ClangASTSource reports back,
44 /// listing all possible objects corresponding to a particular name. But it
45 /// in turn relies on ClangExpressionDeclMap, which performs several important
48 /// First, it records what variables and functions were looked up and what
49 /// Decls were returned for them.
51 /// Second, it constructs a struct on behalf of IRForTarget, recording which
52 /// variables should be placed where and relaying this information back so
53 /// that IRForTarget can generate context-independent code.
55 /// Third, it "materializes" this struct on behalf of the expression command,
56 /// finding the current values of each variable and placing them into the
57 /// struct so that it can be passed to the JITted version of the IR.
59 /// Fourth and finally, it "dematerializes" the struct after the JITted code
60 /// has has executed, placing the new values back where it found the old ones.
61 //----------------------------------------------------------------------
62 class ClangExpressionDeclMap : public ClangASTSource {
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] delegate
75 /// If non-NULL, use this delegate to report result values. This
76 /// allows the client ClangUserExpression to report a result.
78 /// @param[in] exe_ctx
79 /// The execution context to use when parsing.
80 //------------------------------------------------------------------
81 ClangExpressionDeclMap(
82 bool keep_result_in_memory,
83 Materializer::PersistentVariableDelegate *result_delegate,
84 ExecutionContext &exe_ctx);
86 //------------------------------------------------------------------
88 //------------------------------------------------------------------
89 ~ClangExpressionDeclMap() override;
91 //------------------------------------------------------------------
92 /// Enable the state needed for parsing and IR transformation.
94 /// @param[in] exe_ctx
95 /// The execution context to use when finding types for variables.
96 /// Also used to find a "scratch" AST context to store result types.
98 /// @param[in] materializer
99 /// If non-NULL, the materializer to populate with information about
100 /// the variables to use
103 /// True if parsing is possible; false if it is unsafe to continue.
104 //------------------------------------------------------------------
105 bool WillParse(ExecutionContext &exe_ctx, Materializer *materializer);
107 void InstallCodeGenerator(clang::ASTConsumer *code_gen);
109 //------------------------------------------------------------------
110 /// [Used by ClangExpressionParser] For each variable that had an unknown
111 /// type at the beginning of parsing, determine its final type now.
114 /// True on success; false otherwise.
115 //------------------------------------------------------------------
116 bool ResolveUnknownTypes();
118 //------------------------------------------------------------------
119 /// Disable the state needed for parsing and IR transformation.
120 //------------------------------------------------------------------
123 //------------------------------------------------------------------
124 /// [Used by IRForTarget] Add a variable to the list of persistent
125 /// variables for the process.
128 /// The Clang declaration for the persistent variable, used for
129 /// lookup during parsing.
132 /// The name of the persistent variable, usually $something.
135 /// The type of the variable, in the Clang parser's context.
138 /// True on success; false otherwise.
139 //------------------------------------------------------------------
140 bool AddPersistentVariable(const clang::NamedDecl *decl,
141 const ConstString &name, TypeFromParser type,
142 bool is_result, bool is_lvalue);
144 //------------------------------------------------------------------
145 /// [Used by IRForTarget] Add a variable to the struct that needs to
146 /// be materialized each time the expression runs.
149 /// The Clang declaration for the variable.
152 /// The name of the variable.
155 /// The LLVM IR value for this variable.
158 /// The size of the variable in bytes.
160 /// @param[in] alignment
161 /// The required alignment of the variable in bytes.
164 /// True on success; false otherwise.
165 //------------------------------------------------------------------
166 bool AddValueToStruct(const clang::NamedDecl *decl, const ConstString &name,
167 llvm::Value *value, size_t size,
168 lldb::offset_t alignment);
170 //------------------------------------------------------------------
171 /// [Used by IRForTarget] Finalize the struct, laying out the position of
172 /// each object in it.
175 /// True on success; false otherwise.
176 //------------------------------------------------------------------
177 bool DoStructLayout();
179 //------------------------------------------------------------------
180 /// [Used by IRForTarget] Get general information about the laid-out struct
181 /// after DoStructLayout() has been called.
183 /// @param[out] num_elements
184 /// The number of elements in the struct.
187 /// The size of the struct, in bytes.
189 /// @param[out] alignment
190 /// The alignment of the struct, in bytes.
193 /// True if the information could be retrieved; false otherwise.
194 //------------------------------------------------------------------
195 bool GetStructInfo(uint32_t &num_elements, size_t &size,
196 lldb::offset_t &alignment);
198 //------------------------------------------------------------------
199 /// [Used by IRForTarget] Get specific information about one field of the
200 /// laid-out struct after DoStructLayout() has been called.
203 /// The parsed Decl for the field, as generated by ClangASTSource
204 /// on ClangExpressionDeclMap's behalf. In the case of the result
205 /// value, this will have the name $__lldb_result even if the
206 /// result value ends up having the name $1. This is an
207 /// implementation detail of IRForTarget.
209 /// @param[out] value
210 /// The IR value for the field (usually a GlobalVariable). In
211 /// the case of the result value, this will have the correct
212 /// name ($1, for instance). This is an implementation detail
215 /// @param[out] offset
216 /// The offset of the field from the beginning of the struct.
217 /// As long as the struct is aligned according to its required
218 /// alignment, this offset will align the field correctly.
221 /// The name of the field as used in materialization.
224 /// The index of the field about which information is requested.
227 /// True if the information could be retrieved; false otherwise.
228 //------------------------------------------------------------------
229 bool GetStructElement(const clang::NamedDecl *&decl, llvm::Value *&value,
230 lldb::offset_t &offset, ConstString &name,
233 //------------------------------------------------------------------
234 /// [Used by IRForTarget] Get information about a function given its Decl.
237 /// The parsed Decl for the Function, as generated by ClangASTSource
238 /// on ClangExpressionDeclMap's behalf.
241 /// The absolute address of the function in the target.
244 /// True if the information could be retrieved; false otherwise.
245 //------------------------------------------------------------------
246 bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr);
248 //------------------------------------------------------------------
249 /// [Used by IRForTarget] Get the address of a symbol given nothing but its
252 /// @param[in] target
253 /// The target to find the symbol in. If not provided,
254 /// then the current parsing context's Target.
256 /// @param[in] process
257 /// The process to use. For Objective-C symbols, the process's
258 /// Objective-C language runtime may be queried if the process
262 /// The name of the symbol.
264 /// @param[in] module
265 /// The module to limit the search to. This can be NULL
268 /// Valid load address for the symbol
269 //------------------------------------------------------------------
270 lldb::addr_t GetSymbolAddress(Target &target, Process *process,
271 const ConstString &name,
272 lldb::SymbolType symbol_type,
273 Module *module = NULL);
275 lldb::addr_t GetSymbolAddress(const ConstString &name,
276 lldb::SymbolType symbol_type);
278 //------------------------------------------------------------------
279 /// [Used by IRInterpreter] Get basic target information.
281 /// @param[out] byte_order
282 /// The byte order of the target.
284 /// @param[out] address_byte_size
285 /// The size of a pointer in bytes.
288 /// True if the information could be determined; false
290 //------------------------------------------------------------------
292 lldb::ByteOrder byte_order;
293 size_t address_byte_size;
295 TargetInfo() : byte_order(lldb::eByteOrderInvalid), address_byte_size(0) {}
298 return (byte_order != lldb::eByteOrderInvalid && address_byte_size != 0);
301 TargetInfo GetTargetInfo();
303 //------------------------------------------------------------------
304 /// [Used by ClangASTSource] Find all entities matching a given name, using
305 /// a NameSearchContext to make Decls for them.
307 /// @param[in] context
308 /// The NameSearchContext that can construct Decls for this name.
311 /// True on success; false otherwise.
312 //------------------------------------------------------------------
313 void FindExternalVisibleDecls(NameSearchContext &context) override;
315 //------------------------------------------------------------------
316 /// Find all entities matching a given name in a given module/namespace,
317 /// using a NameSearchContext to make Decls for them.
319 /// @param[in] context
320 /// The NameSearchContext that can construct Decls for this name.
322 /// @param[in] module
323 /// If non-NULL, the module to query.
325 /// @param[in] namespace_decl
326 /// If valid and module is non-NULL, the parent namespace.
329 /// The name as a plain C string. The NameSearchContext contains
330 /// a DeclarationName for the name so at first the name may seem
331 /// redundant, but ClangExpressionDeclMap operates in RTTI land so
332 /// it can't access DeclarationName.
334 /// @param[in] current_id
335 /// The ID for the current FindExternalVisibleDecls invocation,
336 /// for logging purposes.
339 /// True on success; false otherwise.
340 //------------------------------------------------------------------
341 void FindExternalVisibleDecls(NameSearchContext &context,
342 lldb::ModuleSP module,
343 CompilerDeclContext &namespace_decl,
344 unsigned int current_id);
347 ExpressionVariableList
348 m_found_entities; ///< All entities that were looked up for the parser.
349 ExpressionVariableList
350 m_struct_members; ///< All entities that need to be placed in the struct.
351 bool m_keep_result_in_memory; ///< True if result persistent variables
352 ///generated by this expression should stay in
354 Materializer::PersistentVariableDelegate
355 *m_result_delegate; ///< If non-NULL, used to report expression results to
356 ///ClangUserExpression.
358 //----------------------------------------------------------------------
359 /// The following values should not live beyond parsing
360 //----------------------------------------------------------------------
365 Target *GetTarget() {
366 if (m_exe_ctx.GetTargetPtr())
367 return m_exe_ctx.GetTargetPtr();
368 else if (m_sym_ctx.target_sp)
369 m_sym_ctx.target_sp.get();
373 ExecutionContext m_exe_ctx; ///< The execution context to use when parsing.
374 SymbolContext m_sym_ctx; ///< The symbol context to use in finding variables
376 ClangPersistentVariables *m_persistent_vars =
377 nullptr; ///< The persistent variables for the process.
378 bool m_enable_lookups = false; ///< Set to true during parsing if we have
379 ///found the first "$__lldb" name.
380 TargetInfo m_target_info; ///< Basic information about the target.
381 Materializer *m_materializer = nullptr; ///< If non-NULL, the materializer
382 ///to use when reporting used
384 clang::ASTConsumer *m_code_gen = nullptr; ///< If non-NULL, a code generator
385 ///that receives new top-level
388 DISALLOW_COPY_AND_ASSIGN(ParserVars);
391 std::unique_ptr<ParserVars> m_parser_vars;
393 //----------------------------------------------------------------------
394 /// Activate parser-specific variables
395 //----------------------------------------------------------------------
396 void EnableParserVars() {
397 if (!m_parser_vars.get())
398 m_parser_vars = llvm::make_unique<ParserVars>();
401 //----------------------------------------------------------------------
402 /// Deallocate parser-specific variables
403 //----------------------------------------------------------------------
404 void DisableParserVars() { m_parser_vars.reset(); }
406 //----------------------------------------------------------------------
407 /// The following values contain layout information for the materialized
408 /// struct, but are not specific to a single materialization
409 //----------------------------------------------------------------------
412 : m_struct_alignment(0), m_struct_size(0), m_struct_laid_out(false),
413 m_result_name(), m_object_pointer_type(NULL, NULL) {}
416 m_struct_alignment; ///< The alignment of the struct in bytes.
417 size_t m_struct_size; ///< The size of the struct in bytes.
418 bool m_struct_laid_out; ///< True if the struct has been laid out and the
419 ///layout is valid (that is, no new fields have been
422 m_result_name; ///< The name of the result variable ($1, for example)
423 TypeFromUser m_object_pointer_type; ///< The type of the "this" variable, if
427 std::unique_ptr<StructVars> m_struct_vars;
429 //----------------------------------------------------------------------
430 /// Activate struct variables
431 //----------------------------------------------------------------------
432 void EnableStructVars() {
433 if (!m_struct_vars.get())
434 m_struct_vars.reset(new struct StructVars);
437 //----------------------------------------------------------------------
438 /// Deallocate struct variables
439 //----------------------------------------------------------------------
440 void DisableStructVars() { m_struct_vars.reset(); }
442 //----------------------------------------------------------------------
443 /// Get this parser's ID for use in extracting parser- and JIT-specific data
444 /// from persistent variables.
445 //----------------------------------------------------------------------
446 uint64_t GetParserID() { return (uint64_t) this; }
448 //------------------------------------------------------------------
449 /// Given a target, find a variable that matches the given name and type.
451 /// @param[in] target
452 /// The target to use as a basis for finding the variable.
454 /// @param[in] module
455 /// If non-NULL, the module to search.
458 /// The name as a plain C string.
460 /// @param[in] namespace_decl
461 /// If non-NULL and module is non-NULL, the parent namespace.
464 /// The required type for the variable. This function may be called
465 /// during parsing, in which case we don't know its type; hence the
469 /// The LLDB Variable found, or NULL if none was found.
470 //------------------------------------------------------------------
471 lldb::VariableSP FindGlobalVariable(Target &target, lldb::ModuleSP &module,
472 const ConstString &name,
473 CompilerDeclContext *namespace_decl,
474 TypeFromUser *type = NULL);
476 //------------------------------------------------------------------
477 /// Get the value of a variable in a given execution context and return the
478 /// associated Types if needed.
481 /// The variable to evaluate.
483 /// @param[out] var_location
484 /// The variable location value to fill in
486 /// @param[out] found_type
487 /// The type of the found value, as it was found in the user process.
488 /// This is only useful when the variable is being inspected on behalf
489 /// of the parser, hence the default.
491 /// @param[out] parser_type
492 /// The type of the found value, as it was copied into the parser's
493 /// AST context. This is only useful when the variable is being
494 /// inspected on behalf of the parser, hence the default.
497 /// The Decl to be looked up.
500 /// Return true if the value was successfully filled in.
501 //------------------------------------------------------------------
502 bool GetVariableValue(lldb::VariableSP &var,
503 lldb_private::Value &var_location,
504 TypeFromUser *found_type = NULL,
505 TypeFromParser *parser_type = NULL);
507 //------------------------------------------------------------------
508 /// Use the NameSearchContext to generate a Decl for the given LLDB
509 /// Variable, and put it in the Tuple list.
511 /// @param[in] context
512 /// The NameSearchContext to use when constructing the Decl.
515 /// The LLDB Variable that needs a Decl.
517 /// @param[in] valobj
518 /// The LLDB ValueObject for that variable.
519 //------------------------------------------------------------------
520 void AddOneVariable(NameSearchContext &context, lldb::VariableSP var,
521 lldb::ValueObjectSP valobj, unsigned int current_id);
523 //------------------------------------------------------------------
524 /// Use the NameSearchContext to generate a Decl for the given persistent
525 /// variable, and put it in the list of found entities.
527 /// @param[in] context
528 /// The NameSearchContext to use when constructing the Decl.
531 /// The persistent variable that needs a Decl.
533 /// @param[in] current_id
534 /// The ID of the current invocation of FindExternalVisibleDecls
535 /// for logging purposes.
536 //------------------------------------------------------------------
537 void AddOneVariable(NameSearchContext &context,
538 lldb::ExpressionVariableSP &pvar_sp,
539 unsigned int current_id);
541 //------------------------------------------------------------------
542 /// Use the NameSearchContext to generate a Decl for the given LLDB symbol
543 /// (treated as a variable), and put it in the list of found entities.
545 /// @param[in] context
546 /// The NameSearchContext to use when constructing the Decl.
549 /// The LLDB Variable that needs a Decl.
550 //------------------------------------------------------------------
551 void AddOneGenericVariable(NameSearchContext &context, const Symbol &symbol,
552 unsigned int current_id);
554 //------------------------------------------------------------------
555 /// Use the NameSearchContext to generate a Decl for the given function.
556 /// (Functions are not placed in the Tuple list.) Can handle both fully
557 /// typed functions and generic functions.
559 /// @param[in] context
560 /// The NameSearchContext to use when constructing the Decl.
563 /// The Function that needs to be created. If non-NULL, this is
564 /// a fully-typed function.
567 /// The Symbol that corresponds to a function that needs to be
568 /// created with generic type (unitptr_t foo(...)).
569 //------------------------------------------------------------------
570 void AddOneFunction(NameSearchContext &context, Function *fun, Symbol *sym,
571 unsigned int current_id);
573 //------------------------------------------------------------------
574 /// Use the NameSearchContext to generate a Decl for the given register.
576 /// @param[in] context
577 /// The NameSearchContext to use when constructing the Decl.
579 /// @param[in] reg_info
580 /// The information corresponding to that register.
581 //------------------------------------------------------------------
582 void AddOneRegister(NameSearchContext &context, const RegisterInfo *reg_info,
583 unsigned int current_id);
585 //------------------------------------------------------------------
586 /// Use the NameSearchContext to generate a Decl for the given type. (Types
587 /// are not placed in the Tuple list.)
589 /// @param[in] context
590 /// The NameSearchContext to use when constructing the Decl.
593 /// The type that needs to be created.
594 //------------------------------------------------------------------
595 void AddOneType(NameSearchContext &context, TypeFromUser &type,
596 unsigned int current_id);
598 //------------------------------------------------------------------
599 /// Generate a Decl for "*this" and add a member function declaration to it
600 /// for the expression, then report it.
602 /// @param[in] context
603 /// The NameSearchContext to use when constructing the Decl.
606 /// The type for *this.
607 //------------------------------------------------------------------
608 void AddThisType(NameSearchContext &context, TypeFromUser &type,
609 unsigned int current_id);
611 //------------------------------------------------------------------
612 /// Move a type out of the current ASTContext into another, but make sure to
613 /// export all components of the type also.
615 /// @param[in] target
616 /// The ClangASTContext to move to.
617 /// @param[in] source
618 /// The ClangASTContext to move from. This is assumed to be going away.
619 /// @param[in] parser_type
620 /// The type as it appears in the source context.
623 /// Returns the moved type, or an empty type if there was a problem.
624 //------------------------------------------------------------------
625 TypeFromUser DeportType(ClangASTContext &target, ClangASTContext &source,
626 TypeFromParser parser_type);
628 ClangASTContext *GetClangASTContext();
631 } // namespace lldb_private
633 #endif // liblldb_ClangExpressionDeclMap_h_