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"
40 /// @brief Manages named entities that are 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,
45 /// all possible objects corresponding to a particular name. But it in turn
46 /// relies on ClangExpressionDeclMap, which performs several important
49 /// First, it records what variables and functions were looked up and what Decls
50 /// were returned for them.
52 /// Second, it constructs a struct on behalf of IRForTarget, recording which
53 /// variables should be placed where and relaying this information back so that
54 /// IRForTarget can generate context-independent code.
56 /// Third, it "materializes" this struct on behalf of the expression command,
57 /// finding the current values of each variable and placing them into the
58 /// struct so that it can be passed to the JITted version of the IR.
60 /// Fourth and finally, it "dematerializes" the struct after the JITted code has
61 /// has executed, placing the new values back where it found the old ones.
62 //----------------------------------------------------------------------
63 class ClangExpressionDeclMap : public ClangASTSource {
65 //------------------------------------------------------------------
68 /// Initializes class variables.
70 /// @param[in] keep_result_in_memory
71 /// If true, inhibits the normal deallocation of the memory for
72 /// the result persistent variable, and instead marks the variable
75 /// @param[in] delegate
76 /// If non-NULL, use this delegate to report result values. This
77 /// allows the client ClangUserExpression to report a result.
79 /// @param[in] exe_ctx
80 /// The execution context to use when parsing.
81 //------------------------------------------------------------------
82 ClangExpressionDeclMap(
83 bool keep_result_in_memory,
84 Materializer::PersistentVariableDelegate *result_delegate,
85 ExecutionContext &exe_ctx);
87 //------------------------------------------------------------------
89 //------------------------------------------------------------------
90 ~ClangExpressionDeclMap() override;
92 //------------------------------------------------------------------
93 /// Enable the state needed for parsing and IR transformation.
95 /// @param[in] exe_ctx
96 /// The execution context to use when finding types for variables.
97 /// Also used to find a "scratch" AST context to store result types.
99 /// @param[in] materializer
100 /// If non-NULL, the materializer to populate with information about
101 /// the variables to use
104 /// True if parsing is possible; false if it is unsafe to continue.
105 //------------------------------------------------------------------
106 bool WillParse(ExecutionContext &exe_ctx, Materializer *materializer);
108 void InstallCodeGenerator(clang::ASTConsumer *code_gen);
110 //------------------------------------------------------------------
111 /// [Used by ClangExpressionParser] For each variable that had an unknown
112 /// type at the beginning of parsing, determine its final type now.
115 /// True on success; false otherwise.
116 //------------------------------------------------------------------
117 bool ResolveUnknownTypes();
119 //------------------------------------------------------------------
120 /// Disable the state needed for parsing and IR transformation.
121 //------------------------------------------------------------------
124 //------------------------------------------------------------------
125 /// [Used by IRForTarget] Add a variable to the list of persistent
126 /// variables for the process.
129 /// The Clang declaration for the persistent variable, used for
130 /// lookup during parsing.
133 /// The name of the persistent variable, usually $something.
136 /// The type of the variable, in the Clang parser's context.
139 /// True on success; false otherwise.
140 //------------------------------------------------------------------
141 bool AddPersistentVariable(const clang::NamedDecl *decl,
142 const ConstString &name, TypeFromParser type,
143 bool is_result, bool is_lvalue);
145 //------------------------------------------------------------------
146 /// [Used by IRForTarget] Add a variable to the struct that needs to
147 /// be materialized each time the expression runs.
150 /// The Clang declaration for the variable.
153 /// The name of the variable.
156 /// The LLVM IR value for this variable.
159 /// The size of the variable in bytes.
161 /// @param[in] alignment
162 /// The required alignment of the variable in bytes.
165 /// True on success; false otherwise.
166 //------------------------------------------------------------------
167 bool AddValueToStruct(const clang::NamedDecl *decl, const ConstString &name,
168 llvm::Value *value, size_t size,
169 lldb::offset_t alignment);
171 //------------------------------------------------------------------
172 /// [Used by IRForTarget] Finalize the struct, laying out the position
173 /// of each object in it.
176 /// True on success; false otherwise.
177 //------------------------------------------------------------------
178 bool DoStructLayout();
180 //------------------------------------------------------------------
181 /// [Used by IRForTarget] Get general information about the laid-out
182 /// struct after DoStructLayout() has been called.
184 /// @param[out] num_elements
185 /// The number of elements in the struct.
188 /// The size of the struct, in bytes.
190 /// @param[out] alignment
191 /// The alignment of the struct, in bytes.
194 /// True if the information could be retrieved; false otherwise.
195 //------------------------------------------------------------------
196 bool GetStructInfo(uint32_t &num_elements, size_t &size,
197 lldb::offset_t &alignment);
199 //------------------------------------------------------------------
200 /// [Used by IRForTarget] Get specific information about one field
201 /// of the laid-out struct after DoStructLayout() has been called.
204 /// The parsed Decl for the field, as generated by ClangASTSource
205 /// on ClangExpressionDeclMap's behalf. In the case of the result
206 /// value, this will have the name $__lldb_result even if the
207 /// result value ends up having the name $1. This is an
208 /// implementation detail of IRForTarget.
210 /// @param[out] value
211 /// The IR value for the field (usually a GlobalVariable). In
212 /// the case of the result value, this will have the correct
213 /// name ($1, for instance). This is an implementation detail
216 /// @param[out] offset
217 /// The offset of the field from the beginning of the struct.
218 /// As long as the struct is aligned according to its required
219 /// alignment, this offset will align the field correctly.
222 /// The name of the field as used in materialization.
225 /// The index of the field about which information is requested.
228 /// True if the information could be retrieved; false otherwise.
229 //------------------------------------------------------------------
230 bool GetStructElement(const clang::NamedDecl *&decl, llvm::Value *&value,
231 lldb::offset_t &offset, ConstString &name,
234 //------------------------------------------------------------------
235 /// [Used by IRForTarget] Get information about a function given its
239 /// The parsed Decl for the Function, as generated by ClangASTSource
240 /// on ClangExpressionDeclMap's behalf.
243 /// The absolute address of the function in the target.
246 /// True if the information could be retrieved; false otherwise.
247 //------------------------------------------------------------------
248 bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr);
250 //------------------------------------------------------------------
251 /// [Used by IRForTarget] Get the address of a symbol given nothing
254 /// @param[in] target
255 /// The target to find the symbol in. If not provided,
256 /// then the current parsing context's Target.
258 /// @param[in] process
259 /// The process to use. For Objective-C symbols, the process's
260 /// Objective-C language runtime may be queried if the process
264 /// The name of the symbol.
266 /// @param[in] module
267 /// The module to limit the search to. This can be NULL
270 /// Valid load address for the symbol
271 //------------------------------------------------------------------
272 lldb::addr_t GetSymbolAddress(Target &target, Process *process,
273 const ConstString &name,
274 lldb::SymbolType symbol_type,
275 Module *module = NULL);
277 lldb::addr_t GetSymbolAddress(const ConstString &name,
278 lldb::SymbolType symbol_type);
280 //------------------------------------------------------------------
281 /// [Used by IRInterpreter] Get basic target information.
283 /// @param[out] byte_order
284 /// The byte order of the target.
286 /// @param[out] address_byte_size
287 /// The size of a pointer in bytes.
290 /// True if the information could be determined; false
292 //------------------------------------------------------------------
294 lldb::ByteOrder byte_order;
295 size_t address_byte_size;
297 TargetInfo() : byte_order(lldb::eByteOrderInvalid), address_byte_size(0) {}
300 return (byte_order != lldb::eByteOrderInvalid && address_byte_size != 0);
303 TargetInfo GetTargetInfo();
305 //------------------------------------------------------------------
306 /// [Used by ClangASTSource] Find all entities matching a given name,
307 /// using a NameSearchContext to make Decls for them.
309 /// @param[in] context
310 /// The NameSearchContext that can construct Decls for this name.
313 /// True on success; false otherwise.
314 //------------------------------------------------------------------
315 void FindExternalVisibleDecls(NameSearchContext &context) override;
317 //------------------------------------------------------------------
318 /// Find all entities matching a given name in a given module/namespace,
319 /// using a NameSearchContext to make Decls for them.
321 /// @param[in] context
322 /// The NameSearchContext that can construct Decls for this name.
324 /// @param[in] module
325 /// If non-NULL, the module to query.
327 /// @param[in] namespace_decl
328 /// If valid and module is non-NULL, the parent namespace.
331 /// The name as a plain C string. The NameSearchContext contains
332 /// a DeclarationName for the name so at first the name may seem
333 /// redundant, but ClangExpressionDeclMap operates in RTTI land so
334 /// it can't access DeclarationName.
336 /// @param[in] current_id
337 /// The ID for the current FindExternalVisibleDecls invocation,
338 /// for logging purposes.
341 /// True on success; false otherwise.
342 //------------------------------------------------------------------
343 void FindExternalVisibleDecls(NameSearchContext &context,
344 lldb::ModuleSP module,
345 CompilerDeclContext &namespace_decl,
346 unsigned int current_id);
349 ExpressionVariableList
350 m_found_entities; ///< All entities that were looked up for the parser.
351 ExpressionVariableList
352 m_struct_members; ///< All entities that need to be placed in the struct.
353 bool m_keep_result_in_memory; ///< True if result persistent variables
354 ///generated by this expression should stay in
356 Materializer::PersistentVariableDelegate
357 *m_result_delegate; ///< If non-NULL, used to report expression results to
358 ///ClangUserExpression.
360 //----------------------------------------------------------------------
361 /// The following values should not live beyond parsing
362 //----------------------------------------------------------------------
367 Target *GetTarget() {
368 if (m_exe_ctx.GetTargetPtr())
369 return m_exe_ctx.GetTargetPtr();
370 else if (m_sym_ctx.target_sp)
371 m_sym_ctx.target_sp.get();
375 ExecutionContext m_exe_ctx; ///< The execution context to use when parsing.
376 SymbolContext m_sym_ctx; ///< The symbol context to use in finding variables
378 ClangPersistentVariables *m_persistent_vars =
379 nullptr; ///< The persistent variables for the process.
380 bool m_enable_lookups = false; ///< Set to true during parsing if we have
381 ///found the first "$__lldb" name.
382 TargetInfo m_target_info; ///< Basic information about the target.
383 Materializer *m_materializer = nullptr; ///< If non-NULL, the materializer
384 ///to use when reporting used
386 clang::ASTConsumer *m_code_gen = nullptr; ///< If non-NULL, a code generator
387 ///that receives new top-level
390 DISALLOW_COPY_AND_ASSIGN(ParserVars);
393 std::unique_ptr<ParserVars> m_parser_vars;
395 //----------------------------------------------------------------------
396 /// Activate parser-specific variables
397 //----------------------------------------------------------------------
398 void EnableParserVars() {
399 if (!m_parser_vars.get())
400 m_parser_vars = llvm::make_unique<ParserVars>();
403 //----------------------------------------------------------------------
404 /// Deallocate parser-specific variables
405 //----------------------------------------------------------------------
406 void DisableParserVars() { m_parser_vars.reset(); }
408 //----------------------------------------------------------------------
409 /// The following values contain layout information for the materialized
410 /// struct, but are not specific to a single materialization
411 //----------------------------------------------------------------------
414 : m_struct_alignment(0), m_struct_size(0), m_struct_laid_out(false),
415 m_result_name(), m_object_pointer_type(NULL, NULL) {}
418 m_struct_alignment; ///< The alignment of the struct in bytes.
419 size_t m_struct_size; ///< The size of the struct in bytes.
420 bool m_struct_laid_out; ///< True if the struct has been laid out and the
421 ///layout is valid (that is, no new fields have been
424 m_result_name; ///< The name of the result variable ($1, for example)
425 TypeFromUser m_object_pointer_type; ///< The type of the "this" variable, if
429 std::unique_ptr<StructVars> m_struct_vars;
431 //----------------------------------------------------------------------
432 /// Activate struct variables
433 //----------------------------------------------------------------------
434 void EnableStructVars() {
435 if (!m_struct_vars.get())
436 m_struct_vars.reset(new struct StructVars);
439 //----------------------------------------------------------------------
440 /// Deallocate struct variables
441 //----------------------------------------------------------------------
442 void DisableStructVars() { m_struct_vars.reset(); }
444 //----------------------------------------------------------------------
445 /// Get this parser's ID for use in extracting parser- and JIT-specific
446 /// data from persistent variables.
447 //----------------------------------------------------------------------
448 uint64_t GetParserID() { return (uint64_t) this; }
450 //------------------------------------------------------------------
451 /// Given a target, find a data symbol that has the given name.
453 /// @param[in] target
454 /// The target to use as the basis for the search.
457 /// The name as a plain C string.
459 /// @param[in] module
460 /// The module to limit the search to. This can be NULL
463 /// The LLDB Symbol found, or NULL if none was found.
464 //------------------------------------------------------------------
465 const Symbol *FindGlobalDataSymbol(Target &target, const ConstString &name,
466 Module *module = NULL);
468 //------------------------------------------------------------------
469 /// Given a target, find a variable that matches the given name and
472 /// @param[in] target
473 /// The target to use as a basis for finding the variable.
475 /// @param[in] module
476 /// If non-NULL, the module to search.
479 /// The name as a plain C string.
481 /// @param[in] namespace_decl
482 /// If non-NULL and module is non-NULL, the parent namespace.
485 /// The required type for the variable. This function may be called
486 /// during parsing, in which case we don't know its type; hence the
490 /// The LLDB Variable found, or NULL if none was found.
491 //------------------------------------------------------------------
492 lldb::VariableSP FindGlobalVariable(Target &target, lldb::ModuleSP &module,
493 const ConstString &name,
494 CompilerDeclContext *namespace_decl,
495 TypeFromUser *type = NULL);
497 //------------------------------------------------------------------
498 /// Get the value of a variable in a given execution context and return
499 /// the associated Types if needed.
502 /// The variable to evaluate.
504 /// @param[out] var_location
505 /// The variable location value to fill in
507 /// @param[out] found_type
508 /// The type of the found value, as it was found in the user process.
509 /// This is only useful when the variable is being inspected on behalf
510 /// of the parser, hence the default.
512 /// @param[out] parser_type
513 /// The type of the found value, as it was copied into the parser's
514 /// AST context. This is only useful when the variable is being
515 /// inspected on behalf of the parser, hence the default.
518 /// The Decl to be looked up.
521 /// Return true if the value was successfully filled in.
522 //------------------------------------------------------------------
523 bool GetVariableValue(lldb::VariableSP &var,
524 lldb_private::Value &var_location,
525 TypeFromUser *found_type = NULL,
526 TypeFromParser *parser_type = NULL);
528 //------------------------------------------------------------------
529 /// Use the NameSearchContext to generate a Decl for the given LLDB
530 /// Variable, and put it in the Tuple list.
532 /// @param[in] context
533 /// The NameSearchContext to use when constructing the Decl.
536 /// The LLDB Variable that needs a Decl.
538 /// @param[in] valobj
539 /// The LLDB ValueObject for that variable.
540 //------------------------------------------------------------------
541 void AddOneVariable(NameSearchContext &context, lldb::VariableSP var,
542 lldb::ValueObjectSP valobj, unsigned int current_id);
544 //------------------------------------------------------------------
545 /// Use the NameSearchContext to generate a Decl for the given
546 /// persistent variable, and put it in the list of found entities.
548 /// @param[in] context
549 /// The NameSearchContext to use when constructing the Decl.
552 /// The persistent variable that needs a Decl.
554 /// @param[in] current_id
555 /// The ID of the current invocation of FindExternalVisibleDecls
556 /// for logging purposes.
557 //------------------------------------------------------------------
558 void AddOneVariable(NameSearchContext &context,
559 lldb::ExpressionVariableSP &pvar_sp,
560 unsigned int current_id);
562 //------------------------------------------------------------------
563 /// Use the NameSearchContext to generate a Decl for the given LLDB
564 /// symbol (treated as a variable), and put it in the list of found
567 /// @param[in] context
568 /// The NameSearchContext to use when constructing the Decl.
571 /// The LLDB Variable that needs a Decl.
572 //------------------------------------------------------------------
573 void AddOneGenericVariable(NameSearchContext &context, const Symbol &symbol,
574 unsigned int current_id);
576 //------------------------------------------------------------------
577 /// Use the NameSearchContext to generate a Decl for the given
578 /// function. (Functions are not placed in the Tuple list.) Can
579 /// handle both fully typed functions and generic functions.
581 /// @param[in] context
582 /// The NameSearchContext to use when constructing the Decl.
585 /// The Function that needs to be created. If non-NULL, this is
586 /// a fully-typed function.
589 /// The Symbol that corresponds to a function that needs to be
590 /// created with generic type (unitptr_t foo(...)).
591 //------------------------------------------------------------------
592 void AddOneFunction(NameSearchContext &context, Function *fun, Symbol *sym,
593 unsigned int current_id);
595 //------------------------------------------------------------------
596 /// Use the NameSearchContext to generate a Decl for the given
599 /// @param[in] context
600 /// The NameSearchContext to use when constructing the Decl.
602 /// @param[in] reg_info
603 /// The information corresponding to that register.
604 //------------------------------------------------------------------
605 void AddOneRegister(NameSearchContext &context, const RegisterInfo *reg_info,
606 unsigned int current_id);
608 //------------------------------------------------------------------
609 /// Use the NameSearchContext to generate a Decl for the given
610 /// type. (Types are not placed in the Tuple list.)
612 /// @param[in] context
613 /// The NameSearchContext to use when constructing the Decl.
616 /// The type that needs to be created.
617 //------------------------------------------------------------------
618 void AddOneType(NameSearchContext &context, TypeFromUser &type,
619 unsigned int current_id);
621 //------------------------------------------------------------------
622 /// Generate a Decl for "*this" and add a member function declaration
623 /// to it for the expression, then report it.
625 /// @param[in] context
626 /// The NameSearchContext to use when constructing the Decl.
629 /// The type for *this.
630 //------------------------------------------------------------------
631 void AddThisType(NameSearchContext &context, TypeFromUser &type,
632 unsigned int current_id);
634 ClangASTContext *GetClangASTContext();
637 } // namespace lldb_private
639 #endif // liblldb_ClangExpressionDeclMap_h_