1 //===-- Thread.h ------------------------------------------------*- C++ -*-===//
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
7 //===----------------------------------------------------------------------===//
9 #ifndef liblldb_Thread_h_
10 #define liblldb_Thread_h_
17 #include "lldb/Core/UserSettingsController.h"
18 #include "lldb/Target/ExecutionContextScope.h"
19 #include "lldb/Target/RegisterCheckpoint.h"
20 #include "lldb/Target/StackFrameList.h"
21 #include "lldb/Utility/Broadcaster.h"
22 #include "lldb/Utility/Event.h"
23 #include "lldb/Utility/StructuredData.h"
24 #include "lldb/Utility/UserID.h"
25 #include "lldb/lldb-private.h"
27 #define LLDB_THREAD_MAX_STOP_EXC_DATA 8
29 namespace lldb_private {
31 class ThreadProperties : public Properties {
33 ThreadProperties(bool is_global);
35 ~ThreadProperties() override;
37 /// The regular expression returned determines symbols that this
38 /// thread won't stop in during "step-in" operations.
41 /// A pointer to a regular expression to compare against symbols,
42 /// or nullptr if all symbols are allowed.
44 const RegularExpression *GetSymbolsToAvoidRegexp();
46 FileSpecList GetLibrariesToAvoid() const;
48 bool GetTraceEnabledState() const;
50 bool GetStepInAvoidsNoDebug() const;
52 bool GetStepOutAvoidsNoDebug() const;
54 uint64_t GetMaxBacktraceDepth() const;
57 typedef std::shared_ptr<ThreadProperties> ThreadPropertiesSP;
59 class Thread : public std::enable_shared_from_this<Thread>,
60 public ThreadProperties,
62 public ExecutionContextScope,
65 /// Broadcaster event bits definitions.
67 eBroadcastBitStackChanged = (1 << 0),
68 eBroadcastBitThreadSuspended = (1 << 1),
69 eBroadcastBitThreadResumed = (1 << 2),
70 eBroadcastBitSelectedFrameChanged = (1 << 3),
71 eBroadcastBitThreadSelected = (1 << 4)
74 static ConstString &GetStaticBroadcasterClass();
76 ConstString &GetBroadcasterClass() const override {
77 return GetStaticBroadcasterClass();
80 class ThreadEventData : public EventData {
82 ThreadEventData(const lldb::ThreadSP thread_sp);
84 ThreadEventData(const lldb::ThreadSP thread_sp, const StackID &stack_id);
88 ~ThreadEventData() override;
90 static ConstString GetFlavorString();
92 ConstString GetFlavor() const override {
93 return ThreadEventData::GetFlavorString();
96 void Dump(Stream *s) const override;
98 static const ThreadEventData *GetEventDataFromEvent(const Event *event_ptr);
100 static lldb::ThreadSP GetThreadFromEvent(const Event *event_ptr);
102 static StackID GetStackIDFromEvent(const Event *event_ptr);
104 static lldb::StackFrameSP GetStackFrameFromEvent(const Event *event_ptr);
106 lldb::ThreadSP GetThread() const { return m_thread_sp; }
108 StackID GetStackID() const { return m_stack_id; }
111 lldb::ThreadSP m_thread_sp;
114 DISALLOW_COPY_AND_ASSIGN(ThreadEventData);
117 struct ThreadStateCheckpoint {
118 uint32_t orig_stop_id; // Dunno if I need this yet but it is an interesting
120 lldb::StopInfoSP stop_info_sp; // You have to restore the stop info or you
121 // might continue with the wrong signals.
122 std::vector<lldb::ThreadPlanSP> m_completed_plan_stack;
123 lldb::RegisterCheckpointSP
124 register_backup_sp; // You need to restore the registers, of course...
125 uint32_t current_inlined_depth;
126 lldb::addr_t current_inlined_pc;
131 /// \param [in] use_invalid_index_id
132 /// Optional parameter, defaults to false. The only subclass that
133 /// is likely to set use_invalid_index_id == true is the HistoryThread
134 /// class. In that case, the Thread we are constructing represents
135 /// a thread from earlier in the program execution. We may have the
136 /// tid of the original thread that they represent but we don't want
137 /// to reuse the IndexID of that thread, or create a new one. If a
138 /// client wants to know the original thread's IndexID, they should use
139 /// Thread::GetExtendedBacktraceOriginatingIndexID().
140 Thread(Process &process, lldb::tid_t tid, bool use_invalid_index_id = false);
144 static void SettingsInitialize();
146 static void SettingsTerminate();
148 static const ThreadPropertiesSP &GetGlobalProperties();
150 lldb::ProcessSP GetProcess() const { return m_process_wp.lock(); }
152 int GetResumeSignal() const { return m_resume_signal; }
154 void SetResumeSignal(int signal) { m_resume_signal = signal; }
156 lldb::StateType GetState() const;
158 void SetState(lldb::StateType state);
160 /// Sets the USER resume state for this thread. If you set a thread to
162 /// this API, it won't take part in any of the arbitration for ShouldResume,
164 /// suspended even when other threads do get to run.
166 /// N.B. This is not the state that is used internally by thread plans to
168 /// staying on one thread while stepping over a breakpoint, etc. The is the
169 /// TemporaryResume state, and if you are implementing some bit of strategy in
171 /// machinery you should be using that state and not the user resume state.
173 /// If you are just preparing all threads to run, you should not override the
175 /// marked as suspended by the debugger. In that case, pass override_suspend
176 /// = false. If you want
177 /// to force the thread to run (e.g. the "thread continue" command, or are
178 /// resetting the state
179 /// (e.g. in SBThread::Resume()), then pass true to override_suspend.
181 /// The User resume state for this thread.
182 void SetResumeState(lldb::StateType state, bool override_suspend = false) {
183 if (m_resume_state == lldb::eStateSuspended && !override_suspend)
185 m_resume_state = state;
188 /// Gets the USER resume state for this thread. This is not the same as what
189 /// this thread is going to do for any particular step, however if this thread
190 /// returns eStateSuspended, then the process control logic will never allow
195 /// The User resume state for this thread.
196 lldb::StateType GetResumeState() const { return m_resume_state; }
198 // This function is called on all the threads before "ShouldResume" and
199 // "WillResume" in case a thread needs to change its state before the
200 // ThreadList polls all the threads to figure out which ones actually will
201 // get to run and how.
202 void SetupForResume();
204 // Do not override this function, it is for thread plan logic only
205 bool ShouldResume(lldb::StateType resume_state);
207 // Override this to do platform specific tasks before resume.
208 virtual void WillResume(lldb::StateType resume_state) {}
210 // This clears generic thread state after a resume. If you subclass this, be
212 virtual void DidResume();
214 // This notifies the thread when a private stop occurs.
215 virtual void DidStop();
217 virtual void RefreshStateAfterStop() = 0;
221 bool ShouldStop(Event *event_ptr);
223 Vote ShouldReportStop(Event *event_ptr);
225 Vote ShouldReportRun(Event *event_ptr);
229 // Return whether this thread matches the specification in ThreadSpec. This
230 // is a virtual method because at some point we may extend the thread spec
231 // with a platform specific dictionary of attributes, which then only the
232 // platform specific Thread implementation would know how to match. For now,
233 // this just calls through to the ThreadSpec's ThreadPassesBasicTests method.
234 virtual bool MatchesSpec(const ThreadSpec *spec);
236 lldb::StopInfoSP GetStopInfo();
238 lldb::StopReason GetStopReason();
240 bool StopInfoIsUpToDate() const;
242 // This sets the stop reason to a "blank" stop reason, so you can call
243 // functions on the thread without having the called function run with
244 // whatever stop reason you stopped with.
245 void SetStopInfoToNothing();
247 bool ThreadStoppedForAReason();
249 static const char *RunModeAsCString(lldb::RunMode mode);
251 static const char *StopReasonAsCString(lldb::StopReason reason);
253 virtual const char *GetInfo() { return nullptr; }
255 /// Retrieve a dictionary of information about this thread
257 /// On Mac OS X systems there may be voucher information.
258 /// The top level dictionary returned will have an "activity" key and the
259 /// value of the activity is a dictionary. Keys in that dictionary will
260 /// be "name" and "id", among others.
261 /// There may also be "trace_messages" (an array) with each entry in that
263 /// being a dictionary (keys include "message" with the text of the trace
265 StructuredData::ObjectSP GetExtendedInfo() {
266 if (!m_extended_info_fetched) {
267 m_extended_info = FetchThreadExtendedInfo();
268 m_extended_info_fetched = true;
270 return m_extended_info;
273 virtual const char *GetName() { return nullptr; }
275 virtual void SetName(const char *name) {}
277 /// Whether this thread can be associated with a libdispatch queue
279 /// The Thread may know if it is associated with a libdispatch queue,
280 /// it may know definitively that it is NOT associated with a libdispatch
281 /// queue, or it may be unknown whether it is associated with a libdispatch
285 /// eLazyBoolNo if this thread is definitely not associated with a
286 /// libdispatch queue (e.g. on a non-Darwin system where GCD aka
287 /// libdispatch is not available).
289 /// eLazyBoolYes this thread is associated with a libdispatch queue.
291 /// eLazyBoolCalculate this thread may be associated with a libdispatch
292 /// queue but the thread doesn't know one way or the other.
293 virtual lldb_private::LazyBool GetAssociatedWithLibdispatchQueue() {
297 virtual void SetAssociatedWithLibdispatchQueue(
298 lldb_private::LazyBool associated_with_libdispatch_queue) {}
300 /// Retrieve the Queue ID for the queue currently using this Thread
302 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
303 /// retrieve the QueueID.
305 /// This is a unique identifier for the libdispatch/GCD queue in a
306 /// process. Often starting at 1 for the initial system-created
307 /// queues and incrementing, a QueueID will not be reused for a
308 /// different queue during the lifetime of a process.
311 /// A QueueID if the Thread subclass implements this, else
312 /// LLDB_INVALID_QUEUE_ID.
313 virtual lldb::queue_id_t GetQueueID() { return LLDB_INVALID_QUEUE_ID; }
315 virtual void SetQueueID(lldb::queue_id_t new_val) {}
317 /// Retrieve the Queue name for the queue currently using this Thread
319 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
320 /// retrieve the Queue name.
323 /// The Queue name, if the Thread subclass implements this, else
325 virtual const char *GetQueueName() { return nullptr; }
327 virtual void SetQueueName(const char *name) {}
329 /// Retrieve the Queue kind for the queue currently using this Thread
331 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
332 /// retrieve the Queue kind - either eQueueKindSerial or
333 /// eQueueKindConcurrent, indicating that this queue processes work
334 /// items serially or concurrently.
337 /// The Queue kind, if the Thread subclass implements this, else
338 /// eQueueKindUnknown.
339 virtual lldb::QueueKind GetQueueKind() { return lldb::eQueueKindUnknown; }
341 virtual void SetQueueKind(lldb::QueueKind kind) {}
343 /// Retrieve the Queue for this thread, if any.
346 /// A QueueSP for the queue that is currently associated with this
348 /// An empty shared pointer indicates that this thread is not
349 /// associated with a queue, or libdispatch queues are not
350 /// supported on this target.
351 virtual lldb::QueueSP GetQueue() { return lldb::QueueSP(); }
353 /// Retrieve the address of the libdispatch_queue_t struct for queue
354 /// currently using this Thread
356 /// If this Thread is doing work on behalf of a libdispatch/GCD queue,
357 /// retrieve the address of the libdispatch_queue_t structure describing
360 /// This address may be reused for different queues later in the Process
361 /// lifetime and should not be used to identify a queue uniquely. Use
362 /// the GetQueueID() call for that.
365 /// The Queue's libdispatch_queue_t address if the Thread subclass
366 /// implements this, else LLDB_INVALID_ADDRESS.
367 virtual lldb::addr_t GetQueueLibdispatchQueueAddress() {
368 return LLDB_INVALID_ADDRESS;
371 virtual void SetQueueLibdispatchQueueAddress(lldb::addr_t dispatch_queue_t) {}
373 /// Whether this Thread already has all the Queue information cached or not
375 /// A Thread may be associated with a libdispatch work Queue at a given
376 /// public stop event. If so, the thread can satisify requests like
377 /// GetQueueLibdispatchQueueAddress, GetQueueKind, GetQueueName, and
379 /// either from information from the remote debug stub when it is initially
380 /// created, or it can query the SystemRuntime for that information.
382 /// This method allows the SystemRuntime to discover if a thread has this
383 /// information already, instead of calling the thread to get the information
384 /// and having the thread call the SystemRuntime again.
385 virtual bool ThreadHasQueueInformation() const { return false; }
387 virtual uint32_t GetStackFrameCount() {
388 return GetStackFrameList()->GetNumFrames();
391 virtual lldb::StackFrameSP GetStackFrameAtIndex(uint32_t idx) {
392 return GetStackFrameList()->GetFrameAtIndex(idx);
395 virtual lldb::StackFrameSP
396 GetFrameWithConcreteFrameIndex(uint32_t unwind_idx);
398 bool DecrementCurrentInlinedDepth() {
399 return GetStackFrameList()->DecrementCurrentInlinedDepth();
402 uint32_t GetCurrentInlinedDepth() {
403 return GetStackFrameList()->GetCurrentInlinedDepth();
406 Status ReturnFromFrameWithIndex(uint32_t frame_idx,
407 lldb::ValueObjectSP return_value_sp,
408 bool broadcast = false);
410 Status ReturnFromFrame(lldb::StackFrameSP frame_sp,
411 lldb::ValueObjectSP return_value_sp,
412 bool broadcast = false);
414 Status JumpToLine(const FileSpec &file, uint32_t line,
415 bool can_leave_function, std::string *warnings = nullptr);
417 virtual lldb::StackFrameSP GetFrameWithStackID(const StackID &stack_id) {
418 if (stack_id.IsValid())
419 return GetStackFrameList()->GetFrameWithStackID(stack_id);
420 return lldb::StackFrameSP();
423 uint32_t GetSelectedFrameIndex() {
424 return GetStackFrameList()->GetSelectedFrameIndex();
427 lldb::StackFrameSP GetSelectedFrame();
429 uint32_t SetSelectedFrame(lldb_private::StackFrame *frame,
430 bool broadcast = false);
432 bool SetSelectedFrameByIndex(uint32_t frame_idx, bool broadcast = false);
434 bool SetSelectedFrameByIndexNoisily(uint32_t frame_idx,
435 Stream &output_stream);
437 void SetDefaultFileAndLineToSelectedFrame() {
438 GetStackFrameList()->SetDefaultFileAndLineToSelectedFrame();
441 virtual lldb::RegisterContextSP GetRegisterContext() = 0;
443 virtual lldb::RegisterContextSP
444 CreateRegisterContextForFrame(StackFrame *frame) = 0;
446 virtual void ClearStackFrames();
448 virtual bool SetBackingThread(const lldb::ThreadSP &thread_sp) {
452 virtual lldb::ThreadSP GetBackingThread() const { return lldb::ThreadSP(); }
454 virtual void ClearBackingThread() {
455 // Subclasses can use this function if a thread is actually backed by
456 // another thread. This is currently used for the OperatingSystem plug-ins
457 // where they might have a thread that is in memory, yet its registers are
458 // available through the lldb_private::Thread subclass for the current
459 // lldb_private::Process class. Since each time the process stops the
460 // backing threads for memory threads can change, we need a way to clear
461 // the backing thread for all memory threads each time we stop.
464 // If stop_format is true, this will be the form used when we print stop
465 // info. If false, it will be the form we use for thread list and co.
466 void DumpUsingSettingsFormat(Stream &strm, uint32_t frame_idx,
469 bool GetDescription(Stream &s, lldb::DescriptionLevel level,
470 bool print_json_thread, bool print_json_stopinfo);
472 /// Default implementation for stepping into.
474 /// This function is designed to be used by commands where the
475 /// process is publicly stopped.
477 /// \param[in] source_step
478 /// If true and the frame has debug info, then do a source level
479 /// step in, else do a single instruction step in.
481 /// \param[in] step_in_avoids_code_without_debug_info
482 /// If \a true, then avoid stepping into code that doesn't have
483 /// debug info, else step into any code regardless of whether it
486 /// \param[in] step_out_avoids_code_without_debug_info
487 /// If \a true, then if you step out to code with no debug info, keep
488 /// stepping out till you get to code with debug info.
491 /// An error that describes anything that went wrong
493 StepIn(bool source_step,
494 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
495 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
497 /// Default implementation for stepping over.
499 /// This function is designed to be used by commands where the
500 /// process is publicly stopped.
502 /// \param[in] source_step
503 /// If true and the frame has debug info, then do a source level
504 /// step over, else do a single instruction step over.
507 /// An error that describes anything that went wrong
508 virtual Status StepOver(
510 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
512 /// Default implementation for stepping out.
514 /// This function is designed to be used by commands where the
515 /// process is publicly stopped.
518 /// An error that describes anything that went wrong
519 virtual Status StepOut();
521 /// Retrieves the per-thread data area.
522 /// Most OSs maintain a per-thread pointer (e.g. the FS register on
523 /// x64), which we return the value of here.
526 /// LLDB_INVALID_ADDRESS if not supported, otherwise the thread
528 virtual lldb::addr_t GetThreadPointer();
530 /// Retrieves the per-module TLS block for a thread.
532 /// \param[in] module
533 /// The module to query TLS data for.
535 /// \param[in] tls_file_addr
536 /// The thread local address in module
538 /// If the thread has TLS data allocated for the
539 /// module, the address of the TLS block. Otherwise
540 /// LLDB_INVALID_ADDRESS is returned.
541 virtual lldb::addr_t GetThreadLocalData(const lldb::ModuleSP module,
542 lldb::addr_t tls_file_addr);
544 /// Check whether this thread is safe to run functions
546 /// The SystemRuntime may know of certain thread states (functions in
547 /// process of execution, for instance) which can make it unsafe for
548 /// functions to be called.
551 /// True if it is safe to call functions on this thread.
552 /// False if function calls should be avoided on this thread.
553 virtual bool SafeToCallFunctions();
555 // Thread Plan Providers:
556 // This section provides the basic thread plans that the Process control
557 // machinery uses to run the target. ThreadPlan.h provides more details on
558 // how this mechanism works. The thread provides accessors to a set of plans
559 // that perform basic operations. The idea is that particular Platform
560 // plugins can override these methods to provide the implementation of these
561 // basic operations appropriate to their environment.
563 // NB: All the QueueThreadPlanXXX providers return Shared Pointers to
564 // Thread plans. This is useful so that you can modify the plans after
565 // creation in ways specific to that plan type. Also, it is often necessary
566 // for ThreadPlans that utilize other ThreadPlans to implement their task to
567 // keep a shared pointer to the sub-plan. But besides that, the shared
568 // pointers should only be held onto by entities who live no longer than the
569 // thread containing the ThreadPlan.
570 // FIXME: If this becomes a problem, we can make a version that just returns a
572 // which it is clearly unsafe to hold onto, and a shared pointer version, and
573 // only allow ThreadPlan and Co. to use the latter. That is made more
574 // annoying to do because there's no elegant way to friend a method to all
575 // sub-classes of a given class.
578 /// Queues the base plan for a thread.
579 /// The version returned by Process does some things that are useful,
580 /// like handle breakpoints and signals, so if you return a plugin specific
581 /// one you probably want to call through to the Process one for anything
582 /// your plugin doesn't explicitly handle.
584 /// \param[in] abort_other_plans
585 /// \b true if we discard the currently queued plans and replace them with
587 /// Otherwise this plan will go on the end of the plan stack.
590 /// A shared pointer to the newly queued thread plan, or nullptr if the
591 /// plan could not be queued.
592 virtual lldb::ThreadPlanSP QueueFundamentalPlan(bool abort_other_plans);
594 /// Queues the plan used to step one instruction from the current PC of \a
597 /// \param[in] step_over
598 /// \b true if we step over calls to functions, false if we step in.
600 /// \param[in] abort_other_plans
601 /// \b true if we discard the currently queued plans and replace them with
603 /// Otherwise this plan will go on the end of the plan stack.
605 /// \param[in] stop_other_threads
606 /// \b true if we will stop other threads while we single step this one.
608 /// \param[out] status
609 /// A status with an error if queuing failed.
612 /// A shared pointer to the newly queued thread plan, or nullptr if the
613 /// plan could not be queued.
614 virtual lldb::ThreadPlanSP QueueThreadPlanForStepSingleInstruction(
615 bool step_over, bool abort_other_plans, bool stop_other_threads,
618 /// Queues the plan used to step through an address range, stepping over
621 /// \param[in] abort_other_plans
622 /// \b true if we discard the currently queued plans and replace them with
624 /// Otherwise this plan will go on the end of the plan stack.
627 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
631 /// The address range to step through.
633 /// \param[in] addr_context
634 /// When dealing with stepping through inlined functions the current PC is
635 /// not enough information to know
636 /// what "step" means. For instance a series of nested inline functions
637 /// might start at the same address.
638 // The \a addr_context provides the current symbol context the step
639 /// is supposed to be out of.
640 // FIXME: Currently unused.
642 /// \param[in] stop_other_threads
643 /// \b true if we will stop other threads while we single step this one.
645 /// \param[out] status
646 /// A status with an error if queuing failed.
648 /// \param[in] step_out_avoids_code_without_debug_info
649 /// If eLazyBoolYes, if the step over steps out it will continue to step
650 /// out till it comes to a frame with debug info.
651 /// If eLazyBoolCalculate, we will consult the default set in the thread.
654 /// A shared pointer to the newly queued thread plan, or nullptr if the
655 /// plan could not be queued.
656 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
657 bool abort_other_plans, const AddressRange &range,
658 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
660 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
662 // Helper function that takes a LineEntry to step, insted of an AddressRange.
663 // This may combine multiple LineEntries of the same source line number to
664 // step over a longer address range in a single operation.
665 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOverRange(
666 bool abort_other_plans, const LineEntry &line_entry,
667 const SymbolContext &addr_context, lldb::RunMode stop_other_threads,
669 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
671 /// Queues the plan used to step through an address range, stepping into
674 /// \param[in] abort_other_plans
675 /// \b true if we discard the currently queued plans and replace them with
677 /// Otherwise this plan will go on the end of the plan stack.
680 /// Type of step to do, only eStepTypeInto and eStepTypeOver are supported
684 /// The address range to step through.
686 /// \param[in] addr_context
687 /// When dealing with stepping through inlined functions the current PC is
688 /// not enough information to know
689 /// what "step" means. For instance a series of nested inline functions
690 /// might start at the same address.
691 // The \a addr_context provides the current symbol context the step
692 /// is supposed to be out of.
693 // FIXME: Currently unused.
695 /// \param[in] step_in_target
696 /// Name if function we are trying to step into. We will step out if we
697 /// don't land in that function.
699 /// \param[in] stop_other_threads
700 /// \b true if we will stop other threads while we single step this one.
702 /// \param[out] status
703 /// A status with an error if queuing failed.
705 /// \param[in] step_in_avoids_code_without_debug_info
706 /// If eLazyBoolYes we will step out if we step into code with no debug
708 /// If eLazyBoolCalculate we will consult the default set in the thread.
710 /// \param[in] step_out_avoids_code_without_debug_info
711 /// If eLazyBoolYes, if the step over steps out it will continue to step
712 /// out till it comes to a frame with debug info.
713 /// If eLazyBoolCalculate, it will consult the default set in the thread.
716 /// A shared pointer to the newly queued thread plan, or nullptr if the
717 /// plan could not be queued.
718 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
719 bool abort_other_plans, const AddressRange &range,
720 const SymbolContext &addr_context, const char *step_in_target,
721 lldb::RunMode stop_other_threads, Status &status,
722 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
723 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
725 // Helper function that takes a LineEntry to step, insted of an AddressRange.
726 // This may combine multiple LineEntries of the same source line number to
727 // step over a longer address range in a single operation.
728 virtual lldb::ThreadPlanSP QueueThreadPlanForStepInRange(
729 bool abort_other_plans, const LineEntry &line_entry,
730 const SymbolContext &addr_context, const char *step_in_target,
731 lldb::RunMode stop_other_threads, Status &status,
732 LazyBool step_in_avoids_code_without_debug_info = eLazyBoolCalculate,
733 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
735 /// Queue the plan used to step out of the function at the current PC of
738 /// \param[in] abort_other_plans
739 /// \b true if we discard the currently queued plans and replace them with
741 /// Otherwise this plan will go on the end of the plan stack.
743 /// \param[in] addr_context
744 /// When dealing with stepping through inlined functions the current PC is
745 /// not enough information to know
746 /// what "step" means. For instance a series of nested inline functions
747 /// might start at the same address.
748 // The \a addr_context provides the current symbol context the step
749 /// is supposed to be out of.
750 // FIXME: Currently unused.
752 /// \param[in] first_insn
753 /// \b true if this is the first instruction of a function.
755 /// \param[in] stop_other_threads
756 /// \b true if we will stop other threads while we single step this one.
758 /// \param[in] stop_vote
759 /// See standard meanings for the stop & run votes in ThreadPlan.h.
761 /// \param[in] run_vote
762 /// See standard meanings for the stop & run votes in ThreadPlan.h.
764 /// \param[out] status
765 /// A status with an error if queuing failed.
767 /// \param[in] step_out_avoids_code_without_debug_info
768 /// If eLazyBoolYes, if the step over steps out it will continue to step
769 /// out till it comes to a frame with debug info.
770 /// If eLazyBoolCalculate, it will consult the default set in the thread.
773 /// A shared pointer to the newly queued thread plan, or nullptr if the
774 /// plan could not be queued.
775 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOut(
776 bool abort_other_plans, SymbolContext *addr_context, bool first_insn,
777 bool stop_other_threads, Vote stop_vote, Vote run_vote,
778 uint32_t frame_idx, Status &status,
779 LazyBool step_out_avoids_code_without_debug_info = eLazyBoolCalculate);
781 /// Queue the plan used to step out of the function at the current PC of
782 /// a thread. This version does not consult the should stop here callback,
784 /// be used by other thread plans when they need to retain control of the step
787 /// \param[in] abort_other_plans
788 /// \b true if we discard the currently queued plans and replace them with
790 /// Otherwise this plan will go on the end of the plan stack.
792 /// \param[in] addr_context
793 /// When dealing with stepping through inlined functions the current PC is
794 /// not enough information to know
795 /// what "step" means. For instance a series of nested inline functions
796 /// might start at the same address.
797 // The \a addr_context provides the current symbol context the step
798 /// is supposed to be out of.
799 // FIXME: Currently unused.
801 /// \param[in] first_insn
802 /// \b true if this is the first instruction of a function.
804 /// \param[in] stop_other_threads
805 /// \b true if we will stop other threads while we single step this one.
807 /// \param[in] stop_vote
808 /// See standard meanings for the stop & run votes in ThreadPlan.h.
810 /// \param[in] run_vote
811 /// See standard meanings for the stop & run votes in ThreadPlan.h.
813 /// \param[in] frame_idx
816 /// \param[out] status
817 /// A status with an error if queuing failed.
819 /// \param[in] continue_to_next_branch
820 /// Normally this will enqueue a plan that will put a breakpoint on the
821 /// return address and continue
822 /// to there. If continue_to_next_branch is true, this is an operation not
823 /// involving the user --
824 /// e.g. stepping "next" in a source line and we instruction stepped into
825 /// another function --
826 /// so instead of putting a breakpoint on the return address, advance the
827 /// breakpoint to the
828 /// end of the source line that is doing the call, or until the next flow
829 /// control instruction.
830 /// If the return value from the function call is to be retrieved /
831 /// displayed to the user, you must stop
832 /// on the return address. The return value may be stored in volatile
833 /// registers which are overwritten
834 /// before the next branch instruction.
837 /// A shared pointer to the newly queued thread plan, or nullptr if the
838 /// plan could not be queued.
839 virtual lldb::ThreadPlanSP QueueThreadPlanForStepOutNoShouldStop(
840 bool abort_other_plans, SymbolContext *addr_context, bool first_insn,
841 bool stop_other_threads, Vote stop_vote, Vote run_vote,
842 uint32_t frame_idx, Status &status, bool continue_to_next_branch = false);
844 /// Gets the plan used to step through the code that steps from a function
845 /// call site at the current PC into the actual function call.
847 /// \param[in] return_stack_id
848 /// The stack id that we will return to (by setting backstop breakpoints on
850 /// address to that frame) if we fail to step through.
852 /// \param[in] abort_other_plans
853 /// \b true if we discard the currently queued plans and replace them with
855 /// Otherwise this plan will go on the end of the plan stack.
857 /// \param[in] stop_other_threads
858 /// \b true if we will stop other threads while we single step this one.
860 /// \param[out] status
861 /// A status with an error if queuing failed.
864 /// A shared pointer to the newly queued thread plan, or nullptr if the
865 /// plan could not be queued.
866 virtual lldb::ThreadPlanSP
867 QueueThreadPlanForStepThrough(StackID &return_stack_id,
868 bool abort_other_plans, bool stop_other_threads,
871 /// Gets the plan used to continue from the current PC.
872 /// This is a simple plan, mostly useful as a backstop when you are continuing
873 /// for some particular purpose.
875 /// \param[in] abort_other_plans
876 /// \b true if we discard the currently queued plans and replace them with
878 /// Otherwise this plan will go on the end of the plan stack.
880 /// \param[in] target_addr
881 /// The address to which we're running.
883 /// \param[in] stop_other_threads
884 /// \b true if we will stop other threads while we single step this one.
886 /// \param[out] status
887 /// A status with an error if queuing failed.
890 /// A shared pointer to the newly queued thread plan, or nullptr if the
891 /// plan could not be queued.
892 virtual lldb::ThreadPlanSP
893 QueueThreadPlanForRunToAddress(bool abort_other_plans, Address &target_addr,
894 bool stop_other_threads, Status &status);
896 virtual lldb::ThreadPlanSP QueueThreadPlanForStepUntil(
897 bool abort_other_plans, lldb::addr_t *address_list, size_t num_addresses,
898 bool stop_others, uint32_t frame_idx, Status &status);
900 virtual lldb::ThreadPlanSP
901 QueueThreadPlanForStepScripted(bool abort_other_plans, const char *class_name,
902 StructuredData::ObjectSP extra_args_sp,
903 bool stop_other_threads, Status &status);
905 // Thread Plan accessors:
907 /// Gets the plan which will execute next on the plan stack.
910 /// A pointer to the next executed plan.
911 ThreadPlan *GetCurrentPlan();
913 /// Unwinds the thread stack for the innermost expression plan currently
914 /// on the thread plan stack.
917 /// An error if the thread plan could not be unwound.
919 Status UnwindInnermostExpression();
921 /// Gets the outer-most plan that was popped off the plan stack in the
922 /// most recent stop. Useful for printing the stop reason accurately.
925 /// A pointer to the last completed plan.
926 lldb::ThreadPlanSP GetCompletedPlan();
928 /// Gets the outer-most return value from the completed plans
931 /// A ValueObjectSP, either empty if there is no return value,
932 /// or containing the return value.
933 lldb::ValueObjectSP GetReturnValueObject();
935 /// Gets the outer-most expression variable from the completed plans
938 /// A ExpressionVariableSP, either empty if there is no
939 /// plan completed an expression during the current stop
940 /// or the expression variable that was made for the completed expression.
941 lldb::ExpressionVariableSP GetExpressionVariable();
943 /// Checks whether the given plan is in the completed plans for this
947 /// Pointer to the plan you're checking.
950 /// Returns true if the input plan is in the completed plan stack,
952 bool IsThreadPlanDone(ThreadPlan *plan);
954 /// Checks whether the given plan is in the discarded plans for this
958 /// Pointer to the plan you're checking.
961 /// Returns true if the input plan is in the discarded plan stack,
963 bool WasThreadPlanDiscarded(ThreadPlan *plan);
965 /// Check if we have completed plan to override breakpoint stop reason
968 /// Returns true if completed plan stack is not empty
970 bool CompletedPlanOverridesBreakpoint();
972 /// Queues a generic thread plan.
974 /// \param[in] plan_sp
975 /// The plan to queue.
977 /// \param[in] abort_other_plans
978 /// \b true if we discard the currently queued plans and replace them with
980 /// Otherwise this plan will go on the end of the plan stack.
983 /// A pointer to the last completed plan.
984 Status QueueThreadPlan(lldb::ThreadPlanSP &plan_sp, bool abort_other_plans);
986 /// Discards the plans queued on the plan stack of the current thread. This
988 /// arbitrated by the "Master" ThreadPlans, using the "OkayToDiscard" call.
989 // But if \a force is true, all thread plans are discarded.
990 void DiscardThreadPlans(bool force);
992 /// Discards the plans queued on the plan stack of the current thread up to
994 /// including up_to_plan_sp.
996 // \param[in] up_to_plan_sp
997 // Discard all plans up to and including this one.
998 void DiscardThreadPlansUpToPlan(lldb::ThreadPlanSP &up_to_plan_sp);
1000 void DiscardThreadPlansUpToPlan(ThreadPlan *up_to_plan_ptr);
1002 /// Discards the plans queued on the plan stack of the current thread up to
1004 /// including the plan in that matches \a thread_index counting only
1005 /// the non-Private plans.
1007 /// \param[in] thread_index
1008 /// Discard all plans up to and including this user plan given by this
1012 /// \b true if there was a thread plan with that user index, \b false
1014 bool DiscardUserThreadPlansUpToIndex(uint32_t thread_index);
1016 /// Prints the current plan stack.
1019 /// The stream to which to dump the plan stack info.
1021 void DumpThreadPlans(
1023 lldb::DescriptionLevel desc_level = lldb::eDescriptionLevelVerbose,
1024 bool include_internal = true, bool ignore_boring = false) const;
1026 virtual bool CheckpointThreadState(ThreadStateCheckpoint &saved_state);
1029 RestoreRegisterStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1032 RestoreThreadStateFromCheckpoint(ThreadStateCheckpoint &saved_state);
1034 void EnableTracer(bool value, bool single_step);
1036 void SetTracer(lldb::ThreadPlanTracerSP &tracer_sp);
1038 // Get the thread index ID. The index ID that is guaranteed to not be re-used
1039 // by a process. They start at 1 and increase with each new thread. This
1040 // allows easy command line access by a unique ID that is easier to type than
1041 // the actual system thread ID.
1042 uint32_t GetIndexID() const;
1044 // Get the originating thread's index ID.
1045 // In the case of an "extended" thread -- a thread which represents the stack
1046 // that enqueued/spawned work that is currently executing -- we need to
1047 // provide the IndexID of the thread that actually did this work. We don't
1048 // want to just masquerade as that thread's IndexID by using it in our own
1049 // IndexID because that way leads to madness - but the driver program which
1050 // is iterating over extended threads may ask for the OriginatingThreadID to
1051 // display that information to the user.
1052 // Normal threads will return the same thing as GetIndexID();
1053 virtual uint32_t GetExtendedBacktraceOriginatingIndexID() {
1054 return GetIndexID();
1057 // The API ID is often the same as the Thread::GetID(), but not in all cases.
1058 // Thread::GetID() is the user visible thread ID that clients would want to
1059 // see. The API thread ID is the thread ID that is used when sending data
1060 // to/from the debugging protocol.
1061 virtual lldb::user_id_t GetProtocolID() const { return GetID(); }
1063 // lldb::ExecutionContextScope pure virtual functions
1064 lldb::TargetSP CalculateTarget() override;
1066 lldb::ProcessSP CalculateProcess() override;
1068 lldb::ThreadSP CalculateThread() override;
1070 lldb::StackFrameSP CalculateStackFrame() override;
1072 void CalculateExecutionContext(ExecutionContext &exe_ctx) override;
1075 GetStackFrameSPForStackFramePtr(StackFrame *stack_frame_ptr);
1077 size_t GetStatus(Stream &strm, uint32_t start_frame, uint32_t num_frames,
1078 uint32_t num_frames_with_source, bool stop_format,
1079 bool only_stacks = false);
1081 size_t GetStackFrameStatus(Stream &strm, uint32_t first_frame,
1082 uint32_t num_frames, bool show_frame_info,
1083 uint32_t num_frames_with_source);
1085 // We need a way to verify that even though we have a thread in a shared
1086 // pointer that the object itself is still valid. Currently this won't be the
1087 // case if DestroyThread() was called. DestroyThread is called when a thread
1088 // has been removed from the Process' thread list.
1089 bool IsValid() const { return !m_destroy_called; }
1091 // Sets and returns a valid stop info based on the process stop ID and the
1092 // current thread plan. If the thread stop ID does not match the process'
1093 // stop ID, the private stop reason is not set and an invalid StopInfoSP may
1096 // NOTE: This function must be called before the current thread plan is
1097 // moved to the completed plan stack (in Thread::ShouldStop()).
1099 // NOTE: If subclasses override this function, ensure they do not overwrite
1100 // the m_actual_stop_info if it is valid. The stop info may be a
1101 // "checkpointed and restored" stop info, so if it is still around it is
1102 // right even if you have not calculated this yourself, or if it disagrees
1103 // with what you might have calculated.
1104 virtual lldb::StopInfoSP GetPrivateStopInfo();
1106 // Calculate the stop info that will be shown to lldb clients. For instance,
1107 // a "step out" is implemented by running to a breakpoint on the function
1108 // return PC, so the process plugin initially sets the stop info to a
1109 // StopInfoBreakpoint. But once we've run the ShouldStop machinery, we
1110 // discover that there's a completed ThreadPlanStepOut, and that's really
1111 // the StopInfo we want to show. That will happen naturally the next
1112 // time GetStopInfo is called, but if you want to force the replacement,
1113 // you can call this.
1115 void CalculatePublicStopInfo();
1117 // Ask the thread subclass to set its stop info.
1119 // Thread subclasses should call Thread::SetStopInfo(...) with the reason the
1123 // True if Thread::SetStopInfo(...) was called, false otherwise.
1124 virtual bool CalculateStopInfo() = 0;
1126 // Gets the temporary resume state for a thread.
1128 // This value gets set in each thread by complex debugger logic in
1129 // Thread::ShouldResume() and an appropriate thread resume state will get set
1130 // in each thread every time the process is resumed prior to calling
1131 // Process::DoResume(). The lldb_private::Process subclass should adhere to
1132 // the thread resume state request which will be one of:
1134 // eStateRunning - thread will resume when process is resumed
1135 // eStateStepping - thread should step 1 instruction and stop when process
1137 // eStateSuspended - thread should not execute any instructions when
1138 // process is resumed
1139 lldb::StateType GetTemporaryResumeState() const {
1140 return m_temporary_resume_state;
1143 void SetStopInfo(const lldb::StopInfoSP &stop_info_sp);
1145 void ResetStopInfo();
1147 void SetShouldReportStop(Vote vote);
1149 /// Sets the extended backtrace token for this thread
1151 /// Some Thread subclasses may maintain a token to help with providing
1152 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1154 /// \param [in] token
1155 virtual void SetExtendedBacktraceToken(uint64_t token) {}
1157 /// Gets the extended backtrace token for this thread
1159 /// Some Thread subclasses may maintain a token to help with providing
1160 /// an extended backtrace. The SystemRuntime plugin will set/request this.
1163 /// The token needed by the SystemRuntime to create an extended backtrace.
1164 /// LLDB_INVALID_ADDRESS is returned if no token is available.
1165 virtual uint64_t GetExtendedBacktraceToken() { return LLDB_INVALID_ADDRESS; }
1167 lldb::ValueObjectSP GetCurrentException();
1169 lldb::ThreadSP GetCurrentExceptionBacktrace();
1172 friend class ThreadPlan;
1173 friend class ThreadList;
1174 friend class ThreadEventData;
1175 friend class StackFrameList;
1176 friend class StackFrame;
1177 friend class OperatingSystem;
1179 // This is necessary to make sure thread assets get destroyed while the
1180 // thread is still in good shape to call virtual thread methods. This must
1181 // be called by classes that derive from Thread in their destructor.
1182 virtual void DestroyThread();
1184 void PushPlan(lldb::ThreadPlanSP &plan_sp);
1190 ThreadPlan *GetPreviousPlan(ThreadPlan *plan);
1192 typedef std::vector<lldb::ThreadPlanSP> plan_stack;
1194 virtual lldb_private::Unwind *GetUnwinder();
1196 // Check to see whether the thread is still at the last breakpoint hit that
1198 virtual bool IsStillAtLastBreakpointHit();
1200 // Some threads are threads that are made up by OperatingSystem plugins that
1201 // are threads that exist and are context switched out into memory. The
1202 // OperatingSystem plug-in need a ways to know if a thread is "real" or made
1204 virtual bool IsOperatingSystemPluginThread() const { return false; }
1206 // Subclasses that have a way to get an extended info dictionary for this
1207 // thread should fill
1208 virtual lldb_private::StructuredData::ObjectSP FetchThreadExtendedInfo() {
1209 return StructuredData::ObjectSP();
1212 lldb::StackFrameListSP GetStackFrameList();
1214 void SetTemporaryResumeState(lldb::StateType new_state) {
1215 m_temporary_resume_state = new_state;
1218 void FunctionOptimizationWarning(lldb_private::StackFrame *frame);
1220 // Classes that inherit from Process can see and modify these
1221 lldb::ProcessWP m_process_wp; ///< The process that owns this thread.
1222 lldb::StopInfoSP m_stop_info_sp; ///< The private stop reason for this thread
1223 uint32_t m_stop_info_stop_id; // This is the stop id for which the StopInfo is
1224 // valid. Can use this so you know that
1225 // the thread's m_stop_info_sp is current and you don't have to fetch it
1227 uint32_t m_stop_info_override_stop_id; // The stop ID containing the last time
1228 // the stop info was checked against
1229 // the stop info override
1230 const uint32_t m_index_id; ///< A unique 1 based index assigned to each thread
1231 ///for easy UI/command line access.
1232 lldb::RegisterContextSP m_reg_context_sp; ///< The register context for this
1233 ///thread's current register state.
1234 lldb::StateType m_state; ///< The state of our process.
1235 mutable std::recursive_mutex
1236 m_state_mutex; ///< Multithreaded protection for m_state.
1237 plan_stack m_plan_stack; ///< The stack of plans this thread is executing.
1238 plan_stack m_completed_plan_stack; ///< Plans that have been completed by this
1239 ///stop. They get deleted when the thread
1241 plan_stack m_discarded_plan_stack; ///< Plans that have been discarded by this
1242 ///stop. They get deleted when the thread
1244 mutable std::recursive_mutex
1245 m_frame_mutex; ///< Multithreaded protection for m_state.
1246 lldb::StackFrameListSP m_curr_frames_sp; ///< The stack frames that get lazily
1247 ///populated after a thread stops.
1248 lldb::StackFrameListSP m_prev_frames_sp; ///< The previous stack frames from
1249 ///the last time this thread stopped.
1250 int m_resume_signal; ///< The signal that should be used when continuing this
1252 lldb::StateType m_resume_state; ///< This state is used to force a thread to
1253 ///be suspended from outside the ThreadPlan
1255 lldb::StateType m_temporary_resume_state; ///< This state records what the
1256 ///thread was told to do by the
1257 ///thread plan logic for the current
1259 /// It gets set in Thread::ShouldResume.
1260 std::unique_ptr<lldb_private::Unwind> m_unwinder_up;
1261 bool m_destroy_called; // This is used internally to make sure derived Thread
1262 // classes call DestroyThread.
1263 LazyBool m_override_should_notify;
1266 bool m_extended_info_fetched; // Have we tried to retrieve the m_extended_info
1268 StructuredData::ObjectSP m_extended_info; // The extended info for this thread
1271 bool PlanIsBasePlan(ThreadPlan *plan_ptr);
1273 void BroadcastSelectedFrameChange(StackID &new_frame_id);
1275 DISALLOW_COPY_AND_ASSIGN(Thread);
1278 } // namespace lldb_private
1280 #endif // liblldb_Thread_h_