ClangFunction.h revision b794020ffbd6473c59a6e98be044df50abf7fc30
1//===-- ClangFunction.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 lldb_ClangFunction_h_ 11#define lldb_ClangFunction_h_ 12 13// C Includes 14// C++ Includes 15#include <vector> 16#include <list> 17// Other libraries and framework includes 18// Project includes 19#include "lldb/Core/ClangForward.h" 20#include "lldb/Core/Address.h" 21#include "lldb/Core/ArchSpec.h" 22#include "lldb/Core/Value.h" 23#include "lldb/Core/ValueObjectList.h" 24#include "lldb/Expression/ClangExpression.h" 25#include "lldb/Target/Process.h" 26 27namespace lldb_private 28{ 29 30class ASTStructExtractor; 31class ClangExpressionParser; 32 33//---------------------------------------------------------------------- 34/// @class ClangFunction ClangFunction.h "lldb/Expression/ClangFunction.h" 35/// @brief Encapsulates a function that can be called. 36/// 37/// A given ClangFunction object can handle a single function signature. 38/// Once constructed, it can set up any number of concurrent calls to 39/// functions with that signature. 40/// 41/// It performs the call by synthesizing a structure that contains the pointer 42/// to the function and the arguments that should be passed to that function, 43/// and producing a special-purpose JIT-compiled function that accepts a void* 44/// pointing to this struct as its only argument and calls the function in the 45/// struct with the written arguments. This method lets Clang handle the 46/// vagaries of function calling conventions. 47/// 48/// The simplest use of the ClangFunction is to construct it with a 49/// function representative of the signature you want to use, then call 50/// ExecuteFunction(ExecutionContext &, Stream &, Value &). 51/// 52/// If you need to reuse the arguments for several calls, you can call 53/// InsertFunction() followed by WriteFunctionArguments(), which will return 54/// the location of the args struct for the wrapper function in args_addr_ref. 55/// 56/// If you need to call the function on the thread plan stack, you can also 57/// call InsertFunction() followed by GetThreadPlanToCallFunction(). 58/// 59/// Any of the methods that take arg_addr_ptr or arg_addr_ref can be passed 60/// a pointer set to LLDB_INVALID_ADDRESS and new structure will be allocated 61/// and its address returned in that variable. 62/// 63/// Any of the methods that take arg_addr_ptr can be passed NULL, and the 64/// argument space will be managed for you. 65//---------------------------------------------------------------------- 66class ClangFunction : public ClangExpression 67{ 68 friend class ASTStructExtractor; 69public: 70 //------------------------------------------------------------------ 71 /// Constructor 72 /// 73 /// @param[in] exe_scope 74 /// An execution context scope that gets us at least a target and 75 /// process. 76 /// 77 /// @param[in] function_ptr 78 /// The default function to be called. Can be overridden using 79 /// WriteFunctionArguments(). 80 /// 81 /// @param[in] ast_context 82 /// The AST context to evaluate argument types in. 83 /// 84 /// @param[in] arg_value_list 85 /// The default values to use when calling this function. Can 86 /// be overridden using WriteFunctionArguments(). 87 //------------------------------------------------------------------ 88 ClangFunction (ExecutionContextScope &exe_scope, 89 Function &function_ptr, 90 ClangASTContext *ast_context, 91 const ValueList &arg_value_list); 92 93 //------------------------------------------------------------------ 94 /// Constructor 95 /// 96 /// @param[in] exe_scope 97 /// An execution context scope that gets us at least a target and 98 /// process. 99 /// 100 /// @param[in] ast_context 101 /// The AST context to evaluate argument types in. 102 /// 103 /// @param[in] return_qualtype 104 /// An opaque Clang QualType for the function result. Should be 105 /// defined in ast_context. 106 /// 107 /// @param[in] function_address 108 /// The address of the function to call. 109 /// 110 /// @param[in] arg_value_list 111 /// The default values to use when calling this function. Can 112 /// be overridden using WriteFunctionArguments(). 113 //------------------------------------------------------------------ 114 ClangFunction (ExecutionContextScope &exe_scope, 115 ClangASTContext *ast_context, 116 void *return_qualtype, 117 const Address& function_address, 118 const ValueList &arg_value_list); 119 120 //------------------------------------------------------------------ 121 /// Destructor 122 //------------------------------------------------------------------ 123 virtual 124 ~ClangFunction(); 125 126 //------------------------------------------------------------------ 127 /// Compile the wrapper function 128 /// 129 /// @param[in] errors 130 /// The stream to print parser errors to. 131 /// 132 /// @return 133 /// The number of errors. 134 //------------------------------------------------------------------ 135 unsigned CompileFunction (Stream &errors); 136 137 //------------------------------------------------------------------ 138 /// Insert the default function wrapper and its default argument struct 139 /// 140 /// @param[in] exe_ctx 141 /// The execution context to insert the function and its arguments 142 /// into. 143 /// 144 /// @param[in,out] args_addr_ref 145 /// The address of the structure to write the arguments into. May 146 /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 147 /// and args_addr_ref is pointed to it. 148 /// 149 /// @param[in] errors 150 /// The stream to write errors to. 151 /// 152 /// @return 153 /// True on success; false otherwise. 154 //------------------------------------------------------------------ 155 bool InsertFunction (ExecutionContext &exe_ctx, 156 lldb::addr_t &args_addr_ref, 157 Stream &errors); 158 159 //------------------------------------------------------------------ 160 /// Insert the default function wrapper (using the JIT) 161 /// 162 /// @param[in] exe_ctx 163 /// The execution context to insert the function and its arguments 164 /// into. 165 /// 166 /// @param[in] errors 167 /// The stream to write errors to. 168 /// 169 /// @return 170 /// True on success; false otherwise. 171 //------------------------------------------------------------------ 172 bool WriteFunctionWrapper (ExecutionContext &exe_ctx, 173 Stream &errors); 174 175 //------------------------------------------------------------------ 176 /// Insert the default function argument struct 177 /// 178 /// @param[in] exe_ctx 179 /// The execution context to insert the function and its arguments 180 /// into. 181 /// 182 /// @param[in,out] args_addr_ref 183 /// The address of the structure to write the arguments into. May 184 /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 185 /// and args_addr_ref is pointed to it. 186 /// 187 /// @param[in] errors 188 /// The stream to write errors to. 189 /// 190 /// @return 191 /// True on success; false otherwise. 192 //------------------------------------------------------------------ 193 bool WriteFunctionArguments (ExecutionContext &exe_ctx, 194 lldb::addr_t &args_addr_ref, 195 Stream &errors); 196 197 //------------------------------------------------------------------ 198 /// Insert an argument struct with a non-default function address and 199 /// non-default argument values 200 /// 201 /// @param[in] exe_ctx 202 /// The execution context to insert the function and its arguments 203 /// into. 204 /// 205 /// @param[in,out] args_addr_ref 206 /// The address of the structure to write the arguments into. May 207 /// be LLDB_INVALID_ADDRESS; if it is, a new structure is allocated 208 /// and args_addr_ref is pointed to it. 209 /// 210 /// @param[in] function_address 211 /// The address of the function to call. 212 /// 213 /// @param[in] arg_values 214 /// The values of the function's arguments. 215 /// 216 /// @param[in] errors 217 /// The stream to write errors to. 218 /// 219 /// @return 220 /// True on success; false otherwise. 221 //------------------------------------------------------------------ 222 bool WriteFunctionArguments (ExecutionContext &exe_ctx, 223 lldb::addr_t &args_addr_ref, 224 Address function_address, 225 ValueList &arg_values, 226 Stream &errors); 227 228 //------------------------------------------------------------------ 229 /// [Static] Execute a function, passing it a single void* parameter. 230 /// ClangFunction uses this to call the wrapper function. 231 /// 232 /// @param[in] exe_ctx 233 /// The execution context to insert the function and its arguments 234 /// into. 235 /// 236 /// @param[in] function_address 237 /// The address of the function in the target process. 238 /// 239 /// @param[in] void_arg 240 /// The value of the void* parameter. 241 /// 242 /// @param[in] stop_others 243 /// True if other threads should pause during execution. 244 /// 245 /// @param[in] try_all_threads 246 /// If the timeout expires, true if other threads should run. If 247 /// the function may try to take locks, this is useful. 248 /// 249 /// @param[in] unwind_on_error 250 /// If true, and the execution stops before completion, we unwind the 251 /// function call, and return the program state to what it was before the 252 /// execution. If false, we leave the program in the stopped state. 253 /// 254 /// @param[in] timeout_usec 255 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 256 /// will try on one thread for the lesser of .25 sec and half the total timeout. 257 /// then switch to running all threads, otherwise this will be the total timeout. 258 /// 259 /// @param[in] errors 260 /// The stream to write errors to. 261 /// 262 /// @param[in] this_arg 263 /// If non-NULL, the function is invoked like a C++ method, with the 264 /// value pointed to by the pointer as its 'this' argument. 265 /// 266 /// @return 267 /// Returns one of the ExecutionResults enum indicating function call status. 268 //------------------------------------------------------------------ 269 static ExecutionResults 270 ExecuteFunction (ExecutionContext &exe_ctx, 271 lldb::addr_t function_address, 272 lldb::addr_t &void_arg, 273 bool stop_others, 274 bool try_all_threads, 275 bool unwind_on_error, 276 bool ignore_breakpoints, 277 uint32_t timeout_usec, 278 Stream &errors, 279 lldb::addr_t* this_arg = 0); 280 281 //------------------------------------------------------------------ 282 /// Run the function this ClangFunction was created with. 283 /// 284 /// This simple version will run the function stopping other threads 285 /// for a fixed timeout period (1000 usec) and if it does not complete, 286 /// we halt the process and try with all threads running. 287 /// 288 /// @param[in] exe_ctx 289 /// The thread & process in which this function will run. 290 /// 291 /// @param[in] errors 292 /// Errors will be written here if there are any. 293 /// 294 /// @param[out] results 295 /// The result value will be put here after running the function. 296 /// 297 /// @return 298 /// Returns one of the ExecutionResults enum indicating function call status. 299 //------------------------------------------------------------------ 300 ExecutionResults 301 ExecuteFunction(ExecutionContext &exe_ctx, 302 Stream &errors, 303 Value &results); 304 305 //------------------------------------------------------------------ 306 /// Run the function this ClangFunction was created with. 307 /// 308 /// This simple version will run the function obeying the stop_others 309 /// argument. There is no timeout. 310 /// 311 /// @param[in] exe_ctx 312 /// The thread & process in which this function will run. 313 /// 314 /// @param[in] errors 315 /// Errors will be written here if there are any. 316 /// 317 /// @param[in] stop_others 318 /// If \b true, run only this thread, if \b false let all threads run. 319 /// 320 /// @param[out] results 321 /// The result value will be put here after running the function. 322 /// 323 /// @return 324 /// Returns one of the ExecutionResults enum indicating function call status. 325 //------------------------------------------------------------------ 326 ExecutionResults 327 ExecuteFunction(ExecutionContext &exe_ctx, 328 Stream &errors, bool stop_others, 329 Value &results); 330 331 //------------------------------------------------------------------ 332 /// Run the function this ClangFunction was created with. 333 /// 334 /// This simple version will run the function on one thread. If \a timeout_usec 335 /// is not zero, we time out after that timeout. If \a try_all_threads is true, then we will 336 /// resume with all threads on, otherwise we halt the process, and eExecutionInterrupted will be returned. 337 /// 338 /// @param[in] exe_ctx 339 /// The thread & process in which this function will run. 340 /// 341 /// @param[in] errors 342 /// Errors will be written here if there are any. 343 /// 344 /// @param[in] timeout_usec 345 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 346 /// will try on one thread for the lesser of .25 sec and half the total timeout. 347 /// then switch to running all threads, otherwise this will be the total timeout. 348 /// 349 /// @param[in] try_all_threads 350 /// If \b true, run only this thread, if \b false let all threads run. 351 /// 352 /// @param[out] results 353 /// The result value will be put here after running the function. 354 /// 355 /// @return 356 /// Returns one of the ExecutionResults enum indicating function call status. 357 //------------------------------------------------------------------ 358 ExecutionResults 359 ExecuteFunction(ExecutionContext &exe_ctx, 360 Stream &errors, 361 uint32_t single_thread_timeout_usec, 362 bool try_all_threads, 363 Value &results); 364 365 //------------------------------------------------------------------ 366 /// Run the function this ClangFunction was created with. 367 /// 368 /// This is the full version. 369 /// 370 /// @param[in] exe_ctx 371 /// The thread & process in which this function will run. 372 /// 373 /// @param[in] args_addr_ptr 374 /// If NULL, the function will take care of allocating & deallocating the wrapper 375 /// args structure. Otherwise, if set to LLDB_INVALID_ADDRESS, a new structure 376 /// will be allocated, filled and the address returned to you. You are responsible 377 /// for deallocating it. And if passed in with a value other than LLDB_INVALID_ADDRESS, 378 /// this should point to an already allocated structure with the values already written. 379 /// 380 /// @param[in] errors 381 /// Errors will be written here if there are any. 382 /// 383 /// @param[in] stop_others 384 /// If \b true, run only this thread, if \b false let all threads run. 385 /// 386 /// @param[in] timeout_usec 387 /// Timeout value (0 for no timeout). If try_all_threads is true, then we 388 /// will try on one thread for the lesser of .25 sec and half the total timeout. 389 /// then switch to running all threads, otherwise this will be the total timeout. 390 /// 391 /// 392 /// @param[in] try_all_threads 393 /// If \b true, run only this thread, if \b false let all threads run. 394 /// 395 /// @param[out] results 396 /// The result value will be put here after running the function. 397 /// 398 /// @return 399 /// Returns one of the ExecutionResults enum indicating function call status. 400 //------------------------------------------------------------------ 401 ExecutionResults 402 ExecuteFunction(ExecutionContext &exe_ctx, 403 lldb::addr_t *args_addr_ptr, 404 Stream &errors, 405 bool stop_others, 406 uint32_t timeout_usec, 407 bool try_all_threads, 408 bool unwind_on_error, 409 bool ignore_breakpoints, 410 Value &results); 411 412 //------------------------------------------------------------------ 413 /// [static] Get a thread plan to run a function. 414 /// 415 /// @param[in] exe_ctx 416 /// The execution context to insert the function and its arguments 417 /// into. 418 /// 419 /// @param[in] func_addr 420 /// The address of the function in the target process. 421 /// 422 /// @param[in] args_addr_ref 423 /// The value of the void* parameter. 424 /// 425 /// @param[in] errors 426 /// The stream to write errors to. 427 /// 428 /// @param[in] stop_others 429 /// True if other threads should pause during execution. 430 /// 431 /// @param[in] unwind_on_error 432 /// True if the thread plan may simply be discarded if an error occurs. 433 /// 434 /// @param[in] ignore_breakpoints 435 /// True if the expression execution will ignore breakpoint hits and continue executing. 436 /// 437 /// @param[in] this_arg 438 /// If non-NULL (and cmd_arg is NULL), the function is invoked like a C++ 439 /// method, with the value pointed to by the pointer as its 'this' 440 /// argument. 441 /// 442 /// @param[in] cmd_arg 443 /// If non-NULL, the function is invoked like an Objective-C method, with 444 /// this_arg in the 'self' slot and cmd_arg in the '_cmd' slot 445 /// 446 /// @return 447 /// A ThreadPlan for executing the function. 448 //------------------------------------------------------------------ 449 static ThreadPlan * 450 GetThreadPlanToCallFunction (ExecutionContext &exe_ctx, 451 lldb::addr_t func_addr, 452 lldb::addr_t &args_addr_ref, 453 Stream &errors, 454 bool stop_others, 455 bool unwind_on_error, 456 bool ignore_breakpoints, 457 lldb::addr_t *this_arg = 0, 458 lldb::addr_t *cmd_arg = 0); 459 460 //------------------------------------------------------------------ 461 /// Get a thread plan to run the function this ClangFunction was created with. 462 /// 463 /// @param[in] exe_ctx 464 /// The execution context to insert the function and its arguments 465 /// into. 466 /// 467 /// @param[in] func_addr 468 /// The address of the function in the target process. 469 /// 470 /// @param[in] args_addr_ref 471 /// The value of the void* parameter. 472 /// 473 /// @param[in] errors 474 /// The stream to write errors to. 475 /// 476 /// @param[in] stop_others 477 /// True if other threads should pause during execution. 478 /// 479 /// @param[in] unwind_on_error 480 /// True if the thread plan may simply be discarded if an error occurs. 481 /// 482 /// @return 483 /// A ThreadPlan for executing the function. 484 //------------------------------------------------------------------ 485 ThreadPlan * 486 GetThreadPlanToCallFunction (ExecutionContext &exe_ctx, 487 lldb::addr_t &args_addr_ref, 488 Stream &errors, 489 bool stop_others, 490 bool unwind_on_error = true, 491 bool ignore_breakpoints = true) 492 { 493 return ClangFunction::GetThreadPlanToCallFunction (exe_ctx, 494 m_jit_start_addr, 495 args_addr_ref, 496 errors, 497 stop_others, 498 unwind_on_error, 499 ignore_breakpoints); 500 } 501 502 //------------------------------------------------------------------ 503 /// Get the result of the function from its struct 504 /// 505 /// @param[in] exe_ctx 506 /// The execution context to retrieve the result from. 507 /// 508 /// @param[in] args_addr 509 /// The address of the argument struct. 510 /// 511 /// @param[in] ret_value 512 /// The value returned by the function. 513 /// 514 /// @return 515 /// True on success; false otherwise. 516 //------------------------------------------------------------------ 517 bool FetchFunctionResults (ExecutionContext &exe_ctx, 518 lldb::addr_t args_addr, 519 Value &ret_value); 520 521 //------------------------------------------------------------------ 522 /// Deallocate the arguments structure 523 /// 524 /// @param[in] exe_ctx 525 /// The execution context to insert the function and its arguments 526 /// into. 527 /// 528 /// @param[in] args_addr 529 /// The address of the argument struct. 530 //------------------------------------------------------------------ 531 void DeallocateFunctionResults (ExecutionContext &exe_ctx, 532 lldb::addr_t args_addr); 533 534 //------------------------------------------------------------------ 535 /// Interface for ClangExpression 536 //------------------------------------------------------------------ 537 538 //------------------------------------------------------------------ 539 /// Return the string that the parser should parse. Must be a full 540 /// translation unit. 541 //------------------------------------------------------------------ 542 const char * 543 Text () 544 { 545 return m_wrapper_function_text.c_str(); 546 } 547 548 //------------------------------------------------------------------ 549 /// Return the function name that should be used for executing the 550 /// expression. Text() should contain the definition of this 551 /// function. 552 //------------------------------------------------------------------ 553 const char * 554 FunctionName () 555 { 556 return m_wrapper_function_name.c_str(); 557 } 558 559 //------------------------------------------------------------------ 560 /// Return the object that the parser should use when resolving external 561 /// values. May be NULL if everything should be self-contained. 562 //------------------------------------------------------------------ 563 ClangExpressionDeclMap * 564 DeclMap () 565 { 566 return NULL; 567 } 568 569 //------------------------------------------------------------------ 570 /// Return the object that the parser should use when registering 571 /// local variables. May be NULL if the Expression doesn't care. 572 //------------------------------------------------------------------ 573 ClangExpressionVariableList * 574 LocalVariables () 575 { 576 return NULL; 577 } 578 579 //------------------------------------------------------------------ 580 /// Return the object that the parser should allow to access ASTs. 581 /// May be NULL if the ASTs do not need to be transformed. 582 /// 583 /// @param[in] passthrough 584 /// The ASTConsumer that the returned transformer should send 585 /// the ASTs to after transformation. 586 //------------------------------------------------------------------ 587 clang::ASTConsumer * 588 ASTTransformer (clang::ASTConsumer *passthrough); 589 590 //------------------------------------------------------------------ 591 /// Return true if validation code should be inserted into the 592 /// expression. 593 //------------------------------------------------------------------ 594 bool 595 NeedsValidation () 596 { 597 return false; 598 } 599 600 //------------------------------------------------------------------ 601 /// Return true if external variables in the expression should be 602 /// resolved. 603 //------------------------------------------------------------------ 604 bool 605 NeedsVariableResolution () 606 { 607 return false; 608 } 609 610private: 611 //------------------------------------------------------------------ 612 // For ClangFunction only 613 //------------------------------------------------------------------ 614 615 std::auto_ptr<ClangExpressionParser> m_parser; ///< The parser responsible for compiling the function. 616 617 Function *m_function_ptr; ///< The function we're going to call. May be NULL if we don't have debug info for the function. 618 Address m_function_addr; ///< If we don't have the FunctionSP, we at least need the address & return type. 619 lldb::clang_type_t m_function_return_qual_type; ///< The opaque clang qual type for the function return type. 620 ClangASTContext *m_clang_ast_context; ///< This is the clang_ast_context that we're getting types from the and value, and the function return the function pointer is NULL. 621 622 std::string m_wrapper_function_name; ///< The name of the wrapper function. 623 std::string m_wrapper_function_text; ///< The contents of the wrapper function. 624 std::string m_wrapper_struct_name; ///< The name of the struct that contains the target function address, arguments, and result. 625 std::list<lldb::addr_t> m_wrapper_args_addrs; ///< The addresses of the arguments to the wrapper function. 626 627 bool m_struct_valid; ///< True if the ASTStructExtractor has populated the variables below. 628 629 //------------------------------------------------------------------ 630 /// These values are populated by the ASTStructExtractor 631 size_t m_struct_size; ///< The size of the argument struct, in bytes. 632 std::vector<uint64_t> m_member_offsets; ///< The offset of each member in the struct, in bytes. 633 uint64_t m_return_size; ///< The size of the result variable, in bytes. 634 uint64_t m_return_offset; ///< The offset of the result variable in the struct, in bytes. 635 //------------------------------------------------------------------ 636 637 ValueList m_arg_values; ///< The default values of the arguments. 638 639 bool m_compiled; ///< True if the wrapper function has already been parsed. 640 bool m_JITted; ///< True if the wrapper function has already been JIT-compiled. 641}; 642 643} // Namespace lldb_private 644 645#endif // lldb_ClangFunction_h_ 646