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/UserSettingsController.h"
25 #include "lldb/Target/ExecutionContextScope.h"
26 #include "lldb/Target/RegisterCheckpoint.h"
27 #include "lldb/Target/StackFrameList.h"
28 #include "lldb/Utility/StructuredData.h"
29 #include "lldb/Utility/UserID.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 std::vector<lldb::ThreadPlanSP> m_completed_plan_stack;
130 lldb::RegisterCheckpointSP
131 register_backup_sp; // You need to restore the registers, of course...
132 uint32_t current_inlined_depth;
133 lldb::addr_t current_inlined_pc;
136 //------------------------------------------------------------------
139 /// @param [in] process
143 /// @param [in] use_invalid_index_id
144 /// Optional parameter, defaults to false. The only subclass that
145 /// is likely to set use_invalid_index_id == true is the HistoryThread
146 /// class. In that case, the Thread we are constructing represents
147 /// a thread from earlier in the program execution. We may have the
148 /// tid of the original thread that they represent but we don't want
149 /// to reuse the IndexID of that thread, or create a new one. If a
150 /// client wants to know the original thread's IndexID, they should use
151 /// Thread::GetExtendedBacktraceOriginatingIndexID().
152 //------------------------------------------------------------------
153 Thread(Process &process, lldb::tid_t tid, bool use_invalid_index_id = false);
157 static void SettingsInitialize();
159 static void SettingsTerminate();
161 static const ThreadPropertiesSP &GetGlobalProperties();
163 lldb::ProcessSP GetProcess() const { return m_process_wp.lock(); }
165 int GetResumeSignal() const { return m_resume_signal; }
167 void SetResumeSignal(int signal) { m_resume_signal = signal; }
169 lldb::StateType GetState() const;
171 void SetState(lldb::StateType state);
173 //------------------------------------------------------------------
174 /// Sets the USER resume state for this thread. If you set a thread to
176 /// this API, it won't take part in any of the arbitration for ShouldResume,
178 /// suspended even when other threads do get to run.
180 /// N.B. This is not the state that is used internally by thread plans to
182 /// staying on one thread while stepping over a breakpoint, etc. The is the
183 /// TemporaryResume state, and if you are implementing some bit of strategy in
185 /// machinery you should be using that state and not the user resume state.
187 /// If you are just preparing all threads to run, you should not override the
189 /// marked as suspended by the debugger. In that case, pass override_suspend
190 /// = false. If you want
191 /// to force the thread to run (e.g. the "thread continue" command, or are
192 /// resetting the state
193 /// (e.g. in SBThread::Resume()), then pass true to override_suspend.
195 /// The User resume state for this thread.
196 //------------------------------------------------------------------
197 void SetResumeState(lldb::StateType state, bool override_suspend = false) {
198 if (m_resume_state == lldb::eStateSuspended && !override_suspend)
200 m_resume_state = state;
203 //------------------------------------------------------------------
204 /// Gets the USER resume state for this thread. This is not the same as what
205 /// this thread is going to do for any particular step, however if this thread
206 /// returns eStateSuspended, then the process control logic will never allow
211 /// The User resume state for this thread.
212 //------------------------------------------------------------------
213 lldb::StateType GetResumeState() const { return m_resume_state; }
215 // This function is called on all the threads before "ShouldResume" and
216 // "WillResume" in case a thread needs to change its state before the
217 // ThreadList polls all the threads to figure out which ones actually
218 // will get to run and how.
219 void SetupForResume();
221 // Do not override this function, it is for thread plan logic only
222 bool ShouldResume(lldb::StateType resume_state);
224 // Override this to do platform specific tasks before resume.
225 virtual void WillResume(lldb::StateType resume_state) {}
227 // This clears generic thread state after a resume. If you subclass this,
228 // be sure to call it.
229 virtual void DidResume();
231 // This notifies the thread when a private stop occurs.
232 virtual void DidStop();
234 virtual void RefreshStateAfterStop() = 0;
238 bool ShouldStop(Event *event_ptr);
240 Vote ShouldReportStop(Event *event_ptr);
242 Vote ShouldReportRun(Event *event_ptr);
246 // Return whether this thread matches the specification in ThreadSpec. This
248 // method because at some point we may extend the thread spec with a platform
250 // dictionary of attributes, which then only the platform specific Thread
252 // would know how to match. For now, this just calls through to the
254 // ThreadPassesBasicTests method.
255 virtual bool MatchesSpec(const ThreadSpec *spec);
257 lldb::StopInfoSP GetStopInfo();
259 lldb::StopReason GetStopReason();
261 bool StopInfoIsUpToDate() const;
263 // This sets the stop reason to a "blank" stop reason, so you can call
264 // functions on the thread
265 // without having the called function run with whatever stop reason you
267 void SetStopInfoToNothing();
269 bool ThreadStoppedForAReason();
271 static const char *RunModeAsCString(lldb::RunMode mode);
273 static const char *StopReasonAsCString(lldb::StopReason reason);
275 virtual const char *GetInfo() { return nullptr; }
277 //------------------------------------------------------------------
278 /// Retrieve a dictionary of information about this thread
280 /// On Mac OS X systems there may be voucher information.
281 /// The top level dictionary returned will have an "activity" key and the
282 /// value of the activity is a dictionary. Keys in that dictionary will
283 /// be "name" and "id", among others.
284 /// There may also be "trace_messages" (an array) with each entry in that
286 /// being a dictionary (keys include "message" with the text of the trace
288 //------------------------------------------------------------------
289 StructuredData::ObjectSP GetExtendedInfo() {
290 if (m_extended_info_fetched == false) {
291 m_extended_info = FetchThreadExtendedInfo();
292 m_extended_info_fetched = true;
294 return m_extended_info;
297 virtual const char *GetName() { return nullptr; }
299 virtual void SetName(const char *name) {}
301 //------------------------------------------------------------------
302 /// Whether this thread can be associated with a libdispatch queue
304 /// The Thread may know if it is associated with a libdispatch queue,
305 /// it may know definitively that it is NOT associated with a libdispatch
306 /// queue, or it may be unknown whether it is associated with a libdispatch
310 /// eLazyBoolNo if this thread is definitely not associated with a
311 /// libdispatch queue (e.g. on a non-Darwin system where GCD aka
312 /// libdispatch is not available).
314 /// eLazyBoolYes this thread is associated with a libdispatch queue.
316 /// eLazyBoolCalculate this thread may be associated with a libdispatch
317 /// queue but the thread doesn't know one way or the other.
318 //------------------------------------------------------------------
319 virtual lldb_private::LazyBool GetAssociatedWithLibdispatchQueue() {
323 virtual void SetAssociatedWithLibdispatchQueue(
324 lldb_private::LazyBool associated_with_libdispatch_queue) {}
326 //------------------------------------------------------------------
327 /// Retrieve the Queue ID for the queue currently using this Thread
329 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
330 /// retrieve the QueueID.
332 /// This is a unique identifier for the libdispatch/GCD queue in a
333 /// process. Often starting at 1 for the initial system-created
334 /// queues and incrementing, a QueueID will not be reused for a
335 /// different queue during the lifetime of a process.
338 /// A QueueID if the Thread subclass implements this, else
339 /// LLDB_INVALID_QUEUE_ID.
340 //------------------------------------------------------------------
341 virtual lldb::queue_id_t GetQueueID() { return LLDB_INVALID_QUEUE_ID; }
343 virtual void SetQueueID(lldb::queue_id_t new_val) {}
345 //------------------------------------------------------------------
346 /// Retrieve the Queue name for the queue currently using this Thread
348 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
349 /// retrieve the Queue name.
352 /// The Queue name, if the Thread subclass implements this, else
354 //------------------------------------------------------------------
355 virtual const char *GetQueueName() { return nullptr; }
357 virtual void SetQueueName(const char *name) {}
359 //------------------------------------------------------------------
360 /// Retrieve the Queue kind for the queue currently using this Thread
362 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
363 /// retrieve the Queue kind - either eQueueKindSerial or
364 /// eQueueKindConcurrent, indicating that this queue processes work
365 /// items serially or concurrently.
368 /// The Queue kind, if the Thread subclass implements this, else
369 /// eQueueKindUnknown.
370 //------------------------------------------------------------------
371 virtual lldb::QueueKind GetQueueKind() { return lldb::eQueueKindUnknown; }
373 virtual void SetQueueKind(lldb::QueueKind kind) {}
375 //------------------------------------------------------------------
376 /// Retrieve the Queue for this thread, if any.
379 /// A QueueSP for the queue that is currently associated with this
381 /// An empty shared pointer indicates that this thread is not
382 /// associated with a queue, or libdispatch queues are not
383 /// supported on this target.
384 //------------------------------------------------------------------
385 virtual lldb::QueueSP GetQueue() { return lldb::QueueSP(); }
387 //------------------------------------------------------------------
388 /// Retrieve the address of the libdispatch_queue_t struct for queue
389 /// currently using this Thread
391 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
392 /// retrieve the address of the libdispatch_queue_t structure describing
395 /// This address may be reused for different queues later in the Process
396 /// lifetime and should not be used to identify a queue uniquely. Use
397 /// the GetQueueID() call for that.
400 /// The Queue's libdispatch_queue_t address if the Thread subclass
401 /// implements this, else LLDB_INVALID_ADDRESS.
402 //------------------------------------------------------------------
403 virtual lldb::addr_t GetQueueLibdispatchQueueAddress() {
404 return LLDB_INVALID_ADDRESS;
407 virtual void SetQueueLibdispatchQueueAddress(lldb::addr_t dispatch_queue_t) {}
409 //------------------------------------------------------------------
410 /// Whether this Thread already has all the Queue information cached or not
412 /// A Thread may be associated with a libdispatch work Queue at a given
413 /// public stop event. If so, the thread can satisify requests like
414 /// GetQueueLibdispatchQueueAddress, GetQueueKind, GetQueueName, and
416 /// either from information from the remote debug stub when it is initially
417 /// created, or it can query the SystemRuntime for that information.
419 /// This method allows the SystemRuntime to discover if a thread has this
420 /// information already, instead of calling the thread to get the information
421 /// and having the thread call the SystemRuntime again.
422 //------------------------------------------------------------------
423 virtual bool ThreadHasQueueInformation() const { return false; }
425 virtual uint32_t GetStackFrameCount() {
426 return GetStackFrameList()->GetNumFrames();
429 virtual lldb::StackFrameSP GetStackFrameAtIndex(uint32_t idx) {
430 return GetStackFrameList()->GetFrameAtIndex(idx);
433 virtual lldb::StackFrameSP
434 GetFrameWithConcreteFrameIndex(uint32_t unwind_idx);
436 bool DecrementCurrentInlinedDepth() {
437 return GetStackFrameList()->DecrementCurrentInlinedDepth();
440 uint32_t GetCurrentInlinedDepth() {
441 return GetStackFrameList()->GetCurrentInlinedDepth();
444 Status ReturnFromFrameWithIndex(uint32_t frame_idx,
445 lldb::ValueObjectSP return_value_sp,
446 bool broadcast = false);
448 Status ReturnFromFrame(lldb::StackFrameSP frame_sp,
449 lldb::ValueObjectSP return_value_sp,
450 bool broadcast = false);
452 Status JumpToLine(const FileSpec &file, uint32_t line,
453 bool can_leave_function, std::string *warnings = nullptr);
455 virtual lldb::StackFrameSP GetFrameWithStackID(const StackID &stack_id) {
456 if (stack_id.IsValid())
457 return GetStackFrameList()->GetFrameWithStackID(stack_id);
458 return lldb::StackFrameSP();
461 uint32_t GetSelectedFrameIndex() {
462 return GetStackFrameList()->GetSelectedFrameIndex();
465 lldb::StackFrameSP GetSelectedFrame();
467 uint32_t SetSelectedFrame(lldb_private::StackFrame *frame,
468 bool broadcast = false);
470 bool SetSelectedFrameByIndex(uint32_t frame_idx, bool broadcast = false);
472 bool SetSelectedFrameByIndexNoisily(uint32_t frame_idx,
473 Stream &output_stream);
475 void SetDefaultFileAndLineToSelectedFrame() {
476 GetStackFrameList()->SetDefaultFileAndLineToSelectedFrame();
479 virtual lldb::RegisterContextSP GetRegisterContext() = 0;
481 virtual lldb::RegisterContextSP
482 CreateRegisterContextForFrame(StackFrame *frame) = 0;
484 virtual void ClearStackFrames();
486 virtual bool SetBackingThread(const lldb::ThreadSP &thread_sp) {
490 virtual lldb::ThreadSP GetBackingThread() const { return lldb::ThreadSP(); }
492 virtual void ClearBackingThread() {
493 // Subclasses can use this function if a thread is actually backed by
494 // another thread. This is currently used for the OperatingSystem plug-ins
495 // where they might have a thread that is in memory, yet its registers
496 // are available through the lldb_private::Thread subclass for the current
497 // lldb_private::Process class. Since each time the process stops the
499 // threads for memory threads can change, we need a way to clear the backing
500 // thread for all memory threads each time we stop.
503 // If stop_format is true, this will be the form used when we print stop info.
504 // If false, it will be the form we use for thread list and co.
505 void DumpUsingSettingsFormat(Stream &strm, uint32_t frame_idx,
508 bool GetDescription(Stream &s, lldb::DescriptionLevel level,
509 bool print_json_thread, bool print_json_stopinfo);
511 //------------------------------------------------------------------
512 /// Default implementation for stepping into.
514 /// This function is designed to be used by commands where the
515 /// process is publicly stopped.
517 /// @param[in] source_step
518 /// If true and the frame has debug info, then do a source level
519 /// step in, else do a single instruction step in.
521 /// @param[in] step_in_avoids_code_without_debug_info
522 /// If \a true, then avoid stepping into code that doesn't have
523 /// debug info, else step into any code regardless of whether it
526 /// @param[in] step_out_avoids_code_without_debug_info
527 /// If \a true, then if you step out to code with no debug info, keep
528 /// stepping out till you get to code with debug info.
531 /// An error that describes anything that went wrong
532 //------------------------------------------------------------------
534 StepIn(bool source_step,
535 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
536 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
538 //------------------------------------------------------------------
539 /// Default implementation for stepping over.
541 /// This function is designed to be used by commands where the
542 /// process is publicly stopped.
544 /// @param[in] source_step
545 /// If true and the frame has debug info, then do a source level
546 /// step over, else do a single instruction step over.
549 /// An error that describes anything that went wrong
550 //------------------------------------------------------------------
551 virtual Status StepOver(
553 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
555 //------------------------------------------------------------------
556 /// Default implementation for stepping out.
558 /// This function is designed to be used by commands where the
559 /// process is publicly stopped.
562 /// An error that describes anything that went wrong
563 //------------------------------------------------------------------
564 virtual Status StepOut();
566 //------------------------------------------------------------------
567 /// Retrieves the per-thread data area.
568 /// Most OSs maintain a per-thread pointer (e.g. the FS register on
569 /// x64), which we return the value of here.
572 /// LLDB_INVALID_ADDRESS if not supported, otherwise the thread
574 //------------------------------------------------------------------
575 virtual lldb::addr_t GetThreadPointer();
577 //------------------------------------------------------------------
578 /// Retrieves the per-module TLS block for a thread.
580 /// @param[in] module
581 /// The module to query TLS data for.
583 /// @param[in] tls_file_addr
584 /// The thread local address in module
586 /// If the thread has TLS data allocated for the
587 /// module, the address of the TLS block. Otherwise
588 /// LLDB_INVALID_ADDRESS is returned.
589 //------------------------------------------------------------------
590 virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module,
591 lldb::addr_t tls_file_addr);
593 //------------------------------------------------------------------
594 /// Check whether this thread is safe to run functions
596 /// The SystemRuntime may know of certain thread states (functions in
597 /// process of execution, for instance) which can make it unsafe for
598 /// functions to be called.
601 /// True if it is safe to call functions on this thread.
602 /// False if function calls should be avoided on this thread.
603 //------------------------------------------------------------------
604 virtual bool SafeToCallFunctions();
606 //------------------------------------------------------------------
607 // Thread Plan Providers:
608 // This section provides the basic thread plans that the Process control
609 // machinery uses to run the target. ThreadPlan.h provides more details on
610 // how this mechanism works.
611 // The thread provides accessors to a set of plans that perform basic
613 // The idea is that particular Platform plugins can override these methods to
614 // provide the implementation of these basic operations appropriate to their
617 // NB: All the QueueThreadPlanXXX providers return Shared Pointers to
618 // Thread plans. This is useful so that you can modify the plans after
619 // creation in ways specific to that plan type. Also, it is often necessary
621 // ThreadPlans that utilize other ThreadPlans to implement their task to keep
623 // pointer to the sub-plan.
624 // But besides that, the shared pointers should only be held onto by entities
625 // who live no longer
626 // than the thread containing the ThreadPlan.
627 // FIXME: If this becomes a problem, we can make a version that just returns a
629 // which it is clearly unsafe to hold onto, and a shared pointer version, and
631 // ThreadPlan and Co. to use the latter. That is made more annoying to do
633 // no elegant way to friend a method to all sub-classes of a given class.
635 //------------------------------------------------------------------
637 //------------------------------------------------------------------
638 /// Queues the base plan for a thread.
639 /// The version returned by Process does some things that are useful,
640 /// like handle breakpoints and signals, so if you return a plugin specific
641 /// one you probably want to call through to the Process one for anything
642 /// your plugin doesn't explicitly handle.
644 /// @param[in] abort_other_plans
645 /// \b true if we discard the currently queued plans and replace them with
647 /// Otherwise this plan will go on the end of the plan stack.
650 /// A shared pointer to the newly queued thread plan, or nullptr if the
651 /// plan could not be queued.
652 //------------------------------------------------------------------
653 virtual lldb::ThreadPlanSP QueueFundamentalPlan(bool abort_other_plans);
655 //------------------------------------------------------------------
656 /// Queues the plan used to step one instruction from the current PC of \a
659 /// @param[in] step_over
660 /// \b true if we step over calls to functions, false if we step in.
662 /// @param[in] abort_other_plans
663 /// \b true if we discard the currently queued plans and replace them with
665 /// Otherwise this plan will go on the end of the plan stack.
667 /// @param[in] stop_other_threads
668 /// \b true if we will stop other threads while we single step this one.
671 /// A shared pointer to the newly queued thread plan, or nullptr if the
672 /// plan could not be queued.
673 //------------------------------------------------------------------
674 virtual lldb::ThreadPlanSP QueueThreadPlanForStepSingleInstruction(
675 bool step_over, bool abort_other_plans, bool stop_other_threads);
677 //------------------------------------------------------------------
678 /// Queues the plan used to step through an address range, stepping over
681 /// @param[in] abort_other_plans
682 /// \b true if we discard the currently queued plans and replace them with
684 /// Otherwise this plan will go on the end of the plan stack.
687 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
691 /// The address range to step through.
693 /// @param[in] addr_context
694 /// When dealing with stepping through inlined functions the current PC is
695 /// not enough information to know
696 /// what "step" means. For instance a series of nested inline functions
697 /// might start at the same address.
698 // The \a addr_context provides the current symbol context the step
699 /// is supposed to be out of.
700 // FIXME: Currently unused.
702 /// @param[in] stop_other_threads
703 /// \b true if we will stop other threads while we single step this one.
705 /// @param[in] step_out_avoids_code_without_debug_info
706 /// If eLazyBoolYes, if the step over steps out it will continue to step
707 /// out till it comes to a frame with debug info.
708 /// If eLazyBoolCalculate, we will consult the default set in the thread.
711 /// A shared pointer to the newly queued thread plan, or nullptr if the
712 /// plan could not be queued.
713 //------------------------------------------------------------------
714 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
715 bool abort_other_plans, const AddressRange &range,
716 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
717 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
719 // Helper function that takes a LineEntry to step, insted of an AddressRange.
720 // This may combine multiple
721 // LineEntries of the same source line number to step over a longer address
722 // range in a single operation.
723 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
724 bool abort_other_plans, const LineEntry &line_entry,
725 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
726 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
728 //------------------------------------------------------------------
729 /// Queues the plan used to step through an address range, stepping into
732 /// @param[in] abort_other_plans
733 /// \b true if we discard the currently queued plans and replace them with
735 /// Otherwise this plan will go on the end of the plan stack.
738 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
742 /// The address range to step through.
744 /// @param[in] addr_context
745 /// When dealing with stepping through inlined functions the current PC is
746 /// not enough information to know
747 /// what "step" means. For instance a series of nested inline functions
748 /// might start at the same address.
749 // The \a addr_context provides the current symbol context the step
750 /// is supposed to be out of.
751 // FIXME: Currently unused.
753 /// @param[in] step_in_target
754 /// Name if function we are trying to step into. We will step out if we
755 /// don't land in that function.
757 /// @param[in] stop_other_threads
758 /// \b true if we will stop other threads while we single step this one.
760 /// @param[in] step_in_avoids_code_without_debug_info
761 /// If eLazyBoolYes we will step out if we step into code with no debug
763 /// If eLazyBoolCalculate we will consult the default set in the thread.
765 /// @param[in] step_out_avoids_code_without_debug_info
766 /// If eLazyBoolYes, if the step over steps out it will continue to step
767 /// out till it comes to a frame with debug info.
768 /// If eLazyBoolCalculate, it will consult the default set in the thread.
771 /// A shared pointer to the newly queued thread plan, or nullptr if the
772 /// plan could not be queued.
773 //------------------------------------------------------------------
774 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
775 bool abort_other_plans, const AddressRange &range,
776 const SymbolContext &addr_context, const char *step_in_target,
777 lldb::RunMode stop_other_threads,
778 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
779 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
781 // Helper function that takes a LineEntry to step, insted of an AddressRange.
782 // This may combine multiple
783 // LineEntries of the same source line number to step over a longer address
784 // range in a single operation.
785 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
786 bool abort_other_plans, const LineEntry &line_entry,
787 const SymbolContext &addr_context, const char *step_in_target,
788 lldb::RunMode stop_other_threads,
789 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
790 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
792 //------------------------------------------------------------------
793 /// Queue the plan used to step out of the function at the current PC of
796 /// @param[in] abort_other_plans
797 /// \b true if we discard the currently queued plans and replace them with
799 /// Otherwise this plan will go on the end of the plan stack.
801 /// @param[in] addr_context
802 /// When dealing with stepping through inlined functions the current PC is
803 /// not enough information to know
804 /// what "step" means. For instance a series of nested inline functions
805 /// might start at the same address.
806 // The \a addr_context provides the current symbol context the step
807 /// is supposed to be out of.
808 // FIXME: Currently unused.
810 /// @param[in] first_insn
811 /// \b true if this is the first instruction of a function.
813 /// @param[in] stop_other_threads
814 /// \b true if we will stop other threads while we single step this one.
816 /// @param[in] stop_vote
817 /// @param[in] run_vote
818 /// See standard meanings for the stop & run votes in ThreadPlan.h.
820 /// @param[in] step_out_avoids_code_without_debug_info
821 /// If eLazyBoolYes, if the step over steps out it will continue to step
822 /// out till it comes to a frame with debug info.
823 /// If eLazyBoolCalculate, it will consult the default set in the thread.
826 /// A shared pointer to the newly queued thread plan, or nullptr if the
827 /// plan could not be queued.
828 //------------------------------------------------------------------
829 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOut(
830 bool abort_other_plans, SymbolContext *addr_context, bool first_insn,
831 bool stop_other_threads,
832 Vote stop_vote, // = eVoteYes,
833 Vote run_vote, // = eVoteNoOpinion);
835 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
837 //------------------------------------------------------------------
838 /// Queue the plan used to step out of the function at the current PC of
839 /// a thread. This version does not consult the should stop here callback,
841 /// be used by other thread plans when they need to retain control of the step
844 /// @param[in] abort_other_plans
845 /// \b true if we discard the currently queued plans and replace them with
847 /// Otherwise this plan will go on the end of the plan stack.
849 /// @param[in] addr_context
850 /// When dealing with stepping through inlined functions the current PC is
851 /// not enough information to know
852 /// what "step" means. For instance a series of nested inline functions
853 /// might start at the same address.
854 // The \a addr_context provides the current symbol context the step
855 /// is supposed to be out of.
856 // FIXME: Currently unused.
858 /// @param[in] first_insn
859 /// \b true if this is the first instruction of a function.
861 /// @param[in] stop_other_threads
862 /// \b true if we will stop other threads while we single step this one.
864 /// @param[in] stop_vote
865 /// @param[in] run_vote
866 /// See standard meanings for the stop & run votes in ThreadPlan.h.
868 /// @param[in] continue_to_next_branch
869 /// Normally this will enqueue a plan that will put a breakpoint on the
870 /// return address and continue
871 /// to there. If continue_to_next_branch is true, this is an operation not
872 /// involving the user --
873 /// e.g. stepping "next" in a source line and we instruction stepped into
874 /// another function --
875 /// so instead of putting a breakpoint on the return address, advance the
876 /// breakpoint to the
877 /// end of the source line that is doing the call, or until the next flow
878 /// control instruction.
879 /// If the return value from the function call is to be retrieved /
880 /// displayed to the user, you must stop
881 /// on the return address. The return value may be stored in volatile
882 /// registers which are overwritten
883 /// before the next branch instruction.
886 /// A shared pointer to the newly queued thread plan, or nullptr if the
887 /// plan could not be queued.
888 //------------------------------------------------------------------
889 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOutNoShouldStop(
890 bool abort_other_plans, SymbolContext *addr_context, bool first_insn,
891 bool stop_other_threads,
892 Vote stop_vote, // = eVoteYes,
893 Vote run_vote, // = eVoteNoOpinion);
894 uint32_t frame_idx, bool continue_to_next_branch = false);
896 //------------------------------------------------------------------
897 /// Gets the plan used to step through the code that steps from a function
898 /// call site at the current PC into the actual function call.
901 /// @param[in] return_stack_id
902 /// The stack id that we will return to (by setting backstop breakpoints on
904 /// address to that frame) if we fail to step through.
906 /// @param[in] abort_other_plans
907 /// \b true if we discard the currently queued plans and replace them with
909 /// Otherwise this plan will go on the end of the plan stack.
911 /// @param[in] stop_other_threads
912 /// \b true if we will stop other threads while we single step this one.
915 /// A shared pointer to the newly queued thread plan, or nullptr if the
916 /// plan could not be queued.
917 //------------------------------------------------------------------
918 virtual lldb::ThreadPlanSP
919 QueueThreadPlanForStepThrough(StackID &return_stack_id,
920 bool abort_other_plans,
921 bool stop_other_threads);
923 //------------------------------------------------------------------
924 /// Gets the plan used to continue from the current PC.
925 /// This is a simple plan, mostly useful as a backstop when you are continuing
926 /// for some particular purpose.
928 /// @param[in] abort_other_plans
929 /// \b true if we discard the currently queued plans and replace them with
931 /// Otherwise this plan will go on the end of the plan stack.
933 /// @param[in] target_addr
934 /// The address to which we're running.
936 /// @param[in] stop_other_threads
937 /// \b true if we will stop other threads while we single step this one.
940 /// A shared pointer to the newly queued thread plan, or nullptr if the
941 /// plan could not be queued.
942 //------------------------------------------------------------------
943 virtual lldb::ThreadPlanSP
944 QueueThreadPlanForRunToAddress(bool abort_other_plans, Address &target_addr,
945 bool stop_other_threads);
947 virtual lldb::ThreadPlanSP
948 QueueThreadPlanForStepUntil(bool abort_other_plans,
949 lldb::addr_t *address_list, size_t num_addresses,
950 bool stop_others, uint32_t frame_idx);
952 virtual lldb::ThreadPlanSP
953 QueueThreadPlanForStepScripted(bool abort_other_plans, const char *class_name,
954 bool stop_other_threads);
956 //------------------------------------------------------------------
957 // Thread Plan accessors:
958 //------------------------------------------------------------------
960 //------------------------------------------------------------------
961 /// Gets the plan which will execute next on the plan stack.
964 /// A pointer to the next executed plan.
965 //------------------------------------------------------------------
966 ThreadPlan *GetCurrentPlan();
968 //------------------------------------------------------------------
969 /// Unwinds the thread stack for the innermost expression plan currently
970 /// on the thread plan stack.
973 /// An error if the thread plan could not be unwound.
974 //------------------------------------------------------------------
976 Status UnwindInnermostExpression();
978 //------------------------------------------------------------------
979 /// Gets the outer-most plan that was popped off the plan stack in the
980 /// most recent stop. Useful for printing the stop reason accurately.
983 /// A pointer to the last completed plan.
984 //------------------------------------------------------------------
985 lldb::ThreadPlanSP GetCompletedPlan();
987 //------------------------------------------------------------------
988 /// Gets the outer-most return value from the completed plans
991 /// A ValueObjectSP, either empty if there is no return value,
992 /// or containing the return value.
993 //------------------------------------------------------------------
994 lldb::ValueObjectSP GetReturnValueObject();
996 //------------------------------------------------------------------
997 /// Gets the outer-most expression variable from the completed plans
1000 /// A ExpressionVariableSP, either empty if there is no
1001 /// plan completed an expression during the current stop
1002 /// or the expression variable that was made for the completed expression.
1003 //------------------------------------------------------------------
1004 lldb::ExpressionVariableSP GetExpressionVariable();
1006 //------------------------------------------------------------------
1007 /// Checks whether the given plan is in the completed plans for this
1011 /// Pointer to the plan you're checking.
1014 /// Returns true if the input plan is in the completed plan stack,
1015 /// false otherwise.
1016 //------------------------------------------------------------------
1017 bool IsThreadPlanDone(ThreadPlan *plan);
1019 //------------------------------------------------------------------
1020 /// Checks whether the given plan is in the discarded plans for this
1024 /// Pointer to the plan you're checking.
1027 /// Returns true if the input plan is in the discarded plan stack,
1028 /// false otherwise.
1029 //------------------------------------------------------------------
1030 bool WasThreadPlanDiscarded(ThreadPlan *plan);
1032 //------------------------------------------------------------------
1033 /// Check if we have completed plan to override breakpoint stop reason
1036 /// Returns true if completed plan stack is not empty
1037 /// false otherwise.
1038 //------------------------------------------------------------------
1039 bool CompletedPlanOverridesBreakpoint();
1041 //------------------------------------------------------------------
1042 /// Queues a generic thread plan.
1044 /// @param[in] plan_sp
1045 /// The plan to queue.
1047 /// @param[in] abort_other_plans
1048 /// \b true if we discard the currently queued plans and replace them with
1050 /// Otherwise this plan will go on the end of the plan stack.
1053 /// A pointer to the last completed plan.
1054 //------------------------------------------------------------------
1055 void QueueThreadPlan(lldb::ThreadPlanSP &plan_sp, bool abort_other_plans);
1057 //------------------------------------------------------------------
1058 /// Discards the plans queued on the plan stack of the current thread. This
1060 /// arbitrated by the "Master" ThreadPlans, using the "OkayToDiscard" call.
1061 // But if \a force is true, all thread plans are discarded.
1062 //------------------------------------------------------------------
1063 void DiscardThreadPlans(bool force);
1065 //------------------------------------------------------------------
1066 /// Discards the plans queued on the plan stack of the current thread up to
1068 /// including up_to_plan_sp.
1070 // @param[in] up_to_plan_sp
1071 // Discard all plans up to and including this one.
1072 //------------------------------------------------------------------
1073 void DiscardThreadPlansUpToPlan(lldb::ThreadPlanSP &up_to_plan_sp);
1075 void DiscardThreadPlansUpToPlan(ThreadPlan *up_to_plan_ptr);
1077 //------------------------------------------------------------------
1078 /// Discards the plans queued on the plan stack of the current thread up to
1080 /// including the plan in that matches \a thread_index counting only
1081 /// the non-Private plans.
1083 /// @param[in] up_to_plan_sp
1084 /// Discard all plans up to and including this user plan given by this
1088 /// \b true if there was a thread plan with that user index, \b false
1090 //------------------------------------------------------------------
1091 bool DiscardUserThreadPlansUpToIndex(uint32_t thread_index);
1093 //------------------------------------------------------------------
1094 /// Prints the current plan stack.
1097 /// The stream to which to dump the plan stack info.
1099 //------------------------------------------------------------------
1100 void DumpThreadPlans(
1102 lldb::DescriptionLevel desc_level = lldb::eDescriptionLevelVerbose,
1103 bool include_internal = true, bool ignore_boring = false) const;
1105 virtual bool CheckpointThreadState(ThreadStateCheckpoint &saved_state);
1108 RestoreRegisterStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1111 RestoreThreadStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1113 void EnableTracer(bool value, bool single_step);
1115 void SetTracer(lldb::ThreadPlanTracerSP &tracer_sp);
1117 //------------------------------------------------------------------
1118 // Get the thread index ID. The index ID that is guaranteed to not
1119 // be re-used by a process. They start at 1 and increase with each
1120 // new thread. This allows easy command line access by a unique ID
1121 // that is easier to type than the actual system thread ID.
1122 //------------------------------------------------------------------
1123 uint32_t GetIndexID() const;
1125 //------------------------------------------------------------------
1126 // Get the originating thread's index ID.
1127 // In the case of an "extended" thread -- a thread which represents
1128 // the stack that enqueued/spawned work that is currently executing --
1129 // we need to provide the IndexID of the thread that actually did
1130 // this work. We don't want to just masquerade as that thread's IndexID
1131 // by using it in our own IndexID because that way leads to madness -
1132 // but the driver program which is iterating over extended threads
1133 // may ask for the OriginatingThreadID to display that information
1135 // Normal threads will return the same thing as GetIndexID();
1136 //------------------------------------------------------------------
1137 virtual uint32_t GetExtendedBacktraceOriginatingIndexID() {
1138 return GetIndexID();
1141 //------------------------------------------------------------------
1142 // The API ID is often the same as the Thread::GetID(), but not in
1143 // all cases. Thread::GetID() is the user visible thread ID that
1144 // clients would want to see. The API thread ID is the thread ID
1145 // that is used when sending data to/from the debugging protocol.
1146 //------------------------------------------------------------------
1147 virtual lldb::user_id_t GetProtocolID() const { return GetID(); }
1149 //------------------------------------------------------------------
1150 // lldb::ExecutionContextScope pure virtual functions
1151 //------------------------------------------------------------------
1152 lldb::TargetSP CalculateTarget() override;
1154 lldb::ProcessSP CalculateProcess() override;
1156 lldb::ThreadSP CalculateThread() override;
1158 lldb::StackFrameSP CalculateStackFrame() override;
1160 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
1163 GetStackFrameSPForStackFramePtr(StackFrame *stack_frame_ptr);
1165 size_t GetStatus(Stream &strm, uint32_t start_frame, uint32_t num_frames,
1166 uint32_t num_frames_with_source, bool stop_format,
1167 bool only_stacks = false);
1169 size_t GetStackFrameStatus(Stream &strm, uint32_t first_frame,
1170 uint32_t num_frames, bool show_frame_info,
1171 uint32_t num_frames_with_source);
1173 // We need a way to verify that even though we have a thread in a shared
1174 // pointer that the object itself is still valid. Currently this won't be
1175 // the case if DestroyThread() was called. DestroyThread is called when
1176 // a thread has been removed from the Process' thread list.
1177 bool IsValid() const { return !m_destroy_called; }
1179 // Sets and returns a valid stop info based on the process stop ID and the
1180 // current thread plan. If the thread stop ID does not match the process'
1181 // stop ID, the private stop reason is not set and an invalid StopInfoSP may
1184 // NOTE: This function must be called before the current thread plan is
1185 // moved to the completed plan stack (in Thread::ShouldStop()).
1187 // NOTE: If subclasses override this function, ensure they do not overwrite
1188 // the m_actual_stop_info if it is valid. The stop info may be a
1189 // "checkpointed and restored" stop info, so if it is still around it is
1190 // right even if you have not calculated this yourself, or if it disagrees
1191 // with what you might have calculated.
1192 virtual lldb::StopInfoSP GetPrivateStopInfo();
1194 //----------------------------------------------------------------------
1195 // Ask the thread subclass to set its stop info.
1197 // Thread subclasses should call Thread::SetStopInfo(...) with the
1198 // reason the thread stopped.
1201 // True if Thread::SetStopInfo(...) was called, false otherwise.
1202 //----------------------------------------------------------------------
1203 virtual bool CalculateStopInfo() = 0;
1205 //----------------------------------------------------------------------
1206 // Gets the temporary resume state for a thread.
1208 // This value gets set in each thread by complex debugger logic in
1209 // Thread::ShouldResume() and an appropriate thread resume state will get
1210 // set in each thread every time the process is resumed prior to calling
1211 // Process::DoResume(). The lldb_private::Process subclass should adhere
1212 // to the thread resume state request which will be one of:
1214 // eStateRunning - thread will resume when process is resumed
1215 // eStateStepping - thread should step 1 instruction and stop when process
1217 // eStateSuspended - thread should not execute any instructions when
1218 // process is resumed
1219 //----------------------------------------------------------------------
1220 lldb::StateType GetTemporaryResumeState() const {
1221 return m_temporary_resume_state;
1224 void SetStopInfo(const lldb::StopInfoSP &stop_info_sp);
1226 void ResetStopInfo();
1228 void SetShouldReportStop(Vote vote);
1230 //----------------------------------------------------------------------
1231 /// Sets the extended backtrace token for this thread
1233 /// Some Thread subclasses may maintain a token to help with providing
1234 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1236 /// @param [in] token
1237 //----------------------------------------------------------------------
1238 virtual void SetExtendedBacktraceToken(uint64_t token) {}
1240 //----------------------------------------------------------------------
1241 /// Gets the extended backtrace token for this thread
1243 /// Some Thread subclasses may maintain a token to help with providing
1244 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1247 /// The token needed by the SystemRuntime to create an extended backtrace.
1248 /// LLDB_INVALID_ADDRESS is returned if no token is available.
1249 //----------------------------------------------------------------------
1250 virtual uint64_t GetExtendedBacktraceToken() { return LLDB_INVALID_ADDRESS; }
1253 friend class ThreadPlan;
1254 friend class ThreadList;
1255 friend class ThreadEventData;
1256 friend class StackFrameList;
1257 friend class StackFrame;
1258 friend class OperatingSystem;
1260 // This is necessary to make sure thread assets get destroyed while the thread
1261 // is still in good shape
1262 // to call virtual thread methods. This must be called by classes that derive
1263 // from Thread in their destructor.
1264 virtual void DestroyThread();
1266 void PushPlan(lldb::ThreadPlanSP &plan_sp);
1272 ThreadPlan *GetPreviousPlan(ThreadPlan *plan);
1274 typedef std::vector<lldb::ThreadPlanSP> plan_stack;
1276 virtual lldb_private::Unwind *GetUnwinder();
1278 // Check to see whether the thread is still at the last breakpoint hit that
1280 virtual bool IsStillAtLastBreakpointHit();
1282 // Some threads are threads that are made up by OperatingSystem plugins that
1283 // are threads that exist and are context switched out into memory. The
1284 // OperatingSystem plug-in need a ways to know if a thread is "real" or made
1286 virtual bool IsOperatingSystemPluginThread() const { return false; }
1288 // Subclasses that have a way to get an extended info dictionary for this
1291 virtual lldb_private::StructuredData::ObjectSP FetchThreadExtendedInfo() {
1292 return StructuredData::ObjectSP();
1295 lldb::StackFrameListSP GetStackFrameList();
1297 void SetTemporaryResumeState(lldb::StateType new_state) {
1298 m_temporary_resume_state = new_state;
1301 void FunctionOptimizationWarning(lldb_private::StackFrame *frame);
1303 //------------------------------------------------------------------
1304 // Classes that inherit from Process can see and modify these
1305 //------------------------------------------------------------------
1306 lldb::ProcessWP m_process_wp; ///< The process that owns this thread.
1307 lldb::StopInfoSP m_stop_info_sp; ///< The private stop reason for this thread
1308 uint32_t m_stop_info_stop_id; // This is the stop id for which the StopInfo is
1309 // valid. Can use this so you know that
1310 // the thread's m_stop_info_sp is current and you don't have to fetch it again
1311 uint32_t m_stop_info_override_stop_id; // The stop ID containing the last time
1312 // the stop info was checked against
1313 // the stop info override
1314 const uint32_t m_index_id; ///< A unique 1 based index assigned to each thread
1315 ///for easy UI/command line access.
1316 lldb::RegisterContextSP m_reg_context_sp; ///< The register context for this
1317 ///thread's current register state.
1318 lldb::StateType m_state; ///< The state of our process.
1319 mutable std::recursive_mutex
1320 m_state_mutex; ///< Multithreaded protection for m_state.
1321 plan_stack m_plan_stack; ///< The stack of plans this thread is executing.
1322 plan_stack m_completed_plan_stack; ///< Plans that have been completed by this
1323 ///stop. They get deleted when the thread
1325 plan_stack m_discarded_plan_stack; ///< Plans that have been discarded by this
1326 ///stop. They get deleted when the thread
1328 mutable std::recursive_mutex
1329 m_frame_mutex; ///< Multithreaded protection for m_state.
1330 lldb::StackFrameListSP m_curr_frames_sp; ///< The stack frames that get lazily
1331 ///populated after a thread stops.
1332 lldb::StackFrameListSP m_prev_frames_sp; ///< The previous stack frames from
1333 ///the last time this thread stopped.
1334 int m_resume_signal; ///< The signal that should be used when continuing this
1336 lldb::StateType m_resume_state; ///< This state is used to force a thread to
1337 ///be suspended from outside the ThreadPlan
1339 lldb::StateType m_temporary_resume_state; ///< This state records what the
1340 ///thread was told to do by the
1341 ///thread plan logic for the current
1343 /// It gets set in Thread::ShouldResume.
1344 std::unique_ptr<lldb_private::Unwind> m_unwinder_ap;
1345 bool m_destroy_called; // This is used internally to make sure derived Thread
1346 // classes call DestroyThread.
1347 LazyBool m_override_should_notify;
1350 bool m_extended_info_fetched; // Have we tried to retrieve the m_extended_info
1352 StructuredData::ObjectSP m_extended_info; // The extended info for this thread
1355 bool PlanIsBasePlan(ThreadPlan *plan_ptr);
1357 void BroadcastSelectedFrameChange(StackID &new_frame_id);
1359 DISALLOW_COPY_AND_ASSIGN(Thread);
1362 } // namespace lldb_private
1364 #endif // liblldb_Thread_h_