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 LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_CLANGEXPRESSIONDECLMAP_H
10#define LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_CLANGEXPRESSIONDECLMAP_H
11
12#include <csignal>
13#include <cstdint>
14
15#include <memory>
16#include <vector>
17
18#include "ClangASTSource.h"
19#include "ClangExpressionVariable.h"
20
21#include "lldb/Core/Value.h"
22#include "lldb/Expression/Materializer.h"
23#include "lldb/Symbol/SymbolContext.h"
24#include "lldb/Symbol/TaggedASTType.h"
25#include "lldb/Target/ExecutionContext.h"
26#include "lldb/lldb-public.h"
27#include "clang/AST/Decl.h"
28#include "llvm/ADT/DenseMap.h"
29
30namespace lldb_private {
31
32class ClangPersistentVariables;
33
34/// \class ClangExpressionDeclMap ClangExpressionDeclMap.h
35/// "lldb/Expression/ClangExpressionDeclMap.h" Manages named entities that are
36/// defined in LLDB's debug information.
37///
38/// The Clang parser uses the ClangASTSource as an interface to request named
39/// entities from outside an expression. The ClangASTSource reports back,
40/// listing all possible objects corresponding to a particular name. But it
41/// in turn relies on ClangExpressionDeclMap, which performs several important
42/// functions.
43///
44/// First, it records what variables and functions were looked up and what
45/// Decls were returned for them.
46///
47/// Second, it constructs a struct on behalf of IRForTarget, recording which
48/// variables should be placed where and relaying this information back so
49/// that IRForTarget can generate context-independent code.
50///
51/// Third, it "materializes" this struct on behalf of the expression command,
52/// finding the current values of each variable and placing them into the
53/// struct so that it can be passed to the JITted version of the IR.
54///
55/// Fourth and finally, it "dematerializes" the struct after the JITted code
56/// has executed, placing the new values back where it found the old ones.
57class ClangExpressionDeclMap : public ClangASTSource {
58public:
59 /// Constructor
60 ///
61 /// Initializes class variables.
62 ///
63 /// \param[in] keep_result_in_memory
64 /// If true, inhibits the normal deallocation of the memory for
65 /// the result persistent variable, and instead marks the variable
66 /// as persisting.
67 ///
68 /// \param[in] result_delegate
69 /// If non-NULL, use this delegate to report result values. This
70 /// allows the client ClangUserExpression to report a result.
71 ///
72 /// \param[in] target
73 /// The target to use when parsing.
74 ///
75 /// \param[in] importer
76 /// The ClangASTImporter to use when parsing.
77 ///
78 /// \param[in] ctx_obj
79 /// If not empty, then expression is evaluated in context of this object.
80 /// See the comment to `UserExpression::Evaluate` for details.
81 ClangExpressionDeclMap(
82 bool keep_result_in_memory,
83 Materializer::PersistentVariableDelegate *result_delegate,
84 const lldb::TargetSP &target,
85 const std::shared_ptr<ClangASTImporter> &importer, ValueObject *ctx_obj);
86
87 /// Destructor
88 ~ClangExpressionDeclMap() override;
89
90 /// Enable the state needed for parsing and IR transformation.
91 ///
92 /// \param[in] exe_ctx
93 /// The execution context to use when finding types for variables.
94 /// Also used to find a "scratch" AST context to store result types.
95 ///
96 /// \param[in] materializer
97 /// If non-NULL, the materializer to populate with information about
98 /// the variables to use
99 ///
100 /// \return
101 /// True if parsing is possible; false if it is unsafe to continue.
102 bool WillParse(ExecutionContext &exe_ctx, Materializer *materializer);
103
104 void InstallCodeGenerator(clang::ASTConsumer *code_gen);
105
106 void InstallDiagnosticManager(DiagnosticManager &diag_manager);
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, lldb::SymbolType symbol_type,
246 Module *module = nullptr);
247
248 lldb::addr_t GetSymbolAddress(ConstString name,
249 lldb::SymbolType symbol_type);
250
251 struct TargetInfo {
252 lldb::ByteOrder byte_order = lldb::eByteOrderInvalid;
253 size_t address_byte_size = 0;
254
255 TargetInfo() = default;
256
257 bool IsValid() {
258 return (byte_order != lldb::eByteOrderInvalid && address_byte_size != 0);
259 }
260 };
261 TargetInfo GetTargetInfo();
262
263 /// [Used by ClangASTSource] Find all entities matching a given name, using
264 /// a NameSearchContext to make Decls for them.
265 ///
266 /// \param[in] context
267 /// The NameSearchContext that can construct Decls for this name.
268 void FindExternalVisibleDecls(NameSearchContext &context) override;
269
270 /// Find all entities matching a given name in a given module/namespace,
271 /// using a NameSearchContext to make Decls for them.
272 ///
273 /// \param[in] context
274 /// The NameSearchContext that can construct Decls for this name.
275 ///
276 /// \param[in] module
277 /// If non-NULL, the module to query.
278 ///
279 /// \param[in] namespace_decl
280 /// If valid and module is non-NULL, the parent namespace.
281 void FindExternalVisibleDecls(NameSearchContext &context,
282 lldb::ModuleSP module,
283 const CompilerDeclContext &namespace_decl);
284
285protected:
286 /// Retrieves the declaration with the given name from the storage of
287 /// persistent declarations.
288 ///
289 /// \return
290 /// A persistent decl with the given name or a nullptr.
291 virtual clang::NamedDecl *GetPersistentDecl(ConstString name);
292
293private:
294 ExpressionVariableList
295 m_found_entities; ///< All entities that were looked up for the parser.
296 ExpressionVariableList
297 m_struct_members; ///< All entities that need to be placed in the struct.
298 bool m_keep_result_in_memory; ///< True if result persistent variables
299 ///generated by this expression should stay in
300 ///memory.
301 Materializer::PersistentVariableDelegate
302 *m_result_delegate; ///< If non-NULL, used to report expression results to
303 ///ClangUserExpression.
304 ValueObject *m_ctx_obj; ///< If not empty, then expression is
305 ///evaluated in context of this object.
306 ///For details see the comment to
307 ///`UserExpression::Evaluate`.
308
309 /// The following values should not live beyond parsing
310 class ParserVars {
311 public:
312 ParserVars() = default;
313
314 Target *GetTarget() {
315 if (m_exe_ctx.GetTargetPtr())
316 return m_exe_ctx.GetTargetPtr();
317 else if (m_sym_ctx.target_sp)
318 return m_sym_ctx.target_sp.get();
319 return nullptr;
320 }
321
322 ExecutionContext m_exe_ctx; ///< The execution context to use when parsing.
323 SymbolContext m_sym_ctx; ///< The symbol context to use in finding variables
324 ///and types.
325 ClangPersistentVariables *m_persistent_vars =
326 nullptr; ///< The persistent variables for the process.
327 bool m_enable_lookups = false; ///< Set to true during parsing if we have
328 ///found the first "$__lldb" name.
329 TargetInfo m_target_info; ///< Basic information about the target.
330 Materializer *m_materializer = nullptr; ///< If non-NULL, the materializer
331 ///to use when reporting used
332 ///variables.
333 clang::ASTConsumer *m_code_gen = nullptr; ///< If non-NULL, a code generator
334 ///that receives new top-level
335 ///functions.
336 DiagnosticManager *m_diagnostics = nullptr;
337
338 private:
339 ParserVars(const ParserVars &) = delete;
340 const ParserVars &operator=(const ParserVars &) = delete;
341 };
342
343 std::unique_ptr<ParserVars> m_parser_vars;
344
345 /// Activate parser-specific variables
346 void EnableParserVars() {
347 if (!m_parser_vars.get())
348 m_parser_vars = std::make_unique<ParserVars>();
349 }
350
351 /// Deallocate parser-specific variables
352 void DisableParserVars() { m_parser_vars.reset(); }
353
354 /// The following values contain layout information for the materialized
355 /// struct, but are not specific to a single materialization
356 struct StructVars {
357 StructVars() = default;
358
359 lldb::offset_t m_struct_alignment =
360 0; ///< The alignment of the struct in bytes.
361 size_t m_struct_size = 0; ///< The size of the struct in bytes.
362 bool m_struct_laid_out =
363 false; ///< True if the struct has been laid out and the
364 /// layout is valid (that is, no new fields have been
365 /// added since).
366 ConstString
367 m_result_name; ///< The name of the result variable ($1, for example)
368 };
369
370 std::unique_ptr<StructVars> m_struct_vars;
371
372 /// Activate struct variables
373 void EnableStructVars() {
374 if (!m_struct_vars.get())
375 m_struct_vars.reset(p: new struct StructVars);
376 }
377
378 /// Deallocate struct variables
379 void DisableStructVars() { m_struct_vars.reset(); }
380
381 lldb::TypeSystemClangSP GetScratchContext(Target &target) {
382 return ScratchTypeSystemClang::GetForTarget(target,
383 lang_opts: m_ast_context->getLangOpts());
384 }
385
386 /// Get this parser's ID for use in extracting parser- and JIT-specific data
387 /// from persistent variables.
388 uint64_t GetParserID() { return (uint64_t) this; }
389
390 /// Should be called on all copied functions.
391 void MaybeRegisterFunctionBody(clang::FunctionDecl *copied_function_decl);
392
393 /// Searches the persistent decls of the target for entities with the
394 /// given name.
395 ///
396 /// \param[in] context
397 /// The NameSearchContext that can construct Decls for this name.
398 ///
399 /// \param[in] name
400 /// The name of the entities that need to be found.
401 void SearchPersistenDecls(NameSearchContext &context, const ConstString name);
402
403 /// Handles looking up $__lldb_class which requires special treatment.
404 ///
405 /// \param[in] context
406 /// The NameSearchContext that can construct Decls for this name.
407 void LookUpLldbClass(NameSearchContext &context);
408
409 /// Handles looking up $__lldb_objc_class which requires special treatment.
410 ///
411 /// \param[in] context
412 /// The NameSearchContext that can construct Decls for this name.
413 void LookUpLldbObjCClass(NameSearchContext &context);
414
415 /// Handles looking up the synthetic namespace that contains our local
416 /// variables for the current frame.
417 ///
418 /// \param[in] sym_ctx
419 /// The current SymbolContext of this frame.
420 ///
421 /// \param[in] name_context
422 /// The NameSearchContext that can construct Decls for this name.
423 void LookupLocalVarNamespace(SymbolContext &sym_ctx,
424 NameSearchContext &name_context);
425
426 /// Lookup entities in the ClangModulesDeclVendor.
427 /// \param[in] context
428 /// The NameSearchContext that can construct Decls for this name.
429 ///
430 /// \param[in] name
431 /// The name of the entities that need to be found.
432 void LookupInModulesDeclVendor(NameSearchContext &context, ConstString name);
433
434 /// Looks up a local variable.
435 ///
436 /// \param[in] context
437 /// The NameSearchContext that can construct Decls for this name.
438 ///
439 /// \param[in] name
440 /// The name of the entities that need to be found.
441 ///
442 /// \param[in] sym_ctx
443 /// The current SymbolContext of this frame.
444 ///
445 /// \param[in] namespace_decl
446 /// The parent namespace if there is one.
447 ///
448 /// \return
449 /// True iff a local variable was found.
450 bool LookupLocalVariable(NameSearchContext &context, ConstString name,
451 SymbolContext &sym_ctx,
452 const CompilerDeclContext &namespace_decl);
453
454 /// Searches for functions in the given SymbolContextList.
455 ///
456 /// \param[in] sc_list
457 /// The SymbolContextList to search.
458 ///
459 /// \param[in] frame_decl_context
460 /// The current DeclContext of the current frame.
461 ///
462 /// \return
463 /// A SymbolContextList with any found functions in the front and
464 /// any unknown SymbolContexts which are not functions in the back.
465 /// The SymbolContexts for the functions are ordered by how close they are
466 /// to the DeclContext for the given frame DeclContext.
467 SymbolContextList SearchFunctionsInSymbolContexts(
468 const SymbolContextList &sc_list,
469 const CompilerDeclContext &frame_decl_context);
470
471 /// Looks up a function.
472 ///
473 /// \param[in] context
474 /// The NameSearchContext that can construct Decls for this name.
475 ///
476 /// \param[in] module_sp
477 /// If non-NULL, the module to query.
478 ///
479 /// \param[in] name
480 /// The name of the function that should be find.
481 ///
482 /// \param[in] namespace_decl
483 /// If valid and module is non-NULL, the parent namespace.
484 void LookupFunction(NameSearchContext &context, lldb::ModuleSP module_sp,
485 ConstString name,
486 const CompilerDeclContext &namespace_decl);
487
488 /// Given a target, find a variable that matches the given name and type.
489 ///
490 /// \param[in] target
491 /// The target to use as a basis for finding the variable.
492 ///
493 /// \param[in] module
494 /// If non-NULL, the module to search.
495 ///
496 /// \param[in] name
497 /// The name as a plain C string.
498 ///
499 /// \param[in] namespace_decl
500 /// If non-NULL and module is non-NULL, the parent namespace.
501 ///
502 /// \return
503 /// The LLDB Variable found, or NULL if none was found.
504 lldb::VariableSP
505 FindGlobalVariable(Target &target, lldb::ModuleSP &module, ConstString name,
506 const CompilerDeclContext &namespace_decl);
507
508 /// Get the value of a variable in a given execution context and return the
509 /// associated Types if needed.
510 ///
511 /// \param[in] var
512 /// The variable to evaluate.
513 ///
514 /// \param[out] var_location
515 /// The variable location value to fill in
516 ///
517 /// \param[out] found_type
518 /// The type of the found value, as it was found in the user process.
519 /// This is only useful when the variable is being inspected on behalf
520 /// of the parser, hence the default.
521 ///
522 /// \param[out] parser_type
523 /// The type of the found value, as it was copied into the parser's
524 /// AST context. This is only useful when the variable is being
525 /// inspected on behalf of the parser, hence the default.
526 ///
527 /// \return
528 /// Return true if the value was successfully filled in.
529 bool GetVariableValue(lldb::VariableSP &var,
530 lldb_private::Value &var_location,
531 TypeFromUser *found_type = nullptr,
532 TypeFromParser *parser_type = nullptr);
533
534 /// Use the NameSearchContext to generate a Decl for the given LLDB
535 /// ValueObject, and put it in the list of found entities.
536 ///
537 /// Helper function used by the other AddOneVariable APIs.
538 ///
539 /// \param[in,out] context
540 /// The NameSearchContext to use when constructing the Decl.
541 ///
542 /// \param[in] pt
543 /// The CompilerType of the variable we're adding a Decl for.
544 ///
545 /// \param[in] var
546 /// The LLDB ValueObject that needs a Decl.
547 ClangExpressionVariable::ParserVars *
548 AddExpressionVariable(NameSearchContext &context, TypeFromParser const &pt,
549 lldb::ValueObjectSP valobj);
550
551 /// Use the NameSearchContext to generate a Decl for the given LLDB
552 /// Variable, and put it in the Tuple list.
553 ///
554 /// \param[in] context
555 /// The NameSearchContext to use when constructing the Decl.
556 ///
557 /// \param[in] var
558 /// The LLDB Variable that needs a Decl.
559 ///
560 /// \param[in] valobj
561 /// The LLDB ValueObject for that variable.
562 void AddOneVariable(NameSearchContext &context, lldb::VariableSP var,
563 lldb::ValueObjectSP valobj);
564
565 /// Use the NameSearchContext to generate a Decl for the given ValueObject
566 /// and put it in the list of found entities.
567 ///
568 /// \param[in,out] context
569 /// The NameSearchContext to use when constructing the Decl.
570 ///
571 /// \param[in] valobj
572 /// The ValueObject that needs a Decl.
573 ///
574 /// \param[in] valobj_provider Callback that fetches a ValueObjectSP
575 /// from the specified frame
576 void AddOneVariable(NameSearchContext &context, lldb::ValueObjectSP valobj,
577 ValueObjectProviderTy valobj_provider);
578
579 /// Use the NameSearchContext to generate a Decl for the given persistent
580 /// variable, and put it in the list of found entities.
581 ///
582 /// \param[in] context
583 /// The NameSearchContext to use when constructing the Decl.
584 ///
585 /// \param[in] pvar_sp
586 /// The persistent variable that needs a Decl.
587 void AddOneVariable(NameSearchContext &context,
588 lldb::ExpressionVariableSP &pvar_sp);
589
590 /// Use the NameSearchContext to generate a Decl for the given LLDB symbol
591 /// (treated as a variable), and put it in the list of found entities.
592 void AddOneGenericVariable(NameSearchContext &context, const Symbol &symbol);
593
594 /// Use the NameSearchContext to generate a Decl for the given function.
595 /// (Functions are not placed in the Tuple list.) Can handle both fully
596 /// typed functions and generic functions.
597 ///
598 /// \param[in] context
599 /// The NameSearchContext to use when constructing the Decl.
600 ///
601 /// \param[in] fun
602 /// The Function that needs to be created. If non-NULL, this is
603 /// a fully-typed function.
604 ///
605 /// \param[in] sym
606 /// The Symbol that corresponds to a function that needs to be
607 /// created with generic type (unitptr_t foo(...)).
608 void AddOneFunction(NameSearchContext &context, Function *fun, Symbol *sym);
609
610 /// Use the NameSearchContext to generate a Decl for the given register.
611 ///
612 /// \param[in] context
613 /// The NameSearchContext to use when constructing the Decl.
614 ///
615 /// \param[in] reg_info
616 /// The information corresponding to that register.
617 void AddOneRegister(NameSearchContext &context, const RegisterInfo *reg_info);
618
619 /// Use the NameSearchContext to generate a Decl for the given type. (Types
620 /// are not placed in the Tuple list.)
621 ///
622 /// \param[in] context
623 /// The NameSearchContext to use when constructing the Decl.
624 ///
625 /// \param[in] type
626 /// The type that needs to be created.
627 void AddOneType(NameSearchContext &context, const TypeFromUser &type);
628
629 /// Adds the class in which the expression is evaluated to the lookup and
630 /// prepares the class to be used as a context for expression evaluation (for
631 /// example, it creates a fake member function that will contain the
632 /// expression LLDB is trying to evaluate).
633 ///
634 /// \param[in] context
635 /// The NameSearchContext to which the class should be added as a lookup
636 /// result.
637 ///
638 /// \param[in] type
639 /// The type of the class that serves as the evaluation context.
640 void AddContextClassType(NameSearchContext &context,
641 const TypeFromUser &type);
642
643 /// Move a type out of the current ASTContext into another, but make sure to
644 /// export all components of the type also.
645 ///
646 /// \param[in] target
647 /// The TypeSystemClang to move to.
648 /// \param[in] source
649 /// The TypeSystemClang to move from. This is assumed to be going away.
650 /// \param[in] parser_type
651 /// The type as it appears in the source context.
652 ///
653 /// \return
654 /// Returns the moved type, or an empty type if there was a problem.
655 TypeFromUser DeportType(TypeSystemClang &target, TypeSystemClang &source,
656 TypeFromParser parser_type);
657
658 TypeSystemClang *GetTypeSystemClang();
659};
660
661} // namespace lldb_private
662
663#endif // LLDB_SOURCE_PLUGINS_EXPRESSIONPARSER_CLANG_CLANGEXPRESSIONDECLMAP_H
664

source code of lldb/source/Plugins/ExpressionParser/Clang/ClangExpressionDeclMap.h