contrib/llvm/tools/lldb/include/lldb/Breakpoint/BreakpointOptions.h

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