contrib/llvm/tools/lldb/include/lldb/Target/Thread.h

   1 //===-- Thread.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_Thread_h_
  11 #define liblldb_Thread_h_
  12
  13 #include "lldb/lldb-private.h"
  14 #include "lldb/Host/Mutex.h"
  15 #include "lldb/Core/Broadcaster.h"
  16 #include "lldb/Core/Event.h"
  17 #include "lldb/Core/UserID.h"
  18 #include "lldb/Core/UserSettingsController.h"
  19 #include "lldb/Target/ExecutionContextScope.h"
  20 #include "lldb/Target/RegisterCheckpoint.h"
  21 #include "lldb/Target/StackFrameList.h"
  22
  23 #define LLDB_THREAD_MAX_STOP_EXC_DATA 8
  24
  25 namespace lldb_private {
  26
  27 class ThreadProperties : public Properties
  28 {
  29 public:
  30     ThreadProperties(bool is_global);
  31
  32     virtual
  33     ~ThreadProperties();
  34
  35     //------------------------------------------------------------------
  36     /// The regular expression returned determines symbols that this
  37     /// thread won't stop in during "step-in" operations.
  38     ///
  39     /// @return
  40     ///    A pointer to a regular expression to compare against symbols,
  41     ///    or NULL if all symbols are allowed.
  42     ///
  43     //------------------------------------------------------------------
  44     const RegularExpression *
  45     GetSymbolsToAvoidRegexp();
  46
  47     FileSpecList &
  48     GetLibrariesToAvoid() const;
  49
  50     bool
  51     GetTraceEnabledState() const;
  52 };
  53
  54 typedef std::shared_ptr<ThreadProperties> ThreadPropertiesSP;
  55
  56 class Thread :
  57     public std::enable_shared_from_this<Thread>,
  58     public ThreadProperties,
  59     public UserID,
  60     public ExecutionContextScope,
  61     public Broadcaster
  62 {
  63 public:
  64     //------------------------------------------------------------------
  65     /// Broadcaster event bits definitions.
  66     //------------------------------------------------------------------
  67     enum
  68     {
  69         eBroadcastBitStackChanged           = (1 << 0),
  70         eBroadcastBitThreadSuspended        = (1 << 1),
  71         eBroadcastBitThreadResumed          = (1 << 2),
  72         eBroadcastBitSelectedFrameChanged   = (1 << 3),
  73         eBroadcastBitThreadSelected         = (1 << 4)
  74     };
  75
  76     static ConstString &GetStaticBroadcasterClass ();
  77
  78     virtual ConstString &GetBroadcasterClass() const
  79     {
  80         return GetStaticBroadcasterClass();
  81     }
  82
  83     class ThreadEventData :
  84         public EventData
  85     {
  86     public:
  87         ThreadEventData (const lldb::ThreadSP thread_sp);
  88
  89         ThreadEventData (const lldb::ThreadSP thread_sp, const StackID &stack_id);
  90
  91         ThreadEventData();
  92
  93         virtual ~ThreadEventData();
  94
  95         static const ConstString &
  96         GetFlavorString ();
  97
  98         virtual const ConstString &
  99         GetFlavor () const
 100         {
 101             return ThreadEventData::GetFlavorString ();
 102         }
 103
 104         virtual void
 105         Dump (Stream *s) const;
 106
 107         static const ThreadEventData *
 108         GetEventDataFromEvent (const Event *event_ptr);
 109
 110         static lldb::ThreadSP
 111         GetThreadFromEvent (const Event *event_ptr);
 112
 113         static StackID
 114         GetStackIDFromEvent (const Event *event_ptr);
 115
 116         static lldb::StackFrameSP
 117         GetStackFrameFromEvent (const Event *event_ptr);
 118
 119         lldb::ThreadSP
 120         GetThread () const
 121         {
 122             return m_thread_sp;
 123         }
 124
 125         StackID
 126         GetStackID () const
 127         {
 128             return m_stack_id;
 129         }
 130
 131     private:
 132         lldb::ThreadSP m_thread_sp;
 133         StackID        m_stack_id;
 134     DISALLOW_COPY_AND_ASSIGN (ThreadEventData);
 135     };
 136
 137
 138     struct ThreadStateCheckpoint
 139     {
 140         uint32_t           orig_stop_id;  // Dunno if I need this yet but it is an interesting bit of data.
 141         lldb::StopInfoSP   stop_info_sp;  // You have to restore the stop info or you might continue with the wrong signals.
 142         lldb::RegisterCheckpointSP register_backup_sp;  // You need to restore the registers, of course...
 143         uint32_t           current_inlined_depth;
 144         lldb::addr_t       current_inlined_pc;
 145     };
 146
 147     static void
 148     SettingsInitialize ();
 149
 150     static void
 151     SettingsTerminate ();
 152
 153     static const ThreadPropertiesSP &
 154     GetGlobalProperties();
 155
 156     Thread (Process &process, lldb::tid_t tid);
 157     virtual ~Thread();
 158
 159     lldb::ProcessSP
 160     GetProcess() const
 161     {
 162         return m_process_wp.lock();
 163     }
 164
 165     int
 166     GetResumeSignal () const
 167     {
 168         return m_resume_signal;
 169     }
 170
 171     void
 172     SetResumeSignal (int signal)
 173     {
 174         m_resume_signal = signal;
 175     }
 176
 177     lldb::StateType
 178     GetState() const;
 179
 180     void
 181     SetState (lldb::StateType state);
 182
 183     lldb::StateType
 184     GetResumeState () const
 185     {
 186         return m_resume_state;
 187     }
 188
 189     void
 190     SetResumeState (lldb::StateType state)
 191     {
 192         m_resume_state = state;
 193     }
 194
 195     // This function is called on all the threads before "ShouldResume" and
 196     // "WillResume" in case a thread needs to change its state before the
 197     // ThreadList polls all the threads to figure out which ones actually
 198     // will get to run and how.
 199     void
 200     SetupForResume ();
 201
 202     // Do not override this function, it is for thread plan logic only
 203     bool
 204     ShouldResume (lldb::StateType resume_state);
 205
 206     // Override this to do platform specific tasks before resume.
 207     virtual void
 208     WillResume (lldb::StateType resume_state)
 209     {
 210     }
 211
 212     // This clears generic thread state after a resume.  If you subclass this,
 213     // be sure to call it.
 214     virtual void
 215     DidResume ();
 216
 217     // This notifies the thread when a private stop occurs.
 218     virtual void
 219     DidStop ();
 220
 221     virtual void
 222     RefreshStateAfterStop() = 0;
 223
 224     void
 225     WillStop ();
 226
 227     bool
 228     ShouldStop (Event *event_ptr);
 229
 230     Vote
 231     ShouldReportStop (Event *event_ptr);
 232
 233     Vote
 234     ShouldReportRun (Event *event_ptr);
 235
 236     void
 237     Flush ();
 238
 239     // Return whether this thread matches the specification in ThreadSpec.  This is a virtual
 240     // method because at some point we may extend the thread spec with a platform specific
 241     // dictionary of attributes, which then only the platform specific Thread implementation
 242     // would know how to match.  For now, this just calls through to the ThreadSpec's
 243     // ThreadPassesBasicTests method.
 244     virtual bool
 245     MatchesSpec (const ThreadSpec *spec);
 246
 247     lldb::StopInfoSP
 248     GetStopInfo ();
 249
 250     lldb::StopReason
 251     GetStopReason();
 252
 253     // This sets the stop reason to a "blank" stop reason, so you can call functions on the thread
 254     // without having the called function run with whatever stop reason you stopped with.
 255     void
 256     SetStopInfoToNothing();
 257
 258     bool
 259     ThreadStoppedForAReason ();
 260
 261     static const char *
 262     RunModeAsCString (lldb::RunMode mode);
 263
 264     static const char *
 265     StopReasonAsCString (lldb::StopReason reason);
 266
 267     virtual const char *
 268     GetInfo ()
 269     {
 270         return NULL;
 271     }
 272
 273     virtual const char *
 274     GetName ()
 275     {
 276         return NULL;
 277     }
 278
 279     virtual void
 280     SetName (const char *name)
 281     {
 282     }
 283
 284     virtual lldb::queue_id_t
 285     GetQueueID ()
 286     {
 287         return LLDB_INVALID_QUEUE_ID;
 288     }
 289
 290     virtual void
 291     SetQueueID (lldb::queue_id_t new_val)
 292     {
 293     }
 294
 295     virtual const char *
 296     GetQueueName ()
 297     {
 298         return NULL;
 299     }
 300
 301     virtual void
 302     SetQueueName (const char *name)
 303     {
 304     }
 305
 306     virtual uint32_t
 307     GetStackFrameCount()
 308     {
 309         return GetStackFrameList()->GetNumFrames();
 310     }
 311
 312     virtual lldb::StackFrameSP
 313     GetStackFrameAtIndex (uint32_t idx)
 314     {
 315         return GetStackFrameList()->GetFrameAtIndex(idx);
 316     }
 317
 318     virtual lldb::StackFrameSP
 319     GetFrameWithConcreteFrameIndex (uint32_t unwind_idx);
 320
 321     bool
 322     DecrementCurrentInlinedDepth()
 323     {
 324         return GetStackFrameList()->DecrementCurrentInlinedDepth();
 325     }
 326
 327     uint32_t
 328     GetCurrentInlinedDepth()
 329     {
 330         return GetStackFrameList()->GetCurrentInlinedDepth();
 331     }
 332
 333     Error
 334     ReturnFromFrameWithIndex (uint32_t frame_idx, lldb::ValueObjectSP return_value_sp, bool broadcast = false);
 335
 336     Error
 337     ReturnFromFrame (lldb::StackFrameSP frame_sp, lldb::ValueObjectSP return_value_sp, bool broadcast = false);
 338
 339     Error
 340     JumpToLine (const FileSpec &file, uint32_t line, bool can_leave_function, std::string *warnings = NULL);
 341
 342     virtual lldb::StackFrameSP
 343     GetFrameWithStackID (const StackID &stack_id)
 344     {
 345         if (stack_id.IsValid())
 346             return GetStackFrameList()->GetFrameWithStackID (stack_id);
 347         return lldb::StackFrameSP();
 348     }
 349
 350     uint32_t
 351     GetSelectedFrameIndex ()
 352     {
 353         return GetStackFrameList()->GetSelectedFrameIndex();
 354     }
 355
 356     lldb::StackFrameSP
 357     GetSelectedFrame ()
 358     {
 359         lldb::StackFrameListSP stack_frame_list_sp(GetStackFrameList());
 360         return stack_frame_list_sp->GetFrameAtIndex (stack_frame_list_sp->GetSelectedFrameIndex());
 361     }
 362
 363     uint32_t
 364     SetSelectedFrame (lldb_private::StackFrame *frame, bool broadcast = false);
 365
 366
 367     bool
 368     SetSelectedFrameByIndex (uint32_t frame_idx, bool broadcast = false);
 369
 370     bool
 371     SetSelectedFrameByIndexNoisily (uint32_t frame_idx, Stream &output_stream);
 372
 373     void
 374     SetDefaultFileAndLineToSelectedFrame()
 375     {
 376         GetStackFrameList()->SetDefaultFileAndLineToSelectedFrame();
 377     }
 378
 379     virtual lldb::RegisterContextSP
 380     GetRegisterContext () = 0;
 381
 382     virtual lldb::RegisterContextSP
 383     CreateRegisterContextForFrame (StackFrame *frame) = 0;
 384
 385     virtual void
 386     ClearStackFrames ();
 387
 388     virtual bool
 389     SetBackingThread (const lldb::ThreadSP &thread_sp)
 390     {
 391         return false;
 392     }
 393
 394     virtual lldb::ThreadSP
 395     GetBackingThread () const
 396     {
 397         return lldb::ThreadSP();
 398     }
 399
 400     virtual void
 401     ClearBackingThread ()
 402     {
 403         // Subclasses can use this function if a thread is actually backed by
 404         // another thread. This is currently used for the OperatingSystem plug-ins
 405         // where they might have a thread that is in memory, yet its registers
 406         // are available through the lldb_private::Thread subclass for the current
 407         // lldb_private::Process class. Since each time the process stops the backing
 408         // threads for memory threads can change, we need a way to clear the backing
 409         // thread for all memory threads each time we stop.
 410     }
 411
 412     void
 413     DumpUsingSettingsFormat (Stream &strm, uint32_t frame_idx);
 414
 415     //------------------------------------------------------------------
 416     /// Default implementation for stepping into.
 417     ///
 418     /// This function is designed to be used by commands where the
 419     /// process is publicly stopped.
 420     ///
 421     /// @param[in] source_step
 422     ///     If true and the frame has debug info, then do a source level
 423     ///     step in, else do a single instruction step in.
 424     ///
 425     /// @param[in] avoid_code_without_debug_info
 426     ///     If \a true, then avoid stepping into code that doesn't have
 427     ///     debug info, else step into any code regardless of wether it
 428     ///     has debug info.
 429     ///
 430     /// @return
 431     ///     An error that describes anything that went wrong
 432     //------------------------------------------------------------------
 433     virtual Error
 434     StepIn (bool source_step,
 435             bool avoid_code_without_debug_info);
 436
 437     //------------------------------------------------------------------
 438     /// Default implementation for stepping over.
 439     ///
 440     /// This function is designed to be used by commands where the
 441     /// process is publicly stopped.
 442     ///
 443     /// @param[in] source_step
 444     ///     If true and the frame has debug info, then do a source level
 445     ///     step over, else do a single instruction step over.
 446     ///
 447     /// @return
 448     ///     An error that describes anything that went wrong
 449     //------------------------------------------------------------------
 450     virtual Error
 451     StepOver (bool source_step);
 452
 453     //------------------------------------------------------------------
 454     /// Default implementation for stepping out.
 455     ///
 456     /// This function is designed to be used by commands where the
 457     /// process is publicly stopped.
 458     ///
 459     /// @return
 460     ///     An error that describes anything that went wrong
 461     //------------------------------------------------------------------
 462     virtual Error
 463     StepOut ();
 464     //------------------------------------------------------------------
 465     /// Retrieves the per-thread data area.
 466     /// Most OSs maintain a per-thread pointer (e.g. the FS register on
 467     /// x64), which we return the value of here.
 468     ///
 469     /// @return
 470     ///     LLDB_INVALID_ADDRESS if not supported, otherwise the thread
 471     ///     pointer value.
 472     //------------------------------------------------------------------
 473     virtual lldb::addr_t
 474     GetThreadPointer ();
 475
 476     //------------------------------------------------------------------
 477     /// Retrieves the per-module TLS block for a thread.
 478     ///
 479     /// @param[in] module
 480     ///     The module to query TLS data for.
 481     ///
 482     /// @return
 483     ///     If the thread has TLS data allocated for the
 484     ///     module, the address of the TLS block. Otherwise
 485     ///     LLDB_INVALID_ADDRESS is returned.
 486     //------------------------------------------------------------------
 487     virtual lldb::addr_t
 488     GetThreadLocalData (const lldb::ModuleSP module);
 489
 490
 491     //------------------------------------------------------------------
 492     // Thread Plan Providers:
 493     // This section provides the basic thread plans that the Process control
 494     // machinery uses to run the target.  ThreadPlan.h provides more details on
 495     // how this mechanism works.
 496     // The thread provides accessors to a set of plans that perform basic operations.
 497     // The idea is that particular Platform plugins can override these methods to
 498     // provide the implementation of these basic operations appropriate to their
 499     // environment.
 500     //
 501     // NB: All the QueueThreadPlanXXX providers return Shared Pointers to
 502     // Thread plans.  This is useful so that you can modify the plans after
 503     // creation in ways specific to that plan type.  Also, it is often necessary for
 504     // ThreadPlans that utilize other ThreadPlans to implement their task to keep a shared
 505     // pointer to the sub-plan.
 506     // But besides that, the shared pointers should only be held onto by entities who live no longer
 507     // than the thread containing the ThreadPlan.
 508     // FIXME: If this becomes a problem, we can make a version that just returns a pointer,
 509     // which it is clearly unsafe to hold onto, and a shared pointer version, and only allow
 510     // ThreadPlan and Co. to use the latter.  That is made more annoying to do because there's
 511     // no elegant way to friend a method to all sub-classes of a given class.
 512     //
 513     //------------------------------------------------------------------
 514
 515     //------------------------------------------------------------------
 516     /// Queues the base plan for a thread.
 517     /// The version returned by Process does some things that are useful,
 518     /// like handle breakpoints and signals, so if you return a plugin specific
 519     /// one you probably want to call through to the Process one for anything
 520     /// your plugin doesn't explicitly handle.
 521     ///
 522     /// @param[in] abort_other_plans
 523     ///    \b true if we discard the currently queued plans and replace them with this one.
 524     ///    Otherwise this plan will go on the end of the plan stack.
 525     ///
 526     /// @return
 527     ///     A shared pointer to the newly queued thread plan, or NULL if the plan could not be queued.
 528     //------------------------------------------------------------------
 529     virtual lldb::ThreadPlanSP
 530     QueueFundamentalPlan (bool abort_other_plans);
 531
 532     //------------------------------------------------------------------
 533     /// Queues the plan used to step one instruction from the current PC of \a thread.
 534     ///
 535     /// @param[in] step_over
 536     ///    \b true if we step over calls to functions, false if we step in.
 537     ///
 538     /// @param[in] abort_other_plans
 539     ///    \b true if we discard the currently queued plans and replace them with this one.
 540     ///    Otherwise this plan will go on the end of the plan stack.
 541     ///
 542     /// @param[in] stop_other_threads
 543     ///    \b true if we will stop other threads while we single step this one.
 544     ///
 545     /// @return
 546     ///     A shared pointer to the newly queued thread plan, or NULL if the plan could not be queued.
 547     //------------------------------------------------------------------
 548     virtual lldb::ThreadPlanSP
 549     QueueThreadPlanForStepSingleInstruction (bool step_over,
 550                                              bool abort_other_plans,
 551                                              bool stop_other_threads);
 552
 553     //------------------------------------------------------------------
 554     /// Queues the plan used to step through an address range, stepping  over
 555     /// function calls.
 556     ///
 557     /// @param[in] abort_other_plans
 558     ///    \b true if we discard the currently queued plans and replace them with this one.
 559     ///    Otherwise this plan will go on the end of the plan stack.
 560     ///
 561     /// @param[in] type
 562     ///    Type of step to do, only eStepTypeInto and eStepTypeOver are supported by this plan.
 563     ///
 564     /// @param[in] range
 565     ///    The address range to step through.
 566     ///
 567     /// @param[in] addr_context
 568     ///    When dealing with stepping through inlined functions the current PC is not enough information to know
 569     ///    what "step" means.  For instance a series of nested inline functions might start at the same address.
 570     //     The \a addr_context provides the current symbol context the step
 571     ///    is supposed to be out of.
 572     //   FIXME: Currently unused.
 573     ///
 574     /// @param[in] stop_other_threads
 575     ///    \b true if we will stop other threads while we single step this one.
 576     ///
 577     /// @return
 578     ///     A shared pointer to the newly queued thread plan, or NULL if the plan could not be queued.
 579     //------------------------------------------------------------------
 580     virtual lldb::ThreadPlanSP
 581     QueueThreadPlanForStepOverRange (bool abort_other_plans,
 582                                  const AddressRange &range,
 583                                  const SymbolContext &addr_context,
 584                                  lldb::RunMode stop_other_threads);
 585
 586     //------------------------------------------------------------------
 587     /// Queues the plan used to step through an address range, stepping into functions.
 588     ///
 589     /// @param[in] abort_other_plans
 590     ///    \b true if we discard the currently queued plans and replace them with this one.
 591     ///    Otherwise this plan will go on the end of the plan stack.
 592     ///
 593     /// @param[in] type
 594     ///    Type of step to do, only eStepTypeInto and eStepTypeOver are supported by this plan.
 595     ///
 596     /// @param[in] range
 597     ///    The address range to step through.
 598     ///
 599     /// @param[in] addr_context
 600     ///    When dealing with stepping through inlined functions the current PC is not enough information to know
 601     ///    what "step" means.  For instance a series of nested inline functions might start at the same address.
 602     //     The \a addr_context provides the current symbol context the step
 603     ///    is supposed to be out of.
 604     //   FIXME: Currently unused.
 605     ///
 606     /// @param[in] step_in_target
 607     ///    Name if function we are trying to step into.  We will step out if we don't land in that function.
 608     ///
 609     /// @param[in] stop_other_threads
 610     ///    \b true if we will stop other threads while we single step this one.
 611     ///
 612     /// @param[in] avoid_code_without_debug_info
 613     ///    If \b true we will step out if we step into code with no debug info.
 614     ///
 615     /// @return
 616     ///     A shared pointer to the newly queued thread plan, or NULL if the plan could not be queued.
 617     //------------------------------------------------------------------
 618     virtual lldb::ThreadPlanSP
 619     QueueThreadPlanForStepInRange (bool abort_other_plans,
 620                                  const AddressRange &range,
 621                                  const SymbolContext &addr_context,
 622                                  const char *step_in_target,
 623                                  lldb::RunMode stop_other_threads,
 624                                  bool avoid_code_without_debug_info);
 625
 626     //------------------------------------------------------------------
 627     /// Queue the plan used to step out of the function at the current PC of
 628     /// \a thread.
 629     ///
 630     /// @param[in] abort_other_plans
 631     ///    \b true if we discard the currently queued plans and replace them with this one.
 632     ///    Otherwise this plan will go on the end of the plan stack.
 633     ///
 634     /// @param[in] addr_context
 635     ///    When dealing with stepping through inlined functions the current PC is not enough information to know
 636     ///    what "step" means.  For instance a series of nested inline functions might start at the same address.
 637     //     The \a addr_context provides the current symbol context the step
 638     ///    is supposed to be out of.
 639     //   FIXME: Currently unused.
 640     ///
 641     /// @param[in] first_insn
 642     ///     \b true if this is the first instruction of a function.
 643     ///
 644     /// @param[in] stop_other_threads
 645     ///    \b true if we will stop other threads while we single step this one.
 646     ///
 647     /// @param[in] stop_vote
 648     /// @param[in] run_vote
 649     ///    See standard meanings for the stop & run votes in ThreadPlan.h.
 650     ///
 651     /// @return
 652     ///     A shared pointer to the newly queued thread plan, or NULL if the plan could not be queued.
 653     //------------------------------------------------------------------
 654     virtual lldb::ThreadPlanSP
 655     QueueThreadPlanForStepOut (bool abort_other_plans,
 656                                SymbolContext *addr_context,
 657                                bool first_insn,
 658                                bool stop_other_threads,
 659                                Vote stop_vote, // = eVoteYes,
 660                                Vote run_vote, // = eVoteNoOpinion);
 661                                uint32_t frame_idx);
 662
 663     //------------------------------------------------------------------
 664     /// Gets the plan used to step through the code that steps from a function
 665     /// call site at the current PC into the actual function call.
 666     ///
 667     ///
 668     /// @param[in] return_stack_id
 669     ///    The stack id that we will return to (by setting backstop breakpoints on the return
 670     ///    address to that frame) if we fail to step through.
 671     ///
 672     /// @param[in] abort_other_plans
 673     ///    \b true if we discard the currently queued plans and replace them with this one.
 674     ///    Otherwise this plan will go on the end of the plan stack.
 675     ///
 676     /// @param[in] stop_other_threads
 677     ///    \b true if we will stop other threads while we single step this one.
 678     ///
 679     /// @return
 680     ///     A shared pointer to the newly queued thread plan, or NULL if the plan could not be queued.
 681     //------------------------------------------------------------------
 682     virtual lldb::ThreadPlanSP
 683     QueueThreadPlanForStepThrough (StackID &return_stack_id,
 684                                    bool abort_other_plans,
 685                                    bool stop_other_threads);
 686
 687     //------------------------------------------------------------------
 688     /// Gets the plan used to continue from the current PC.
 689     /// This is a simple plan, mostly useful as a backstop when you are continuing
 690     /// for some particular purpose.
 691     ///
 692     /// @param[in] abort_other_plans
 693     ///    \b true if we discard the currently queued plans and replace them with this one.
 694     ///    Otherwise this plan will go on the end of the plan stack.
 695     ///
 696     /// @param[in] target_addr
 697     ///    The address to which we're running.
 698     ///
 699     /// @param[in] stop_other_threads
 700     ///    \b true if we will stop other threads while we single step this one.
 701     ///
 702     /// @return
 703     ///     A shared pointer to the newly queued thread plan, or NULL if the plan could not be queued.
 704     //------------------------------------------------------------------
 705     virtual lldb::ThreadPlanSP
 706     QueueThreadPlanForRunToAddress (bool abort_other_plans,
 707                                     Address &target_addr,
 708                                     bool stop_other_threads);
 709
 710     virtual lldb::ThreadPlanSP
 711     QueueThreadPlanForStepUntil (bool abort_other_plans,
 712                                  lldb::addr_t *address_list,
 713                                  size_t num_addresses,
 714                                  bool stop_others,
 715                                  uint32_t frame_idx);
 716
 717     //------------------------------------------------------------------
 718     // Thread Plan accessors:
 719     //------------------------------------------------------------------
 720
 721     //------------------------------------------------------------------
 722     /// Gets the plan which will execute next on the plan stack.
 723     ///
 724     /// @return
 725     ///     A pointer to the next executed plan.
 726     //------------------------------------------------------------------
 727     ThreadPlan *
 728     GetCurrentPlan ();
 729
 730     //------------------------------------------------------------------
 731     /// Unwinds the thread stack for the innermost expression plan currently
 732     /// on the thread plan stack.
 733     ///
 734     /// @return
 735     ///     An error if the thread plan could not be unwound.
 736     //------------------------------------------------------------------
 737
 738     Error
 739     UnwindInnermostExpression();
 740
 741 private:
 742     bool
 743     PlanIsBasePlan (ThreadPlan *plan_ptr);
 744
 745     void
 746     BroadcastSelectedFrameChange(StackID &new_frame_id);
 747
 748 public:
 749
 750     //------------------------------------------------------------------
 751     /// Gets the outer-most plan that was popped off the plan stack in the
 752     /// most recent stop.  Useful for printing the stop reason accurately.
 753     ///
 754     /// @return
 755     ///     A pointer to the last completed plan.
 756     //------------------------------------------------------------------
 757     lldb::ThreadPlanSP
 758     GetCompletedPlan ();
 759
 760     //------------------------------------------------------------------
 761     /// Gets the outer-most return value from the completed plans
 762     ///
 763     /// @return
 764     ///     A ValueObjectSP, either empty if there is no return value,
 765     ///     or containing the return value.
 766     //------------------------------------------------------------------
 767     lldb::ValueObjectSP
 768     GetReturnValueObject ();
 769
 770     //------------------------------------------------------------------
 771     ///  Checks whether the given plan is in the completed plans for this
 772     ///  stop.
 773     ///
 774     /// @param[in] plan
 775     ///     Pointer to the plan you're checking.
 776     ///
 777     /// @return
 778     ///     Returns true if the input plan is in the completed plan stack,
 779     ///     false otherwise.
 780     //------------------------------------------------------------------
 781     bool
 782     IsThreadPlanDone (ThreadPlan *plan);
 783
 784     //------------------------------------------------------------------
 785     ///  Checks whether the given plan is in the discarded plans for this
 786     ///  stop.
 787     ///
 788     /// @param[in] plan
 789     ///     Pointer to the plan you're checking.
 790     ///
 791     /// @return
 792     ///     Returns true if the input plan is in the discarded plan stack,
 793     ///     false otherwise.
 794     //------------------------------------------------------------------
 795     bool
 796     WasThreadPlanDiscarded (ThreadPlan *plan);
 797
 798     //------------------------------------------------------------------
 799     /// Queues a generic thread plan.
 800     ///
 801     /// @param[in] plan_sp
 802     ///    The plan to queue.
 803     ///
 804     /// @param[in] abort_other_plans
 805     ///    \b true if we discard the currently queued plans and replace them with this one.
 806     ///    Otherwise this plan will go on the end of the plan stack.
 807     ///
 808     /// @return
 809     ///     A pointer to the last completed plan.
 810     //------------------------------------------------------------------
 811     void
 812     QueueThreadPlan (lldb::ThreadPlanSP &plan_sp, bool abort_other_plans);
 813
 814
 815     //------------------------------------------------------------------
 816     /// Discards the plans queued on the plan stack of the current thread.  This is
 817     /// arbitrated by the "Master" ThreadPlans, using the "OkayToDiscard" call.
 818     //  But if \a force is true, all thread plans are discarded.
 819     //------------------------------------------------------------------
 820     void
 821     DiscardThreadPlans (bool force);
 822
 823     //------------------------------------------------------------------
 824     /// Discards the plans queued on the plan stack of the current thread up to and
 825     /// including up_to_plan_sp.
 826     //
 827     // @param[in] up_to_plan_sp
 828     //   Discard all plans up to and including this one.
 829     //------------------------------------------------------------------
 830     void
 831     DiscardThreadPlansUpToPlan (lldb::ThreadPlanSP &up_to_plan_sp);
 832
 833     void
 834     DiscardThreadPlansUpToPlan (ThreadPlan *up_to_plan_ptr);
 835
 836     //------------------------------------------------------------------
 837     /// Prints the current plan stack.
 838     ///
 839     /// @param[in] s
 840     ///    The stream to which to dump the plan stack info.
 841     ///
 842     //------------------------------------------------------------------
 843     void
 844     DumpThreadPlans (Stream *s) const;
 845
 846     virtual bool
 847     CheckpointThreadState (ThreadStateCheckpoint &saved_state);
 848
 849     virtual bool
 850     RestoreRegisterStateFromCheckpoint (ThreadStateCheckpoint &saved_state);
 851
 852     virtual bool
 853     RestoreThreadStateFromCheckpoint (ThreadStateCheckpoint &saved_state);
 854
 855     void
 856     EnableTracer (bool value, bool single_step);
 857
 858     void
 859     SetTracer (lldb::ThreadPlanTracerSP &tracer_sp);
 860
 861     //------------------------------------------------------------------
 862     // Get the thread index ID. The index ID that is guaranteed to not
 863     // be re-used by a process. They start at 1 and increase with each
 864     // new thread. This allows easy command line access by a unique ID
 865     // that is easier to type than the actual system thread ID.
 866     //------------------------------------------------------------------
 867     uint32_t
 868     GetIndexID () const;
 869
 870     //------------------------------------------------------------------
 871     // Get the originating thread's index ID.
 872     // In the case of an "extended" thread -- a thread which represents
 873     // the stack that enqueued/spawned work that is currently executing --
 874     // we need to provide the IndexID of the thread that actually did
 875     // this work.  We don't want to just masquerade as that thread's IndexID
 876     // by using it in our own IndexID because that way leads to madness -
 877     // but the driver program which is iterating over extended threads
 878     // may ask for the OriginatingThreadID to display that information
 879     // to the user.
 880     // Normal threads will return the same thing as GetIndexID();
 881     //------------------------------------------------------------------
 882     virtual uint32_t
 883     GetExtendedBacktraceOriginatingIndexID ()
 884     {
 885         return GetIndexID ();
 886     }
 887
 888     //------------------------------------------------------------------
 889     // The API ID is often the same as the Thread::GetID(), but not in
 890     // all cases. Thread::GetID() is the user visible thread ID that
 891     // clients would want to see. The API thread ID is the thread ID
 892     // that is used when sending data to/from the debugging protocol.
 893     //------------------------------------------------------------------
 894     virtual lldb::user_id_t
 895     GetProtocolID () const
 896     {
 897         return GetID();
 898     }
 899
 900     //------------------------------------------------------------------
 901     // lldb::ExecutionContextScope pure virtual functions
 902     //------------------------------------------------------------------
 903     virtual lldb::TargetSP
 904     CalculateTarget ();
 905
 906     virtual lldb::ProcessSP
 907     CalculateProcess ();
 908
 909     virtual lldb::ThreadSP
 910     CalculateThread ();
 911
 912     virtual lldb::StackFrameSP
 913     CalculateStackFrame ();
 914
 915     virtual void
 916     CalculateExecutionContext (ExecutionContext &exe_ctx);
 917
 918     lldb::StackFrameSP
 919     GetStackFrameSPForStackFramePtr (StackFrame *stack_frame_ptr);
 920
 921     size_t
 922     GetStatus (Stream &strm,
 923                uint32_t start_frame,
 924                uint32_t num_frames,
 925                uint32_t num_frames_with_source);
 926
 927     size_t
 928     GetStackFrameStatus (Stream& strm,
 929                          uint32_t first_frame,
 930                          uint32_t num_frames,
 931                          bool show_frame_info,
 932                          uint32_t num_frames_with_source);
 933
 934     // We need a way to verify that even though we have a thread in a shared
 935     // pointer that the object itself is still valid. Currently this won't be
 936     // the case if DestroyThread() was called. DestroyThread is called when
 937     // a thread has been removed from the Process' thread list.
 938     bool
 939     IsValid () const
 940     {
 941         return !m_destroy_called;
 942     }
 943
 944     // Sets and returns a valid stop info based on the process stop ID and the
 945     // current thread plan. If the thread stop ID does not match the process'
 946     // stop ID, the private stop reason is not set and an invalid StopInfoSP may
 947     // be returned.
 948     //
 949     // NOTE: This function must be called before the current thread plan is
 950     // moved to the completed plan stack (in Thread::ShouldStop()).
 951     //
 952     // NOTE: If subclasses override this function, ensure they do not overwrite
 953     // the m_actual_stop_info if it is valid.  The stop info may be a
 954     // "checkpointed and restored" stop info, so if it is still around it is
 955     // right even if you have not calculated this yourself, or if it disagrees
 956     // with what you might have calculated.
 957     virtual lldb::StopInfoSP
 958     GetPrivateStopInfo ();
 959
 960     //----------------------------------------------------------------------
 961     // Ask the thread subclass to set its stop info.
 962     //
 963     // Thread subclasses should call Thread::SetStopInfo(...) with the
 964     // reason the thread stopped.
 965     //
 966     // @return
 967     //      True if Thread::SetStopInfo(...) was called, false otherwise.
 968     //----------------------------------------------------------------------
 969     virtual bool
 970     CalculateStopInfo () = 0;
 971
 972     //----------------------------------------------------------------------
 973     // Gets the temporary resume state for a thread.
 974     //
 975     // This value gets set in each thread by complex debugger logic in
 976     // Thread::ShouldResume() and an appropriate thread resume state will get
 977     // set in each thread every time the process is resumed prior to calling
 978     // Process::DoResume(). The lldb_private::Process subclass should adhere
 979     // to the thread resume state request which will be one of:
 980     //
 981     //  eStateRunning   - thread will resume when process is resumed
 982     //  eStateStepping  - thread should step 1 instruction and stop when process
 983     //                    is resumed
 984     //  eStateSuspended - thread should not execute any instructions when
 985     //                    process is resumed
 986     //----------------------------------------------------------------------
 987     lldb::StateType
 988     GetTemporaryResumeState() const
 989     {
 990         return m_temporary_resume_state;
 991     }
 992
 993     void
 994     SetStopInfo (const lldb::StopInfoSP &stop_info_sp);
 995
 996     void
 997     SetShouldReportStop (Vote vote);
 998
 999     //----------------------------------------------------------------------
1000     /// Sets the extended backtrace token for this thread
1001     ///
1002     /// Some Thread subclasses may maintain a token to help with providing
1003     /// an extended backtrace.  The SystemRuntime plugin will set/request this.
1004     ///
1005     /// @param [in] token
1006     //----------------------------------------------------------------------
1007     virtual void
1008     SetExtendedBacktraceToken (uint64_t token) { }
1009
1010     //----------------------------------------------------------------------
1011     /// Gets the extended backtrace token for this thread
1012     ///
1013     /// Some Thread subclasses may maintain a token to help with providing
1014     /// an extended backtrace.  The SystemRuntime plugin will set/request this.
1015     ///
1016     /// @return
1017     ///     The token needed by the SystemRuntime to create an extended backtrace.
1018     ///     LLDB_INVALID_ADDRESS is returned if no token is available.
1019     //----------------------------------------------------------------------
1020     virtual uint64_t
1021     GetExtendedBacktraceToken ()
1022     {
1023         return LLDB_INVALID_ADDRESS;
1024     }
1025
1026 protected:
1027
1028     friend class ThreadPlan;
1029     friend class ThreadList;
1030     friend class ThreadEventData;
1031     friend class StackFrameList;
1032     friend class StackFrame;
1033     friend class OperatingSystem;
1034
1035     // This is necessary to make sure thread assets get destroyed while the thread is still in good shape
1036     // to call virtual thread methods.  This must be called by classes that derive from Thread in their destructor.
1037     virtual void DestroyThread ();
1038
1039     void
1040     PushPlan (lldb::ThreadPlanSP &plan_sp);
1041
1042     void
1043     PopPlan ();
1044
1045     void
1046     DiscardPlan ();
1047
1048     ThreadPlan *GetPreviousPlan (ThreadPlan *plan);
1049
1050     typedef std::vector<lldb::ThreadPlanSP> plan_stack;
1051
1052     virtual lldb_private::Unwind *
1053     GetUnwinder ();
1054
1055     // Check to see whether the thread is still at the last breakpoint hit that stopped it.
1056     virtual bool
1057     IsStillAtLastBreakpointHit();
1058
1059     // Some threads are threads that are made up by OperatingSystem plugins that
1060     // are threads that exist and are context switched out into memory. The
1061     // OperatingSystem plug-in need a ways to know if a thread is "real" or made
1062     // up.
1063     virtual bool
1064     IsOperatingSystemPluginThread () const
1065     {
1066         return false;
1067     }
1068
1069
1070     lldb::StackFrameListSP
1071     GetStackFrameList ();
1072
1073
1074     //------------------------------------------------------------------
1075     // Classes that inherit from Process can see and modify these
1076     //------------------------------------------------------------------
1077     lldb::ProcessWP     m_process_wp;           ///< The process that owns this thread.
1078     lldb::StopInfoSP    m_stop_info_sp;         ///< The private stop reason for this thread
1079     uint32_t            m_stop_info_stop_id;    // This is the stop id for which the StopInfo is valid.  Can use this so you know that
1080     // the thread's m_stop_info_sp is current and you don't have to fetch it again
1081     const uint32_t      m_index_id;             ///< A unique 1 based index assigned to each thread for easy UI/command line access.
1082     lldb::RegisterContextSP m_reg_context_sp;   ///< The register context for this thread's current register state.
1083     lldb::StateType     m_state;                ///< The state of our process.
1084     mutable Mutex       m_state_mutex;          ///< Multithreaded protection for m_state.
1085     plan_stack          m_plan_stack;           ///< The stack of plans this thread is executing.
1086     plan_stack          m_completed_plan_stack; ///< Plans that have been completed by this stop.  They get deleted when the thread resumes.
1087     plan_stack          m_discarded_plan_stack; ///< Plans that have been discarded by this stop.  They get deleted when the thread resumes.
1088     mutable Mutex       m_frame_mutex;          ///< Multithreaded protection for m_state.
1089     lldb::StackFrameListSP m_curr_frames_sp;    ///< The stack frames that get lazily populated after a thread stops.
1090     lldb::StackFrameListSP m_prev_frames_sp;    ///< The previous stack frames from the last time this thread stopped.
1091     int                 m_resume_signal;        ///< The signal that should be used when continuing this thread.
1092     lldb::StateType     m_resume_state;         ///< This state is used to force a thread to be suspended from outside the ThreadPlan logic.
1093     lldb::StateType     m_temporary_resume_state; ///< This state records what the thread was told to do by the thread plan logic for the current resume.
1094                                                   /// It gets set in Thread::ShoudResume.
1095     std::unique_ptr<lldb_private::Unwind> m_unwinder_ap;
1096     bool                m_destroy_called;       // This is used internally to make sure derived Thread classes call DestroyThread.
1097     LazyBool            m_override_should_notify;
1098 private:
1099     //------------------------------------------------------------------
1100     // For Thread only
1101     //------------------------------------------------------------------
1102
1103     DISALLOW_COPY_AND_ASSIGN (Thread);
1104
1105 };
1106
1107 } // namespace lldb_private
1108
1109 #endif  // liblldb_Thread_h_