lldb/Target/StopInfo.h

0001 //===-- StopInfo.h ----------------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLDB_TARGET_STOPINFO_H
0010 #define LLDB_TARGET_STOPINFO_H
0011
0012 #include <string>
0013
0014 #include "lldb/Target/Process.h"
0015 #include "lldb/Utility/StructuredData.h"
0016 #include "lldb/lldb-public.h"
0017
0018 namespace lldb_private {
0019
0020 class StopInfo : public std::enable_shared_from_this<StopInfo> {
0021   friend class Process::ProcessEventData;
0022   friend class ThreadPlanBase;
0023
0024 public:
0025   // Constructors and Destructors
0026   StopInfo(Thread &thread, uint64_t value);
0027
0028   virtual ~StopInfo() = default;
0029
0030   bool IsValid() const;
0031
0032   void SetThread(const lldb::ThreadSP &thread_sp) { m_thread_wp = thread_sp; }
0033
0034   lldb::ThreadSP GetThread() const { return m_thread_wp.lock(); }
0035
0036   // The value of the StopInfo depends on the StopReason.
0037   //
0038   // StopReason Meaning
0039   // ------------------------------------------------
0040   // eStopReasonBreakpoint       BreakpointSiteID
0041   // eStopReasonSignal           Signal number
0042   // eStopReasonWatchpoint       WatchpointLocationID
0043   // eStopReasonPlanComplete     No significance
0044
0045   uint64_t GetValue() const { return m_value; }
0046
0047   virtual lldb::StopReason GetStopReason() const = 0;
0048
0049   // ShouldStopSynchronous will get called before any thread plans are
0050   // consulted, and if it says we should resume the target, then we will just
0051   // immediately resume.  This should not run any code in or resume the target.
0052
0053   virtual bool ShouldStopSynchronous(Event *event_ptr) { return true; }
0054
0055   void OverrideShouldNotify(bool override_value) {
0056     m_override_should_notify = override_value ? eLazyBoolYes : eLazyBoolNo;
0057   }
0058
0059   // If should stop returns false, check if we should notify of this event
0060   virtual bool ShouldNotify(Event *event_ptr) {
0061     if (m_override_should_notify == eLazyBoolCalculate)
0062       return DoShouldNotify(event_ptr);
0063     else
0064       return m_override_should_notify == eLazyBoolYes;
0065   }
0066
0067   virtual void WillResume(lldb::StateType resume_state) {
0068     // By default, don't do anything
0069   }
0070
0071   virtual const char *GetDescription() { return m_description.c_str(); }
0072
0073   virtual void SetDescription(const char *desc_cstr) {
0074     if (desc_cstr && desc_cstr[0])
0075       m_description.assign(desc_cstr);
0076     else
0077       m_description.clear();
0078   }
0079
0080   /// This gives the StopInfo a chance to suggest a stack frame to select.
0081   /// Passing true for inlined_stack will request changes to the inlined
0082   /// call stack.  Passing false will request changes to the real stack
0083   /// frame.  The inlined stack gets adjusted before we call into the thread
0084   /// plans so they can reason based on the correct values.  The real stack
0085   /// adjustment is handled after the frame recognizers get a chance to adjust
0086   /// the frame.
0087   virtual std::optional<uint32_t>
0088   GetSuggestedStackFrameIndex(bool inlined_stack) {
0089     return {};
0090   }
0091
0092   virtual bool IsValidForOperatingSystemThread(Thread &thread) { return true; }
0093
0094   /// A Continue operation can result in a false stop event
0095   /// before any execution has happened. We need to detect this
0096   /// and silently continue again one more time.
0097   virtual bool WasContinueInterrupted(Thread &thread) { return false; }
0098
0099   // Sometimes the thread plan logic will know that it wants a given stop to
0100   // stop or not, regardless of what the ordinary logic for that StopInfo would
0101   // dictate.  The main example of this is the ThreadPlanCallFunction, which
0102   // for instance knows - based on how that particular expression was executed
0103   // - whether it wants all breakpoints to auto-continue or not. Use
0104   // OverrideShouldStop on the StopInfo to implement this.
0105
0106   void OverrideShouldStop(bool override_value) {
0107     m_override_should_stop = override_value ? eLazyBoolYes : eLazyBoolNo;
0108   }
0109
0110   bool GetOverrideShouldStop() {
0111     return m_override_should_stop != eLazyBoolCalculate;
0112   }
0113
0114   bool GetOverriddenShouldStopValue() {
0115     return m_override_should_stop == eLazyBoolYes;
0116   }
0117
0118   StructuredData::ObjectSP GetExtendedInfo() { return m_extended_info; }
0119
0120   static lldb::StopInfoSP
0121   CreateStopReasonWithBreakpointSiteID(Thread &thread,
0122                                        lldb::break_id_t break_id);
0123
0124   // This creates a StopInfo for the thread where the should_stop is already
0125   // set, and won't be recalculated.
0126   static lldb::StopInfoSP CreateStopReasonWithBreakpointSiteID(
0127       Thread &thread, lldb::break_id_t break_id, bool should_stop);
0128
0129   static lldb::StopInfoSP
0130   CreateStopReasonWithWatchpointID(Thread &thread, lldb::break_id_t watch_id,
0131                                    bool silently_continue = false);
0132
0133   static lldb::StopInfoSP
0134   CreateStopReasonWithSignal(Thread &thread, int signo,
0135                              const char *description = nullptr,
0136                              std::optional<int> code = std::nullopt);
0137
0138   static lldb::StopInfoSP
0139   CreateStopReasonWithInterrupt(Thread &thread, int signo,
0140                                 const char *description);
0141
0142   static lldb::StopInfoSP CreateStopReasonToTrace(Thread &thread);
0143
0144   static lldb::StopInfoSP
0145   CreateStopReasonWithPlan(lldb::ThreadPlanSP &plan,
0146                            lldb::ValueObjectSP return_valobj_sp,
0147                            lldb::ExpressionVariableSP expression_variable_sp);
0148
0149   static lldb::StopInfoSP
0150   CreateStopReasonWithException(Thread &thread, const char *description);
0151
0152   static lldb::StopInfoSP CreateStopReasonWithExec(Thread &thread);
0153
0154   static lldb::StopInfoSP
0155   CreateStopReasonProcessorTrace(Thread &thread, const char *description);
0156
0157   static lldb::StopInfoSP CreateStopReasonFork(Thread &thread,
0158                                                lldb::pid_t child_pid,
0159                                                lldb::tid_t child_tid);
0160
0161   static lldb::StopInfoSP CreateStopReasonVFork(Thread &thread,
0162                                                 lldb::pid_t child_pid,
0163                                                 lldb::tid_t child_tid);
0164
0165   static lldb::StopInfoSP CreateStopReasonVForkDone(Thread &thread);
0166
0167   static lldb::ValueObjectSP
0168   GetReturnValueObject(lldb::StopInfoSP &stop_info_sp);
0169
0170   static lldb::ExpressionVariableSP
0171   GetExpressionVariable(lldb::StopInfoSP &stop_info_sp);
0172
0173   static lldb::ValueObjectSP
0174   GetCrashingDereference(lldb::StopInfoSP &stop_info_sp,
0175                          lldb::addr_t *crashing_address = nullptr);
0176
0177 protected:
0178   // Perform any action that is associated with this stop.  This is done as the
0179   // Event is removed from the event queue.  ProcessEventData::DoOnRemoval does
0180   // the job.
0181
0182   virtual void PerformAction(Event *event_ptr) {}
0183
0184   virtual bool DoShouldNotify(Event *event_ptr) { return false; }
0185
0186   // Stop the thread by default. Subclasses can override this to allow the
0187   // thread to continue if desired.  The ShouldStop method should not do
0188   // anything that might run code.  If you need to run code when deciding
0189   // whether to stop at this StopInfo, that must be done in the PerformAction.
0190   // The PerformAction will always get called before the ShouldStop.  This is
0191   // done by the ProcessEventData::DoOnRemoval, though the ThreadPlanBase needs
0192   // to consult this later on.
0193   virtual bool ShouldStop(Event *event_ptr) { return true; }
0194
0195   // Classes that inherit from StackID can see and modify these
0196   lldb::ThreadWP m_thread_wp; // The thread corresponding to the stop reason.
0197   uint32_t m_stop_id;   // The process stop ID for which this stop info is valid
0198   uint32_t m_resume_id; // This is the resume ID when we made this stop ID.
0199   uint64_t m_value; // A generic value that can be used for things pertaining to
0200                     // this stop info
0201   std::string m_description; // A textual description describing this stop.
0202   LazyBool m_override_should_notify;
0203   LazyBool m_override_should_stop;
0204
0205   StructuredData::ObjectSP
0206       m_extended_info; // The extended info for this stop info
0207
0208   // This determines whether the target has run since this stop info. N.B.
0209   // running to evaluate a user expression does not count.
0210   bool HasTargetRunSinceMe();
0211
0212   // MakeStopInfoValid is necessary to allow saved stop infos to resurrect
0213   // themselves as valid. It should only be used by
0214   // Thread::RestoreThreadStateFromCheckpoint and to make sure the one-step
0215   // needed for before-the-fact watchpoints does not prevent us from stopping
0216   void MakeStopInfoValid();
0217
0218 private:
0219   friend class Thread;
0220
0221   StopInfo(const StopInfo &) = delete;
0222   const StopInfo &operator=(const StopInfo &) = delete;
0223 };
0224
0225 } // namespace lldb_private
0226
0227 #endif // LLDB_TARGET_STOPINFO_H