1 //===-- Thread.h ------------------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_Thread_h_
11 #define liblldb_Thread_h_
20 // Other libraries and framework includes
22 #include "lldb/lldb-private.h"
23 #include "lldb/Core/Broadcaster.h"
24 #include "lldb/Core/Event.h"
25 #include "lldb/Core/StructuredData.h"
26 #include "lldb/Core/UserID.h"
27 #include "lldb/Core/UserSettingsController.h"
28 #include "lldb/Target/ExecutionContextScope.h"
29 #include "lldb/Target/RegisterCheckpoint.h"
30 #include "lldb/Target/StackFrameList.h"
32 #define LLDB_THREAD_MAX_STOP_EXC_DATA 8
34 namespace lldb_private {
36 class ThreadProperties : public Properties
39 ThreadProperties(bool is_global);
41 ~ThreadProperties() override;
43 //------------------------------------------------------------------
44 /// The regular expression returned determines symbols that this
45 /// thread won't stop in during "step-in" operations.
48 /// A pointer to a regular expression to compare against symbols,
49 /// or nullptr if all symbols are allowed.
51 //------------------------------------------------------------------
52 const RegularExpression *
53 GetSymbolsToAvoidRegexp();
56 GetLibrariesToAvoid() const;
59 GetTraceEnabledState() const;
62 GetStepInAvoidsNoDebug () const;
65 GetStepOutAvoidsNoDebug () const;
68 typedef std::shared_ptr<ThreadProperties> ThreadPropertiesSP;
71 public std::enable_shared_from_this<Thread>,
72 public ThreadProperties,
74 public ExecutionContextScope,
78 //------------------------------------------------------------------
79 /// Broadcaster event bits definitions.
80 //------------------------------------------------------------------
83 eBroadcastBitStackChanged = (1 << 0),
84 eBroadcastBitThreadSuspended = (1 << 1),
85 eBroadcastBitThreadResumed = (1 << 2),
86 eBroadcastBitSelectedFrameChanged = (1 << 3),
87 eBroadcastBitThreadSelected = (1 << 4)
90 static ConstString &GetStaticBroadcasterClass ();
92 ConstString &GetBroadcasterClass() const override
94 return GetStaticBroadcasterClass();
97 class ThreadEventData :
101 ThreadEventData (const lldb::ThreadSP thread_sp);
103 ThreadEventData (const lldb::ThreadSP thread_sp, const StackID &stack_id);
107 ~ThreadEventData() override;
109 static const ConstString &
113 GetFlavor() const override
115 return ThreadEventData::GetFlavorString ();
119 Dump(Stream *s) const override;
121 static const ThreadEventData *
122 GetEventDataFromEvent (const Event *event_ptr);
124 static lldb::ThreadSP
125 GetThreadFromEvent (const Event *event_ptr);
128 GetStackIDFromEvent (const Event *event_ptr);
130 static lldb::StackFrameSP
131 GetStackFrameFromEvent (const Event *event_ptr);
146 lldb::ThreadSP m_thread_sp;
149 DISALLOW_COPY_AND_ASSIGN (ThreadEventData);
152 struct ThreadStateCheckpoint
154 uint32_t orig_stop_id; // Dunno if I need this yet but it is an interesting bit of data.
155 lldb::StopInfoSP stop_info_sp; // You have to restore the stop info or you might continue with the wrong signals.
156 lldb::RegisterCheckpointSP register_backup_sp; // You need to restore the registers, of course...
157 uint32_t current_inlined_depth;
158 lldb::addr_t current_inlined_pc;
161 //------------------------------------------------------------------
164 /// @param [in] process
168 /// @param [in] use_invalid_index_id
169 /// Optional parameter, defaults to false. The only subclass that
170 /// is likely to set use_invalid_index_id == true is the HistoryThread
171 /// class. In that case, the Thread we are constructing represents
172 /// a thread from earlier in the program execution. We may have the
173 /// tid of the original thread that they represent but we don't want
174 /// to reuse the IndexID of that thread, or create a new one. If a
175 /// client wants to know the original thread's IndexID, they should use
176 /// Thread::GetExtendedBacktraceOriginatingIndexID().
177 //------------------------------------------------------------------
178 Thread (Process &process, lldb::tid_t tid, bool use_invalid_index_id = false);
183 SettingsInitialize ();
186 SettingsTerminate ();
188 static const ThreadPropertiesSP &
189 GetGlobalProperties();
194 return m_process_wp.lock();
198 GetResumeSignal () const
200 return m_resume_signal;
204 SetResumeSignal (int signal)
206 m_resume_signal = signal;
213 SetState (lldb::StateType state);
215 //------------------------------------------------------------------
216 /// Sets the USER resume state for this thread. If you set a thread to suspended with
217 /// this API, it won't take part in any of the arbitration for ShouldResume, and will stay
218 /// suspended even when other threads do get to run.
220 /// N.B. This is not the state that is used internally by thread plans to implement
221 /// staying on one thread while stepping over a breakpoint, etc. The is the
222 /// TemporaryResume state, and if you are implementing some bit of strategy in the stepping
223 /// machinery you should be using that state and not the user resume state.
225 /// If you are just preparing all threads to run, you should not override the threads that are
226 /// marked as suspended by the debugger. In that case, pass override_suspend = false. If you want
227 /// to force the thread to run (e.g. the "thread continue" command, or are resetting the state
228 /// (e.g. in SBThread::Resume()), then pass true to override_suspend.
230 /// The User resume state for this thread.
231 //------------------------------------------------------------------
233 SetResumeState (lldb::StateType state, bool override_suspend = false)
235 if (m_resume_state == lldb::eStateSuspended && !override_suspend)
237 m_resume_state = state;
240 //------------------------------------------------------------------
241 /// Gets the USER resume state for this thread. This is not the same as what
242 /// this thread is going to do for any particular step, however if this thread
243 /// returns eStateSuspended, then the process control logic will never allow this
247 /// The User resume state for this thread.
248 //------------------------------------------------------------------
250 GetResumeState () const
252 return m_resume_state;
255 // This function is called on all the threads before "ShouldResume" and
256 // "WillResume" in case a thread needs to change its state before the
257 // ThreadList polls all the threads to figure out which ones actually
258 // will get to run and how.
262 // Do not override this function, it is for thread plan logic only
264 ShouldResume (lldb::StateType resume_state);
266 // Override this to do platform specific tasks before resume.
268 WillResume (lldb::StateType resume_state)
272 // This clears generic thread state after a resume. If you subclass this,
273 // be sure to call it.
277 // This notifies the thread when a private stop occurs.
282 RefreshStateAfterStop() = 0;
288 ShouldStop (Event *event_ptr);
291 ShouldReportStop (Event *event_ptr);
294 ShouldReportRun (Event *event_ptr);
299 // Return whether this thread matches the specification in ThreadSpec. This is a virtual
300 // method because at some point we may extend the thread spec with a platform specific
301 // dictionary of attributes, which then only the platform specific Thread implementation
302 // would know how to match. For now, this just calls through to the ThreadSpec's
303 // ThreadPassesBasicTests method.
305 MatchesSpec (const ThreadSpec *spec);
314 StopInfoIsUpToDate() const;
316 // This sets the stop reason to a "blank" stop reason, so you can call functions on the thread
317 // without having the called function run with whatever stop reason you stopped with.
319 SetStopInfoToNothing();
322 ThreadStoppedForAReason ();
325 RunModeAsCString (lldb::RunMode mode);
328 StopReasonAsCString (lldb::StopReason reason);
336 //------------------------------------------------------------------
337 /// Retrieve a dictionary of information about this thread
339 /// On Mac OS X systems there may be voucher information.
340 /// The top level dictionary returned will have an "activity" key and the
341 /// value of the activity is a dictionary. Keys in that dictionary will
342 /// be "name" and "id", among others.
343 /// There may also be "trace_messages" (an array) with each entry in that array
344 /// being a dictionary (keys include "message" with the text of the trace
346 //------------------------------------------------------------------
347 StructuredData::ObjectSP
350 if (m_extended_info_fetched == false)
352 m_extended_info = FetchThreadExtendedInfo ();
353 m_extended_info_fetched = true;
355 return m_extended_info;
365 SetName (const char *name)
369 //------------------------------------------------------------------
370 /// Whether this thread can be associated with a libdispatch queue
372 /// The Thread may know if it is associated with a libdispatch queue,
373 /// it may know definitively that it is NOT associated with a libdispatch
374 /// queue, or it may be unknown whether it is associated with a libdispatch
378 /// eLazyBoolNo if this thread is definitely not associated with a
379 /// libdispatch queue (e.g. on a non-Darwin system where GCD aka
380 /// libdispatch is not available).
382 /// eLazyBoolYes this thread is associated with a libdispatch queue.
384 /// eLazyBoolCalculate this thread may be associated with a libdispatch
385 /// queue but the thread doesn't know one way or the other.
386 //------------------------------------------------------------------
387 virtual lldb_private::LazyBool
388 GetAssociatedWithLibdispatchQueue ()
394 SetAssociatedWithLibdispatchQueue (lldb_private::LazyBool associated_with_libdispatch_queue)
398 //------------------------------------------------------------------
399 /// Retrieve the Queue ID for the queue currently using this Thread
401 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
402 /// retrieve the QueueID.
404 /// This is a unique identifier for the libdispatch/GCD queue in a
405 /// process. Often starting at 1 for the initial system-created
406 /// queues and incrementing, a QueueID will not be reused for a
407 /// different queue during the lifetime of a proces.
410 /// A QueueID if the Thread subclass implements this, else
411 /// LLDB_INVALID_QUEUE_ID.
412 //------------------------------------------------------------------
413 virtual lldb::queue_id_t
416 return LLDB_INVALID_QUEUE_ID;
420 SetQueueID (lldb::queue_id_t new_val)
424 //------------------------------------------------------------------
425 /// Retrieve the Queue name for the queue currently using this Thread
427 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
428 /// retrieve the Queue name.
431 /// The Queue name, if the Thread subclass implements this, else
433 //------------------------------------------------------------------
441 SetQueueName (const char *name)
445 //------------------------------------------------------------------
446 /// Retrieve the Queue kind for the queue currently using this Thread
448 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
449 /// retrieve the Queue kind - either eQueueKindSerial or
450 /// eQueueKindConcurrent, indicating that this queue processes work
451 /// items serially or concurrently.
454 /// The Queue kind, if the Thread subclass implements this, else
455 /// eQueueKindUnknown.
456 //------------------------------------------------------------------
457 virtual lldb::QueueKind
460 return lldb::eQueueKindUnknown;
464 SetQueueKind (lldb::QueueKind kind)
468 //------------------------------------------------------------------
469 /// Retrieve the Queue for this thread, if any.
472 /// A QueueSP for the queue that is currently associated with this
474 /// An empty shared pointer indicates that this thread is not
475 /// associated with a queue, or libdispatch queues are not
476 /// supported on this target.
477 //------------------------------------------------------------------
478 virtual lldb::QueueSP
481 return lldb::QueueSP();
484 //------------------------------------------------------------------
485 /// Retrieve the address of the libdispatch_queue_t struct for queue
486 /// currently using this Thread
488 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
489 /// retrieve the address of the libdispatch_queue_t structure describing
492 /// This address may be reused for different queues later in the Process
493 /// lifetime and should not be used to identify a queue uniquely. Use
494 /// the GetQueueID() call for that.
497 /// The Queue's libdispatch_queue_t address if the Thread subclass
498 /// implements this, else LLDB_INVALID_ADDRESS.
499 //------------------------------------------------------------------
501 GetQueueLibdispatchQueueAddress ()
503 return LLDB_INVALID_ADDRESS;
507 SetQueueLibdispatchQueueAddress (lldb::addr_t dispatch_queue_t)
511 //------------------------------------------------------------------
512 /// Whether this Thread already has all the Queue information cached or not
514 /// A Thread may be associated with a libdispatch work Queue at a given
515 /// public stop event. If so, the thread can satisify requests like
516 /// GetQueueLibdispatchQueueAddress, GetQueueKind, GetQueueName, and GetQueueID
517 /// either from information from the remote debug stub when it is initially
518 /// created, or it can query the SystemRuntime for that information.
520 /// This method allows the SystemRuntime to discover if a thread has this
521 /// information already, instead of calling the thread to get the information
522 /// and having the thread call the SystemRuntime again.
523 //------------------------------------------------------------------
525 ThreadHasQueueInformation () const
533 return GetStackFrameList()->GetNumFrames();
536 virtual lldb::StackFrameSP
537 GetStackFrameAtIndex (uint32_t idx)
539 return GetStackFrameList()->GetFrameAtIndex(idx);
542 virtual lldb::StackFrameSP
543 GetFrameWithConcreteFrameIndex (uint32_t unwind_idx);
546 DecrementCurrentInlinedDepth()
548 return GetStackFrameList()->DecrementCurrentInlinedDepth();
552 GetCurrentInlinedDepth()
554 return GetStackFrameList()->GetCurrentInlinedDepth();
558 ReturnFromFrameWithIndex (uint32_t frame_idx, lldb::ValueObjectSP return_value_sp, bool broadcast = false);
561 ReturnFromFrame (lldb::StackFrameSP frame_sp, lldb::ValueObjectSP return_value_sp, bool broadcast = false);
564 JumpToLine(const FileSpec &file, uint32_t line, bool can_leave_function, std::string *warnings = nullptr);
566 virtual lldb::StackFrameSP
567 GetFrameWithStackID (const StackID &stack_id)
569 if (stack_id.IsValid())
570 return GetStackFrameList()->GetFrameWithStackID (stack_id);
571 return lldb::StackFrameSP();
575 GetSelectedFrameIndex ()
577 return GetStackFrameList()->GetSelectedFrameIndex();
584 SetSelectedFrame (lldb_private::StackFrame *frame, bool broadcast = false);
587 SetSelectedFrameByIndex (uint32_t frame_idx, bool broadcast = false);
590 SetSelectedFrameByIndexNoisily (uint32_t frame_idx, Stream &output_stream);
593 SetDefaultFileAndLineToSelectedFrame()
595 GetStackFrameList()->SetDefaultFileAndLineToSelectedFrame();
598 virtual lldb::RegisterContextSP
599 GetRegisterContext () = 0;
601 virtual lldb::RegisterContextSP
602 CreateRegisterContextForFrame (StackFrame *frame) = 0;
608 SetBackingThread (const lldb::ThreadSP &thread_sp)
613 virtual lldb::ThreadSP
614 GetBackingThread () const
616 return lldb::ThreadSP();
620 ClearBackingThread ()
622 // Subclasses can use this function if a thread is actually backed by
623 // another thread. This is currently used for the OperatingSystem plug-ins
624 // where they might have a thread that is in memory, yet its registers
625 // are available through the lldb_private::Thread subclass for the current
626 // lldb_private::Process class. Since each time the process stops the backing
627 // threads for memory threads can change, we need a way to clear the backing
628 // thread for all memory threads each time we stop.
632 DumpUsingSettingsFormat (Stream &strm, uint32_t frame_idx);
635 GetDescription (Stream &s, lldb::DescriptionLevel level, bool print_json_thread, bool print_json_stopinfo);
637 //------------------------------------------------------------------
638 /// Default implementation for stepping into.
640 /// This function is designed to be used by commands where the
641 /// process is publicly stopped.
643 /// @param[in] source_step
644 /// If true and the frame has debug info, then do a source level
645 /// step in, else do a single instruction step in.
647 /// @param[in] step_in_avoids_code_without_debug_info
648 /// If \a true, then avoid stepping into code that doesn't have
649 /// debug info, else step into any code regardless of whether it
652 /// @param[in] step_out_avoids_code_without_debug_info
653 /// If \a true, then if you step out to code with no debug info, keep
654 /// stepping out till you get to code with debug info.
657 /// An error that describes anything that went wrong
658 //------------------------------------------------------------------
660 StepIn (bool source_step,
661 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
662 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
664 //------------------------------------------------------------------
665 /// Default implementation for stepping over.
667 /// This function is designed to be used by commands where the
668 /// process is publicly stopped.
670 /// @param[in] source_step
671 /// If true and the frame has debug info, then do a source level
672 /// step over, else do a single instruction step over.
675 /// An error that describes anything that went wrong
676 //------------------------------------------------------------------
678 StepOver (bool source_step,
679 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
681 //------------------------------------------------------------------
682 /// Default implementation for stepping out.
684 /// This function is designed to be used by commands where the
685 /// process is publicly stopped.
688 /// An error that describes anything that went wrong
689 //------------------------------------------------------------------
693 //------------------------------------------------------------------
694 /// Retrieves the per-thread data area.
695 /// Most OSs maintain a per-thread pointer (e.g. the FS register on
696 /// x64), which we return the value of here.
699 /// LLDB_INVALID_ADDRESS if not supported, otherwise the thread
701 //------------------------------------------------------------------
705 //------------------------------------------------------------------
706 /// Retrieves the per-module TLS block for a thread.
708 /// @param[in] module
709 /// The module to query TLS data for.
711 /// @param[in] tls_file_addr
712 /// The thread local address in module
714 /// If the thread has TLS data allocated for the
715 /// module, the address of the TLS block. Otherwise
716 /// LLDB_INVALID_ADDRESS is returned.
717 //------------------------------------------------------------------
719 GetThreadLocalData(const lldb::ModuleSP module, lldb::addr_t tls_file_addr);
721 //------------------------------------------------------------------
722 /// Check whether this thread is safe to run functions
724 /// The SystemRuntime may know of certain thread states (functions in
725 /// process of execution, for instance) which can make it unsafe for
726 /// functions to be called.
729 /// True if it is safe to call functions on this thread.
730 /// False if function calls should be avoided on this thread.
731 //------------------------------------------------------------------
733 SafeToCallFunctions ();
735 //------------------------------------------------------------------
736 // Thread Plan Providers:
737 // This section provides the basic thread plans that the Process control
738 // machinery uses to run the target. ThreadPlan.h provides more details on
739 // how this mechanism works.
740 // The thread provides accessors to a set of plans that perform basic operations.
741 // The idea is that particular Platform plugins can override these methods to
742 // provide the implementation of these basic operations appropriate to their
745 // NB: All the QueueThreadPlanXXX providers return Shared Pointers to
746 // Thread plans. This is useful so that you can modify the plans after
747 // creation in ways specific to that plan type. Also, it is often necessary for
748 // ThreadPlans that utilize other ThreadPlans to implement their task to keep a shared
749 // pointer to the sub-plan.
750 // But besides that, the shared pointers should only be held onto by entities who live no longer
751 // than the thread containing the ThreadPlan.
752 // FIXME: If this becomes a problem, we can make a version that just returns a pointer,
753 // which it is clearly unsafe to hold onto, and a shared pointer version, and only allow
754 // ThreadPlan and Co. to use the latter. That is made more annoying to do because there's
755 // no elegant way to friend a method to all sub-classes of a given class.
757 //------------------------------------------------------------------
759 //------------------------------------------------------------------
760 /// Queues the base plan for a thread.
761 /// The version returned by Process does some things that are useful,
762 /// like handle breakpoints and signals, so if you return a plugin specific
763 /// one you probably want to call through to the Process one for anything
764 /// your plugin doesn't explicitly handle.
766 /// @param[in] abort_other_plans
767 /// \b true if we discard the currently queued plans and replace them with this one.
768 /// Otherwise this plan will go on the end of the plan stack.
771 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
772 //------------------------------------------------------------------
773 virtual lldb::ThreadPlanSP
774 QueueFundamentalPlan (bool abort_other_plans);
776 //------------------------------------------------------------------
777 /// Queues the plan used to step one instruction from the current PC of \a thread.
779 /// @param[in] step_over
780 /// \b true if we step over calls to functions, false if we step in.
782 /// @param[in] abort_other_plans
783 /// \b true if we discard the currently queued plans and replace them with this one.
784 /// Otherwise this plan will go on the end of the plan stack.
786 /// @param[in] stop_other_threads
787 /// \b true if we will stop other threads while we single step this one.
790 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
791 //------------------------------------------------------------------
792 virtual lldb::ThreadPlanSP
793 QueueThreadPlanForStepSingleInstruction (bool step_over,
794 bool abort_other_plans,
795 bool stop_other_threads);
797 //------------------------------------------------------------------
798 /// Queues the plan used to step through an address range, stepping over
801 /// @param[in] abort_other_plans
802 /// \b true if we discard the currently queued plans and replace them with this one.
803 /// Otherwise this plan will go on the end of the plan stack.
806 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported by this plan.
809 /// The address range to step through.
811 /// @param[in] addr_context
812 /// When dealing with stepping through inlined functions the current PC is not enough information to know
813 /// what "step" means. For instance a series of nested inline functions might start at the same address.
814 // The \a addr_context provides the current symbol context the step
815 /// is supposed to be out of.
816 // FIXME: Currently unused.
818 /// @param[in] stop_other_threads
819 /// \b true if we will stop other threads while we single step this one.
821 /// @param[in] step_out_avoids_code_without_debug_info
822 /// If eLazyBoolYes, if the step over steps out it will continue to step out till it comes to a frame with debug info.
823 /// If eLazyBoolCalculate, we will consult the default set in the thread.
826 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
827 //------------------------------------------------------------------
828 virtual lldb::ThreadPlanSP
829 QueueThreadPlanForStepOverRange (bool abort_other_plans,
830 const AddressRange &range,
831 const SymbolContext &addr_context,
832 lldb::RunMode stop_other_threads,
833 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
835 // Helper function that takes a LineEntry to step, insted of an AddressRange. This may combine multiple
836 // LineEntries of the same source line number to step over a longer address range in a single operation.
837 virtual lldb::ThreadPlanSP
838 QueueThreadPlanForStepOverRange (bool abort_other_plans,
839 const LineEntry &line_entry,
840 const SymbolContext &addr_context,
841 lldb::RunMode stop_other_threads,
842 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
844 //------------------------------------------------------------------
845 /// Queues the plan used to step through an address range, stepping into functions.
847 /// @param[in] abort_other_plans
848 /// \b true if we discard the currently queued plans and replace them with this one.
849 /// Otherwise this plan will go on the end of the plan stack.
852 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported by this plan.
855 /// The address range to step through.
857 /// @param[in] addr_context
858 /// When dealing with stepping through inlined functions the current PC is not enough information to know
859 /// what "step" means. For instance a series of nested inline functions might start at the same address.
860 // The \a addr_context provides the current symbol context the step
861 /// is supposed to be out of.
862 // FIXME: Currently unused.
864 /// @param[in] step_in_target
865 /// Name if function we are trying to step into. We will step out if we don't land in that function.
867 /// @param[in] stop_other_threads
868 /// \b true if we will stop other threads while we single step this one.
870 /// @param[in] step_in_avoids_code_without_debug_info
871 /// If eLazyBoolYes we will step out if we step into code with no debug info.
872 /// If eLazyBoolCalculate we will consult the default set in the thread.
874 /// @param[in] step_out_avoids_code_without_debug_info
875 /// If eLazyBoolYes, if the step over steps out it will continue to step out till it comes to a frame with debug info.
876 /// If eLazyBoolCalculate, it will consult the default set in the thread.
879 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
880 //------------------------------------------------------------------
881 virtual lldb::ThreadPlanSP
882 QueueThreadPlanForStepInRange (bool abort_other_plans,
883 const AddressRange &range,
884 const SymbolContext &addr_context,
885 const char *step_in_target,
886 lldb::RunMode stop_other_threads,
887 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
888 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
890 // Helper function that takes a LineEntry to step, insted of an AddressRange. This may combine multiple
891 // LineEntries of the same source line number to step over a longer address range in a single operation.
892 virtual lldb::ThreadPlanSP
893 QueueThreadPlanForStepInRange (bool abort_other_plans,
894 const LineEntry &line_entry,
895 const SymbolContext &addr_context,
896 const char *step_in_target,
897 lldb::RunMode stop_other_threads,
898 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
899 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
901 //------------------------------------------------------------------
902 /// Queue the plan used to step out of the function at the current PC of
905 /// @param[in] abort_other_plans
906 /// \b true if we discard the currently queued plans and replace them with this one.
907 /// Otherwise this plan will go on the end of the plan stack.
909 /// @param[in] addr_context
910 /// When dealing with stepping through inlined functions the current PC is not enough information to know
911 /// what "step" means. For instance a series of nested inline functions might start at the same address.
912 // The \a addr_context provides the current symbol context the step
913 /// is supposed to be out of.
914 // FIXME: Currently unused.
916 /// @param[in] first_insn
917 /// \b true if this is the first instruction of a function.
919 /// @param[in] stop_other_threads
920 /// \b true if we will stop other threads while we single step this one.
922 /// @param[in] stop_vote
923 /// @param[in] run_vote
924 /// See standard meanings for the stop & run votes in ThreadPlan.h.
926 /// @param[in] step_out_avoids_code_without_debug_info
927 /// If eLazyBoolYes, if the step over steps out it will continue to step out till it comes to a frame with debug info.
928 /// If eLazyBoolCalculate, it will consult the default set in the thread.
931 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
932 //------------------------------------------------------------------
933 virtual lldb::ThreadPlanSP
934 QueueThreadPlanForStepOut (bool abort_other_plans,
935 SymbolContext *addr_context,
937 bool stop_other_threads,
938 Vote stop_vote, // = eVoteYes,
939 Vote run_vote, // = eVoteNoOpinion);
941 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
943 //------------------------------------------------------------------
944 /// Queue the plan used to step out of the function at the current PC of
945 /// a thread. This version does not consult the should stop here callback, and should only
946 /// be used by other thread plans when they need to retain control of the step out.
948 /// @param[in] abort_other_plans
949 /// \b true if we discard the currently queued plans and replace them with this one.
950 /// Otherwise this plan will go on the end of the plan stack.
952 /// @param[in] addr_context
953 /// When dealing with stepping through inlined functions the current PC is not enough information to know
954 /// what "step" means. For instance a series of nested inline functions might start at the same address.
955 // The \a addr_context provides the current symbol context the step
956 /// is supposed to be out of.
957 // FIXME: Currently unused.
959 /// @param[in] first_insn
960 /// \b true if this is the first instruction of a function.
962 /// @param[in] stop_other_threads
963 /// \b true if we will stop other threads while we single step this one.
965 /// @param[in] stop_vote
966 /// @param[in] run_vote
967 /// See standard meanings for the stop & run votes in ThreadPlan.h.
969 /// @param[in] continue_to_next_branch
970 /// Normally this will enqueue a plan that will put a breakpoint on the return address and continue
971 /// to there. If continue_to_next_branch is true, this is an operation not involving the user --
972 /// e.g. stepping "next" in a source line and we instruction stepped into another function --
973 /// so instead of putting a breakpoint on the return address, advance the breakpoint to the
974 /// end of the source line that is doing the call, or until the next flow control instruction.
975 /// If the return value from the function call is to be retrieved / displayed to the user, you must stop
976 /// on the return address. The return value may be stored in volatile registers which are overwritten
977 /// before the next branch instruction.
980 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
981 //------------------------------------------------------------------
982 virtual lldb::ThreadPlanSP
983 QueueThreadPlanForStepOutNoShouldStop (bool abort_other_plans,
984 SymbolContext *addr_context,
986 bool stop_other_threads,
987 Vote stop_vote, // = eVoteYes,
988 Vote run_vote, // = eVoteNoOpinion);
990 bool continue_to_next_branch = false);
992 //------------------------------------------------------------------
993 /// Gets the plan used to step through the code that steps from a function
994 /// call site at the current PC into the actual function call.
997 /// @param[in] return_stack_id
998 /// The stack id that we will return to (by setting backstop breakpoints on the return
999 /// address to that frame) if we fail to step through.
1001 /// @param[in] abort_other_plans
1002 /// \b true if we discard the currently queued plans and replace them with this one.
1003 /// Otherwise this plan will go on the end of the plan stack.
1005 /// @param[in] stop_other_threads
1006 /// \b true if we will stop other threads while we single step this one.
1009 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
1010 //------------------------------------------------------------------
1011 virtual lldb::ThreadPlanSP
1012 QueueThreadPlanForStepThrough (StackID &return_stack_id,
1013 bool abort_other_plans,
1014 bool stop_other_threads);
1016 //------------------------------------------------------------------
1017 /// Gets the plan used to continue from the current PC.
1018 /// This is a simple plan, mostly useful as a backstop when you are continuing
1019 /// for some particular purpose.
1021 /// @param[in] abort_other_plans
1022 /// \b true if we discard the currently queued plans and replace them with this one.
1023 /// Otherwise this plan will go on the end of the plan stack.
1025 /// @param[in] target_addr
1026 /// The address to which we're running.
1028 /// @param[in] stop_other_threads
1029 /// \b true if we will stop other threads while we single step this one.
1032 /// A shared pointer to the newly queued thread plan, or nullptr if the plan could not be queued.
1033 //------------------------------------------------------------------
1034 virtual lldb::ThreadPlanSP
1035 QueueThreadPlanForRunToAddress (bool abort_other_plans,
1036 Address &target_addr,
1037 bool stop_other_threads);
1039 virtual lldb::ThreadPlanSP
1040 QueueThreadPlanForStepUntil (bool abort_other_plans,
1041 lldb::addr_t *address_list,
1042 size_t num_addresses,
1044 uint32_t frame_idx);
1046 virtual lldb::ThreadPlanSP
1047 QueueThreadPlanForStepScripted (bool abort_other_plans,
1048 const char *class_name,
1049 bool stop_other_threads);
1051 //------------------------------------------------------------------
1052 // Thread Plan accessors:
1053 //------------------------------------------------------------------
1055 //------------------------------------------------------------------
1056 /// Gets the plan which will execute next on the plan stack.
1059 /// A pointer to the next executed plan.
1060 //------------------------------------------------------------------
1064 //------------------------------------------------------------------
1065 /// Unwinds the thread stack for the innermost expression plan currently
1066 /// on the thread plan stack.
1069 /// An error if the thread plan could not be unwound.
1070 //------------------------------------------------------------------
1073 UnwindInnermostExpression();
1075 //------------------------------------------------------------------
1076 /// Gets the outer-most plan that was popped off the plan stack in the
1077 /// most recent stop. Useful for printing the stop reason accurately.
1080 /// A pointer to the last completed plan.
1081 //------------------------------------------------------------------
1083 GetCompletedPlan ();
1085 //------------------------------------------------------------------
1086 /// Gets the outer-most return value from the completed plans
1089 /// A ValueObjectSP, either empty if there is no return value,
1090 /// or containing the return value.
1091 //------------------------------------------------------------------
1093 GetReturnValueObject ();
1095 //------------------------------------------------------------------
1096 /// Gets the outer-most expression variable from the completed plans
1099 /// A ExpressionVariableSP, either empty if there is no
1100 /// plan completed an expression during the current stop
1101 /// or the expression variable that was made for the completed expression.
1102 //------------------------------------------------------------------
1103 lldb::ExpressionVariableSP
1104 GetExpressionVariable ();
1106 //------------------------------------------------------------------
1107 /// Checks whether the given plan is in the completed plans for this
1111 /// Pointer to the plan you're checking.
1114 /// Returns true if the input plan is in the completed plan stack,
1115 /// false otherwise.
1116 //------------------------------------------------------------------
1118 IsThreadPlanDone (ThreadPlan *plan);
1120 //------------------------------------------------------------------
1121 /// Checks whether the given plan is in the discarded plans for this
1125 /// Pointer to the plan you're checking.
1128 /// Returns true if the input plan is in the discarded plan stack,
1129 /// false otherwise.
1130 //------------------------------------------------------------------
1132 WasThreadPlanDiscarded (ThreadPlan *plan);
1134 //------------------------------------------------------------------
1135 /// Queues a generic thread plan.
1137 /// @param[in] plan_sp
1138 /// The plan to queue.
1140 /// @param[in] abort_other_plans
1141 /// \b true if we discard the currently queued plans and replace them with this one.
1142 /// Otherwise this plan will go on the end of the plan stack.
1145 /// A pointer to the last completed plan.
1146 //------------------------------------------------------------------
1148 QueueThreadPlan (lldb::ThreadPlanSP &plan_sp, bool abort_other_plans);
1150 //------------------------------------------------------------------
1151 /// Discards the plans queued on the plan stack of the current thread. This is
1152 /// arbitrated by the "Master" ThreadPlans, using the "OkayToDiscard" call.
1153 // But if \a force is true, all thread plans are discarded.
1154 //------------------------------------------------------------------
1156 DiscardThreadPlans (bool force);
1158 //------------------------------------------------------------------
1159 /// Discards the plans queued on the plan stack of the current thread up to and
1160 /// including up_to_plan_sp.
1162 // @param[in] up_to_plan_sp
1163 // Discard all plans up to and including this one.
1164 //------------------------------------------------------------------
1166 DiscardThreadPlansUpToPlan (lldb::ThreadPlanSP &up_to_plan_sp);
1169 DiscardThreadPlansUpToPlan (ThreadPlan *up_to_plan_ptr);
1171 //------------------------------------------------------------------
1172 /// Discards the plans queued on the plan stack of the current thread up to and
1173 /// including the plan in that matches \a thread_index counting only
1174 /// the non-Private plans.
1176 /// @param[in] up_to_plan_sp
1177 /// Discard all plans up to and including this user plan given by this index.
1180 /// \b true if there was a thread plan with that user index, \b false otherwise.
1181 //------------------------------------------------------------------
1183 DiscardUserThreadPlansUpToIndex (uint32_t thread_index);
1185 //------------------------------------------------------------------
1186 /// Prints the current plan stack.
1189 /// The stream to which to dump the plan stack info.
1191 //------------------------------------------------------------------
1193 DumpThreadPlans (Stream *s,
1194 lldb::DescriptionLevel desc_level = lldb::eDescriptionLevelVerbose,
1195 bool include_internal = true,
1196 bool ignore_boring = false) const;
1199 CheckpointThreadState (ThreadStateCheckpoint &saved_state);
1202 RestoreRegisterStateFromCheckpoint (ThreadStateCheckpoint &saved_state);
1205 RestoreThreadStateFromCheckpoint (ThreadStateCheckpoint &saved_state);
1208 EnableTracer (bool value, bool single_step);
1211 SetTracer (lldb::ThreadPlanTracerSP &tracer_sp);
1213 //------------------------------------------------------------------
1214 // Get the thread index ID. The index ID that is guaranteed to not
1215 // be re-used by a process. They start at 1 and increase with each
1216 // new thread. This allows easy command line access by a unique ID
1217 // that is easier to type than the actual system thread ID.
1218 //------------------------------------------------------------------
1220 GetIndexID () const;
1222 //------------------------------------------------------------------
1223 // Get the originating thread's index ID.
1224 // In the case of an "extended" thread -- a thread which represents
1225 // the stack that enqueued/spawned work that is currently executing --
1226 // we need to provide the IndexID of the thread that actually did
1227 // this work. We don't want to just masquerade as that thread's IndexID
1228 // by using it in our own IndexID because that way leads to madness -
1229 // but the driver program which is iterating over extended threads
1230 // may ask for the OriginatingThreadID to display that information
1232 // Normal threads will return the same thing as GetIndexID();
1233 //------------------------------------------------------------------
1235 GetExtendedBacktraceOriginatingIndexID ()
1237 return GetIndexID ();
1240 //------------------------------------------------------------------
1241 // The API ID is often the same as the Thread::GetID(), but not in
1242 // all cases. Thread::GetID() is the user visible thread ID that
1243 // clients would want to see. The API thread ID is the thread ID
1244 // that is used when sending data to/from the debugging protocol.
1245 //------------------------------------------------------------------
1246 virtual lldb::user_id_t
1247 GetProtocolID () const
1252 //------------------------------------------------------------------
1253 // lldb::ExecutionContextScope pure virtual functions
1254 //------------------------------------------------------------------
1256 CalculateTarget() override;
1259 CalculateProcess() override;
1262 CalculateThread() override;
1265 CalculateStackFrame() override;
1268 CalculateExecutionContext(ExecutionContext &exe_ctx) override;
1271 GetStackFrameSPForStackFramePtr (StackFrame *stack_frame_ptr);
1274 GetStatus (Stream &strm,
1275 uint32_t start_frame,
1276 uint32_t num_frames,
1277 uint32_t num_frames_with_source);
1280 GetStackFrameStatus (Stream& strm,
1281 uint32_t first_frame,
1282 uint32_t num_frames,
1283 bool show_frame_info,
1284 uint32_t num_frames_with_source);
1286 // We need a way to verify that even though we have a thread in a shared
1287 // pointer that the object itself is still valid. Currently this won't be
1288 // the case if DestroyThread() was called. DestroyThread is called when
1289 // a thread has been removed from the Process' thread list.
1293 return !m_destroy_called;
1296 // Sets and returns a valid stop info based on the process stop ID and the
1297 // current thread plan. If the thread stop ID does not match the process'
1298 // stop ID, the private stop reason is not set and an invalid StopInfoSP may
1301 // NOTE: This function must be called before the current thread plan is
1302 // moved to the completed plan stack (in Thread::ShouldStop()).
1304 // NOTE: If subclasses override this function, ensure they do not overwrite
1305 // the m_actual_stop_info if it is valid. The stop info may be a
1306 // "checkpointed and restored" stop info, so if it is still around it is
1307 // right even if you have not calculated this yourself, or if it disagrees
1308 // with what you might have calculated.
1309 virtual lldb::StopInfoSP
1310 GetPrivateStopInfo ();
1312 //----------------------------------------------------------------------
1313 // Ask the thread subclass to set its stop info.
1315 // Thread subclasses should call Thread::SetStopInfo(...) with the
1316 // reason the thread stopped.
1319 // True if Thread::SetStopInfo(...) was called, false otherwise.
1320 //----------------------------------------------------------------------
1322 CalculateStopInfo () = 0;
1324 //----------------------------------------------------------------------
1325 // Gets the temporary resume state for a thread.
1327 // This value gets set in each thread by complex debugger logic in
1328 // Thread::ShouldResume() and an appropriate thread resume state will get
1329 // set in each thread every time the process is resumed prior to calling
1330 // Process::DoResume(). The lldb_private::Process subclass should adhere
1331 // to the thread resume state request which will be one of:
1333 // eStateRunning - thread will resume when process is resumed
1334 // eStateStepping - thread should step 1 instruction and stop when process
1336 // eStateSuspended - thread should not execute any instructions when
1337 // process is resumed
1338 //----------------------------------------------------------------------
1340 GetTemporaryResumeState() const
1342 return m_temporary_resume_state;
1346 SetStopInfo (const lldb::StopInfoSP &stop_info_sp);
1349 SetShouldReportStop (Vote vote);
1351 //----------------------------------------------------------------------
1352 /// Sets the extended backtrace token for this thread
1354 /// Some Thread subclasses may maintain a token to help with providing
1355 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1357 /// @param [in] token
1358 //----------------------------------------------------------------------
1360 SetExtendedBacktraceToken (uint64_t token) { }
1362 //----------------------------------------------------------------------
1363 /// Gets the extended backtrace token for this thread
1365 /// Some Thread subclasses may maintain a token to help with providing
1366 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1369 /// The token needed by the SystemRuntime to create an extended backtrace.
1370 /// LLDB_INVALID_ADDRESS is returned if no token is available.
1371 //----------------------------------------------------------------------
1373 GetExtendedBacktraceToken ()
1375 return LLDB_INVALID_ADDRESS;
1379 friend class ThreadPlan;
1380 friend class ThreadList;
1381 friend class ThreadEventData;
1382 friend class StackFrameList;
1383 friend class StackFrame;
1384 friend class OperatingSystem;
1386 // This is necessary to make sure thread assets get destroyed while the thread is still in good shape
1387 // to call virtual thread methods. This must be called by classes that derive from Thread in their destructor.
1388 virtual void DestroyThread ();
1391 PushPlan (lldb::ThreadPlanSP &plan_sp);
1399 ThreadPlan *GetPreviousPlan (ThreadPlan *plan);
1401 typedef std::vector<lldb::ThreadPlanSP> plan_stack;
1403 virtual lldb_private::Unwind *
1406 // Check to see whether the thread is still at the last breakpoint hit that stopped it.
1408 IsStillAtLastBreakpointHit();
1410 // Some threads are threads that are made up by OperatingSystem plugins that
1411 // are threads that exist and are context switched out into memory. The
1412 // OperatingSystem plug-in need a ways to know if a thread is "real" or made
1415 IsOperatingSystemPluginThread () const
1420 // Subclasses that have a way to get an extended info dictionary for this thread should
1422 virtual lldb_private::StructuredData::ObjectSP
1423 FetchThreadExtendedInfo ()
1425 return StructuredData::ObjectSP();
1428 lldb::StackFrameListSP
1429 GetStackFrameList ();
1432 SetTemporaryResumeState(lldb::StateType new_state)
1434 m_temporary_resume_state = new_state;
1438 FunctionOptimizationWarning (lldb_private::StackFrame *frame);
1440 //------------------------------------------------------------------
1441 // Classes that inherit from Process can see and modify these
1442 //------------------------------------------------------------------
1443 lldb::ProcessWP m_process_wp; ///< The process that owns this thread.
1444 lldb::StopInfoSP m_stop_info_sp; ///< The private stop reason for this thread
1445 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
1446 // the thread's m_stop_info_sp is current and you don't have to fetch it again
1447 uint32_t m_stop_info_override_stop_id; // The stop ID containing the last time the stop info was checked against the stop info override
1448 const uint32_t m_index_id; ///< A unique 1 based index assigned to each thread for easy UI/command line access.
1449 lldb::RegisterContextSP m_reg_context_sp; ///< The register context for this thread's current register state.
1450 lldb::StateType m_state; ///< The state of our process.
1451 mutable std::recursive_mutex m_state_mutex; ///< Multithreaded protection for m_state.
1452 plan_stack m_plan_stack; ///< The stack of plans this thread is executing.
1453 plan_stack m_completed_plan_stack; ///< Plans that have been completed by this stop. They get deleted when the thread resumes.
1454 plan_stack m_discarded_plan_stack; ///< Plans that have been discarded by this stop. They get deleted when the thread resumes.
1455 mutable std::recursive_mutex m_frame_mutex; ///< Multithreaded protection for m_state.
1456 lldb::StackFrameListSP m_curr_frames_sp; ///< The stack frames that get lazily populated after a thread stops.
1457 lldb::StackFrameListSP m_prev_frames_sp; ///< The previous stack frames from the last time this thread stopped.
1458 int m_resume_signal; ///< The signal that should be used when continuing this thread.
1459 lldb::StateType m_resume_state; ///< This state is used to force a thread to be suspended from outside the ThreadPlan logic.
1460 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.
1461 /// It gets set in Thread::ShouldResume.
1462 std::unique_ptr<lldb_private::Unwind> m_unwinder_ap;
1463 bool m_destroy_called; // This is used internally to make sure derived Thread classes call DestroyThread.
1464 LazyBool m_override_should_notify;
1466 bool m_extended_info_fetched; // Have we tried to retrieve the m_extended_info for this thread?
1467 StructuredData::ObjectSP m_extended_info; // The extended info for this thread
1471 PlanIsBasePlan (ThreadPlan *plan_ptr);
1474 BroadcastSelectedFrameChange(StackID &new_frame_id);
1476 DISALLOW_COPY_AND_ASSIGN (Thread);
1479 } // namespace lldb_private
1481 #endif // liblldb_Thread_h_