contrib/llvm/tools/lldb/include/lldb/Expression/ClangUserExpression.h

   1 //===-- ClangUserExpression.h -----------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_ClangUserExpression_h_
  11 #define liblldb_ClangUserExpression_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 #include <string>
  16 #include <map>
  17 #include <vector>
  18
  19 // Other libraries and framework includes
  20 // Project includes
  21
  22 #include "lldb/lldb-forward.h"
  23 #include "lldb/lldb-private.h"
  24 #include "lldb/Core/Address.h"
  25 #include "lldb/Core/ClangForward.h"
  26 #include "lldb/Expression/ClangExpression.h"
  27 #include "lldb/Expression/ClangExpressionVariable.h"
  28 #include "lldb/Expression/IRForTarget.h"
  29 #include "lldb/Expression/Materializer.h"
  30 #include "lldb/Symbol/TaggedASTType.h"
  31 #include "lldb/Target/ExecutionContext.h"
  32
  33 #include "llvm/ExecutionEngine/JITMemoryManager.h"
  34
  35 namespace lldb_private
  36 {
  37
  38 //----------------------------------------------------------------------
  39 /// @class ClangUserExpression ClangUserExpression.h "lldb/Expression/ClangUserExpression.h"
  40 /// @brief Encapsulates a single expression for use with Clang
  41 ///
  42 /// LLDB uses expressions for various purposes, notably to call functions
  43 /// and as a backend for the expr command.  ClangUserExpression encapsulates
  44 /// the objects needed to parse and interpret or JIT an expression.  It
  45 /// uses the Clang parser to produce LLVM IR from the expression.
  46 //----------------------------------------------------------------------
  47 class ClangUserExpression : public ClangExpression
  48 {
  49 public:
  50     typedef std::shared_ptr<ClangUserExpression> ClangUserExpressionSP;
  51
  52     enum { kDefaultTimeout = 500000u };
  53     //------------------------------------------------------------------
  54     /// Constructor
  55     ///
  56     /// @param[in] expr
  57     ///     The expression to parse.
  58     ///
  59     /// @param[in] expr_prefix
  60     ///     If non-NULL, a C string containing translation-unit level
  61     ///     definitions to be included when the expression is parsed.
  62     ///
  63     /// @param[in] language
  64     ///     If not eLanguageTypeUnknown, a language to use when parsing
  65     ///     the expression.  Currently restricted to those languages
  66     ///     supported by Clang.
  67     ///
  68     /// @param[in] desired_type
  69     ///     If not eResultTypeAny, the type to use for the expression
  70     ///     result.
  71     //------------------------------------------------------------------
  72     ClangUserExpression (const char *expr,
  73                          const char *expr_prefix,
  74                          lldb::LanguageType language,
  75                          ResultType desired_type);
  76
  77     //------------------------------------------------------------------
  78     /// Destructor
  79     //------------------------------------------------------------------
  80     virtual
  81     ~ClangUserExpression ();
  82
  83     //------------------------------------------------------------------
  84     /// Parse the expression
  85     ///
  86     /// @param[in] error_stream
  87     ///     A stream to print parse errors and warnings to.
  88     ///
  89     /// @param[in] exe_ctx
  90     ///     The execution context to use when looking up entities that
  91     ///     are needed for parsing (locations of functions, types of
  92     ///     variables, persistent variables, etc.)
  93     ///
  94     /// @param[in] execution_policy
  95     ///     Determines whether interpretation is possible or mandatory.
  96     ///
  97     /// @param[in] keep_result_in_memory
  98     ///     True if the resulting persistent variable should reside in
  99     ///     target memory, if applicable.
 100     ///
 101     /// @return
 102     ///     True on success (no errors); false otherwise.
 103     //------------------------------------------------------------------
 104     bool
 105     Parse (Stream &error_stream,
 106            ExecutionContext &exe_ctx,
 107            lldb_private::ExecutionPolicy execution_policy,
 108            bool keep_result_in_memory);
 109
 110     bool
 111     CanInterpret ()
 112     {
 113         return m_can_interpret;
 114     }
 115
 116     bool
 117     MatchesContext (ExecutionContext &exe_ctx);
 118
 119     //------------------------------------------------------------------
 120     /// Execute the parsed expression
 121     ///
 122     /// @param[in] error_stream
 123     ///     A stream to print errors to.
 124     ///
 125     /// @param[in] exe_ctx
 126     ///     The execution context to use when looking up entities that
 127     ///     are needed for parsing (locations of variables, etc.)
 128     ///
 129     /// @param[in] options
 130     ///     Expression evaluation options.
 131     ///
 132     /// @param[in] shared_ptr_to_me
 133     ///     This is a shared pointer to this ClangUserExpression.  This is
 134     ///     needed because Execute can push a thread plan that will hold onto
 135     ///     the ClangUserExpression for an unbounded period of time.  So you
 136     ///     need to give the thread plan a reference to this object that can
 137     ///     keep it alive.
 138     ///
 139     /// @param[in] result
 140     ///     A pointer to direct at the persistent variable in which the
 141     ///     expression's result is stored.
 142     ///
 143     /// @return
 144     ///     A Process::Execution results value.
 145     //------------------------------------------------------------------
 146     ExecutionResults
 147     Execute (Stream &error_stream,
 148              ExecutionContext &exe_ctx,
 149              const EvaluateExpressionOptions& options,
 150              ClangUserExpressionSP &shared_ptr_to_me,
 151              lldb::ClangExpressionVariableSP &result);
 152
 153     //------------------------------------------------------------------
 154     /// Apply the side effects of the function to program state.
 155     ///
 156     /// @param[in] error_stream
 157     ///     A stream to print errors to.
 158     ///
 159     /// @param[in] exe_ctx
 160     ///     The execution context to use when looking up entities that
 161     ///     are needed for parsing (locations of variables, etc.)
 162     ///
 163     /// @param[in] result
 164     ///     A pointer to direct at the persistent variable in which the
 165     ///     expression's result is stored.
 166     ///
 167     /// @param[in] function_stack_pointer
 168     ///     A pointer to the base of the function's stack frame.  This
 169     ///     is used to determine whether the expession result resides in
 170     ///     memory that will still be valid, or whether it needs to be
 171     ///     treated as homeless for the purpose of future expressions.
 172     ///
 173     /// @return
 174     ///     A Process::Execution results value.
 175     //------------------------------------------------------------------
 176     bool
 177     FinalizeJITExecution (Stream &error_stream,
 178                           ExecutionContext &exe_ctx,
 179                           lldb::ClangExpressionVariableSP &result,
 180                           lldb::addr_t function_stack_bottom = LLDB_INVALID_ADDRESS,
 181                           lldb::addr_t function_stack_top = LLDB_INVALID_ADDRESS);
 182
 183     //------------------------------------------------------------------
 184     /// Return the string that the parser should parse.  Must be a full
 185     /// translation unit.
 186     //------------------------------------------------------------------
 187     const char *
 188     Text ()
 189     {
 190         return m_transformed_text.c_str();
 191     }
 192
 193     //------------------------------------------------------------------
 194     /// Return the string that the user typed.
 195     //------------------------------------------------------------------
 196     const char *
 197     GetUserText ()
 198     {
 199         return m_expr_text.c_str();
 200     }
 201
 202     //------------------------------------------------------------------
 203     /// Return the function name that should be used for executing the
 204     /// expression.  Text() should contain the definition of this
 205     /// function.
 206     //------------------------------------------------------------------
 207     const char *
 208     FunctionName ()
 209     {
 210         return "$__lldb_expr";
 211     }
 212
 213     //------------------------------------------------------------------
 214     /// Return the language that should be used when parsing.  To use
 215     /// the default, return eLanguageTypeUnknown.
 216     //------------------------------------------------------------------
 217     virtual lldb::LanguageType
 218     Language ()
 219     {
 220         return m_language;
 221     }
 222
 223     //------------------------------------------------------------------
 224     /// Return the object that the parser should use when resolving external
 225     /// values.  May be NULL if everything should be self-contained.
 226     //------------------------------------------------------------------
 227     ClangExpressionDeclMap *
 228     DeclMap ()
 229     {
 230         return m_expr_decl_map.get();
 231     }
 232
 233     //------------------------------------------------------------------
 234     /// Return the object that the parser should allow to access ASTs.
 235     /// May be NULL if the ASTs do not need to be transformed.
 236     ///
 237     /// @param[in] passthrough
 238     ///     The ASTConsumer that the returned transformer should send
 239     ///     the ASTs to after transformation.
 240     //------------------------------------------------------------------
 241     clang::ASTConsumer *
 242     ASTTransformer (clang::ASTConsumer *passthrough);
 243
 244     //------------------------------------------------------------------
 245     /// Return the desired result type of the function, or
 246     /// eResultTypeAny if indifferent.
 247     //------------------------------------------------------------------
 248     virtual ResultType
 249     DesiredResultType ()
 250     {
 251         return m_desired_type;
 252     }
 253
 254     //------------------------------------------------------------------
 255     /// Return true if validation code should be inserted into the
 256     /// expression.
 257     //------------------------------------------------------------------
 258     bool
 259     NeedsValidation ()
 260     {
 261         return true;
 262     }
 263
 264     //------------------------------------------------------------------
 265     /// Return true if external variables in the expression should be
 266     /// resolved.
 267     //------------------------------------------------------------------
 268     bool
 269     NeedsVariableResolution ()
 270     {
 271         return true;
 272     }
 273
 274     //------------------------------------------------------------------
 275     /// Evaluate one expression and return its result.
 276     ///
 277     /// @param[in] exe_ctx
 278     ///     The execution context to use when evaluating the expression.
 279     ///
 280     /// @param[in] options
 281     ///     Expression evaluation options.
 282     ///
 283     /// @param[in] expr_cstr
 284     ///     A C string containing the expression to be evaluated.
 285     ///
 286     /// @param[in] expr_prefix
 287     ///     If non-NULL, a C string containing translation-unit level
 288     ///     definitions to be included when the expression is parsed.
 289     ///
 290     /// @param[in/out] result_valobj_sp
 291     ///      If execution is successful, the result valobj is placed here.
 292     ///
 293     /// @param[out]
 294     ///     Filled in with an error in case the expression evaluation
 295     ///     fails to parse, run, or evaluated.
 296     ///
 297     /// @result
 298     ///      A Process::ExecutionResults value.  eExecutionCompleted for success.
 299     //------------------------------------------------------------------
 300     static ExecutionResults
 301     Evaluate (ExecutionContext &exe_ctx,
 302               const EvaluateExpressionOptions& options,
 303               const char *expr_cstr,
 304               const char *expr_prefix,
 305               lldb::ValueObjectSP &result_valobj_sp,
 306               Error &error);
 307
 308     static const Error::ValueType kNoResult = 0x1001; ///< ValueObject::GetError() returns this if there is no result from the expression.
 309 private:
 310     //------------------------------------------------------------------
 311     /// Populate m_cplusplus and m_objetivec based on the environment.
 312     //------------------------------------------------------------------
 313
 314     void
 315     ScanContext (ExecutionContext &exe_ctx,
 316                  lldb_private::Error &err);
 317
 318     bool
 319     PrepareToExecuteJITExpression (Stream &error_stream,
 320                                    ExecutionContext &exe_ctx,
 321                                    lldb::addr_t &struct_address,
 322                                    lldb::addr_t &object_ptr,
 323                                    lldb::addr_t &cmd_ptr);
 324
 325     void
 326     InstallContext (ExecutionContext &exe_ctx);
 327
 328     bool
 329     LockAndCheckContext (ExecutionContext &exe_ctx,
 330                          lldb::TargetSP &target_sp,
 331                          lldb::ProcessSP &process_sp,
 332                          lldb::StackFrameSP &frame_sp);
 333
 334     lldb::ProcessWP                             m_process_wp;           ///< The process used as the context for the expression.
 335     Address                                     m_address;              ///< The address the process is stopped in.
 336     lldb::addr_t                                m_stack_frame_bottom;   ///< The bottom of the allocated stack frame.
 337     lldb::addr_t                                m_stack_frame_top;      ///< The top of the allocated stack frame.
 338
 339     std::string                                 m_expr_text;            ///< The text of the expression, as typed by the user
 340     std::string                                 m_expr_prefix;          ///< The text of the translation-level definitions, as provided by the user
 341     lldb::LanguageType                          m_language;             ///< The language to use when parsing (eLanguageTypeUnknown means use defaults)
 342     bool                                        m_allow_cxx;            ///< True if the language allows C++.
 343     bool                                        m_allow_objc;           ///< True if the language allows Objective-C.
 344     std::string                                 m_transformed_text;     ///< The text of the expression, as send to the parser
 345     ResultType                                  m_desired_type;         ///< The type to coerce the expression's result to.  If eResultTypeAny, inferred from the expression.
 346
 347     std::unique_ptr<ClangExpressionDeclMap>      m_expr_decl_map;        ///< The map to use when parsing the expression.
 348     std::unique_ptr<IRExecutionUnit>             m_execution_unit_ap;    ///< The execution unit the expression is stored in.
 349     std::unique_ptr<Materializer>                m_materializer_ap;      ///< The materializer to use when running the expression.
 350     std::unique_ptr<ASTResultSynthesizer>        m_result_synthesizer;   ///< The result synthesizer, if one is needed.
 351
 352     bool                                        m_enforce_valid_object; ///< True if the expression parser should enforce the presence of a valid class pointer in order to generate the expression as a method.
 353     bool                                        m_cplusplus;            ///< True if the expression is compiled as a C++ member function (true if it was parsed when exe_ctx was in a C++ method).
 354     bool                                        m_objectivec;           ///< True if the expression is compiled as an Objective-C method (true if it was parsed when exe_ctx was in an Objective-C method).
 355     bool                                        m_static_method;        ///< True if the expression is compiled as a static (or class) method (currently true if it was parsed when exe_ctx was in an Objective-C class method).
 356     bool                                        m_needs_object_ptr;     ///< True if "this" or "self" must be looked up and passed in.  False if the expression doesn't really use them and they can be NULL.
 357     bool                                        m_const_object;         ///< True if "this" is const.
 358     Target                                     *m_target;               ///< The target for storing persistent data like types and variables.
 359
 360     bool                                        m_can_interpret;        ///< True if the expression could be evaluated statically; false otherwise.
 361     lldb::addr_t                                m_materialized_address; ///< The address at which the arguments to the expression have been materialized.
 362     Materializer::DematerializerSP              m_dematerializer_sp;    ///< The dematerializer.
 363 };
 364
 365 } // namespace lldb_private
 366
 367 #endif  // liblldb_ClangUserExpression_h_