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/Core/Broadcaster.h"
23 #include "lldb/Core/Event.h"
24 #include "lldb/Core/StructuredData.h"
25 #include "lldb/Core/UserID.h"
26 #include "lldb/Core/UserSettingsController.h"
27 #include "lldb/Target/ExecutionContextScope.h"
28 #include "lldb/Target/RegisterCheckpoint.h"
29 #include "lldb/Target/StackFrameList.h"
30 #include "lldb/lldb-private.h"
32 #define LLDB_THREAD_MAX_STOP_EXC_DATA 8
34 namespace lldb_private {
36 class ThreadProperties : public Properties {
38 ThreadProperties(bool is_global);
40 ~ThreadProperties() override;
42 //------------------------------------------------------------------
43 /// The regular expression returned determines symbols that this
44 /// thread won't stop in during "step-in" operations.
47 /// A pointer to a regular expression to compare against symbols,
48 /// or nullptr if all symbols are allowed.
50 //------------------------------------------------------------------
51 const RegularExpression *GetSymbolsToAvoidRegexp();
53 FileSpecList &GetLibrariesToAvoid() const;
55 bool GetTraceEnabledState() const;
57 bool GetStepInAvoidsNoDebug() const;
59 bool GetStepOutAvoidsNoDebug() const;
62 typedef std::shared_ptr<ThreadProperties> ThreadPropertiesSP;
64 class Thread : public std::enable_shared_from_this<Thread>,
65 public ThreadProperties,
67 public ExecutionContextScope,
70 //------------------------------------------------------------------
71 /// Broadcaster event bits definitions.
72 //------------------------------------------------------------------
74 eBroadcastBitStackChanged = (1 << 0),
75 eBroadcastBitThreadSuspended = (1 << 1),
76 eBroadcastBitThreadResumed = (1 << 2),
77 eBroadcastBitSelectedFrameChanged = (1 << 3),
78 eBroadcastBitThreadSelected = (1 << 4)
81 static ConstString &GetStaticBroadcasterClass();
83 ConstString &GetBroadcasterClass() const override {
84 return GetStaticBroadcasterClass();
87 class ThreadEventData : public EventData {
89 ThreadEventData(const lldb::ThreadSP thread_sp);
91 ThreadEventData(const lldb::ThreadSP thread_sp, const StackID &stack_id);
95 ~ThreadEventData() override;
97 static const ConstString &GetFlavorString();
99 const ConstString &GetFlavor() const override {
100 return ThreadEventData::GetFlavorString();
103 void Dump(Stream *s) const override;
105 static const ThreadEventData *GetEventDataFromEvent(const Event *event_ptr);
107 static lldb::ThreadSP GetThreadFromEvent(const Event *event_ptr);
109 static StackID GetStackIDFromEvent(const Event *event_ptr);
111 static lldb::StackFrameSP GetStackFrameFromEvent(const Event *event_ptr);
113 lldb::ThreadSP GetThread() const { return m_thread_sp; }
115 StackID GetStackID() const { return m_stack_id; }
118 lldb::ThreadSP m_thread_sp;
121 DISALLOW_COPY_AND_ASSIGN(ThreadEventData);
124 struct ThreadStateCheckpoint {
125 uint32_t orig_stop_id; // Dunno if I need this yet but it is an interesting
127 lldb::StopInfoSP stop_info_sp; // You have to restore the stop info or you
128 // might continue with the wrong signals.
129 lldb::RegisterCheckpointSP
130 register_backup_sp; // You need to restore the registers, of course...
131 uint32_t current_inlined_depth;
132 lldb::addr_t current_inlined_pc;
135 //------------------------------------------------------------------
138 /// @param [in] process
142 /// @param [in] use_invalid_index_id
143 /// Optional parameter, defaults to false. The only subclass that
144 /// is likely to set use_invalid_index_id == true is the HistoryThread
145 /// class. In that case, the Thread we are constructing represents
146 /// a thread from earlier in the program execution. We may have the
147 /// tid of the original thread that they represent but we don't want
148 /// to reuse the IndexID of that thread, or create a new one. If a
149 /// client wants to know the original thread's IndexID, they should use
150 /// Thread::GetExtendedBacktraceOriginatingIndexID().
151 //------------------------------------------------------------------
152 Thread(Process &process, lldb::tid_t tid, bool use_invalid_index_id = false);
156 static void SettingsInitialize();
158 static void SettingsTerminate();
160 static const ThreadPropertiesSP &GetGlobalProperties();
162 lldb::ProcessSP GetProcess() const { return m_process_wp.lock(); }
164 int GetResumeSignal() const { return m_resume_signal; }
166 void SetResumeSignal(int signal) { m_resume_signal = signal; }
168 lldb::StateType GetState() const;
170 void SetState(lldb::StateType state);
172 //------------------------------------------------------------------
173 /// Sets the USER resume state for this thread. If you set a thread to
175 /// this API, it won't take part in any of the arbitration for ShouldResume,
177 /// suspended even when other threads do get to run.
179 /// N.B. This is not the state that is used internally by thread plans to
181 /// staying on one thread while stepping over a breakpoint, etc. The is the
182 /// TemporaryResume state, and if you are implementing some bit of strategy in
184 /// machinery you should be using that state and not the user resume state.
186 /// If you are just preparing all threads to run, you should not override the
188 /// marked as suspended by the debugger. In that case, pass override_suspend
189 /// = false. If you want
190 /// to force the thread to run (e.g. the "thread continue" command, or are
191 /// resetting the state
192 /// (e.g. in SBThread::Resume()), then pass true to override_suspend.
194 /// The User resume state for this thread.
195 //------------------------------------------------------------------
196 void SetResumeState(lldb::StateType state, bool override_suspend = false) {
197 if (m_resume_state == lldb::eStateSuspended && !override_suspend)
199 m_resume_state = state;
202 //------------------------------------------------------------------
203 /// Gets the USER resume state for this thread. This is not the same as what
204 /// this thread is going to do for any particular step, however if this thread
205 /// returns eStateSuspended, then the process control logic will never allow
210 /// The User resume state for this thread.
211 //------------------------------------------------------------------
212 lldb::StateType GetResumeState() const { return m_resume_state; }
214 // This function is called on all the threads before "ShouldResume" and
215 // "WillResume" in case a thread needs to change its state before the
216 // ThreadList polls all the threads to figure out which ones actually
217 // will get to run and how.
218 void SetupForResume();
220 // Do not override this function, it is for thread plan logic only
221 bool ShouldResume(lldb::StateType resume_state);
223 // Override this to do platform specific tasks before resume.
224 virtual void WillResume(lldb::StateType resume_state) {}
226 // This clears generic thread state after a resume. If you subclass this,
227 // be sure to call it.
228 virtual void DidResume();
230 // This notifies the thread when a private stop occurs.
231 virtual void DidStop();
233 virtual void RefreshStateAfterStop() = 0;
237 bool ShouldStop(Event *event_ptr);
239 Vote ShouldReportStop(Event *event_ptr);
241 Vote ShouldReportRun(Event *event_ptr);
245 // Return whether this thread matches the specification in ThreadSpec. This
247 // method because at some point we may extend the thread spec with a platform
249 // dictionary of attributes, which then only the platform specific Thread
251 // would know how to match. For now, this just calls through to the
253 // ThreadPassesBasicTests method.
254 virtual bool MatchesSpec(const ThreadSpec *spec);
256 lldb::StopInfoSP GetStopInfo();
258 lldb::StopReason GetStopReason();
260 bool StopInfoIsUpToDate() const;
262 // This sets the stop reason to a "blank" stop reason, so you can call
263 // functions on the thread
264 // without having the called function run with whatever stop reason you
266 void SetStopInfoToNothing();
268 bool ThreadStoppedForAReason();
270 static const char *RunModeAsCString(lldb::RunMode mode);
272 static const char *StopReasonAsCString(lldb::StopReason reason);
274 virtual const char *GetInfo() { return nullptr; }
276 //------------------------------------------------------------------
277 /// Retrieve a dictionary of information about this thread
279 /// On Mac OS X systems there may be voucher information.
280 /// The top level dictionary returned will have an "activity" key and the
281 /// value of the activity is a dictionary. Keys in that dictionary will
282 /// be "name" and "id", among others.
283 /// There may also be "trace_messages" (an array) with each entry in that
285 /// being a dictionary (keys include "message" with the text of the trace
287 //------------------------------------------------------------------
288 StructuredData::ObjectSP GetExtendedInfo() {
289 if (m_extended_info_fetched == false) {
290 m_extended_info = FetchThreadExtendedInfo();
291 m_extended_info_fetched = true;
293 return m_extended_info;
296 virtual const char *GetName() { return nullptr; }
298 virtual void SetName(const char *name) {}
300 //------------------------------------------------------------------
301 /// Whether this thread can be associated with a libdispatch queue
303 /// The Thread may know if it is associated with a libdispatch queue,
304 /// it may know definitively that it is NOT associated with a libdispatch
305 /// queue, or it may be unknown whether it is associated with a libdispatch
309 /// eLazyBoolNo if this thread is definitely not associated with a
310 /// libdispatch queue (e.g. on a non-Darwin system where GCD aka
311 /// libdispatch is not available).
313 /// eLazyBoolYes this thread is associated with a libdispatch queue.
315 /// eLazyBoolCalculate this thread may be associated with a libdispatch
316 /// queue but the thread doesn't know one way or the other.
317 //------------------------------------------------------------------
318 virtual lldb_private::LazyBool GetAssociatedWithLibdispatchQueue() {
322 virtual void SetAssociatedWithLibdispatchQueue(
323 lldb_private::LazyBool associated_with_libdispatch_queue) {}
325 //------------------------------------------------------------------
326 /// Retrieve the Queue ID for the queue currently using this Thread
328 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
329 /// retrieve the QueueID.
331 /// This is a unique identifier for the libdispatch/GCD queue in a
332 /// process. Often starting at 1 for the initial system-created
333 /// queues and incrementing, a QueueID will not be reused for a
334 /// different queue during the lifetime of a process.
337 /// A QueueID if the Thread subclass implements this, else
338 /// LLDB_INVALID_QUEUE_ID.
339 //------------------------------------------------------------------
340 virtual lldb::queue_id_t GetQueueID() { return LLDB_INVALID_QUEUE_ID; }
342 virtual void SetQueueID(lldb::queue_id_t new_val) {}
344 //------------------------------------------------------------------
345 /// Retrieve the Queue name for the queue currently using this Thread
347 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
348 /// retrieve the Queue name.
351 /// The Queue name, if the Thread subclass implements this, else
353 //------------------------------------------------------------------
354 virtual const char *GetQueueName() { return nullptr; }
356 virtual void SetQueueName(const char *name) {}
358 //------------------------------------------------------------------
359 /// Retrieve the Queue kind for the queue currently using this Thread
361 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
362 /// retrieve the Queue kind - either eQueueKindSerial or
363 /// eQueueKindConcurrent, indicating that this queue processes work
364 /// items serially or concurrently.
367 /// The Queue kind, if the Thread subclass implements this, else
368 /// eQueueKindUnknown.
369 //------------------------------------------------------------------
370 virtual lldb::QueueKind GetQueueKind() { return lldb::eQueueKindUnknown; }
372 virtual void SetQueueKind(lldb::QueueKind kind) {}
374 //------------------------------------------------------------------
375 /// Retrieve the Queue for this thread, if any.
378 /// A QueueSP for the queue that is currently associated with this
380 /// An empty shared pointer indicates that this thread is not
381 /// associated with a queue, or libdispatch queues are not
382 /// supported on this target.
383 //------------------------------------------------------------------
384 virtual lldb::QueueSP GetQueue() { return lldb::QueueSP(); }
386 //------------------------------------------------------------------
387 /// Retrieve the address of the libdispatch_queue_t struct for queue
388 /// currently using this Thread
390 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
391 /// retrieve the address of the libdispatch_queue_t structure describing
394 /// This address may be reused for different queues later in the Process
395 /// lifetime and should not be used to identify a queue uniquely. Use
396 /// the GetQueueID() call for that.
399 /// The Queue's libdispatch_queue_t address if the Thread subclass
400 /// implements this, else LLDB_INVALID_ADDRESS.
401 //------------------------------------------------------------------
402 virtual lldb::addr_t GetQueueLibdispatchQueueAddress() {
403 return LLDB_INVALID_ADDRESS;
406 virtual void SetQueueLibdispatchQueueAddress(lldb::addr_t dispatch_queue_t) {}
408 //------------------------------------------------------------------
409 /// Whether this Thread already has all the Queue information cached or not
411 /// A Thread may be associated with a libdispatch work Queue at a given
412 /// public stop event. If so, the thread can satisify requests like
413 /// GetQueueLibdispatchQueueAddress, GetQueueKind, GetQueueName, and
415 /// either from information from the remote debug stub when it is initially
416 /// created, or it can query the SystemRuntime for that information.
418 /// This method allows the SystemRuntime to discover if a thread has this
419 /// information already, instead of calling the thread to get the information
420 /// and having the thread call the SystemRuntime again.
421 //------------------------------------------------------------------
422 virtual bool ThreadHasQueueInformation() const { return false; }
424 virtual uint32_t GetStackFrameCount() {
425 return GetStackFrameList()->GetNumFrames();
428 virtual lldb::StackFrameSP GetStackFrameAtIndex(uint32_t idx) {
429 return GetStackFrameList()->GetFrameAtIndex(idx);
432 virtual lldb::StackFrameSP
433 GetFrameWithConcreteFrameIndex(uint32_t unwind_idx);
435 bool DecrementCurrentInlinedDepth() {
436 return GetStackFrameList()->DecrementCurrentInlinedDepth();
439 uint32_t GetCurrentInlinedDepth() {
440 return GetStackFrameList()->GetCurrentInlinedDepth();
443 Error ReturnFromFrameWithIndex(uint32_t frame_idx,
444 lldb::ValueObjectSP return_value_sp,
445 bool broadcast = false);
447 Error ReturnFromFrame(lldb::StackFrameSP frame_sp,
448 lldb::ValueObjectSP return_value_sp,
449 bool broadcast = false);
451 Error JumpToLine(const FileSpec &file, uint32_t line, bool can_leave_function,
452 std::string *warnings = nullptr);
454 virtual lldb::StackFrameSP GetFrameWithStackID(const StackID &stack_id) {
455 if (stack_id.IsValid())
456 return GetStackFrameList()->GetFrameWithStackID(stack_id);
457 return lldb::StackFrameSP();
460 uint32_t GetSelectedFrameIndex() {
461 return GetStackFrameList()->GetSelectedFrameIndex();
464 lldb::StackFrameSP GetSelectedFrame();
466 uint32_t SetSelectedFrame(lldb_private::StackFrame *frame,
467 bool broadcast = false);
469 bool SetSelectedFrameByIndex(uint32_t frame_idx, bool broadcast = false);
471 bool SetSelectedFrameByIndexNoisily(uint32_t frame_idx,
472 Stream &output_stream);
474 void SetDefaultFileAndLineToSelectedFrame() {
475 GetStackFrameList()->SetDefaultFileAndLineToSelectedFrame();
478 virtual lldb::RegisterContextSP GetRegisterContext() = 0;
480 virtual lldb::RegisterContextSP
481 CreateRegisterContextForFrame(StackFrame *frame) = 0;
483 virtual void ClearStackFrames();
485 virtual bool SetBackingThread(const lldb::ThreadSP &thread_sp) {
489 virtual lldb::ThreadSP GetBackingThread() const { return lldb::ThreadSP(); }
491 virtual void ClearBackingThread() {
492 // Subclasses can use this function if a thread is actually backed by
493 // another thread. This is currently used for the OperatingSystem plug-ins
494 // where they might have a thread that is in memory, yet its registers
495 // are available through the lldb_private::Thread subclass for the current
496 // lldb_private::Process class. Since each time the process stops the
498 // threads for memory threads can change, we need a way to clear the backing
499 // thread for all memory threads each time we stop.
502 // If stop_format is true, this will be the form used when we print stop info.
503 // If false, it will be the form we use for thread list and co.
504 void DumpUsingSettingsFormat(Stream &strm, uint32_t frame_idx,
507 bool GetDescription(Stream &s, lldb::DescriptionLevel level,
508 bool print_json_thread, bool print_json_stopinfo);
510 //------------------------------------------------------------------
511 /// Default implementation for stepping into.
513 /// This function is designed to be used by commands where the
514 /// process is publicly stopped.
516 /// @param[in] source_step
517 /// If true and the frame has debug info, then do a source level
518 /// step in, else do a single instruction step in.
520 /// @param[in] step_in_avoids_code_without_debug_info
521 /// If \a true, then avoid stepping into code that doesn't have
522 /// debug info, else step into any code regardless of whether it
525 /// @param[in] step_out_avoids_code_without_debug_info
526 /// If \a true, then if you step out to code with no debug info, keep
527 /// stepping out till you get to code with debug info.
530 /// An error that describes anything that went wrong
531 //------------------------------------------------------------------
533 StepIn(bool source_step,
534 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
535 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
537 //------------------------------------------------------------------
538 /// Default implementation for stepping over.
540 /// This function is designed to be used by commands where the
541 /// process is publicly stopped.
543 /// @param[in] source_step
544 /// If true and the frame has debug info, then do a source level
545 /// step over, else do a single instruction step over.
548 /// An error that describes anything that went wrong
549 //------------------------------------------------------------------
550 virtual Error StepOver(
552 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
554 //------------------------------------------------------------------
555 /// Default implementation for stepping out.
557 /// This function is designed to be used by commands where the
558 /// process is publicly stopped.
561 /// An error that describes anything that went wrong
562 //------------------------------------------------------------------
563 virtual Error StepOut();
565 //------------------------------------------------------------------
566 /// Retrieves the per-thread data area.
567 /// Most OSs maintain a per-thread pointer (e.g. the FS register on
568 /// x64), which we return the value of here.
571 /// LLDB_INVALID_ADDRESS if not supported, otherwise the thread
573 //------------------------------------------------------------------
574 virtual lldb::addr_t GetThreadPointer();
576 //------------------------------------------------------------------
577 /// Retrieves the per-module TLS block for a thread.
579 /// @param[in] module
580 /// The module to query TLS data for.
582 /// @param[in] tls_file_addr
583 /// The thread local address in module
585 /// If the thread has TLS data allocated for the
586 /// module, the address of the TLS block. Otherwise
587 /// LLDB_INVALID_ADDRESS is returned.
588 //------------------------------------------------------------------
589 virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module,
590 lldb::addr_t tls_file_addr);
592 //------------------------------------------------------------------
593 /// Check whether this thread is safe to run functions
595 /// The SystemRuntime may know of certain thread states (functions in
596 /// process of execution, for instance) which can make it unsafe for
597 /// functions to be called.
600 /// True if it is safe to call functions on this thread.
601 /// False if function calls should be avoided on this thread.
602 //------------------------------------------------------------------
603 virtual bool SafeToCallFunctions();
605 //------------------------------------------------------------------
606 // Thread Plan Providers:
607 // This section provides the basic thread plans that the Process control
608 // machinery uses to run the target. ThreadPlan.h provides more details on
609 // how this mechanism works.
610 // The thread provides accessors to a set of plans that perform basic
612 // The idea is that particular Platform plugins can override these methods to
613 // provide the implementation of these basic operations appropriate to their
616 // NB: All the QueueThreadPlanXXX providers return Shared Pointers to
617 // Thread plans. This is useful so that you can modify the plans after
618 // creation in ways specific to that plan type. Also, it is often necessary
620 // ThreadPlans that utilize other ThreadPlans to implement their task to keep
622 // pointer to the sub-plan.
623 // But besides that, the shared pointers should only be held onto by entities
624 // who live no longer
625 // than the thread containing the ThreadPlan.
626 // FIXME: If this becomes a problem, we can make a version that just returns a
628 // which it is clearly unsafe to hold onto, and a shared pointer version, and
630 // ThreadPlan and Co. to use the latter. That is made more annoying to do
632 // no elegant way to friend a method to all sub-classes of a given class.
634 //------------------------------------------------------------------
636 //------------------------------------------------------------------
637 /// Queues the base plan for a thread.
638 /// The version returned by Process does some things that are useful,
639 /// like handle breakpoints and signals, so if you return a plugin specific
640 /// one you probably want to call through to the Process one for anything
641 /// your plugin doesn't explicitly handle.
643 /// @param[in] abort_other_plans
644 /// \b true if we discard the currently queued plans and replace them with
646 /// Otherwise this plan will go on the end of the plan stack.
649 /// A shared pointer to the newly queued thread plan, or nullptr if the
650 /// plan could not be queued.
651 //------------------------------------------------------------------
652 virtual lldb::ThreadPlanSP QueueFundamentalPlan(bool abort_other_plans);
654 //------------------------------------------------------------------
655 /// Queues the plan used to step one instruction from the current PC of \a
658 /// @param[in] step_over
659 /// \b true if we step over calls to functions, false if we step in.
661 /// @param[in] abort_other_plans
662 /// \b true if we discard the currently queued plans and replace them with
664 /// Otherwise this plan will go on the end of the plan stack.
666 /// @param[in] stop_other_threads
667 /// \b true if we will stop other threads while we single step this one.
670 /// A shared pointer to the newly queued thread plan, or nullptr if the
671 /// plan could not be queued.
672 //------------------------------------------------------------------
673 virtual lldb::ThreadPlanSP QueueThreadPlanForStepSingleInstruction(
674 bool step_over, bool abort_other_plans, bool stop_other_threads);
676 //------------------------------------------------------------------
677 /// Queues the plan used to step through an address range, stepping over
680 /// @param[in] abort_other_plans
681 /// \b true if we discard the currently queued plans and replace them with
683 /// Otherwise this plan will go on the end of the plan stack.
686 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
690 /// The address range to step through.
692 /// @param[in] addr_context
693 /// When dealing with stepping through inlined functions the current PC is
694 /// not enough information to know
695 /// what "step" means. For instance a series of nested inline functions
696 /// might start at the same address.
697 // The \a addr_context provides the current symbol context the step
698 /// is supposed to be out of.
699 // FIXME: Currently unused.
701 /// @param[in] stop_other_threads
702 /// \b true if we will stop other threads while we single step this one.
704 /// @param[in] step_out_avoids_code_without_debug_info
705 /// If eLazyBoolYes, if the step over steps out it will continue to step
706 /// out till it comes to a frame with debug info.
707 /// If eLazyBoolCalculate, we will consult the default set in the thread.
710 /// A shared pointer to the newly queued thread plan, or nullptr if the
711 /// plan could not be queued.
712 //------------------------------------------------------------------
713 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
714 bool abort_other_plans, const AddressRange &range,
715 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
716 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
718 // Helper function that takes a LineEntry to step, insted of an AddressRange.
719 // This may combine multiple
720 // LineEntries of the same source line number to step over a longer address
721 // range in a single operation.
722 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
723 bool abort_other_plans, const LineEntry &line_entry,
724 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
725 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
727 //------------------------------------------------------------------
728 /// Queues the plan used to step through an address range, stepping into
731 /// @param[in] abort_other_plans
732 /// \b true if we discard the currently queued plans and replace them with
734 /// Otherwise this plan will go on the end of the plan stack.
737 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
741 /// The address range to step through.
743 /// @param[in] addr_context
744 /// When dealing with stepping through inlined functions the current PC is
745 /// not enough information to know
746 /// what "step" means. For instance a series of nested inline functions
747 /// might start at the same address.
748 // The \a addr_context provides the current symbol context the step
749 /// is supposed to be out of.
750 // FIXME: Currently unused.
752 /// @param[in] step_in_target
753 /// Name if function we are trying to step into. We will step out if we
754 /// don't land in that function.
756 /// @param[in] stop_other_threads
757 /// \b true if we will stop other threads while we single step this one.
759 /// @param[in] step_in_avoids_code_without_debug_info
760 /// If eLazyBoolYes we will step out if we step into code with no debug
762 /// If eLazyBoolCalculate we will consult the default set in the thread.
764 /// @param[in] step_out_avoids_code_without_debug_info
765 /// If eLazyBoolYes, if the step over steps out it will continue to step
766 /// out till it comes to a frame with debug info.
767 /// If eLazyBoolCalculate, it will consult the default set in the thread.
770 /// A shared pointer to the newly queued thread plan, or nullptr if the
771 /// plan could not be queued.
772 //------------------------------------------------------------------
773 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
774 bool abort_other_plans, const AddressRange &range,
775 const SymbolContext &addr_context, const char *step_in_target,
776 lldb::RunMode stop_other_threads,
777 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
778 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
780 // Helper function that takes a LineEntry to step, insted of an AddressRange.
781 // This may combine multiple
782 // LineEntries of the same source line number to step over a longer address
783 // range in a single operation.
784 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
785 bool abort_other_plans, const LineEntry &line_entry,
786 const SymbolContext &addr_context, const char *step_in_target,
787 lldb::RunMode stop_other_threads,
788 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
789 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
791 //------------------------------------------------------------------
792 /// Queue the plan used to step out of the function at the current PC of
795 /// @param[in] abort_other_plans
796 /// \b true if we discard the currently queued plans and replace them with
798 /// Otherwise this plan will go on the end of the plan stack.
800 /// @param[in] addr_context
801 /// When dealing with stepping through inlined functions the current PC is
802 /// not enough information to know
803 /// what "step" means. For instance a series of nested inline functions
804 /// might start at the same address.
805 // The \a addr_context provides the current symbol context the step
806 /// is supposed to be out of.
807 // FIXME: Currently unused.
809 /// @param[in] first_insn
810 /// \b true if this is the first instruction of a function.
812 /// @param[in] stop_other_threads
813 /// \b true if we will stop other threads while we single step this one.
815 /// @param[in] stop_vote
816 /// @param[in] run_vote
817 /// See standard meanings for the stop & run votes in ThreadPlan.h.
819 /// @param[in] step_out_avoids_code_without_debug_info
820 /// If eLazyBoolYes, if the step over steps out it will continue to step
821 /// out till it comes to a frame with debug info.
822 /// If eLazyBoolCalculate, it will consult the default set in the thread.
825 /// A shared pointer to the newly queued thread plan, or nullptr if the
826 /// plan could not be queued.
827 //------------------------------------------------------------------
828 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOut(
829 bool abort_other_plans, SymbolContext *addr_context, bool first_insn,
830 bool stop_other_threads,
831 Vote stop_vote, // = eVoteYes,
832 Vote run_vote, // = eVoteNoOpinion);
834 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
836 //------------------------------------------------------------------
837 /// Queue the plan used to step out of the function at the current PC of
838 /// a thread. This version does not consult the should stop here callback,
840 /// be used by other thread plans when they need to retain control of the step
843 /// @param[in] abort_other_plans
844 /// \b true if we discard the currently queued plans and replace them with
846 /// Otherwise this plan will go on the end of the plan stack.
848 /// @param[in] addr_context
849 /// When dealing with stepping through inlined functions the current PC is
850 /// not enough information to know
851 /// what "step" means. For instance a series of nested inline functions
852 /// might start at the same address.
853 // The \a addr_context provides the current symbol context the step
854 /// is supposed to be out of.
855 // FIXME: Currently unused.
857 /// @param[in] first_insn
858 /// \b true if this is the first instruction of a function.
860 /// @param[in] stop_other_threads
861 /// \b true if we will stop other threads while we single step this one.
863 /// @param[in] stop_vote
864 /// @param[in] run_vote
865 /// See standard meanings for the stop & run votes in ThreadPlan.h.
867 /// @param[in] continue_to_next_branch
868 /// Normally this will enqueue a plan that will put a breakpoint on the
869 /// return address and continue
870 /// to there. If continue_to_next_branch is true, this is an operation not
871 /// involving the user --
872 /// e.g. stepping "next" in a source line and we instruction stepped into
873 /// another function --
874 /// so instead of putting a breakpoint on the return address, advance the
875 /// breakpoint to the
876 /// end of the source line that is doing the call, or until the next flow
877 /// control instruction.
878 /// If the return value from the function call is to be retrieved /
879 /// displayed to the user, you must stop
880 /// on the return address. The return value may be stored in volatile
881 /// registers which are overwritten
882 /// before the next branch instruction.
885 /// A shared pointer to the newly queued thread plan, or nullptr if the
886 /// plan could not be queued.
887 //------------------------------------------------------------------
888 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOutNoShouldStop(
889 bool abort_other_plans, SymbolContext *addr_context, bool first_insn,
890 bool stop_other_threads,
891 Vote stop_vote, // = eVoteYes,
892 Vote run_vote, // = eVoteNoOpinion);
893 uint32_t frame_idx, bool continue_to_next_branch = false);
895 //------------------------------------------------------------------
896 /// Gets the plan used to step through the code that steps from a function
897 /// call site at the current PC into the actual function call.
900 /// @param[in] return_stack_id
901 /// The stack id that we will return to (by setting backstop breakpoints on
903 /// address to that frame) if we fail to step through.
905 /// @param[in] abort_other_plans
906 /// \b true if we discard the currently queued plans and replace them with
908 /// Otherwise this plan will go on the end of the plan stack.
910 /// @param[in] stop_other_threads
911 /// \b true if we will stop other threads while we single step this one.
914 /// A shared pointer to the newly queued thread plan, or nullptr if the
915 /// plan could not be queued.
916 //------------------------------------------------------------------
917 virtual lldb::ThreadPlanSP
918 QueueThreadPlanForStepThrough(StackID &return_stack_id,
919 bool abort_other_plans,
920 bool stop_other_threads);
922 //------------------------------------------------------------------
923 /// Gets the plan used to continue from the current PC.
924 /// This is a simple plan, mostly useful as a backstop when you are continuing
925 /// for some particular purpose.
927 /// @param[in] abort_other_plans
928 /// \b true if we discard the currently queued plans and replace them with
930 /// Otherwise this plan will go on the end of the plan stack.
932 /// @param[in] target_addr
933 /// The address to which we're running.
935 /// @param[in] stop_other_threads
936 /// \b true if we will stop other threads while we single step this one.
939 /// A shared pointer to the newly queued thread plan, or nullptr if the
940 /// plan could not be queued.
941 //------------------------------------------------------------------
942 virtual lldb::ThreadPlanSP
943 QueueThreadPlanForRunToAddress(bool abort_other_plans, Address &target_addr,
944 bool stop_other_threads);
946 virtual lldb::ThreadPlanSP
947 QueueThreadPlanForStepUntil(bool abort_other_plans,
948 lldb::addr_t *address_list, size_t num_addresses,
949 bool stop_others, uint32_t frame_idx);
951 virtual lldb::ThreadPlanSP
952 QueueThreadPlanForStepScripted(bool abort_other_plans, const char *class_name,
953 bool stop_other_threads);
955 //------------------------------------------------------------------
956 // Thread Plan accessors:
957 //------------------------------------------------------------------
959 //------------------------------------------------------------------
960 /// Gets the plan which will execute next on the plan stack.
963 /// A pointer to the next executed plan.
964 //------------------------------------------------------------------
965 ThreadPlan *GetCurrentPlan();
967 //------------------------------------------------------------------
968 /// Unwinds the thread stack for the innermost expression plan currently
969 /// on the thread plan stack.
972 /// An error if the thread plan could not be unwound.
973 //------------------------------------------------------------------
975 Error UnwindInnermostExpression();
977 //------------------------------------------------------------------
978 /// Gets the outer-most plan that was popped off the plan stack in the
979 /// most recent stop. Useful for printing the stop reason accurately.
982 /// A pointer to the last completed plan.
983 //------------------------------------------------------------------
984 lldb::ThreadPlanSP GetCompletedPlan();
986 //------------------------------------------------------------------
987 /// Gets the outer-most return value from the completed plans
990 /// A ValueObjectSP, either empty if there is no return value,
991 /// or containing the return value.
992 //------------------------------------------------------------------
993 lldb::ValueObjectSP GetReturnValueObject();
995 //------------------------------------------------------------------
996 /// Gets the outer-most expression variable from the completed plans
999 /// A ExpressionVariableSP, either empty if there is no
1000 /// plan completed an expression during the current stop
1001 /// or the expression variable that was made for the completed expression.
1002 //------------------------------------------------------------------
1003 lldb::ExpressionVariableSP GetExpressionVariable();
1005 //------------------------------------------------------------------
1006 /// Checks whether the given plan is in the completed plans for this
1010 /// Pointer to the plan you're checking.
1013 /// Returns true if the input plan is in the completed plan stack,
1014 /// false otherwise.
1015 //------------------------------------------------------------------
1016 bool IsThreadPlanDone(ThreadPlan *plan);
1018 //------------------------------------------------------------------
1019 /// Checks whether the given plan is in the discarded plans for this
1023 /// Pointer to the plan you're checking.
1026 /// Returns true if the input plan is in the discarded plan stack,
1027 /// false otherwise.
1028 //------------------------------------------------------------------
1029 bool WasThreadPlanDiscarded(ThreadPlan *plan);
1031 //------------------------------------------------------------------
1032 /// Queues a generic thread plan.
1034 /// @param[in] plan_sp
1035 /// The plan to queue.
1037 /// @param[in] abort_other_plans
1038 /// \b true if we discard the currently queued plans and replace them with
1040 /// Otherwise this plan will go on the end of the plan stack.
1043 /// A pointer to the last completed plan.
1044 //------------------------------------------------------------------
1045 void QueueThreadPlan(lldb::ThreadPlanSP &plan_sp, bool abort_other_plans);
1047 //------------------------------------------------------------------
1048 /// Discards the plans queued on the plan stack of the current thread. This
1050 /// arbitrated by the "Master" ThreadPlans, using the "OkayToDiscard" call.
1051 // But if \a force is true, all thread plans are discarded.
1052 //------------------------------------------------------------------
1053 void DiscardThreadPlans(bool force);
1055 //------------------------------------------------------------------
1056 /// Discards the plans queued on the plan stack of the current thread up to
1058 /// including up_to_plan_sp.
1060 // @param[in] up_to_plan_sp
1061 // Discard all plans up to and including this one.
1062 //------------------------------------------------------------------
1063 void DiscardThreadPlansUpToPlan(lldb::ThreadPlanSP &up_to_plan_sp);
1065 void DiscardThreadPlansUpToPlan(ThreadPlan *up_to_plan_ptr);
1067 //------------------------------------------------------------------
1068 /// Discards the plans queued on the plan stack of the current thread up to
1070 /// including the plan in that matches \a thread_index counting only
1071 /// the non-Private plans.
1073 /// @param[in] up_to_plan_sp
1074 /// Discard all plans up to and including this user plan given by this
1078 /// \b true if there was a thread plan with that user index, \b false
1080 //------------------------------------------------------------------
1081 bool DiscardUserThreadPlansUpToIndex(uint32_t thread_index);
1083 //------------------------------------------------------------------
1084 /// Prints the current plan stack.
1087 /// The stream to which to dump the plan stack info.
1089 //------------------------------------------------------------------
1090 void DumpThreadPlans(
1092 lldb::DescriptionLevel desc_level = lldb::eDescriptionLevelVerbose,
1093 bool include_internal = true, bool ignore_boring = false) const;
1095 virtual bool CheckpointThreadState(ThreadStateCheckpoint &saved_state);
1098 RestoreRegisterStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1101 RestoreThreadStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1103 void EnableTracer(bool value, bool single_step);
1105 void SetTracer(lldb::ThreadPlanTracerSP &tracer_sp);
1107 //------------------------------------------------------------------
1108 // Get the thread index ID. The index ID that is guaranteed to not
1109 // be re-used by a process. They start at 1 and increase with each
1110 // new thread. This allows easy command line access by a unique ID
1111 // that is easier to type than the actual system thread ID.
1112 //------------------------------------------------------------------
1113 uint32_t GetIndexID() const;
1115 //------------------------------------------------------------------
1116 // Get the originating thread's index ID.
1117 // In the case of an "extended" thread -- a thread which represents
1118 // the stack that enqueued/spawned work that is currently executing --
1119 // we need to provide the IndexID of the thread that actually did
1120 // this work. We don't want to just masquerade as that thread's IndexID
1121 // by using it in our own IndexID because that way leads to madness -
1122 // but the driver program which is iterating over extended threads
1123 // may ask for the OriginatingThreadID to display that information
1125 // Normal threads will return the same thing as GetIndexID();
1126 //------------------------------------------------------------------
1127 virtual uint32_t GetExtendedBacktraceOriginatingIndexID() {
1128 return GetIndexID();
1131 //------------------------------------------------------------------
1132 // The API ID is often the same as the Thread::GetID(), but not in
1133 // all cases. Thread::GetID() is the user visible thread ID that
1134 // clients would want to see. The API thread ID is the thread ID
1135 // that is used when sending data to/from the debugging protocol.
1136 //------------------------------------------------------------------
1137 virtual lldb::user_id_t GetProtocolID() const { return GetID(); }
1139 //------------------------------------------------------------------
1140 // lldb::ExecutionContextScope pure virtual functions
1141 //------------------------------------------------------------------
1142 lldb::TargetSP CalculateTarget() override;
1144 lldb::ProcessSP CalculateProcess() override;
1146 lldb::ThreadSP CalculateThread() override;
1148 lldb::StackFrameSP CalculateStackFrame() override;
1150 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
1153 GetStackFrameSPForStackFramePtr(StackFrame *stack_frame_ptr);
1155 size_t GetStatus(Stream &strm, uint32_t start_frame, uint32_t num_frames,
1156 uint32_t num_frames_with_source,
1159 size_t GetStackFrameStatus(Stream &strm, uint32_t first_frame,
1160 uint32_t num_frames, bool show_frame_info,
1161 uint32_t num_frames_with_source);
1163 // We need a way to verify that even though we have a thread in a shared
1164 // pointer that the object itself is still valid. Currently this won't be
1165 // the case if DestroyThread() was called. DestroyThread is called when
1166 // a thread has been removed from the Process' thread list.
1167 bool IsValid() const { return !m_destroy_called; }
1169 // Sets and returns a valid stop info based on the process stop ID and the
1170 // current thread plan. If the thread stop ID does not match the process'
1171 // stop ID, the private stop reason is not set and an invalid StopInfoSP may
1174 // NOTE: This function must be called before the current thread plan is
1175 // moved to the completed plan stack (in Thread::ShouldStop()).
1177 // NOTE: If subclasses override this function, ensure they do not overwrite
1178 // the m_actual_stop_info if it is valid. The stop info may be a
1179 // "checkpointed and restored" stop info, so if it is still around it is
1180 // right even if you have not calculated this yourself, or if it disagrees
1181 // with what you might have calculated.
1182 virtual lldb::StopInfoSP GetPrivateStopInfo();
1184 //----------------------------------------------------------------------
1185 // Ask the thread subclass to set its stop info.
1187 // Thread subclasses should call Thread::SetStopInfo(...) with the
1188 // reason the thread stopped.
1191 // True if Thread::SetStopInfo(...) was called, false otherwise.
1192 //----------------------------------------------------------------------
1193 virtual bool CalculateStopInfo() = 0;
1195 //----------------------------------------------------------------------
1196 // Gets the temporary resume state for a thread.
1198 // This value gets set in each thread by complex debugger logic in
1199 // Thread::ShouldResume() and an appropriate thread resume state will get
1200 // set in each thread every time the process is resumed prior to calling
1201 // Process::DoResume(). The lldb_private::Process subclass should adhere
1202 // to the thread resume state request which will be one of:
1204 // eStateRunning - thread will resume when process is resumed
1205 // eStateStepping - thread should step 1 instruction and stop when process
1207 // eStateSuspended - thread should not execute any instructions when
1208 // process is resumed
1209 //----------------------------------------------------------------------
1210 lldb::StateType GetTemporaryResumeState() const {
1211 return m_temporary_resume_state;
1214 void SetStopInfo(const lldb::StopInfoSP &stop_info_sp);
1216 void SetShouldReportStop(Vote vote);
1218 //----------------------------------------------------------------------
1219 /// Sets the extended backtrace token for this thread
1221 /// Some Thread subclasses may maintain a token to help with providing
1222 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1224 /// @param [in] token
1225 //----------------------------------------------------------------------
1226 virtual void SetExtendedBacktraceToken(uint64_t token) {}
1228 //----------------------------------------------------------------------
1229 /// Gets the extended backtrace token for this thread
1231 /// Some Thread subclasses may maintain a token to help with providing
1232 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1235 /// The token needed by the SystemRuntime to create an extended backtrace.
1236 /// LLDB_INVALID_ADDRESS is returned if no token is available.
1237 //----------------------------------------------------------------------
1238 virtual uint64_t GetExtendedBacktraceToken() { return LLDB_INVALID_ADDRESS; }
1241 friend class ThreadPlan;
1242 friend class ThreadList;
1243 friend class ThreadEventData;
1244 friend class StackFrameList;
1245 friend class StackFrame;
1246 friend class OperatingSystem;
1248 // This is necessary to make sure thread assets get destroyed while the thread
1249 // is still in good shape
1250 // to call virtual thread methods. This must be called by classes that derive
1251 // from Thread in their destructor.
1252 virtual void DestroyThread();
1254 void PushPlan(lldb::ThreadPlanSP &plan_sp);
1260 ThreadPlan *GetPreviousPlan(ThreadPlan *plan);
1262 typedef std::vector<lldb::ThreadPlanSP> plan_stack;
1264 virtual lldb_private::Unwind *GetUnwinder();
1266 // Check to see whether the thread is still at the last breakpoint hit that
1268 virtual bool IsStillAtLastBreakpointHit();
1270 // Some threads are threads that are made up by OperatingSystem plugins that
1271 // are threads that exist and are context switched out into memory. The
1272 // OperatingSystem plug-in need a ways to know if a thread is "real" or made
1274 virtual bool IsOperatingSystemPluginThread() const { return false; }
1276 // Subclasses that have a way to get an extended info dictionary for this
1279 virtual lldb_private::StructuredData::ObjectSP FetchThreadExtendedInfo() {
1280 return StructuredData::ObjectSP();
1283 lldb::StackFrameListSP GetStackFrameList();
1285 void SetTemporaryResumeState(lldb::StateType new_state) {
1286 m_temporary_resume_state = new_state;
1289 void FunctionOptimizationWarning(lldb_private::StackFrame *frame);
1291 //------------------------------------------------------------------
1292 // Classes that inherit from Process can see and modify these
1293 //------------------------------------------------------------------
1294 lldb::ProcessWP m_process_wp; ///< The process that owns this thread.
1295 lldb::StopInfoSP m_stop_info_sp; ///< The private stop reason for this thread
1296 uint32_t m_stop_info_stop_id; // This is the stop id for which the StopInfo is
1297 // valid. Can use this so you know that
1298 // the thread's m_stop_info_sp is current and you don't have to fetch it again
1299 uint32_t m_stop_info_override_stop_id; // The stop ID containing the last time
1300 // the stop info was checked against
1301 // the stop info override
1302 const uint32_t m_index_id; ///< A unique 1 based index assigned to each thread
1303 ///for easy UI/command line access.
1304 lldb::RegisterContextSP m_reg_context_sp; ///< The register context for this
1305 ///thread's current register state.
1306 lldb::StateType m_state; ///< The state of our process.
1307 mutable std::recursive_mutex
1308 m_state_mutex; ///< Multithreaded protection for m_state.
1309 plan_stack m_plan_stack; ///< The stack of plans this thread is executing.
1310 plan_stack m_completed_plan_stack; ///< Plans that have been completed by this
1311 ///stop. They get deleted when the thread
1313 plan_stack m_discarded_plan_stack; ///< Plans that have been discarded by this
1314 ///stop. They get deleted when the thread
1316 mutable std::recursive_mutex
1317 m_frame_mutex; ///< Multithreaded protection for m_state.
1318 lldb::StackFrameListSP m_curr_frames_sp; ///< The stack frames that get lazily
1319 ///populated after a thread stops.
1320 lldb::StackFrameListSP m_prev_frames_sp; ///< The previous stack frames from
1321 ///the last time this thread stopped.
1322 int m_resume_signal; ///< The signal that should be used when continuing this
1324 lldb::StateType m_resume_state; ///< This state is used to force a thread to
1325 ///be suspended from outside the ThreadPlan
1327 lldb::StateType m_temporary_resume_state; ///< This state records what the
1328 ///thread was told to do by the
1329 ///thread plan logic for the current
1331 /// It gets set in Thread::ShouldResume.
1332 std::unique_ptr<lldb_private::Unwind> m_unwinder_ap;
1333 bool m_destroy_called; // This is used internally to make sure derived Thread
1334 // classes call DestroyThread.
1335 LazyBool m_override_should_notify;
1338 bool m_extended_info_fetched; // Have we tried to retrieve the m_extended_info
1340 StructuredData::ObjectSP m_extended_info; // The extended info for this thread
1343 bool PlanIsBasePlan(ThreadPlan *plan_ptr);
1345 void BroadcastSelectedFrameChange(StackID &new_frame_id);
1347 DISALLOW_COPY_AND_ASSIGN(Thread);
1350 } // namespace lldb_private
1352 #endif // liblldb_Thread_h_