| //===-- ThreadPlan.h --------------------------------------------*- C++ -*-===// |
| // |
| // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
| // See https://llvm.org/LICENSE.txt for license information. |
| // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
| // |
| //===----------------------------------------------------------------------===// |
| |
| #ifndef LLDB_TARGET_THREADPLAN_H |
| #define LLDB_TARGET_THREADPLAN_H |
| |
| #include <mutex> |
| #include <string> |
| |
| #include "lldb/Target/Process.h" |
| #include "lldb/Target/StopInfo.h" |
| #include "lldb/Target/Target.h" |
| #include "lldb/Target/Thread.h" |
| #include "lldb/Target/ThreadPlanTracer.h" |
| #include "lldb/Utility/UserID.h" |
| #include "lldb/lldb-private.h" |
| |
| namespace lldb_private { |
| |
| // ThreadPlan: |
| // |
| // This is the pure virtual base class for thread plans. |
| // |
| // The thread plans provide the "atoms" of behavior that all the logical |
| // process control, either directly from commands or through more complex |
| // composite plans will rely on. |
| // |
| // Plan Stack: |
| // |
| // The thread maintaining a thread plan stack, and you program the actions of |
| // a particular thread by pushing plans onto the plan stack. There is always |
| // a "Current" plan, which is the top of the plan stack, though in some cases |
| // a plan may defer to plans higher in the stack for some piece of information |
| // (let us define that the plan stack grows downwards). |
| // |
| // The plan stack is never empty, there is always a Base Plan which persists |
| // through the life of the running process. |
| // |
| // |
| // Creating Plans: |
| // |
| // The thread plan is generally created and added to the plan stack through |
| // the QueueThreadPlanFor... API in lldb::Thread. Those API's will return the |
| // plan that performs the named operation in a manner appropriate for the |
| // current process. The plans in lldb/source/Target are generic |
| // implementations, but a Process plugin can override them. |
| // |
| // ValidatePlan is then called. If it returns false, the plan is unshipped. |
| // This is a little convenience which keeps us from having to error out of the |
| // constructor. |
| // |
| // Then the plan is added to the plan stack. When the plan is added to the |
| // plan stack its DidPush will get called. This is useful if a plan wants to |
| // push any additional plans as it is constructed, since you need to make sure |
| // you're already on the stack before you push additional plans. |
| // |
| // Completed Plans: |
| // |
| // When the target process stops the plans are queried, among other things, |
| // for whether their job is done. If it is they are moved from the plan stack |
| // to the Completed Plan stack in reverse order from their position on the |
| // plan stack (since multiple plans may be done at a given stop.) This is |
| // used primarily so that the lldb::Thread::StopInfo for the thread can be set |
| // properly. If one plan pushes another to achieve part of its job, but it |
| // doesn't want that sub-plan to be the one that sets the StopInfo, then call |
| // SetPrivate on the sub-plan when you create it, and the Thread will pass |
| // over that plan in reporting the reason for the stop. |
| // |
| // Discarded plans: |
| // |
| // Your plan may also get discarded, i.e. moved from the plan stack to the |
| // "discarded plan stack". This can happen, for instance, if the plan is |
| // calling a function and the function call crashes and you want to unwind the |
| // attempt to call. So don't assume that your plan will always successfully |
| // stop. Which leads to: |
| // |
| // Cleaning up after your plans: |
| // |
| // When the plan is moved from the plan stack its DidPop method is always |
| // called, no matter why. Once it is moved off the plan stack it is done, and |
| // won't get a chance to run again. So you should undo anything that affects |
| // target state in this method. But be sure to leave the plan able to |
| // correctly fill the StopInfo, however. N.B. Don't wait to do clean up |
| // target state till the destructor, since that will usually get called when |
| // the target resumes, and you want to leave the target state correct for new |
| // plans in the time between when your plan gets unshipped and the next |
| // resume. |
| // |
| // Thread State Checkpoint: |
| // |
| // Note that calling functions on target process (ThreadPlanCallFunction) |
| // changes current thread state. The function can be called either by direct |
| // user demand or internally, for example lldb allocates memory on device to |
| // calculate breakpoint condition expression - on Linux it is performed by |
| // calling mmap on device. ThreadStateCheckpoint saves Thread state (stop |
| // info and completed plan stack) to restore it after completing function |
| // call. |
| // |
| // Over the lifetime of the plan, various methods of the ThreadPlan are then |
| // called in response to changes of state in the process we are debugging as |
| // follows: |
| // |
| // Resuming: |
| // |
| // When the target process is about to be restarted, the plan's WillResume |
| // method is called, giving the plan a chance to prepare for the run. If |
| // WillResume returns false, then the process is not restarted. Be sure to |
| // set an appropriate error value in the Process if you have to do this. |
| // Note, ThreadPlans actually implement DoWillResume, WillResume wraps that |
| // call. |
| // |
| // Next the "StopOthers" method of all the threads are polled, and if one |
| // thread's Current plan returns "true" then only that thread gets to run. If |
| // more than one returns "true" the threads that want to run solo get run one |
| // by one round robin fashion. Otherwise all are let to run. |
| // |
| // Note, the way StopOthers is implemented, the base class implementation just |
| // asks the previous plan. So if your plan has no opinion about whether it |
| // should run stopping others or not, just don't implement StopOthers, and the |
| // parent will be asked. |
| // |
| // Finally, for each thread that is running, it run state is set to the return |
| // of RunState from the thread's Current plan. |
| // |
| // Responding to a stop: |
| // |
| // When the target process stops, the plan is called in the following stages: |
| // |
| // First the thread asks the Current Plan if it can handle this stop by |
| // calling PlanExplainsStop. If the Current plan answers "true" then it is |
| // asked if the stop should percolate all the way to the user by calling the |
| // ShouldStop method. If the current plan doesn't explain the stop, then we |
| // query up the plan stack for a plan that does explain the stop. The plan |
| // that does explain the stop then needs to figure out what to do about the |
| // plans below it in the stack. If the stop is recoverable, then the plan |
| // that understands it can just do what it needs to set up to restart, and |
| // then continue. Otherwise, the plan that understood the stop should call |
| // DiscardPlanStack to clean up the stack below it. Note, plans actually |
| // implement DoPlanExplainsStop, the result is cached in PlanExplainsStop so |
| // the DoPlanExplainsStop itself will only get called once per stop. |
| // |
| // Controlling plans: |
| // |
| // In the normal case, when we decide to stop, we will collapse the plan |
| // stack up to the point of the plan that understood the stop reason. |
| // However, if a plan wishes to stay on the stack after an event it didn't |
| // directly handle it can designate itself a "Controlling" plan by responding |
| // true to IsControllingPlan, and then if it wants not to be discarded, it can |
| // return false to OkayToDiscard, and it and all its dependent plans will be |
| // preserved when we resume execution. |
| // |
| // The other effect of being a controlling plan is that when the Controlling |
| // plan is |
| // done , if it has set "OkayToDiscard" to false, then it will be popped & |
| // execution will stop and return to the user. Remember that if OkayToDiscard |
| // is false, the plan will be popped and control will be given to the next |
| // plan above it on the stack So setting OkayToDiscard to false means the |
| // user will regain control when the ControllingPlan is completed. |
| // |
| // Between these two controls this allows things like: a |
| // ControllingPlan/DontDiscard Step Over to hit a breakpoint, stop and return |
| // control to the user, but then when the user continues, the step out |
| // succeeds. Even more tricky, when the breakpoint is hit, the user can |
| // continue to step in/step over/etc, and finally when they continue, they |
| // will finish up the Step Over. |
| // |
| // FIXME: ControllingPlan & OkayToDiscard aren't really orthogonal. |
| // ControllingPlan |
| // designation means that this plan controls it's fate and the fate of plans |
| // below it. OkayToDiscard tells whether the ControllingPlan wants to stay on |
| // the stack. I originally thought "ControllingPlan-ness" would need to be a |
| // fixed |
| // characteristic of a ThreadPlan, in which case you needed the extra control. |
| // But that doesn't seem to be true. So we should be able to convert to only |
| // ControllingPlan status to mean the current "ControllingPlan/DontDiscard". |
| // Then no plans would be ControllingPlans by default, and you would set the |
| // ones you wanted to be "user level" in this way. |
| // |
| // |
| // Actually Stopping: |
| // |
| // If a plan says responds "true" to ShouldStop, then it is asked if it's job |
| // is complete by calling MischiefManaged. If that returns true, the plan is |
| // popped from the plan stack and added to the Completed Plan Stack. Then the |
| // next plan in the stack is asked if it ShouldStop, and it returns "true", |
| // it is asked if it is done, and if yes popped, and so on till we reach a |
| // plan that is not done. |
| // |
| // Since you often know in the ShouldStop method whether your plan is |
| // complete, as a convenience you can call SetPlanComplete and the ThreadPlan |
| // implementation of MischiefManaged will return "true", without your having |
| // to redo the calculation when your sub-classes MischiefManaged is called. |
| // If you call SetPlanComplete, you can later use IsPlanComplete to determine |
| // whether the plan is complete. This is only a convenience for sub-classes, |
| // the logic in lldb::Thread will only call MischiefManaged. |
| // |
| // One slightly tricky point is you have to be careful using SetPlanComplete |
| // in PlanExplainsStop because you are not guaranteed that PlanExplainsStop |
| // for a plan will get called before ShouldStop gets called. If your sub-plan |
| // explained the stop and then popped itself, only your ShouldStop will get |
| // called. |
| // |
| // If ShouldStop for any thread returns "true", then the WillStop method of |
| // the Current plan of all threads will be called, the stop event is placed on |
| // the Process's public broadcaster, and control returns to the upper layers |
| // of the debugger. |
| // |
| // Reporting the stop: |
| // |
| // When the process stops, the thread is given a StopReason, in the form of a |
| // StopInfo object. If there is a completed plan corresponding to the stop, |
| // then the "actual" stop reason can be suppressed, and instead a |
| // StopInfoThreadPlan object will be cons'ed up from the top completed plan in |
| // the stack. However, if the plan doesn't want to be the stop reason, then |
| // it can call SetPlanComplete and pass in "false" for the "success" |
| // parameter. In that case, the real stop reason will be used instead. One |
| // example of this is the "StepRangeStepIn" thread plan. If it stops because |
| // of a crash or breakpoint hit, it wants to unship itself, because it isn't |
| // so useful to have step in keep going after a breakpoint hit. But it can't |
| // be the reason for the stop or no-one would see that they had hit a |
| // breakpoint. |
| // |
| // Cleaning up the plan stack: |
| // |
| // One of the complications of ControllingPlans is that you may get past the |
| // limits |
| // of a plan without triggering it to clean itself up. For instance, if you |
| // are doing a ControllingPlan StepOver, and hit a breakpoint in a called |
| // function, |
| // then step over enough times to step out of the initial StepOver range, each |
| // of the step overs will explain the stop & take themselves off the stack, |
| // but control would never be returned to the original StepOver. Eventually, |
| // the user will continue, and when that continue stops, the old stale |
| // StepOver plan that was left on the stack will get woken up and notice it is |
| // done. But that can leave junk on the stack for a while. To avoid that, the |
| // plans implement a "IsPlanStale" method, that can check whether it is |
| // relevant anymore. On stop, after the regular plan negotiation, the |
| // remaining plan stack is consulted and if any plan says it is stale, it and |
| // the plans below it are discarded from the stack. |
| // |
| // Automatically Resuming: |
| // |
| // If ShouldStop for all threads returns "false", then the target process will |
| // resume. This then cycles back to Resuming above. |
| // |
| // Reporting eStateStopped events when the target is restarted: |
| // |
| // If a plan decides to auto-continue the target by returning "false" from |
| // ShouldStop, then it will be asked whether the Stopped event should still be |
| // reported. For instance, if you hit a breakpoint that is a User set |
| // breakpoint, but the breakpoint callback said to continue the target |
| // process, you might still want to inform the upper layers of lldb that the |
| // stop had happened. The way this works is every thread gets to vote on |
| // whether to report the stop. If all votes are eVoteNoOpinion, then the |
| // thread list will decide what to do (at present it will pretty much always |
| // suppress these stopped events.) If there is an eVoteYes, then the event |
| // will be reported regardless of the other votes. If there is an eVoteNo and |
| // no eVoteYes's, then the event won't be reported. |
| // |
| // One other little detail here, sometimes a plan will push another plan onto |
| // the plan stack to do some part of the first plan's job, and it would be |
| // convenient to tell that plan how it should respond to ShouldReportStop. |
| // You can do that by setting the report_stop_vote in the child plan when you |
| // create it. |
| // |
| // Suppressing the initial eStateRunning event: |
| // |
| // The private process running thread will take care of ensuring that only one |
| // "eStateRunning" event will be delivered to the public Process broadcaster |
| // per public eStateStopped event. However there are some cases where the |
| // public state of this process is eStateStopped, but a thread plan needs to |
| // restart the target, but doesn't want the running event to be publicly |
| // broadcast. The obvious example of this is running functions by hand as |
| // part of expression evaluation. To suppress the running event return |
| // eVoteNo from ShouldReportStop, to force a running event to be reported |
| // return eVoteYes, in general though you should return eVoteNoOpinion which |
| // will allow the ThreadList to figure out the right thing to do. The |
| // report_run_vote argument to the constructor works like report_stop_vote, and |
| // is a way for a plan to instruct a sub-plan on how to respond to |
| // ShouldReportStop. |
| |
| class ThreadPlan : public std::enable_shared_from_this<ThreadPlan>, |
| public UserID { |
| public: |
| // We use these enums so that we can cast a base thread plan to it's real |
| // type without having to resort to dynamic casting. |
| enum ThreadPlanKind { |
| eKindGeneric, |
| eKindNull, |
| eKindBase, |
| eKindCallFunction, |
| eKindPython, |
| eKindStepInstruction, |
| eKindStepOut, |
| eKindStepOverBreakpoint, |
| eKindStepOverRange, |
| eKindStepInRange, |
| eKindRunToAddress, |
| eKindStepThrough, |
| eKindStepUntil |
| }; |
| |
| virtual ~ThreadPlan(); |
| |
| /// Returns the name of this thread plan. |
| /// |
| /// \return |
| /// A const char * pointer to the thread plan's name. |
| const char *GetName() const { return m_name.c_str(); } |
| |
| /// Returns the Thread that is using this thread plan. |
| /// |
| /// \return |
| /// A pointer to the thread plan's owning thread. |
| Thread &GetThread(); |
| |
| Target &GetTarget(); |
| |
| const Target &GetTarget() const; |
| |
| /// Clear the Thread* cache. |
| /// |
| /// This is useful in situations like when a new Thread list is being |
| /// generated. |
| void ClearThreadCache(); |
| |
| /// Print a description of this thread to the stream \a s. |
| /// \a thread. Don't expect that the result of GetThread is valid in |
| /// the description method. This might get called when the underlying |
| /// Thread has not been reported, so we only know the TID and not the thread. |
| /// |
| /// \param[in] s |
| /// The stream to which to print the description. |
| /// |
| /// \param[in] level |
| /// The level of description desired. Note that eDescriptionLevelBrief |
| /// will be used in the stop message printed when the plan is complete. |
| virtual void GetDescription(Stream *s, lldb::DescriptionLevel level) = 0; |
| |
| /// Returns whether this plan could be successfully created. |
| /// |
| /// \param[in] error |
| /// A stream to which to print some reason why the plan could not be |
| /// created. |
| /// Can be NULL. |
| /// |
| /// \return |
| /// \b true if the plan should be queued, \b false otherwise. |
| virtual bool ValidatePlan(Stream *error) = 0; |
| |
| bool TracerExplainsStop() { |
| if (!m_tracer_sp) |
| return false; |
| else |
| return m_tracer_sp->TracerExplainsStop(); |
| } |
| |
| lldb::StateType RunState(); |
| |
| bool PlanExplainsStop(Event *event_ptr); |
| |
| virtual bool ShouldStop(Event *event_ptr) = 0; |
| |
| /// Returns whether this thread plan overrides the `ShouldStop` of |
| /// subsequently processed plans. |
| /// |
| /// When processing the thread plan stack, this function gives plans the |
| /// ability to continue - even when subsequent plans return true from |
| /// `ShouldStop`. \see Thread::ShouldStop |
| virtual bool ShouldAutoContinue(Event *event_ptr) { return false; } |
| |
| // Whether a "stop class" event should be reported to the "outside world". |
| // In general if a thread plan is active, events should not be reported. |
| |
| virtual Vote ShouldReportStop(Event *event_ptr); |
| |
| Vote ShouldReportRun(Event *event_ptr); |
| |
| virtual void SetStopOthers(bool new_value); |
| |
| virtual bool StopOthers(); |
| |
| // This is the wrapper for DoWillResume that does generic ThreadPlan logic, |
| // then calls DoWillResume. |
| bool WillResume(lldb::StateType resume_state, bool current_plan); |
| |
| virtual bool WillStop() = 0; |
| |
| bool IsControllingPlan() { return m_is_controlling_plan; } |
| |
| bool SetIsControllingPlan(bool value) { |
| bool old_value = m_is_controlling_plan; |
| m_is_controlling_plan = value; |
| return old_value; |
| } |
| |
| virtual bool OkayToDiscard(); |
| |
| void SetOkayToDiscard(bool value) { m_okay_to_discard = value; } |
| |
| // The base class MischiefManaged does some cleanup - so you have to call it |
| // in your MischiefManaged derived class. |
| virtual bool MischiefManaged(); |
| |
| virtual void ThreadDestroyed() { |
| // Any cleanup that a plan might want to do in case the thread goes away in |
| // the middle of the plan being queued on a thread can be done here. |
| } |
| |
| bool GetPrivate() { return m_plan_private; } |
| |
| void SetPrivate(bool input) { m_plan_private = input; } |
| |
| virtual void DidPush(); |
| |
| virtual void DidPop(); |
| |
| ThreadPlanKind GetKind() const { return m_kind; } |
| |
| bool IsPlanComplete(); |
| |
| void SetPlanComplete(bool success = true); |
| |
| virtual bool IsPlanStale() { return false; } |
| |
| bool PlanSucceeded() { return m_plan_succeeded; } |
| |
| virtual bool IsBasePlan() { return false; } |
| |
| lldb::ThreadPlanTracerSP &GetThreadPlanTracer() { return m_tracer_sp; } |
| |
| void SetThreadPlanTracer(lldb::ThreadPlanTracerSP new_tracer_sp) { |
| m_tracer_sp = new_tracer_sp; |
| } |
| |
| void DoTraceLog() { |
| if (m_tracer_sp && m_tracer_sp->TracingEnabled()) |
| m_tracer_sp->Log(); |
| } |
| |
| // If the completion of the thread plan stepped out of a function, the return |
| // value of the function might have been captured by the thread plan |
| // (currently only ThreadPlanStepOut does this.) If so, the ReturnValueObject |
| // can be retrieved from here. |
| |
| virtual lldb::ValueObjectSP GetReturnValueObject() { |
| return lldb::ValueObjectSP(); |
| } |
| |
| // If the thread plan managing the evaluation of a user expression lives |
| // longer than the command that instigated the expression (generally because |
| // the expression evaluation hit a breakpoint, and the user regained control |
| // at that point) a subsequent process control command step/continue/etc. |
| // might complete the expression evaluations. If so, the result of the |
| // expression evaluation will show up here. |
| |
| virtual lldb::ExpressionVariableSP GetExpressionVariable() { |
| return lldb::ExpressionVariableSP(); |
| } |
| |
| // If a thread plan stores the state before it was run, then you might want |
| // to restore the state when it is done. This will do that job. This is |
| // mostly useful for artificial plans like CallFunction plans. |
| |
| virtual void RestoreThreadState() {} |
| |
| virtual bool IsVirtualStep() { return false; } |
| |
| bool SetIterationCount(size_t count) { |
| if (m_takes_iteration_count) { |
| // Don't tell me to do something 0 times... |
| if (count == 0) |
| return false; |
| m_iteration_count = count; |
| } |
| return m_takes_iteration_count; |
| } |
| |
| protected: |
| // Constructors and Destructors |
| ThreadPlan(ThreadPlanKind kind, const char *name, Thread &thread, |
| Vote report_stop_vote, Vote report_run_vote); |
| |
| // Classes that inherit from ThreadPlan can see and modify these |
| |
| virtual bool DoWillResume(lldb::StateType resume_state, bool current_plan) { |
| return true; |
| } |
| |
| virtual bool DoPlanExplainsStop(Event *event_ptr) = 0; |
| |
| // This pushes a plan onto the plan stack of the current plan's thread. |
| // Also sets the plans to private and not controlling plans. A plan pushed by |
| // another thread plan is never either of the above. |
| void PushPlan(lldb::ThreadPlanSP &thread_plan_sp) { |
| GetThread().PushPlan(thread_plan_sp); |
| thread_plan_sp->SetPrivate(true); |
| thread_plan_sp->SetIsControllingPlan(false); |
| } |
| |
| // This gets the previous plan to the current plan (for forwarding requests). |
| // This is mostly a formal requirement, it allows us to make the Thread's |
| // GetPreviousPlan protected, but only friend ThreadPlan to thread. |
| |
| ThreadPlan *GetPreviousPlan() { return GetThread().GetPreviousPlan(this); } |
| |
| // This forwards the private Thread::GetPrivateStopInfo which is generally |
| // what ThreadPlan's need to know. |
| |
| lldb::StopInfoSP GetPrivateStopInfo() { |
| return GetThread().GetPrivateStopInfo(); |
| } |
| |
| void SetStopInfo(lldb::StopInfoSP stop_reason_sp) { |
| GetThread().SetStopInfo(stop_reason_sp); |
| } |
| |
| virtual lldb::StateType GetPlanRunState() = 0; |
| |
| bool IsUsuallyUnexplainedStopReason(lldb::StopReason); |
| |
| Status m_status; |
| Process &m_process; |
| lldb::tid_t m_tid; |
| Vote m_report_stop_vote; |
| Vote m_report_run_vote; |
| bool m_takes_iteration_count; |
| bool m_could_not_resolve_hw_bp; |
| int32_t m_iteration_count = 1; |
| |
| private: |
| void CachePlanExplainsStop(bool does_explain) { |
| m_cached_plan_explains_stop = does_explain ? eLazyBoolYes : eLazyBoolNo; |
| } |
| |
| // For ThreadPlan only |
| static lldb::user_id_t GetNextID(); |
| |
| Thread *m_thread; // Stores a cached value of the thread, which is set to |
| // nullptr when the thread resumes. Don't use this anywhere |
| // but ThreadPlan::GetThread(). |
| ThreadPlanKind m_kind; |
| std::string m_name; |
| std::recursive_mutex m_plan_complete_mutex; |
| LazyBool m_cached_plan_explains_stop; |
| bool m_plan_complete; |
| bool m_plan_private; |
| bool m_okay_to_discard; |
| bool m_is_controlling_plan; |
| bool m_plan_succeeded; |
| |
| lldb::ThreadPlanTracerSP m_tracer_sp; |
| |
| ThreadPlan(const ThreadPlan &) = delete; |
| const ThreadPlan &operator=(const ThreadPlan &) = delete; |
| }; |
| |
| // ThreadPlanNull: |
| // Threads are assumed to always have at least one plan on the plan stack. This |
| // is put on the plan stack when a thread is destroyed so that if you |
| // accidentally access a thread after it is destroyed you won't crash. But |
| // asking questions of the ThreadPlanNull is definitely an error. |
| |
| class ThreadPlanNull : public ThreadPlan { |
| public: |
| ThreadPlanNull(Thread &thread); |
| ~ThreadPlanNull() override; |
| |
| void GetDescription(Stream *s, lldb::DescriptionLevel level) override; |
| |
| bool ValidatePlan(Stream *error) override; |
| |
| bool ShouldStop(Event *event_ptr) override; |
| |
| bool MischiefManaged() override; |
| |
| bool WillStop() override; |
| |
| bool IsBasePlan() override { return true; } |
| |
| bool OkayToDiscard() override { return false; } |
| |
| const Status &GetStatus() { return m_status; } |
| |
| protected: |
| bool DoPlanExplainsStop(Event *event_ptr) override; |
| |
| lldb::StateType GetPlanRunState() override; |
| |
| ThreadPlanNull(const ThreadPlanNull &) = delete; |
| const ThreadPlanNull &operator=(const ThreadPlanNull &) = delete; |
| }; |
| |
| } // namespace lldb_private |
| |
| #endif // LLDB_TARGET_THREADPLAN_H |