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_
18 #include "lldb/Core/UserSettingsController.h"
19 #include "lldb/Target/ExecutionContextScope.h"
20 #include "lldb/Target/RegisterCheckpoint.h"
21 #include "lldb/Target/StackFrameList.h"
22 #include "lldb/Utility/Broadcaster.h"
23 #include "lldb/Utility/Event.h"
24 #include "lldb/Utility/StructuredData.h"
25 #include "lldb/Utility/UserID.h"
26 #include "lldb/lldb-private.h"
28 #define LLDB_THREAD_MAX_STOP_EXC_DATA 8
30 namespace lldb_private {
32 class ThreadProperties : public Properties {
34 ThreadProperties(bool is_global);
36 ~ThreadProperties() override;
38 //------------------------------------------------------------------
39 /// The regular expression returned determines symbols that this
40 /// thread won't stop in during "step-in" operations.
43 /// A pointer to a regular expression to compare against symbols,
44 /// or nullptr if all symbols are allowed.
46 //------------------------------------------------------------------
47 const RegularExpression *GetSymbolsToAvoidRegexp();
49 FileSpecList &GetLibrariesToAvoid() const;
51 bool GetTraceEnabledState() const;
53 bool GetStepInAvoidsNoDebug() const;
55 bool GetStepOutAvoidsNoDebug() const;
57 uint64_t GetMaxBacktraceDepth() const;
60 typedef std::shared_ptr<ThreadProperties> ThreadPropertiesSP;
62 class Thread : public std::enable_shared_from_this<Thread>,
63 public ThreadProperties,
65 public ExecutionContextScope,
68 //------------------------------------------------------------------
69 /// Broadcaster event bits definitions.
70 //------------------------------------------------------------------
72 eBroadcastBitStackChanged = (1 << 0),
73 eBroadcastBitThreadSuspended = (1 << 1),
74 eBroadcastBitThreadResumed = (1 << 2),
75 eBroadcastBitSelectedFrameChanged = (1 << 3),
76 eBroadcastBitThreadSelected = (1 << 4)
79 static ConstString &GetStaticBroadcasterClass();
81 ConstString &GetBroadcasterClass() const override {
82 return GetStaticBroadcasterClass();
85 class ThreadEventData : public EventData {
87 ThreadEventData(const lldb::ThreadSP thread_sp);
89 ThreadEventData(const lldb::ThreadSP thread_sp, const StackID &stack_id);
93 ~ThreadEventData() override;
95 static const ConstString &GetFlavorString();
97 const ConstString &GetFlavor() const override {
98 return ThreadEventData::GetFlavorString();
101 void Dump(Stream *s) const override;
103 static const ThreadEventData *GetEventDataFromEvent(const Event *event_ptr);
105 static lldb::ThreadSP GetThreadFromEvent(const Event *event_ptr);
107 static StackID GetStackIDFromEvent(const Event *event_ptr);
109 static lldb::StackFrameSP GetStackFrameFromEvent(const Event *event_ptr);
111 lldb::ThreadSP GetThread() const { return m_thread_sp; }
113 StackID GetStackID() const { return m_stack_id; }
116 lldb::ThreadSP m_thread_sp;
119 DISALLOW_COPY_AND_ASSIGN(ThreadEventData);
122 struct ThreadStateCheckpoint {
123 uint32_t orig_stop_id; // Dunno if I need this yet but it is an interesting
125 lldb::StopInfoSP stop_info_sp; // You have to restore the stop info or you
126 // might continue with the wrong signals.
127 std::vector<lldb::ThreadPlanSP> m_completed_plan_stack;
128 lldb::RegisterCheckpointSP
129 register_backup_sp; // You need to restore the registers, of course...
130 uint32_t current_inlined_depth;
131 lldb::addr_t current_inlined_pc;
134 //------------------------------------------------------------------
137 /// @param [in] process
141 /// @param [in] use_invalid_index_id
142 /// Optional parameter, defaults to false. The only subclass that
143 /// is likely to set use_invalid_index_id == true is the HistoryThread
144 /// class. In that case, the Thread we are constructing represents
145 /// a thread from earlier in the program execution. We may have the
146 /// tid of the original thread that they represent but we don't want
147 /// to reuse the IndexID of that thread, or create a new one. If a
148 /// client wants to know the original thread's IndexID, they should use
149 /// Thread::GetExtendedBacktraceOriginatingIndexID().
150 //------------------------------------------------------------------
151 Thread(Process &process, lldb::tid_t tid, bool use_invalid_index_id = false);
155 static void SettingsInitialize();
157 static void SettingsTerminate();
159 static const ThreadPropertiesSP &GetGlobalProperties();
161 lldb::ProcessSP GetProcess() const { return m_process_wp.lock(); }
163 int GetResumeSignal() const { return m_resume_signal; }
165 void SetResumeSignal(int signal) { m_resume_signal = signal; }
167 lldb::StateType GetState() const;
169 void SetState(lldb::StateType state);
171 //------------------------------------------------------------------
172 /// Sets the USER resume state for this thread. If you set a thread to
174 /// this API, it won't take part in any of the arbitration for ShouldResume,
176 /// suspended even when other threads do get to run.
178 /// N.B. This is not the state that is used internally by thread plans to
180 /// staying on one thread while stepping over a breakpoint, etc. The is the
181 /// TemporaryResume state, and if you are implementing some bit of strategy in
183 /// machinery you should be using that state and not the user resume state.
185 /// If you are just preparing all threads to run, you should not override the
187 /// marked as suspended by the debugger. In that case, pass override_suspend
188 /// = false. If you want
189 /// to force the thread to run (e.g. the "thread continue" command, or are
190 /// resetting the state
191 /// (e.g. in SBThread::Resume()), then pass true to override_suspend.
193 /// The User resume state for this thread.
194 //------------------------------------------------------------------
195 void SetResumeState(lldb::StateType state, bool override_suspend = false) {
196 if (m_resume_state == lldb::eStateSuspended && !override_suspend)
198 m_resume_state = state;
201 //------------------------------------------------------------------
202 /// Gets the USER resume state for this thread. This is not the same as what
203 /// this thread is going to do for any particular step, however if this thread
204 /// returns eStateSuspended, then the process control logic will never allow
209 /// The User resume state for this thread.
210 //------------------------------------------------------------------
211 lldb::StateType GetResumeState() const { return m_resume_state; }
213 // This function is called on all the threads before "ShouldResume" and
214 // "WillResume" in case a thread needs to change its state before the
215 // ThreadList polls all the threads to figure out which ones actually will
216 // get to run and how.
217 void SetupForResume();
219 // Do not override this function, it is for thread plan logic only
220 bool ShouldResume(lldb::StateType resume_state);
222 // Override this to do platform specific tasks before resume.
223 virtual void WillResume(lldb::StateType resume_state) {}
225 // This clears generic thread state after a resume. If you subclass this, be
227 virtual void DidResume();
229 // This notifies the thread when a private stop occurs.
230 virtual void DidStop();
232 virtual void RefreshStateAfterStop() = 0;
236 bool ShouldStop(Event *event_ptr);
238 Vote ShouldReportStop(Event *event_ptr);
240 Vote ShouldReportRun(Event *event_ptr);
244 // Return whether this thread matches the specification in ThreadSpec. This
245 // is a virtual method because at some point we may extend the thread spec
246 // with a platform specific dictionary of attributes, which then only the
247 // platform specific Thread implementation would know how to match. For now,
248 // this just calls through to the ThreadSpec's ThreadPassesBasicTests method.
249 virtual bool MatchesSpec(const ThreadSpec *spec);
251 lldb::StopInfoSP GetStopInfo();
253 lldb::StopReason GetStopReason();
255 bool StopInfoIsUpToDate() const;
257 // This sets the stop reason to a "blank" stop reason, so you can call
258 // functions on the thread without having the called function run with
259 // whatever stop reason you stopped with.
260 void SetStopInfoToNothing();
262 bool ThreadStoppedForAReason();
264 static const char *RunModeAsCString(lldb::RunMode mode);
266 static const char *StopReasonAsCString(lldb::StopReason reason);
268 virtual const char *GetInfo() { return nullptr; }
270 //------------------------------------------------------------------
271 /// Retrieve a dictionary of information about this thread
273 /// On Mac OS X systems there may be voucher information.
274 /// The top level dictionary returned will have an "activity" key and the
275 /// value of the activity is a dictionary. Keys in that dictionary will
276 /// be "name" and "id", among others.
277 /// There may also be "trace_messages" (an array) with each entry in that
279 /// being a dictionary (keys include "message" with the text of the trace
281 //------------------------------------------------------------------
282 StructuredData::ObjectSP GetExtendedInfo() {
283 if (!m_extended_info_fetched) {
284 m_extended_info = FetchThreadExtendedInfo();
285 m_extended_info_fetched = true;
287 return m_extended_info;
290 virtual const char *GetName() { return nullptr; }
292 virtual void SetName(const char *name) {}
294 //------------------------------------------------------------------
295 /// Whether this thread can be associated with a libdispatch queue
297 /// The Thread may know if it is associated with a libdispatch queue,
298 /// it may know definitively that it is NOT associated with a libdispatch
299 /// queue, or it may be unknown whether it is associated with a libdispatch
303 /// eLazyBoolNo if this thread is definitely not associated with a
304 /// libdispatch queue (e.g. on a non-Darwin system where GCD aka
305 /// libdispatch is not available).
307 /// eLazyBoolYes this thread is associated with a libdispatch queue.
309 /// eLazyBoolCalculate this thread may be associated with a libdispatch
310 /// queue but the thread doesn't know one way or the other.
311 //------------------------------------------------------------------
312 virtual lldb_private::LazyBool GetAssociatedWithLibdispatchQueue() {
316 virtual void SetAssociatedWithLibdispatchQueue(
317 lldb_private::LazyBool associated_with_libdispatch_queue) {}
319 //------------------------------------------------------------------
320 /// Retrieve the Queue ID for the queue currently using this Thread
322 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
323 /// retrieve the QueueID.
325 /// This is a unique identifier for the libdispatch/GCD queue in a
326 /// process. Often starting at 1 for the initial system-created
327 /// queues and incrementing, a QueueID will not be reused for a
328 /// different queue during the lifetime of a process.
331 /// A QueueID if the Thread subclass implements this, else
332 /// LLDB_INVALID_QUEUE_ID.
333 //------------------------------------------------------------------
334 virtual lldb::queue_id_t GetQueueID() { return LLDB_INVALID_QUEUE_ID; }
336 virtual void SetQueueID(lldb::queue_id_t new_val) {}
338 //------------------------------------------------------------------
339 /// Retrieve the Queue name for the queue currently using this Thread
341 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
342 /// retrieve the Queue name.
345 /// The Queue name, if the Thread subclass implements this, else
347 //------------------------------------------------------------------
348 virtual const char *GetQueueName() { return nullptr; }
350 virtual void SetQueueName(const char *name) {}
352 //------------------------------------------------------------------
353 /// Retrieve the Queue kind for the queue currently using this Thread
355 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
356 /// retrieve the Queue kind - either eQueueKindSerial or
357 /// eQueueKindConcurrent, indicating that this queue processes work
358 /// items serially or concurrently.
361 /// The Queue kind, if the Thread subclass implements this, else
362 /// eQueueKindUnknown.
363 //------------------------------------------------------------------
364 virtual lldb::QueueKind GetQueueKind() { return lldb::eQueueKindUnknown; }
366 virtual void SetQueueKind(lldb::QueueKind kind) {}
368 //------------------------------------------------------------------
369 /// Retrieve the Queue for this thread, if any.
372 /// A QueueSP for the queue that is currently associated with this
374 /// An empty shared pointer indicates that this thread is not
375 /// associated with a queue, or libdispatch queues are not
376 /// supported on this target.
377 //------------------------------------------------------------------
378 virtual lldb::QueueSP GetQueue() { return lldb::QueueSP(); }
380 //------------------------------------------------------------------
381 /// Retrieve the address of the libdispatch_queue_t struct for queue
382 /// currently using this Thread
384 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
385 /// retrieve the address of the libdispatch_queue_t structure describing
388 /// This address may be reused for different queues later in the Process
389 /// lifetime and should not be used to identify a queue uniquely. Use
390 /// the GetQueueID() call for that.
393 /// The Queue's libdispatch_queue_t address if the Thread subclass
394 /// implements this, else LLDB_INVALID_ADDRESS.
395 //------------------------------------------------------------------
396 virtual lldb::addr_t GetQueueLibdispatchQueueAddress() {
397 return LLDB_INVALID_ADDRESS;
400 virtual void SetQueueLibdispatchQueueAddress(lldb::addr_t dispatch_queue_t) {}
402 //------------------------------------------------------------------
403 /// Whether this Thread already has all the Queue information cached or not
405 /// A Thread may be associated with a libdispatch work Queue at a given
406 /// public stop event. If so, the thread can satisify requests like
407 /// GetQueueLibdispatchQueueAddress, GetQueueKind, GetQueueName, and
409 /// either from information from the remote debug stub when it is initially
410 /// created, or it can query the SystemRuntime for that information.
412 /// This method allows the SystemRuntime to discover if a thread has this
413 /// information already, instead of calling the thread to get the information
414 /// and having the thread call the SystemRuntime again.
415 //------------------------------------------------------------------
416 virtual bool ThreadHasQueueInformation() const { return false; }
418 virtual uint32_t GetStackFrameCount() {
419 return GetStackFrameList()->GetNumFrames();
422 virtual lldb::StackFrameSP GetStackFrameAtIndex(uint32_t idx) {
423 return GetStackFrameList()->GetFrameAtIndex(idx);
426 virtual lldb::StackFrameSP
427 GetFrameWithConcreteFrameIndex(uint32_t unwind_idx);
429 bool DecrementCurrentInlinedDepth() {
430 return GetStackFrameList()->DecrementCurrentInlinedDepth();
433 uint32_t GetCurrentInlinedDepth() {
434 return GetStackFrameList()->GetCurrentInlinedDepth();
437 Status ReturnFromFrameWithIndex(uint32_t frame_idx,
438 lldb::ValueObjectSP return_value_sp,
439 bool broadcast = false);
441 Status ReturnFromFrame(lldb::StackFrameSP frame_sp,
442 lldb::ValueObjectSP return_value_sp,
443 bool broadcast = false);
445 Status JumpToLine(const FileSpec &file, uint32_t line,
446 bool can_leave_function, std::string *warnings = nullptr);
448 virtual lldb::StackFrameSP GetFrameWithStackID(const StackID &stack_id) {
449 if (stack_id.IsValid())
450 return GetStackFrameList()->GetFrameWithStackID(stack_id);
451 return lldb::StackFrameSP();
454 uint32_t GetSelectedFrameIndex() {
455 return GetStackFrameList()->GetSelectedFrameIndex();
458 lldb::StackFrameSP GetSelectedFrame();
460 uint32_t SetSelectedFrame(lldb_private::StackFrame *frame,
461 bool broadcast = false);
463 bool SetSelectedFrameByIndex(uint32_t frame_idx, bool broadcast = false);
465 bool SetSelectedFrameByIndexNoisily(uint32_t frame_idx,
466 Stream &output_stream);
468 void SetDefaultFileAndLineToSelectedFrame() {
469 GetStackFrameList()->SetDefaultFileAndLineToSelectedFrame();
472 virtual lldb::RegisterContextSP GetRegisterContext() = 0;
474 virtual lldb::RegisterContextSP
475 CreateRegisterContextForFrame(StackFrame *frame) = 0;
477 virtual void ClearStackFrames();
479 virtual bool SetBackingThread(const lldb::ThreadSP &thread_sp) {
483 virtual lldb::ThreadSP GetBackingThread() const { return lldb::ThreadSP(); }
485 virtual void ClearBackingThread() {
486 // Subclasses can use this function if a thread is actually backed by
487 // another thread. This is currently used for the OperatingSystem plug-ins
488 // where they might have a thread that is in memory, yet its registers are
489 // available through the lldb_private::Thread subclass for the current
490 // lldb_private::Process class. Since each time the process stops the
491 // backing threads for memory threads can change, we need a way to clear
492 // the backing thread for all memory threads each time we stop.
495 // If stop_format is true, this will be the form used when we print stop
496 // info. If false, it will be the form we use for thread list and co.
497 void DumpUsingSettingsFormat(Stream &strm, uint32_t frame_idx,
500 bool GetDescription(Stream &s, lldb::DescriptionLevel level,
501 bool print_json_thread, bool print_json_stopinfo);
503 //------------------------------------------------------------------
504 /// Default implementation for stepping into.
506 /// This function is designed to be used by commands where the
507 /// process is publicly stopped.
509 /// @param[in] source_step
510 /// If true and the frame has debug info, then do a source level
511 /// step in, else do a single instruction step in.
513 /// @param[in] step_in_avoids_code_without_debug_info
514 /// If \a true, then avoid stepping into code that doesn't have
515 /// debug info, else step into any code regardless of whether it
518 /// @param[in] step_out_avoids_code_without_debug_info
519 /// If \a true, then if you step out to code with no debug info, keep
520 /// stepping out till you get to code with debug info.
523 /// An error that describes anything that went wrong
524 //------------------------------------------------------------------
526 StepIn(bool source_step,
527 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
528 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
530 //------------------------------------------------------------------
531 /// Default implementation for stepping over.
533 /// This function is designed to be used by commands where the
534 /// process is publicly stopped.
536 /// @param[in] source_step
537 /// If true and the frame has debug info, then do a source level
538 /// step over, else do a single instruction step over.
541 /// An error that describes anything that went wrong
542 //------------------------------------------------------------------
543 virtual Status StepOver(
545 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
547 //------------------------------------------------------------------
548 /// Default implementation for stepping out.
550 /// This function is designed to be used by commands where the
551 /// process is publicly stopped.
554 /// An error that describes anything that went wrong
555 //------------------------------------------------------------------
556 virtual Status StepOut();
558 //------------------------------------------------------------------
559 /// Retrieves the per-thread data area.
560 /// Most OSs maintain a per-thread pointer (e.g. the FS register on
561 /// x64), which we return the value of here.
564 /// LLDB_INVALID_ADDRESS if not supported, otherwise the thread
566 //------------------------------------------------------------------
567 virtual lldb::addr_t GetThreadPointer();
569 //------------------------------------------------------------------
570 /// Retrieves the per-module TLS block for a thread.
572 /// @param[in] module
573 /// The module to query TLS data for.
575 /// @param[in] tls_file_addr
576 /// The thread local address in module
578 /// If the thread has TLS data allocated for the
579 /// module, the address of the TLS block. Otherwise
580 /// LLDB_INVALID_ADDRESS is returned.
581 //------------------------------------------------------------------
582 virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module,
583 lldb::addr_t tls_file_addr);
585 //------------------------------------------------------------------
586 /// Check whether this thread is safe to run functions
588 /// The SystemRuntime may know of certain thread states (functions in
589 /// process of execution, for instance) which can make it unsafe for
590 /// functions to be called.
593 /// True if it is safe to call functions on this thread.
594 /// False if function calls should be avoided on this thread.
595 //------------------------------------------------------------------
596 virtual bool SafeToCallFunctions();
598 //------------------------------------------------------------------
599 // Thread Plan Providers:
600 // This section provides the basic thread plans that the Process control
601 // machinery uses to run the target. ThreadPlan.h provides more details on
602 // how this mechanism works. The thread provides accessors to a set of plans
603 // that perform basic operations. The idea is that particular Platform
604 // plugins can override these methods to provide the implementation of these
605 // basic operations appropriate to their environment.
607 // NB: All the QueueThreadPlanXXX providers return Shared Pointers to
608 // Thread plans. This is useful so that you can modify the plans after
609 // creation in ways specific to that plan type. Also, it is often necessary
610 // for ThreadPlans that utilize other ThreadPlans to implement their task to
611 // keep a shared pointer to the sub-plan. But besides that, the shared
612 // pointers should only be held onto by entities who live no longer than the
613 // thread containing the ThreadPlan.
614 // FIXME: If this becomes a problem, we can make a version that just returns a
616 // which it is clearly unsafe to hold onto, and a shared pointer version, and
617 // only allow ThreadPlan and Co. to use the latter. That is made more
618 // annoying to do because there's no elegant way to friend a method to all
619 // sub-classes of a given class.
621 //------------------------------------------------------------------
623 //------------------------------------------------------------------
624 /// Queues the base plan for a thread.
625 /// The version returned by Process does some things that are useful,
626 /// like handle breakpoints and signals, so if you return a plugin specific
627 /// one you probably want to call through to the Process one for anything
628 /// your plugin doesn't explicitly handle.
630 /// @param[in] abort_other_plans
631 /// \b true if we discard the currently queued plans and replace them with
633 /// Otherwise this plan will go on the end of the plan stack.
636 /// A shared pointer to the newly queued thread plan, or nullptr if the
637 /// plan could not be queued.
638 //------------------------------------------------------------------
639 virtual lldb::ThreadPlanSP QueueFundamentalPlan(bool abort_other_plans);
641 //------------------------------------------------------------------
642 /// Queues the plan used to step one instruction from the current PC of \a
645 /// @param[in] step_over
646 /// \b true if we step over calls to functions, false if we step in.
648 /// @param[in] abort_other_plans
649 /// \b true if we discard the currently queued plans and replace them with
651 /// Otherwise this plan will go on the end of the plan stack.
653 /// @param[in] stop_other_threads
654 /// \b true if we will stop other threads while we single step this one.
656 /// @param[out] status
657 /// A status with an error if queuing failed.
660 /// A shared pointer to the newly queued thread plan, or nullptr if the
661 /// plan could not be queued.
662 //------------------------------------------------------------------
663 virtual lldb::ThreadPlanSP QueueThreadPlanForStepSingleInstruction(
664 bool step_over, bool abort_other_plans, bool stop_other_threads,
667 //------------------------------------------------------------------
668 /// Queues the plan used to step through an address range, stepping over
671 /// @param[in] abort_other_plans
672 /// \b true if we discard the currently queued plans and replace them with
674 /// Otherwise this plan will go on the end of the plan stack.
677 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
681 /// The address range to step through.
683 /// @param[in] addr_context
684 /// When dealing with stepping through inlined functions the current PC is
685 /// not enough information to know
686 /// what "step" means. For instance a series of nested inline functions
687 /// might start at the same address.
688 // The \a addr_context provides the current symbol context the step
689 /// is supposed to be out of.
690 // FIXME: Currently unused.
692 /// @param[in] stop_other_threads
693 /// \b true if we will stop other threads while we single step this one.
695 /// @param[out] status
696 /// A status with an error if queuing failed.
698 /// @param[in] step_out_avoids_code_without_debug_info
699 /// If eLazyBoolYes, if the step over steps out it will continue to step
700 /// out till it comes to a frame with debug info.
701 /// If eLazyBoolCalculate, we will consult the default set in the thread.
704 /// A shared pointer to the newly queued thread plan, or nullptr if the
705 /// plan could not be queued.
706 //------------------------------------------------------------------
707 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
708 bool abort_other_plans, const AddressRange &range,
709 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
711 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
713 // Helper function that takes a LineEntry to step, insted of an AddressRange.
714 // This may combine multiple LineEntries of the same source line number to
715 // step over a longer address range in a single operation.
716 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
717 bool abort_other_plans, const LineEntry &line_entry,
718 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
720 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
722 //------------------------------------------------------------------
723 /// Queues the plan used to step through an address range, stepping into
726 /// @param[in] abort_other_plans
727 /// \b true if we discard the currently queued plans and replace them with
729 /// Otherwise this plan will go on the end of the plan stack.
732 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
736 /// The address range to step through.
738 /// @param[in] addr_context
739 /// When dealing with stepping through inlined functions the current PC is
740 /// not enough information to know
741 /// what "step" means. For instance a series of nested inline functions
742 /// might start at the same address.
743 // The \a addr_context provides the current symbol context the step
744 /// is supposed to be out of.
745 // FIXME: Currently unused.
747 /// @param[in] step_in_target
748 /// Name if function we are trying to step into. We will step out if we
749 /// don't land in that function.
751 /// @param[in] stop_other_threads
752 /// \b true if we will stop other threads while we single step this one.
754 /// @param[out] status
755 /// A status with an error if queuing failed.
757 /// @param[in] step_in_avoids_code_without_debug_info
758 /// If eLazyBoolYes we will step out if we step into code with no debug
760 /// If eLazyBoolCalculate we will consult the default set in the thread.
762 /// @param[in] step_out_avoids_code_without_debug_info
763 /// If eLazyBoolYes, if the step over steps out it will continue to step
764 /// out till it comes to a frame with debug info.
765 /// If eLazyBoolCalculate, it will consult the default set in the thread.
768 /// A shared pointer to the newly queued thread plan, or nullptr if the
769 /// plan could not be queued.
770 //------------------------------------------------------------------
771 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
772 bool abort_other_plans, const AddressRange &range,
773 const SymbolContext &addr_context, const char *step_in_target,
774 lldb::RunMode stop_other_threads, Status &status,
775 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
776 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
778 // Helper function that takes a LineEntry to step, insted of an AddressRange.
779 // This may combine multiple LineEntries of the same source line number to
780 // step over a longer address range in a single operation.
781 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
782 bool abort_other_plans, const LineEntry &line_entry,
783 const SymbolContext &addr_context, const char *step_in_target,
784 lldb::RunMode stop_other_threads, Status &status,
785 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
786 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
788 //------------------------------------------------------------------
789 /// Queue the plan used to step out of the function at the current PC of
792 /// @param[in] abort_other_plans
793 /// \b true if we discard the currently queued plans and replace them with
795 /// Otherwise this plan will go on the end of the plan stack.
797 /// @param[in] addr_context
798 /// When dealing with stepping through inlined functions the current PC is
799 /// not enough information to know
800 /// what "step" means. For instance a series of nested inline functions
801 /// might start at the same address.
802 // The \a addr_context provides the current symbol context the step
803 /// is supposed to be out of.
804 // FIXME: Currently unused.
806 /// @param[in] first_insn
807 /// \b true if this is the first instruction of a function.
809 /// @param[in] stop_other_threads
810 /// \b true if we will stop other threads while we single step this one.
812 /// @param[in] stop_vote
813 /// @param[in] run_vote
814 /// See standard meanings for the stop & run votes in ThreadPlan.h.
816 /// @param[out] status
817 /// A status with an error if queuing failed.
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, Vote stop_vote, Vote run_vote,
831 uint32_t frame_idx, Status &status,
832 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
834 //------------------------------------------------------------------
835 /// Queue the plan used to step out of the function at the current PC of
836 /// a thread. This version does not consult the should stop here callback,
838 /// be used by other thread plans when they need to retain control of the step
841 /// @param[in] abort_other_plans
842 /// \b true if we discard the currently queued plans and replace them with
844 /// Otherwise this plan will go on the end of the plan stack.
846 /// @param[in] addr_context
847 /// When dealing with stepping through inlined functions the current PC is
848 /// not enough information to know
849 /// what "step" means. For instance a series of nested inline functions
850 /// might start at the same address.
851 // The \a addr_context provides the current symbol context the step
852 /// is supposed to be out of.
853 // FIXME: Currently unused.
855 /// @param[in] first_insn
856 /// \b true if this is the first instruction of a function.
858 /// @param[in] stop_other_threads
859 /// \b true if we will stop other threads while we single step this one.
861 /// @param[in] stop_vote
863 /// @param[in] run_vote
864 /// See standard meanings for the stop & run votes in ThreadPlan.h.
866 /// @param[in] frame_idx
868 /// @param[out] status
869 /// A status with an error if queuing failed.
871 /// @param[in] continue_to_next_branch
872 /// Normally this will enqueue a plan that will put a breakpoint on the
873 /// return address and continue
874 /// to there. If continue_to_next_branch is true, this is an operation not
875 /// involving the user --
876 /// e.g. stepping "next" in a source line and we instruction stepped into
877 /// another function --
878 /// so instead of putting a breakpoint on the return address, advance the
879 /// breakpoint to the
880 /// end of the source line that is doing the call, or until the next flow
881 /// control instruction.
882 /// If the return value from the function call is to be retrieved /
883 /// displayed to the user, you must stop
884 /// on the return address. The return value may be stored in volatile
885 /// registers which are overwritten
886 /// before the next branch instruction.
889 /// A shared pointer to the newly queued thread plan, or nullptr if the
890 /// plan could not be queued.
891 //------------------------------------------------------------------
892 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOutNoShouldStop(
893 bool abort_other_plans, SymbolContext *addr_context, bool first_insn,
894 bool stop_other_threads, Vote stop_vote, Vote run_vote,
895 uint32_t frame_idx, Status &status, bool continue_to_next_branch = false);
897 //------------------------------------------------------------------
898 /// Gets the plan used to step through the code that steps from a function
899 /// 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.
914 /// @param[out] status
915 /// A status with an error if queuing failed.
918 /// A shared pointer to the newly queued thread plan, or nullptr if the
919 /// plan could not be queued.
920 //------------------------------------------------------------------
921 virtual lldb::ThreadPlanSP
922 QueueThreadPlanForStepThrough(StackID &return_stack_id,
923 bool abort_other_plans, bool stop_other_threads,
926 //------------------------------------------------------------------
927 /// Gets the plan used to continue from the current PC.
928 /// This is a simple plan, mostly useful as a backstop when you are continuing
929 /// for some particular purpose.
931 /// @param[in] abort_other_plans
932 /// \b true if we discard the currently queued plans and replace them with
934 /// Otherwise this plan will go on the end of the plan stack.
936 /// @param[in] target_addr
937 /// The address to which we're running.
939 /// @param[in] stop_other_threads
940 /// \b true if we will stop other threads while we single step this one.
942 /// @param[out] status
943 /// A status with an error if queuing failed.
946 /// A shared pointer to the newly queued thread plan, or nullptr if the
947 /// plan could not be queued.
948 //------------------------------------------------------------------
949 virtual lldb::ThreadPlanSP
950 QueueThreadPlanForRunToAddress(bool abort_other_plans, Address &target_addr,
951 bool stop_other_threads, Status &status);
953 virtual lldb::ThreadPlanSP QueueThreadPlanForStepUntil(
954 bool abort_other_plans, lldb::addr_t *address_list, size_t num_addresses,
955 bool stop_others, uint32_t frame_idx, Status &status);
957 virtual lldb::ThreadPlanSP
958 QueueThreadPlanForStepScripted(bool abort_other_plans, const char *class_name,
959 bool stop_other_threads, Status &status);
961 //------------------------------------------------------------------
962 // Thread Plan accessors:
963 //------------------------------------------------------------------
965 //------------------------------------------------------------------
966 /// Gets the plan which will execute next on the plan stack.
969 /// A pointer to the next executed plan.
970 //------------------------------------------------------------------
971 ThreadPlan *GetCurrentPlan();
973 //------------------------------------------------------------------
974 /// Unwinds the thread stack for the innermost expression plan currently
975 /// on the thread plan stack.
978 /// An error if the thread plan could not be unwound.
979 //------------------------------------------------------------------
981 Status UnwindInnermostExpression();
983 //------------------------------------------------------------------
984 /// Gets the outer-most plan that was popped off the plan stack in the
985 /// most recent stop. Useful for printing the stop reason accurately.
988 /// A pointer to the last completed plan.
989 //------------------------------------------------------------------
990 lldb::ThreadPlanSP GetCompletedPlan();
992 //------------------------------------------------------------------
993 /// Gets the outer-most return value from the completed plans
996 /// A ValueObjectSP, either empty if there is no return value,
997 /// or containing the return value.
998 //------------------------------------------------------------------
999 lldb::ValueObjectSP GetReturnValueObject();
1001 //------------------------------------------------------------------
1002 /// Gets the outer-most expression variable from the completed plans
1005 /// A ExpressionVariableSP, either empty if there is no
1006 /// plan completed an expression during the current stop
1007 /// or the expression variable that was made for the completed expression.
1008 //------------------------------------------------------------------
1009 lldb::ExpressionVariableSP GetExpressionVariable();
1011 //------------------------------------------------------------------
1012 /// Checks whether the given plan is in the completed plans for this
1016 /// Pointer to the plan you're checking.
1019 /// Returns true if the input plan is in the completed plan stack,
1020 /// false otherwise.
1021 //------------------------------------------------------------------
1022 bool IsThreadPlanDone(ThreadPlan *plan);
1024 //------------------------------------------------------------------
1025 /// Checks whether the given plan is in the discarded plans for this
1029 /// Pointer to the plan you're checking.
1032 /// Returns true if the input plan is in the discarded plan stack,
1033 /// false otherwise.
1034 //------------------------------------------------------------------
1035 bool WasThreadPlanDiscarded(ThreadPlan *plan);
1037 //------------------------------------------------------------------
1038 /// Check if we have completed plan to override breakpoint stop reason
1041 /// Returns true if completed plan stack is not empty
1042 /// false otherwise.
1043 //------------------------------------------------------------------
1044 bool CompletedPlanOverridesBreakpoint();
1046 //------------------------------------------------------------------
1047 /// Queues a generic thread plan.
1049 /// @param[in] plan_sp
1050 /// The plan to queue.
1052 /// @param[in] abort_other_plans
1053 /// \b true if we discard the currently queued plans and replace them with
1055 /// Otherwise this plan will go on the end of the plan stack.
1058 /// A pointer to the last completed plan.
1059 //------------------------------------------------------------------
1060 Status QueueThreadPlan(lldb::ThreadPlanSP &plan_sp, bool abort_other_plans);
1062 //------------------------------------------------------------------
1063 /// Discards the plans queued on the plan stack of the current thread. This
1065 /// arbitrated by the "Master" ThreadPlans, using the "OkayToDiscard" call.
1066 // But if \a force is true, all thread plans are discarded.
1067 //------------------------------------------------------------------
1068 void DiscardThreadPlans(bool force);
1070 //------------------------------------------------------------------
1071 /// Discards the plans queued on the plan stack of the current thread up to
1073 /// including up_to_plan_sp.
1075 // @param[in] up_to_plan_sp
1076 // Discard all plans up to and including this one.
1077 //------------------------------------------------------------------
1078 void DiscardThreadPlansUpToPlan(lldb::ThreadPlanSP &up_to_plan_sp);
1080 void DiscardThreadPlansUpToPlan(ThreadPlan *up_to_plan_ptr);
1082 //------------------------------------------------------------------
1083 /// Discards the plans queued on the plan stack of the current thread up to
1085 /// including the plan in that matches \a thread_index counting only
1086 /// the non-Private plans.
1088 /// @param[in] up_to_plan_sp
1089 /// Discard all plans up to and including this user plan given by this
1093 /// \b true if there was a thread plan with that user index, \b false
1095 //------------------------------------------------------------------
1096 bool DiscardUserThreadPlansUpToIndex(uint32_t thread_index);
1098 //------------------------------------------------------------------
1099 /// Prints the current plan stack.
1102 /// The stream to which to dump the plan stack info.
1104 //------------------------------------------------------------------
1105 void DumpThreadPlans(
1107 lldb::DescriptionLevel desc_level = lldb::eDescriptionLevelVerbose,
1108 bool include_internal = true, bool ignore_boring = false) const;
1110 virtual bool CheckpointThreadState(ThreadStateCheckpoint &saved_state);
1113 RestoreRegisterStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1116 RestoreThreadStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1118 void EnableTracer(bool value, bool single_step);
1120 void SetTracer(lldb::ThreadPlanTracerSP &tracer_sp);
1122 //------------------------------------------------------------------
1123 // Get the thread index ID. The index ID that is guaranteed to not be re-used
1124 // by a process. They start at 1 and increase with each new thread. This
1125 // allows easy command line access by a unique ID that is easier to type than
1126 // the actual system thread ID.
1127 //------------------------------------------------------------------
1128 uint32_t GetIndexID() const;
1130 //------------------------------------------------------------------
1131 // Get the originating thread's index ID.
1132 // In the case of an "extended" thread -- a thread which represents the stack
1133 // that enqueued/spawned work that is currently executing -- we need to
1134 // provide the IndexID of the thread that actually did this work. We don't
1135 // want to just masquerade as that thread's IndexID by using it in our own
1136 // IndexID because that way leads to madness - but the driver program which
1137 // is iterating over extended threads may ask for the OriginatingThreadID to
1138 // display that information to the user.
1139 // Normal threads will return the same thing as GetIndexID();
1140 //------------------------------------------------------------------
1141 virtual uint32_t GetExtendedBacktraceOriginatingIndexID() {
1142 return GetIndexID();
1145 //------------------------------------------------------------------
1146 // The API ID is often the same as the Thread::GetID(), but not in all cases.
1147 // Thread::GetID() is the user visible thread ID that clients would want to
1148 // see. The API thread ID is the thread ID that is used when sending data
1149 // to/from the debugging protocol.
1150 //------------------------------------------------------------------
1151 virtual lldb::user_id_t GetProtocolID() const { return GetID(); }
1153 //------------------------------------------------------------------
1154 // lldb::ExecutionContextScope pure virtual functions
1155 //------------------------------------------------------------------
1156 lldb::TargetSP CalculateTarget() override;
1158 lldb::ProcessSP CalculateProcess() override;
1160 lldb::ThreadSP CalculateThread() override;
1162 lldb::StackFrameSP CalculateStackFrame() override;
1164 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
1167 GetStackFrameSPForStackFramePtr(StackFrame *stack_frame_ptr);
1169 size_t GetStatus(Stream &strm, uint32_t start_frame, uint32_t num_frames,
1170 uint32_t num_frames_with_source, bool stop_format,
1171 bool only_stacks = false);
1173 size_t GetStackFrameStatus(Stream &strm, uint32_t first_frame,
1174 uint32_t num_frames, bool show_frame_info,
1175 uint32_t num_frames_with_source);
1177 // We need a way to verify that even though we have a thread in a shared
1178 // pointer that the object itself is still valid. Currently this won't be the
1179 // case if DestroyThread() was called. DestroyThread is called when a thread
1180 // has been removed from the Process' thread list.
1181 bool IsValid() const { return !m_destroy_called; }
1183 // Sets and returns a valid stop info based on the process stop ID and the
1184 // current thread plan. If the thread stop ID does not match the process'
1185 // stop ID, the private stop reason is not set and an invalid StopInfoSP may
1188 // NOTE: This function must be called before the current thread plan is
1189 // moved to the completed plan stack (in Thread::ShouldStop()).
1191 // NOTE: If subclasses override this function, ensure they do not overwrite
1192 // the m_actual_stop_info if it is valid. The stop info may be a
1193 // "checkpointed and restored" stop info, so if it is still around it is
1194 // right even if you have not calculated this yourself, or if it disagrees
1195 // with what you might have calculated.
1196 virtual lldb::StopInfoSP GetPrivateStopInfo();
1198 //----------------------------------------------------------------------
1199 // Ask the thread subclass to set its stop info.
1201 // Thread subclasses should call Thread::SetStopInfo(...) with the reason the
1205 // True if Thread::SetStopInfo(...) was called, false otherwise.
1206 //----------------------------------------------------------------------
1207 virtual bool CalculateStopInfo() = 0;
1209 //----------------------------------------------------------------------
1210 // Gets the temporary resume state for a thread.
1212 // This value gets set in each thread by complex debugger logic in
1213 // Thread::ShouldResume() and an appropriate thread resume state will get set
1214 // in each thread every time the process is resumed prior to calling
1215 // Process::DoResume(). The lldb_private::Process subclass should adhere to
1216 // the thread resume state request which will be one of:
1218 // eStateRunning - thread will resume when process is resumed
1219 // eStateStepping - thread should step 1 instruction and stop when process
1221 // eStateSuspended - thread should not execute any instructions when
1222 // process is resumed
1223 //----------------------------------------------------------------------
1224 lldb::StateType GetTemporaryResumeState() const {
1225 return m_temporary_resume_state;
1228 void SetStopInfo(const lldb::StopInfoSP &stop_info_sp);
1230 void ResetStopInfo();
1232 void SetShouldReportStop(Vote vote);
1234 //----------------------------------------------------------------------
1235 /// Sets the extended backtrace token for this thread
1237 /// Some Thread subclasses may maintain a token to help with providing
1238 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1240 /// @param [in] token
1241 //----------------------------------------------------------------------
1242 virtual void SetExtendedBacktraceToken(uint64_t token) {}
1244 //----------------------------------------------------------------------
1245 /// Gets the extended backtrace token for this thread
1247 /// Some Thread subclasses may maintain a token to help with providing
1248 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1251 /// The token needed by the SystemRuntime to create an extended backtrace.
1252 /// LLDB_INVALID_ADDRESS is returned if no token is available.
1253 //----------------------------------------------------------------------
1254 virtual uint64_t GetExtendedBacktraceToken() { return LLDB_INVALID_ADDRESS; }
1256 lldb::ValueObjectSP GetCurrentException();
1258 lldb::ThreadSP GetCurrentExceptionBacktrace();
1261 friend class ThreadPlan;
1262 friend class ThreadList;
1263 friend class ThreadEventData;
1264 friend class StackFrameList;
1265 friend class StackFrame;
1266 friend class OperatingSystem;
1268 // This is necessary to make sure thread assets get destroyed while the
1269 // thread is still in good shape to call virtual thread methods. This must
1270 // be called by classes that derive from Thread in their destructor.
1271 virtual void DestroyThread();
1273 void PushPlan(lldb::ThreadPlanSP &plan_sp);
1279 ThreadPlan *GetPreviousPlan(ThreadPlan *plan);
1281 typedef std::vector<lldb::ThreadPlanSP> plan_stack;
1283 virtual lldb_private::Unwind *GetUnwinder();
1285 // Check to see whether the thread is still at the last breakpoint hit that
1287 virtual bool IsStillAtLastBreakpointHit();
1289 // Some threads are threads that are made up by OperatingSystem plugins that
1290 // are threads that exist and are context switched out into memory. The
1291 // OperatingSystem plug-in need a ways to know if a thread is "real" or made
1293 virtual bool IsOperatingSystemPluginThread() const { return false; }
1295 // Subclasses that have a way to get an extended info dictionary for this
1296 // thread should fill
1297 virtual lldb_private::StructuredData::ObjectSP FetchThreadExtendedInfo() {
1298 return StructuredData::ObjectSP();
1301 lldb::StackFrameListSP GetStackFrameList();
1303 void SetTemporaryResumeState(lldb::StateType new_state) {
1304 m_temporary_resume_state = new_state;
1307 void FunctionOptimizationWarning(lldb_private::StackFrame *frame);
1309 //------------------------------------------------------------------
1310 // Classes that inherit from Process can see and modify these
1311 //------------------------------------------------------------------
1312 lldb::ProcessWP m_process_wp; ///< The process that owns this thread.
1313 lldb::StopInfoSP m_stop_info_sp; ///< The private stop reason for this thread
1314 uint32_t m_stop_info_stop_id; // This is the stop id for which the StopInfo is
1315 // valid. Can use this so you know that
1316 // the thread's m_stop_info_sp is current and you don't have to fetch it
1318 uint32_t m_stop_info_override_stop_id; // The stop ID containing the last time
1319 // the stop info was checked against
1320 // the stop info override
1321 const uint32_t m_index_id; ///< A unique 1 based index assigned to each thread
1322 ///for easy UI/command line access.
1323 lldb::RegisterContextSP m_reg_context_sp; ///< The register context for this
1324 ///thread's current register state.
1325 lldb::StateType m_state; ///< The state of our process.
1326 mutable std::recursive_mutex
1327 m_state_mutex; ///< Multithreaded protection for m_state.
1328 plan_stack m_plan_stack; ///< The stack of plans this thread is executing.
1329 plan_stack m_completed_plan_stack; ///< Plans that have been completed by this
1330 ///stop. They get deleted when the thread
1332 plan_stack m_discarded_plan_stack; ///< Plans that have been discarded by this
1333 ///stop. They get deleted when the thread
1335 mutable std::recursive_mutex
1336 m_frame_mutex; ///< Multithreaded protection for m_state.
1337 lldb::StackFrameListSP m_curr_frames_sp; ///< The stack frames that get lazily
1338 ///populated after a thread stops.
1339 lldb::StackFrameListSP m_prev_frames_sp; ///< The previous stack frames from
1340 ///the last time this thread stopped.
1341 int m_resume_signal; ///< The signal that should be used when continuing this
1343 lldb::StateType m_resume_state; ///< This state is used to force a thread to
1344 ///be suspended from outside the ThreadPlan
1346 lldb::StateType m_temporary_resume_state; ///< This state records what the
1347 ///thread was told to do by the
1348 ///thread plan logic for the current
1350 /// It gets set in Thread::ShouldResume.
1351 std::unique_ptr<lldb_private::Unwind> m_unwinder_ap;
1352 bool m_destroy_called; // This is used internally to make sure derived Thread
1353 // classes call DestroyThread.
1354 LazyBool m_override_should_notify;
1357 bool m_extended_info_fetched; // Have we tried to retrieve the m_extended_info
1359 StructuredData::ObjectSP m_extended_info; // The extended info for this thread
1362 bool PlanIsBasePlan(ThreadPlan *plan_ptr);
1364 void BroadcastSelectedFrameChange(StackID &new_frame_id);
1366 DISALLOW_COPY_AND_ASSIGN(Thread);
1369 } // namespace lldb_private
1371 #endif // liblldb_Thread_h_