contrib/llvm-project/lldb/include/lldb/Breakpoint/BreakpointOptions.h

   1 //===-- BreakpointOptions.h -------------------------------------*- C++ -*-===//
   2 //
   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
   6 //
   7 //===----------------------------------------------------------------------===//
   8
   9 #ifndef liblldb_BreakpointOptions_h_
  10 #define liblldb_BreakpointOptions_h_
  11
  12 #include <memory>
  13 #include <string>
  14
  15 #include "lldb/Utility/Baton.h"
  16 #include "lldb/Utility/Flags.h"
  17 #include "lldb/Utility/StringList.h"
  18 #include "lldb/Utility/StructuredData.h"
  19 #include "lldb/lldb-private.h"
  20
  21 namespace lldb_private {
  22
  23 /// \class BreakpointOptions BreakpointOptions.h
  24 /// "lldb/Breakpoint/BreakpointOptions.h" Class that manages the options on a
  25 /// breakpoint or breakpoint location.
  26
  27 class BreakpointOptions {
  28 friend class BreakpointLocation;
  29 friend class BreakpointName;
  30 friend class lldb_private::BreakpointOptionGroup;
  31 friend class Breakpoint;
  32
  33 public:
  34   enum OptionKind {
  35     eCallback     = 1 << 0,
  36     eEnabled      = 1 << 1,
  37     eOneShot      = 1 << 2,
  38     eIgnoreCount  = 1 << 3,
  39     eThreadSpec   = 1 << 4,
  40     eCondition    = 1 << 5,
  41     eAutoContinue = 1 << 6,
  42     eAllOptions   = (eCallback | eEnabled | eOneShot | eIgnoreCount | eThreadSpec
  43                      | eCondition | eAutoContinue)
  44   };
  45   struct CommandData {
  46     CommandData()
  47         : user_source(), script_source(),
  48           interpreter(lldb::eScriptLanguageNone), stop_on_error(true) {}
  49
  50     CommandData(const StringList &user_source, lldb::ScriptLanguage interp)
  51         : user_source(user_source), script_source(), interpreter(interp),
  52           stop_on_error(true) {}
  53
  54     ~CommandData() = default;
  55
  56     static const char *GetSerializationKey() { return "BKPTCMDData"; }
  57
  58     StructuredData::ObjectSP SerializeToStructuredData();
  59
  60     static std::unique_ptr<CommandData>
  61     CreateFromStructuredData(const StructuredData::Dictionary &options_dict,
  62                              Status &error);
  63
  64     StringList user_source;
  65     std::string script_source;
  66     enum lldb::ScriptLanguage
  67         interpreter; // eScriptLanguageNone means command interpreter.
  68     bool stop_on_error;
  69
  70   private:
  71     enum class OptionNames : uint32_t {
  72       UserSource = 0,
  73       Interpreter,
  74       StopOnError,
  75       LastOptionName
  76     };
  77
  78     static const char
  79         *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)];
  80
  81     static const char *GetKey(OptionNames enum_value) {
  82       return g_option_names[static_cast<uint32_t>(enum_value)];
  83     }
  84   };
  85
  86   class CommandBaton : public TypedBaton<CommandData> {
  87   public:
  88     explicit CommandBaton(std::unique_ptr<CommandData> Data)
  89         : TypedBaton(std::move(Data)) {}
  90
  91     void GetDescription(Stream *s, lldb::DescriptionLevel level) const override;
  92   };
  93
  94   typedef std::shared_ptr<CommandBaton> CommandBatonSP;
  95
  96   // Constructors and Destructors
  97
  98   /// This constructor allows you to specify all the breakpoint options except
  99   /// the callback.  That one is more complicated, and better to do by hand.
 100   ///
 101   /// \param[in] condition
 102   ///    The expression which if it evaluates to \b true if we are to stop
 103   ///
 104   /// \param[in] enabled
 105   ///    Is this breakpoint enabled.
 106   ///
 107   /// \param[in] ignore
 108   ///    How many breakpoint hits we should ignore before stopping.
 109   ///
 110   BreakpointOptions(const char *condition, bool enabled = true,
 111                     int32_t ignore = 0, bool one_shot = false,
 112                     bool auto_continue = false);
 113
 114   /// Breakpoints make options with all flags set.  Locations and Names make
 115   /// options with no flags set.
 116   BreakpointOptions(bool all_flags_set);
 117   BreakpointOptions(const BreakpointOptions &rhs);
 118
 119   virtual ~BreakpointOptions();
 120
 121   static std::unique_ptr<BreakpointOptions>
 122   CreateFromStructuredData(Target &target,
 123                            const StructuredData::Dictionary &data_dict,
 124                            Status &error);
 125
 126   virtual StructuredData::ObjectSP SerializeToStructuredData();
 127
 128   static const char *GetSerializationKey() { return "BKPTOptions"; }
 129
 130   // Operators
 131   const BreakpointOptions &operator=(const BreakpointOptions &rhs);
 132
 133   /// Copy over only the options set in the incoming BreakpointOptions.
 134   void CopyOverSetOptions(const BreakpointOptions &rhs);
 135
 136   // Callbacks
 137   //
 138   // Breakpoint callbacks come in two forms, synchronous and asynchronous.
 139   // Synchronous callbacks will get run before any of the thread plans are
 140   // consulted, and if they return false the target will continue "under the
 141   // radar" of the thread plans.  There are a couple of restrictions to
 142   // synchronous callbacks:
 143   // 1) They should NOT resume the target themselves.
 144   //     Just return false if you want the target to restart.
 145   // 2) Breakpoints with synchronous callbacks can't have conditions
 146   //    (or rather, they can have them, but they won't do anything.
 147   //    Ditto with ignore counts, etc...  You are supposed to control that all
 148   //    through the callback.
 149   // Asynchronous callbacks get run as part of the "ShouldStop" logic in the
 150   // thread plan.  The logic there is:
 151   //   a) If the breakpoint is thread specific and not for this thread, continue
 152   //   w/o running the callback.
 153   //      NB. This is actually enforced underneath the breakpoint system, the
 154   //      Process plugin is expected to
 155   //      call BreakpointSite::IsValidForThread, and set the thread's StopInfo
 156   //      to "no reason".  That way,
 157   //      thread displays won't show stops for breakpoints not for that
 158   //      thread...
 159   //   b) If the ignore count says we shouldn't stop, then ditto.
 160   //   c) If the condition says we shouldn't stop, then ditto.
 161   //   d) Otherwise, the callback will get run, and if it returns true we will
 162   //      stop, and if false we won't.
 163   //  The asynchronous callback can run the target itself, but at present that
 164   //  should be the last action the callback does.  We will relax this condition
 165   //  at some point, but it will take a bit of plumbing to get that to work.
 166   //
 167
 168   /// Adds a callback to the breakpoint option set.
 169   ///
 170   /// \param[in] callback
 171   ///    The function to be called when the breakpoint gets hit.
 172   ///
 173   /// \param[in] baton_sp
 174   ///    A baton which will get passed back to the callback when it is invoked.
 175   ///
 176   /// \param[in] synchronous
 177   ///    Whether this is a synchronous or asynchronous callback.  See discussion
 178   ///    above.
 179   void SetCallback(BreakpointHitCallback callback,
 180                    const lldb::BatonSP &baton_sp, bool synchronous = false);
 181
 182   void SetCallback(BreakpointHitCallback callback,
 183                    const BreakpointOptions::CommandBatonSP &command_baton_sp,
 184                    bool synchronous = false);
 185
 186   /// Returns the command line commands for the callback on this breakpoint.
 187   ///
 188   /// \param[out] command_list
 189   ///    The commands will be appended to this list.
 190   ///
 191   /// \return
 192   ///    \btrue if the command callback is a command-line callback,
 193   ///    \bfalse otherwise.
 194   bool GetCommandLineCallbacks(StringList &command_list);
 195
 196   /// Remove the callback from this option set.
 197   void ClearCallback();
 198
 199   // The rest of these functions are meant to be used only within the
 200   // breakpoint handling mechanism.
 201
 202   /// Use this function to invoke the callback for a specific stop.
 203   ///
 204   /// \param[in] context
 205   ///    The context in which the callback is to be invoked.  This includes the
 206   ///    stop event, the
 207   ///    execution context of the stop (since you might hit the same breakpoint
 208   ///    on multiple threads) and
 209   ///    whether we are currently executing synchronous or asynchronous
 210   ///    callbacks.
 211   ///
 212   /// \param[in] break_id
 213   ///    The breakpoint ID that owns this option set.
 214   ///
 215   /// \param[in] break_loc_id
 216   ///    The breakpoint location ID that owns this option set.
 217   ///
 218   /// \return
 219   ///     The callback return value.
 220   bool InvokeCallback(StoppointCallbackContext *context,
 221                       lldb::user_id_t break_id, lldb::user_id_t break_loc_id);
 222
 223   /// Used in InvokeCallback to tell whether it is the right time to run this
 224   /// kind of callback.
 225   ///
 226   /// \return
 227   ///     The synchronicity of our callback.
 228   bool IsCallbackSynchronous() const { return m_callback_is_synchronous; }
 229
 230   /// Fetch the baton from the callback.
 231   ///
 232   /// \return
 233   ///     The baton.
 234   Baton *GetBaton();
 235
 236   /// Fetch  a const version of the baton from the callback.
 237   ///
 238   /// \return
 239   ///     The baton.
 240   const Baton *GetBaton() const;
 241
 242   // Condition
 243   /// Set the breakpoint option's condition.
 244   ///
 245   /// \param[in] condition
 246   ///    The condition expression to evaluate when the breakpoint is hit.
 247   void SetCondition(const char *condition);
 248
 249   /// Return a pointer to the text of the condition expression.
 250   ///
 251   /// \return
 252   ///    A pointer to the condition expression text, or nullptr if no
 253   //     condition has been set.
 254   const char *GetConditionText(size_t *hash = nullptr) const;
 255
 256   // Enabled/Ignore Count
 257
 258   /// Check the Enable/Disable state.
 259   /// \return
 260   ///     \b true if the breakpoint is enabled, \b false if disabled.
 261   bool IsEnabled() const { return m_enabled; }
 262
 263   /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
 264   void SetEnabled(bool enabled) {
 265     m_enabled = enabled;
 266     m_set_flags.Set(eEnabled);
 267   }
 268
 269   /// Check the auto-continue state.
 270   /// \return
 271   ///     \b true if the breakpoint is set to auto-continue, \b false otherwise.
 272   bool IsAutoContinue() const { return m_auto_continue; }
 273
 274   /// Set the auto-continue state.
 275   void SetAutoContinue(bool auto_continue) {
 276     m_auto_continue = auto_continue;
 277     m_set_flags.Set(eAutoContinue);
 278   }
 279
 280   /// Check the One-shot state.
 281   /// \return
 282   ///     \b true if the breakpoint is one-shot, \b false otherwise.
 283   bool IsOneShot() const { return m_one_shot; }
 284
 285   /// If \a enable is \b true, enable the breakpoint, if \b false disable it.
 286   void SetOneShot(bool one_shot) {
 287     m_one_shot = one_shot;
 288     m_set_flags.Set(eOneShot);
 289   }
 290
 291   /// Set the breakpoint to ignore the next \a count breakpoint hits.
 292   /// \param[in] count
 293   ///    The number of breakpoint hits to ignore.
 294
 295   void SetIgnoreCount(uint32_t n) {
 296     m_ignore_count = n;
 297     m_set_flags.Set(eIgnoreCount);
 298   }
 299
 300   /// Return the current Ignore Count.
 301   /// \return
 302   ///     The number of breakpoint hits to be ignored.
 303   uint32_t GetIgnoreCount() const { return m_ignore_count; }
 304
 305   /// Return the current thread spec for this option. This will return nullptr
 306   /// if the no thread specifications have been set for this Option yet.
 307   /// \return
 308   ///     The thread specification pointer for this option, or nullptr if none
 309   ///     has
 310   ///     been set yet.
 311   const ThreadSpec *GetThreadSpecNoCreate() const;
 312
 313   /// Returns a pointer to the ThreadSpec for this option, creating it. if it
 314   /// hasn't been created already.   This API is used for setting the
 315   /// ThreadSpec items for this option.
 316   ThreadSpec *GetThreadSpec();
 317
 318   void SetThreadID(lldb::tid_t thread_id);
 319
 320   void GetDescription(Stream *s, lldb::DescriptionLevel level) const;
 321
 322   /// Returns true if the breakpoint option has a callback set.
 323   bool HasCallback() const;
 324
 325   /// This is the default empty callback.
 326   static bool NullCallback(void *baton, StoppointCallbackContext *context,
 327                            lldb::user_id_t break_id,
 328                            lldb::user_id_t break_loc_id);
 329
 330   /// Set a callback based on BreakpointOptions::CommandData. \param[in]
 331   /// cmd_data
 332   ///     A UP holding the new'ed CommandData object.
 333   ///     The breakpoint will take ownership of pointer held by this object.
 334   void SetCommandDataCallback(std::unique_ptr<CommandData> &cmd_data);
 335
 336   void Clear();
 337
 338   bool AnySet() const {
 339     return m_set_flags.AnySet(eAllOptions);
 340   }
 341
 342 protected:
 343   // Classes that inherit from BreakpointOptions can see and modify these
 344   bool IsOptionSet(OptionKind kind)
 345   {
 346     return m_set_flags.Test(kind);
 347   }
 348
 349   enum class OptionNames {
 350     ConditionText = 0,
 351     IgnoreCount,
 352     EnabledState,
 353     OneShotState,
 354     AutoContinue,
 355     LastOptionName
 356   };
 357   static const char *g_option_names[(size_t)OptionNames::LastOptionName];
 358
 359   static const char *GetKey(OptionNames enum_value) {
 360     return g_option_names[(size_t)enum_value];
 361   }
 362
 363   static bool BreakpointOptionsCallbackFunction(
 364       void *baton, StoppointCallbackContext *context, lldb::user_id_t break_id,
 365       lldb::user_id_t break_loc_id);
 366
 367   void SetThreadSpec(std::unique_ptr<ThreadSpec> &thread_spec_up);
 368
 369 private:
 370   // For BreakpointOptions only
 371   BreakpointHitCallback m_callback;  // This is the callback function pointer
 372   lldb::BatonSP m_callback_baton_sp; // This is the client data for the callback
 373   bool m_baton_is_command_baton;
 374   bool m_callback_is_synchronous;
 375   bool m_enabled;
 376   bool m_one_shot;
 377   uint32_t m_ignore_count; // Number of times to ignore this breakpoint
 378   std::unique_ptr<ThreadSpec>
 379       m_thread_spec_up;         // Thread for which this breakpoint will take
 380   std::string m_condition_text; // The condition to test.
 381   size_t m_condition_text_hash; // Its hash, so that locations know when the
 382                                 // condition is updated.
 383   bool m_auto_continue;         // If set, auto-continue from breakpoint.
 384   Flags m_set_flags;            // Which options are set at this level.  Drawn
 385                                 // from BreakpointOptions::SetOptionsFlags.
 386 };
 387
 388 } // namespace lldb_private
 389
 390 #endif // liblldb_BreakpointOptions_h_