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