LLDB  mainline
ClangExpressionDeclMap.h
Go to the documentation of this file.
1 //===-- ClangExpressionDeclMap.h --------------------------------*- C++ -*-===//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 
9 #ifndef liblldb_ClangExpressionDeclMap_h_
10 #define liblldb_ClangExpressionDeclMap_h_
11 
12 #include <signal.h>
13 #include <stdint.h>
14 
15 #include <vector>
16 
17 #include "ClangASTSource.h"
19 
20 #include "lldb/Core/ClangForward.h"
21 #include "lldb/Core/Value.h"
26 #include "lldb/lldb-public.h"
27 #include "clang/AST/Decl.h"
28 #include "llvm/ADT/DenseMap.h"
29 
30 namespace lldb_private {
31 
32 /// \class ClangExpressionDeclMap ClangExpressionDeclMap.h
33 /// "lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are
34 /// defined in LLDB's debug information.
35 ///
36 /// The Clang parser uses the ClangASTSource as an interface to request named
37 /// entities from outside an expression. The ClangASTSource reports back,
38 /// listing all possible objects corresponding to a particular name. But it
39 /// in turn relies on ClangExpressionDeclMap, which performs several important
40 /// functions.
41 ///
42 /// First, it records what variables and functions were looked up and what
43 /// Decls were returned for them.
44 ///
45 /// Second, it constructs a struct on behalf of IRForTarget, recording which
46 /// variables should be placed where and relaying this information back so
47 /// that IRForTarget can generate context-independent code.
48 ///
49 /// Third, it "materializes" this struct on behalf of the expression command,
50 /// finding the current values of each variable and placing them into the
51 /// struct so that it can be passed to the JITted version of the IR.
52 ///
53 /// Fourth and finally, it "dematerializes" the struct after the JITted code
54 /// has has executed, placing the new values back where it found the old ones.
56 public:
57  /// Constructor
58  ///
59  /// Initializes class variables.
60  ///
61  /// \param[in] keep_result_in_memory
62  /// If true, inhibits the normal deallocation of the memory for
63  /// the result persistent variable, and instead marks the variable
64  /// as persisting.
65  ///
66  /// \param[in] delegate
67  /// If non-NULL, use this delegate to report result values. This
68  /// allows the client ClangUserExpression to report a result.
69  ///
70  /// \param[in] exe_ctx
71  /// The execution context to use when parsing.
72  ///
73  /// \param[in] ctx_obj
74  /// If not empty, then expression is evaluated in context of this object.
75  /// See the comment to `UserExpression::Evaluate` for details.
77  bool keep_result_in_memory,
79  ExecutionContext &exe_ctx,
80  ValueObject *ctx_obj);
81 
82  /// Destructor
83  ~ClangExpressionDeclMap() override;
84 
85  /// Enable the state needed for parsing and IR transformation.
86  ///
87  /// \param[in] exe_ctx
88  /// The execution context to use when finding types for variables.
89  /// Also used to find a "scratch" AST context to store result types.
90  ///
91  /// \param[in] materializer
92  /// If non-NULL, the materializer to populate with information about
93  /// the variables to use
94  ///
95  /// \return
96  /// True if parsing is possible; false if it is unsafe to continue.
97  bool WillParse(ExecutionContext &exe_ctx, Materializer *materializer);
98 
99  void InstallCodeGenerator(clang::ASTConsumer *code_gen);
100 
101  /// [Used by ClangExpressionParser] For each variable that had an unknown
102  /// type at the beginning of parsing, determine its final type now.
103  ///
104  /// \return
105  /// True on success; false otherwise.
106  bool ResolveUnknownTypes();
107 
108  /// Disable the state needed for parsing and IR transformation.
109  void DidParse();
110 
111  /// [Used by IRForTarget] Add a variable to the list of persistent
112  /// variables for the process.
113  ///
114  /// \param[in] decl
115  /// The Clang declaration for the persistent variable, used for
116  /// lookup during parsing.
117  ///
118  /// \param[in] name
119  /// The name of the persistent variable, usually $something.
120  ///
121  /// \param[in] type
122  /// The type of the variable, in the Clang parser's context.
123  ///
124  /// \return
125  /// True on success; false otherwise.
126  bool AddPersistentVariable(const clang::NamedDecl *decl,
127  ConstString name, TypeFromParser type,
128  bool is_result, bool is_lvalue);
129 
130  /// [Used by IRForTarget] Add a variable to the struct that needs to
131  /// be materialized each time the expression runs.
132  ///
133  /// \param[in] decl
134  /// The Clang declaration for the variable.
135  ///
136  /// \param[in] name
137  /// The name of the variable.
138  ///
139  /// \param[in] value
140  /// The LLVM IR value for this variable.
141  ///
142  /// \param[in] size
143  /// The size of the variable in bytes.
144  ///
145  /// \param[in] alignment
146  /// The required alignment of the variable in bytes.
147  ///
148  /// \return
149  /// True on success; false otherwise.
150  bool AddValueToStruct(const clang::NamedDecl *decl, ConstString name,
151  llvm::Value *value, size_t size,
152  lldb::offset_t alignment);
153 
154  /// [Used by IRForTarget] Finalize the struct, laying out the position of
155  /// each object in it.
156  ///
157  /// \return
158  /// True on success; false otherwise.
159  bool DoStructLayout();
160 
161  /// [Used by IRForTarget] Get general information about the laid-out struct
162  /// after DoStructLayout() has been called.
163  ///
164  /// \param[out] num_elements
165  /// The number of elements in the struct.
166  ///
167  /// \param[out] size
168  /// The size of the struct, in bytes.
169  ///
170  /// \param[out] alignment
171  /// The alignment of the struct, in bytes.
172  ///
173  /// \return
174  /// True if the information could be retrieved; false otherwise.
175  bool GetStructInfo(uint32_t &num_elements, size_t &size,
176  lldb::offset_t &alignment);
177 
178  /// [Used by IRForTarget] Get specific information about one field of the
179  /// laid-out struct after DoStructLayout() has been called.
180  ///
181  /// \param[out] decl
182  /// The parsed Decl for the field, as generated by ClangASTSource
183  /// on ClangExpressionDeclMap's behalf. In the case of the result
184  /// value, this will have the name $__lldb_result even if the
185  /// result value ends up having the name $1. This is an
186  /// implementation detail of IRForTarget.
187  ///
188  /// \param[out] value
189  /// The IR value for the field (usually a GlobalVariable). In
190  /// the case of the result value, this will have the correct
191  /// name ($1, for instance). This is an implementation detail
192  /// of IRForTarget.
193  ///
194  /// \param[out] offset
195  /// The offset of the field from the beginning of the struct.
196  /// As long as the struct is aligned according to its required
197  /// alignment, this offset will align the field correctly.
198  ///
199  /// \param[out] name
200  /// The name of the field as used in materialization.
201  ///
202  /// \param[in] index
203  /// The index of the field about which information is requested.
204  ///
205  /// \return
206  /// True if the information could be retrieved; false otherwise.
207  bool GetStructElement(const clang::NamedDecl *&decl, llvm::Value *&value,
208  lldb::offset_t &offset, ConstString &name,
209  uint32_t index);
210 
211  /// [Used by IRForTarget] Get information about a function given its Decl.
212  ///
213  /// \param[in] decl
214  /// The parsed Decl for the Function, as generated by ClangASTSource
215  /// on ClangExpressionDeclMap's behalf.
216  ///
217  /// \param[out] ptr
218  /// The absolute address of the function in the target.
219  ///
220  /// \return
221  /// True if the information could be retrieved; false otherwise.
222  bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr);
223 
224  /// [Used by IRForTarget] Get the address of a symbol given nothing but its
225  /// name.
226  ///
227  /// \param[in] target
228  /// The target to find the symbol in. If not provided,
229  /// then the current parsing context's Target.
230  ///
231  /// \param[in] process
232  /// The process to use. For Objective-C symbols, the process's
233  /// Objective-C language runtime may be queried if the process
234  /// is non-NULL.
235  ///
236  /// \param[in] name
237  /// The name of the symbol.
238  ///
239  /// \param[in] module
240  /// The module to limit the search to. This can be NULL
241  ///
242  /// \return
243  /// Valid load address for the symbol
244  lldb::addr_t GetSymbolAddress(Target &target, Process *process,
245  ConstString name,
246  lldb::SymbolType symbol_type,
247  Module *module = NULL);
248 
250  lldb::SymbolType symbol_type);
251 
252  /// [Used by IRInterpreter] Get basic target information.
253  ///
254  /// \param[out] byte_order
255  /// The byte order of the target.
256  ///
257  /// \param[out] address_byte_size
258  /// The size of a pointer in bytes.
259  ///
260  /// \return
261  /// True if the information could be determined; false
262  /// otherwise.
263  struct TargetInfo {
266 
267  TargetInfo() : byte_order(lldb::eByteOrderInvalid), address_byte_size(0) {}
268 
269  bool IsValid() {
270  return (byte_order != lldb::eByteOrderInvalid && address_byte_size != 0);
271  }
272  };
274 
275  /// [Used by ClangASTSource] Find all entities matching a given name, using
276  /// a NameSearchContext to make Decls for them.
277  ///
278  /// \param[in] context
279  /// The NameSearchContext that can construct Decls for this name.
280  ///
281  /// \return
282  /// True on success; false otherwise.
283  void FindExternalVisibleDecls(NameSearchContext &context) override;
284 
285  /// Find all entities matching a given name in a given module/namespace,
286  /// using a NameSearchContext to make Decls for them.
287  ///
288  /// \param[in] context
289  /// The NameSearchContext that can construct Decls for this name.
290  ///
291  /// \param[in] module
292  /// If non-NULL, the module to query.
293  ///
294  /// \param[in] namespace_decl
295  /// If valid and module is non-NULL, the parent namespace.
296  ///
297  /// \param[in] current_id
298  /// The ID for the current FindExternalVisibleDecls invocation,
299  /// for logging purposes.
300  ///
301  /// \return
302  /// True on success; false otherwise.
304  lldb::ModuleSP module,
305  CompilerDeclContext &namespace_decl,
306  unsigned int current_id);
307 
308 private:
310  m_found_entities; ///< All entities that were looked up for the parser.
312  m_struct_members; ///< All entities that need to be placed in the struct.
313  bool m_keep_result_in_memory; ///< True if result persistent variables
314  ///generated by this expression should stay in
315  ///memory.
317  *m_result_delegate; ///< If non-NULL, used to report expression results to
318  ///ClangUserExpression.
319  ValueObject *m_ctx_obj; ///< If not empty, then expression is
320  ///evaluated in context of this object.
321  ///For details see the comment to
322  ///`UserExpression::Evaluate`.
323 
324  /// The following values should not live beyond parsing
325  class ParserVars {
326  public:
327  ParserVars() {}
328 
329  Target *GetTarget() {
330  if (m_exe_ctx.GetTargetPtr())
331  return m_exe_ctx.GetTargetPtr();
332  else if (m_sym_ctx.target_sp)
333  m_sym_ctx.target_sp.get();
334  return NULL;
335  }
336 
337  ExecutionContext m_exe_ctx; ///< The execution context to use when parsing.
338  SymbolContext m_sym_ctx; ///< The symbol context to use in finding variables
339  ///and types.
340  ClangPersistentVariables *m_persistent_vars =
341  nullptr; ///< The persistent variables for the process.
342  bool m_enable_lookups = false; ///< Set to true during parsing if we have
343  ///found the first "$__lldb" name.
344  TargetInfo m_target_info; ///< Basic information about the target.
345  Materializer *m_materializer = nullptr; ///< If non-NULL, the materializer
346  ///to use when reporting used
347  ///variables.
348  clang::ASTConsumer *m_code_gen = nullptr; ///< If non-NULL, a code generator
349  ///that receives new top-level
350  ///functions.
351  private:
352  DISALLOW_COPY_AND_ASSIGN(ParserVars);
353  };
354 
355  std::unique_ptr<ParserVars> m_parser_vars;
356 
357  /// Activate parser-specific variables
358  void EnableParserVars() {
359  if (!m_parser_vars.get())
360  m_parser_vars = llvm::make_unique<ParserVars>();
361  }
362 
363  /// Deallocate parser-specific variables
364  void DisableParserVars() { m_parser_vars.reset(); }
365 
366  /// The following values contain layout information for the materialized
367  /// struct, but are not specific to a single materialization
368  struct StructVars {
369  StructVars()
370  : m_struct_alignment(0), m_struct_size(0), m_struct_laid_out(false),
371  m_result_name(), m_object_pointer_type(NULL, NULL) {}
372 
374  m_struct_alignment; ///< The alignment of the struct in bytes.
375  size_t m_struct_size; ///< The size of the struct in bytes.
376  bool m_struct_laid_out; ///< True if the struct has been laid out and the
377  ///layout is valid (that is, no new fields have been
378  ///added since).
380  m_result_name; ///< The name of the result variable ($1, for example)
381  TypeFromUser m_object_pointer_type; ///< The type of the "this" variable, if
382  ///one exists
383  };
384 
385  std::unique_ptr<StructVars> m_struct_vars;
386 
387  /// Activate struct variables
388  void EnableStructVars() {
389  if (!m_struct_vars.get())
390  m_struct_vars.reset(new struct StructVars);
391  }
392 
393  /// Deallocate struct variables
394  void DisableStructVars() { m_struct_vars.reset(); }
395 
396  /// Get this parser's ID for use in extracting parser- and JIT-specific data
397  /// from persistent variables.
398  uint64_t GetParserID() { return (uint64_t) this; }
399 
400  /// Given a target, find a variable that matches the given name and type.
401  ///
402  /// \param[in] target
403  /// The target to use as a basis for finding the variable.
404  ///
405  /// \param[in] module
406  /// If non-NULL, the module to search.
407  ///
408  /// \param[in] name
409  /// The name as a plain C string.
410  ///
411  /// \param[in] namespace_decl
412  /// If non-NULL and module is non-NULL, the parent namespace.
413  ///
414  /// \param[in] type
415  /// The required type for the variable. This function may be called
416  /// during parsing, in which case we don't know its type; hence the
417  /// default.
418  ///
419  /// \return
420  /// The LLDB Variable found, or NULL if none was found.
421  lldb::VariableSP FindGlobalVariable(Target &target, lldb::ModuleSP &module,
422  ConstString name,
423  CompilerDeclContext *namespace_decl,
424  TypeFromUser *type = NULL);
425 
426  /// Get the value of a variable in a given execution context and return the
427  /// associated Types if needed.
428  ///
429  /// \param[in] var
430  /// The variable to evaluate.
431  ///
432  /// \param[out] var_location
433  /// The variable location value to fill in
434  ///
435  /// \param[out] found_type
436  /// The type of the found value, as it was found in the user process.
437  /// This is only useful when the variable is being inspected on behalf
438  /// of the parser, hence the default.
439  ///
440  /// \param[out] parser_type
441  /// The type of the found value, as it was copied into the parser's
442  /// AST context. This is only useful when the variable is being
443  /// inspected on behalf of the parser, hence the default.
444  ///
445  /// \param[in] decl
446  /// The Decl to be looked up.
447  ///
448  /// \return
449  /// Return true if the value was successfully filled in.
450  bool GetVariableValue(lldb::VariableSP &var,
451  lldb_private::Value &var_location,
452  TypeFromUser *found_type = NULL,
453  TypeFromParser *parser_type = NULL);
454 
455  /// Use the NameSearchContext to generate a Decl for the given LLDB
456  /// Variable, and put it in the Tuple list.
457  ///
458  /// \param[in] context
459  /// The NameSearchContext to use when constructing the Decl.
460  ///
461  /// \param[in] var
462  /// The LLDB Variable that needs a Decl.
463  ///
464  /// \param[in] valobj
465  /// The LLDB ValueObject for that variable.
466  void AddOneVariable(NameSearchContext &context, lldb::VariableSP var,
467  lldb::ValueObjectSP valobj, unsigned int current_id);
468 
469  /// Use the NameSearchContext to generate a Decl for the given persistent
470  /// variable, and put it in the list of found entities.
471  ///
472  /// \param[in] context
473  /// The NameSearchContext to use when constructing the Decl.
474  ///
475  /// \param[in] pvar
476  /// The persistent variable that needs a Decl.
477  ///
478  /// \param[in] current_id
479  /// The ID of the current invocation of FindExternalVisibleDecls
480  /// for logging purposes.
481  void AddOneVariable(NameSearchContext &context,
482  lldb::ExpressionVariableSP &pvar_sp,
483  unsigned int current_id);
484 
485  /// Use the NameSearchContext to generate a Decl for the given LLDB symbol
486  /// (treated as a variable), and put it in the list of found entities.
487  ///
488  /// \param[in] context
489  /// The NameSearchContext to use when constructing the Decl.
490  ///
491  /// \param[in] var
492  /// The LLDB Variable that needs a Decl.
493  void AddOneGenericVariable(NameSearchContext &context, const Symbol &symbol,
494  unsigned int current_id);
495 
496  /// Use the NameSearchContext to generate a Decl for the given function.
497  /// (Functions are not placed in the Tuple list.) Can handle both fully
498  /// typed functions and generic functions.
499  ///
500  /// \param[in] context
501  /// The NameSearchContext to use when constructing the Decl.
502  ///
503  /// \param[in] fun
504  /// The Function that needs to be created. If non-NULL, this is
505  /// a fully-typed function.
506  ///
507  /// \param[in] sym
508  /// The Symbol that corresponds to a function that needs to be
509  /// created with generic type (unitptr_t foo(...)).
510  void AddOneFunction(NameSearchContext &context, Function *fun, Symbol *sym,
511  unsigned int current_id);
512 
513  /// Use the NameSearchContext to generate a Decl for the given register.
514  ///
515  /// \param[in] context
516  /// The NameSearchContext to use when constructing the Decl.
517  ///
518  /// \param[in] reg_info
519  /// The information corresponding to that register.
520  void AddOneRegister(NameSearchContext &context, const RegisterInfo *reg_info,
521  unsigned int current_id);
522 
523  /// Use the NameSearchContext to generate a Decl for the given type. (Types
524  /// are not placed in the Tuple list.)
525  ///
526  /// \param[in] context
527  /// The NameSearchContext to use when constructing the Decl.
528  ///
529  /// \param[in] type
530  /// The type that needs to be created.
531  void AddOneType(NameSearchContext &context, const TypeFromUser &type,
532  unsigned int current_id);
533 
534  /// Generate a Decl for "*this" and add a member function declaration to it
535  /// for the expression, then report it.
536  ///
537  /// \param[in] context
538  /// The NameSearchContext to use when constructing the Decl.
539  ///
540  /// \param[in] type
541  /// The type for *this.
542  void AddThisType(NameSearchContext &context, const TypeFromUser &type,
543  unsigned int current_id);
544 
545  /// Move a type out of the current ASTContext into another, but make sure to
546  /// export all components of the type also.
547  ///
548  /// \param[in] target
549  /// The ClangASTContext to move to.
550  /// \param[in] source
551  /// The ClangASTContext to move from. This is assumed to be going away.
552  /// \param[in] parser_type
553  /// The type as it appears in the source context.
554  ///
555  /// \return
556  /// Returns the moved type, or an empty type if there was a problem.
557  TypeFromUser DeportType(ClangASTContext &target, ClangASTContext &source,
558  TypeFromParser parser_type);
559 
560  ClangASTContext *GetClangASTContext();
561 };
562 
563 } // namespace lldb_private
564 
565 #endif // liblldb_ClangExpressionDeclMap_h_
Enumerations for broadcasting.
Definition: SBLaunchInfo.h:14
Provider for named objects defined in the debug info for Clang.
Defines a symbol context baton that can be handed other debug core functions.
Definition: SymbolContext.h:33
bool GetStructElement(const clang::NamedDecl *&decl, llvm::Value *&value, lldb::offset_t &offset, ConstString &name, uint32_t index)
[Used by IRForTarget] Get specific information about one field of the laid-out struct after DoStructL...
"lldb/Expression/ClangASTSource.h" Container for all objects relevant to a single name lookup ...
A class that describes a function.
Definition: Function.h:323
"lldb/Target/ExecutionContext.h" A class that contains an execution context.
"lldb/Expression/ClangPersistentVariables.h" Manages persistent values that need to be preserved betw...
bool DoStructLayout()
[Used by IRForTarget] Finalize the struct, laying out the position of each object in it...
bool AddPersistentVariable(const clang::NamedDecl *decl, ConstString name, TypeFromParser type, bool is_result, bool is_lvalue)
[Used by IRForTarget] Add a variable to the list of persistent variables for the process.
void DidParse()
Disable the state needed for parsing and IR transformation.
[Used by IRInterpreter] Get basic target information.
uint64_t offset_t
Definition: lldb-types.h:87
bool GetStructInfo(uint32_t &num_elements, size_t &size, lldb::offset_t &alignment)
[Used by IRForTarget] Get general information about the laid-out struct after DoStructLayout() has be...
A class that describes an executable image and its associated object and symbol files.
Definition: Module.h:109
"lldb/Expression/ExpressionVariable.h" A list of variable references.
void FindExternalVisibleDecls(NameSearchContext &context) override
[Used by ClangASTSource] Find all entities matching a given name, using a NameSearchContext to make D...
bool GetFunctionInfo(const clang::NamedDecl *decl, uint64_t &ptr)
[Used by IRForTarget] Get information about a function given its Decl.
A plug-in interface definition class for debugging a process.
Definition: Process.h:353
lldb::addr_t GetSymbolAddress(Target &target, Process *process, ConstString name, lldb::SymbolType symbol_type, Module *module=NULL)
[Used by IRForTarget] Get the address of a symbol given nothing but its name.
ClangExpressionDeclMap(bool keep_result_in_memory, Materializer::PersistentVariableDelegate *result_delegate, ExecutionContext &exe_ctx, ValueObject *ctx_obj)
Constructor.
uint64_t addr_t
Definition: lldb-types.h:83
A uniqued constant string class.
Definition: ConstString.h:38
Definition: SBAddress.h:15
bool ResolveUnknownTypes()
[Used by ClangExpressionParser] For each variable that had an unknown type at the beginning of parsin...
bool WillParse(ExecutionContext &exe_ctx, Materializer *materializer)
Enable the state needed for parsing and IR transformation.
void InstallCodeGenerator(clang::ASTConsumer *code_gen)
bool AddValueToStruct(const clang::NamedDecl *decl, ConstString name, llvm::Value *value, size_t size, lldb::offset_t alignment)
[Used by IRForTarget] Add a variable to the struct that needs to be materialized each time the expres...
"lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are defined in LLDB&#39;s debug in...