ClangFunction.h revision b344843f75ef893762c93fd0a22d2d45712ce74d
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] discard_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] single_thread_timeout_usec 255 /// If stop_others is true, the length of time to wait before 256 /// concluding that the system is deadlocked. 257 /// 258 /// @param[in] errors 259 /// The stream to write errors to. 260 /// 261 /// @param[in] this_arg 262 /// If non-NULL, the function is invoked like a C++ method, with the 263 /// value pointed to by the pointer as its 'this' argument. 264 /// 265 /// @return 266 /// Returns one of the ExecutionResults enum indicating function call status. 267 //------------------------------------------------------------------ 268 static ExecutionResults 269 ExecuteFunction (ExecutionContext &exe_ctx, 270 lldb::addr_t function_address, 271 lldb::addr_t &void_arg, 272 bool stop_others, 273 bool try_all_threads, 274 bool discard_on_error, 275 uint32_t single_thread_timeout_usec, 276 Stream &errors, 277 lldb::addr_t* this_arg = 0); 278 279 //------------------------------------------------------------------ 280 /// Run the function this ClangFunction was created with. 281 /// 282 /// This simple version will run the function stopping other threads 283 /// for a fixed timeout period (1000 usec) and if it does not complete, 284 /// we halt the process and try with all threads running. 285 /// 286 /// @param[in] exe_ctx 287 /// The thread & process in which this function will run. 288 /// 289 /// @param[in] errors 290 /// Errors will be written here if there are any. 291 /// 292 /// @param[out] results 293 /// The result value will be put here after running the function. 294 /// 295 /// @return 296 /// Returns one of the ExecutionResults enum indicating function call status. 297 //------------------------------------------------------------------ 298 ExecutionResults 299 ExecuteFunction(ExecutionContext &exe_ctx, 300 Stream &errors, 301 Value &results); 302 303 //------------------------------------------------------------------ 304 /// Run the function this ClangFunction was created with. 305 /// 306 /// This simple version will run the function obeying the stop_others 307 /// argument. There is no timeout. 308 /// 309 /// @param[in] exe_ctx 310 /// The thread & process in which this function will run. 311 /// 312 /// @param[in] errors 313 /// Errors will be written here if there are any. 314 /// 315 /// @param[in] stop_others 316 /// If \b true, run only this thread, if \b false let all threads run. 317 /// 318 /// @param[out] results 319 /// The result value will be put here after running the function. 320 /// 321 /// @return 322 /// Returns one of the ExecutionResults enum indicating function call status. 323 //------------------------------------------------------------------ 324 ExecutionResults 325 ExecuteFunction(ExecutionContext &exe_ctx, 326 Stream &errors, bool stop_others, 327 Value &results); 328 329 //------------------------------------------------------------------ 330 /// Run the function this ClangFunction was created with. 331 /// 332 /// This simple version will run the function on one thread. If \a single_thread_timeout_usec 333 /// is not zero, we time out after that timeout. If \a try_all_threads is true, then we will 334 /// resume with all threads on, otherwise we halt the process, and eExecutionInterrupted will be returned. 335 /// 336 /// @param[in] exe_ctx 337 /// The thread & process in which this function will run. 338 /// 339 /// @param[in] errors 340 /// Errors will be written here if there are any. 341 /// 342 /// @param[in] single_thread_timeout_usec 343 /// If \b true, run only this thread, if \b false let all threads run. 344 /// 345 /// @param[in] try_all_threads 346 /// If \b true, run only this thread, if \b false let all threads run. 347 /// 348 /// @param[out] results 349 /// The result value will be put here after running the function. 350 /// 351 /// @return 352 /// Returns one of the ExecutionResults enum indicating function call status. 353 //------------------------------------------------------------------ 354 ExecutionResults 355 ExecuteFunction(ExecutionContext &exe_ctx, 356 Stream &errors, 357 uint32_t single_thread_timeout_usec, 358 bool try_all_threads, 359 Value &results); 360 361 //------------------------------------------------------------------ 362 /// Run the function this ClangFunction was created with. 363 /// 364 /// This is the full version. 365 /// 366 /// @param[in] exe_ctx 367 /// The thread & process in which this function will run. 368 /// 369 /// @param[in] args_addr_ptr 370 /// If NULL, the function will take care of allocating & deallocating the wrapper 371 /// args structure. Otherwise, if set to LLDB_INVALID_ADDRESS, a new structure 372 /// will be allocated, filled and the address returned to you. You are responsible 373 /// for deallocating it. And if passed in with a value other than LLDB_INVALID_ADDRESS, 374 /// this should point to an already allocated structure with the values already written. 375 /// 376 /// @param[in] errors 377 /// Errors will be written here if there are any. 378 /// 379 /// @param[in] stop_others 380 /// If \b true, run only this thread, if \b false let all threads run. 381 /// 382 /// @param[in] single_thread_timeout_usec 383 /// If \b true, run only this thread, if \b false let all threads run. 384 /// 385 /// @param[in] try_all_threads 386 /// If \b true, run only this thread, if \b false let all threads run. 387 /// 388 /// @param[out] results 389 /// The result value will be put here after running the function. 390 /// 391 /// @return 392 /// Returns one of the ExecutionResults enum indicating function call status. 393 //------------------------------------------------------------------ 394 ExecutionResults 395 ExecuteFunction(ExecutionContext &exe_ctx, 396 lldb::addr_t *args_addr_ptr, 397 Stream &errors, 398 bool stop_others, 399 uint32_t single_thread_timeout_usec, 400 bool try_all_threads, 401 bool discard_on_error, 402 Value &results); 403 404 //------------------------------------------------------------------ 405 /// [static] Get a thread plan to run a function. 406 /// 407 /// @param[in] exe_ctx 408 /// The execution context to insert the function and its arguments 409 /// into. 410 /// 411 /// @param[in] func_addr 412 /// The address of the function in the target process. 413 /// 414 /// @param[in] args_addr_ref 415 /// The value of the void* parameter. 416 /// 417 /// @param[in] errors 418 /// The stream to write errors to. 419 /// 420 /// @param[in] stop_others 421 /// True if other threads should pause during execution. 422 /// 423 /// @param[in] discard_on_error 424 /// True if the thread plan may simply be discarded if an error occurs. 425 /// 426 /// @param[in] this_arg 427 /// If non-NULL (and cmd_arg is NULL), the function is invoked like a C++ 428 /// method, with the value pointed to by the pointer as its 'this' 429 /// argument. 430 /// 431 /// @param[in] cmd_arg 432 /// If non-NULL, the function is invoked like an Objective-C method, with 433 /// this_arg in the 'self' slot and cmd_arg in the '_cmd' slot 434 /// 435 /// @return 436 /// A ThreadPlan for executing the function. 437 //------------------------------------------------------------------ 438 static ThreadPlan * 439 GetThreadPlanToCallFunction (ExecutionContext &exe_ctx, 440 lldb::addr_t func_addr, 441 lldb::addr_t &args_addr_ref, 442 Stream &errors, 443 bool stop_others, 444 bool discard_on_error, 445 lldb::addr_t *this_arg = 0, 446 lldb::addr_t *cmd_arg = 0); 447 448 //------------------------------------------------------------------ 449 /// Get a thread plan to run the function this ClangFunction was created with. 450 /// 451 /// @param[in] exe_ctx 452 /// The execution context to insert the function and its arguments 453 /// into. 454 /// 455 /// @param[in] func_addr 456 /// The address of the function in the target process. 457 /// 458 /// @param[in] args_addr_ref 459 /// The value of the void* parameter. 460 /// 461 /// @param[in] errors 462 /// The stream to write errors to. 463 /// 464 /// @param[in] stop_others 465 /// True if other threads should pause during execution. 466 /// 467 /// @param[in] discard_on_error 468 /// True if the thread plan may simply be discarded if an error occurs. 469 /// 470 /// @return 471 /// A ThreadPlan for executing the function. 472 //------------------------------------------------------------------ 473 ThreadPlan * 474 GetThreadPlanToCallFunction (ExecutionContext &exe_ctx, 475 lldb::addr_t &args_addr_ref, 476 Stream &errors, 477 bool stop_others, 478 bool discard_on_error = true) 479 { 480 return ClangFunction::GetThreadPlanToCallFunction (exe_ctx, 481 m_jit_start_addr, 482 args_addr_ref, 483 errors, 484 stop_others, 485 discard_on_error); 486 } 487 488 //------------------------------------------------------------------ 489 /// Get the result of the function from its struct 490 /// 491 /// @param[in] exe_ctx 492 /// The execution context to retrieve the result from. 493 /// 494 /// @param[in] args_addr 495 /// The address of the argument struct. 496 /// 497 /// @param[in] ret_value 498 /// The value returned by the function. 499 /// 500 /// @return 501 /// True on success; false otherwise. 502 //------------------------------------------------------------------ 503 bool FetchFunctionResults (ExecutionContext &exe_ctx, 504 lldb::addr_t args_addr, 505 Value &ret_value); 506 507 //------------------------------------------------------------------ 508 /// Deallocate the arguments structure 509 /// 510 /// @param[in] exe_ctx 511 /// The execution context to insert the function and its arguments 512 /// into. 513 /// 514 /// @param[in] args_addr 515 /// The address of the argument struct. 516 //------------------------------------------------------------------ 517 void DeallocateFunctionResults (ExecutionContext &exe_ctx, 518 lldb::addr_t args_addr); 519 520 //------------------------------------------------------------------ 521 /// Interface for ClangExpression 522 //------------------------------------------------------------------ 523 524 //------------------------------------------------------------------ 525 /// Return the string that the parser should parse. Must be a full 526 /// translation unit. 527 //------------------------------------------------------------------ 528 const char * 529 Text () 530 { 531 return m_wrapper_function_text.c_str(); 532 } 533 534 //------------------------------------------------------------------ 535 /// Return the function name that should be used for executing the 536 /// expression. Text() should contain the definition of this 537 /// function. 538 //------------------------------------------------------------------ 539 const char * 540 FunctionName () 541 { 542 return m_wrapper_function_name.c_str(); 543 } 544 545 //------------------------------------------------------------------ 546 /// Return the object that the parser should use when resolving external 547 /// values. May be NULL if everything should be self-contained. 548 //------------------------------------------------------------------ 549 ClangExpressionDeclMap * 550 DeclMap () 551 { 552 return NULL; 553 } 554 555 //------------------------------------------------------------------ 556 /// Return the object that the parser should use when registering 557 /// local variables. May be NULL if the Expression doesn't care. 558 //------------------------------------------------------------------ 559 ClangExpressionVariableList * 560 LocalVariables () 561 { 562 return NULL; 563 } 564 565 //------------------------------------------------------------------ 566 /// Return the object that the parser should allow to access ASTs. 567 /// May be NULL if the ASTs do not need to be transformed. 568 /// 569 /// @param[in] passthrough 570 /// The ASTConsumer that the returned transformer should send 571 /// the ASTs to after transformation. 572 //------------------------------------------------------------------ 573 clang::ASTConsumer * 574 ASTTransformer (clang::ASTConsumer *passthrough); 575 576 //------------------------------------------------------------------ 577 /// Return the stream that the parser should use to write DWARF 578 /// opcodes. 579 //------------------------------------------------------------------ 580 StreamString & 581 DwarfOpcodeStream () 582 { 583 return *((StreamString*)0); 584 } 585 586 //------------------------------------------------------------------ 587 /// Return true if validation code should be inserted into the 588 /// expression. 589 //------------------------------------------------------------------ 590 bool 591 NeedsValidation () 592 { 593 return false; 594 } 595 596 //------------------------------------------------------------------ 597 /// Return true if external variables in the expression should be 598 /// resolved. 599 //------------------------------------------------------------------ 600 bool 601 NeedsVariableResolution () 602 { 603 return false; 604 } 605 606private: 607 //------------------------------------------------------------------ 608 // For ClangFunction only 609 //------------------------------------------------------------------ 610 611 std::auto_ptr<ClangExpressionParser> m_parser; ///< The parser responsible for compiling the function. 612 613 Function *m_function_ptr; ///< The function we're going to call. May be NULL if we don't have debug info for the function. 614 Address m_function_addr; ///< If we don't have the FunctionSP, we at least need the address & return type. 615 void *m_function_return_qual_type; ///< The opaque clang qual type for the function return type. 616 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. 617 618 std::string m_wrapper_function_name; ///< The name of the wrapper function. 619 std::string m_wrapper_function_text; ///< The contents of the wrapper function. 620 std::string m_wrapper_struct_name; ///< The name of the struct that contains the target function address, arguments, and result. 621 std::list<lldb::addr_t> m_wrapper_args_addrs; ///< The addresses of the arguments to the wrapper function. 622 623 bool m_struct_valid; ///< True if the ASTStructExtractor has populated the variables below. 624 625 //------------------------------------------------------------------ 626 /// These values are populated by the ASTStructExtractor 627 size_t m_struct_size; ///< The size of the argument struct, in bytes. 628 std::vector<uint64_t> m_member_offsets; ///< The offset of each member in the struct, in bytes. 629 uint64_t m_return_size; ///< The size of the result variable, in bytes. 630 uint64_t m_return_offset; ///< The offset of the result variable in the struct, in bytes. 631 //------------------------------------------------------------------ 632 633 ValueList m_arg_values; ///< The default values of the arguments. 634 635 bool m_compiled; ///< True if the wrapper function has already been parsed. 636 bool m_JITted; ///< True if the wrapper function has already been JIT-compiled. 637}; 638 639} // Namespace lldb_private 640 641#endif // lldb_ClangFunction_h_ 642