lldb/Target/UnixSignals.h

0001 //===-- UnixSignals.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_UNIXSIGNALS_H
0010 #define LLDB_TARGET_UNIXSIGNALS_H
0011
0012 #include <map>
0013 #include <optional>
0014 #include <string>
0015 #include <vector>
0016
0017 #include "lldb/lldb-private.h"
0018 #include "llvm/Support/JSON.h"
0019
0020 namespace lldb_private {
0021
0022 class UnixSignals {
0023 public:
0024   static lldb::UnixSignalsSP Create(const ArchSpec &arch);
0025   static lldb::UnixSignalsSP CreateForHost();
0026
0027   // Constructors and Destructors
0028   UnixSignals();
0029
0030   virtual ~UnixSignals();
0031
0032   llvm::StringRef GetSignalAsStringRef(int32_t signo) const;
0033
0034   std::string
0035   GetSignalDescription(int32_t signo,
0036                        std::optional<int32_t> code = std::nullopt,
0037                        std::optional<lldb::addr_t> addr = std::nullopt,
0038                        std::optional<lldb::addr_t> lower = std::nullopt,
0039                        std::optional<lldb::addr_t> upper = std::nullopt) const;
0040
0041   bool SignalIsValid(int32_t signo) const;
0042
0043   int32_t GetSignalNumberFromName(const char *name) const;
0044
0045   /// Gets the information for a particular signal
0046   ///
0047   /// GetSignalInfo takes a signal number and populates 3 out parameters
0048   /// describing how lldb should react when a particular signal is received in
0049   /// the inferior.
0050   ///
0051   /// \param[in] signo
0052   ///   The signal number to get information about.
0053   /// \param[out] should_suppress
0054   ///   Should we suppress this signal?
0055   /// \param[out] should_stop
0056   ///   Should we stop if this signal is received?
0057   /// \param[out] should_notify
0058   ///   Should we notify the user if this signal is received?
0059   ///
0060   /// \return
0061   ///   Returns a boolean value. Returns true if the out parameters were
0062   ///   successfully populated, false otherwise.
0063   bool GetSignalInfo(int32_t signo, bool &should_suppress, bool &should_stop,
0064                      bool &should_notify) const;
0065
0066   bool GetShouldSuppress(int32_t signo) const;
0067
0068   bool SetShouldSuppress(int32_t signo, bool value);
0069
0070   bool SetShouldSuppress(const char *signal_name, bool value);
0071
0072   bool GetShouldStop(int32_t signo) const;
0073
0074   bool SetShouldStop(int32_t signo, bool value);
0075   bool SetShouldStop(const char *signal_name, bool value);
0076
0077   bool GetShouldNotify(int32_t signo) const;
0078
0079   bool SetShouldNotify(int32_t signo, bool value);
0080
0081   bool SetShouldNotify(const char *signal_name, bool value);
0082
0083   bool ResetSignal(int32_t signo, bool reset_stop = true,
0084                    bool reset_notify = true, bool reset_suppress = true);
0085
0086   // These provide an iterator through the signals available on this system.
0087   // Call GetFirstSignalNumber to get the first entry, then iterate on
0088   // GetNextSignalNumber till you get back LLDB_INVALID_SIGNAL_NUMBER.
0089   int32_t GetFirstSignalNumber() const;
0090
0091   int32_t GetNextSignalNumber(int32_t current_signal) const;
0092
0093   int32_t GetNumSignals() const;
0094
0095   int32_t GetSignalAtIndex(int32_t index) const;
0096
0097   // We assume that the elements of this object are constant once it is
0098   // constructed, since a process should never need to add or remove symbols as
0099   // it runs.  So don't call these functions anywhere but the constructor of
0100   // your subclass of UnixSignals or in your Process Plugin's GetUnixSignals
0101   // method before you return the UnixSignal object.
0102
0103   void AddSignal(int signo, llvm::StringRef name, bool default_suppress,
0104                  bool default_stop, bool default_notify,
0105                  llvm::StringRef description,
0106                  llvm::StringRef alias = llvm::StringRef());
0107
0108   enum SignalCodePrintOption { None, Address, Bounds };
0109
0110   // Instead of calling this directly, use a ADD_SIGCODE macro to get compile
0111   // time checks when on the native platform.
0112   void AddSignalCode(
0113       int signo, int code, const llvm::StringLiteral description,
0114       SignalCodePrintOption print_option = SignalCodePrintOption::None);
0115
0116   void RemoveSignal(int signo);
0117
0118   /// Track how many times signals are hit as stop reasons.
0119   void IncrementSignalHitCount(int signo);
0120
0121   /// Get the hit count statistics for signals.
0122   ///
0123   /// Gettings statistics on the hit counts of signals can help explain why some
0124   /// debug sessions are slow since each stop takes a few hundred ms and some
0125   /// software use signals a lot and can cause slow debugging performance if
0126   /// they are used too often. Even if a signal is not stopped at, it will auto
0127   /// continue the process and a delay will happen.
0128   llvm::json::Value GetHitCountStatistics() const;
0129
0130   // Returns a current version of the data stored in this class. Version gets
0131   // incremented each time Set... method is called.
0132   uint64_t GetVersion() const;
0133
0134   // Returns a vector of signals that meet criteria provided in arguments. Each
0135   // should_[suppress|stop|notify] flag can be std::nullopt - no filtering by
0136   // this flag true - only signals that have it set to true are returned false -
0137   // only signals that have it set to true are returned
0138   std::vector<int32_t> GetFilteredSignals(std::optional<bool> should_suppress,
0139                                           std::optional<bool> should_stop,
0140                                           std::optional<bool> should_notify);
0141
0142 protected:
0143   // Classes that inherit from UnixSignals can see and modify these
0144
0145   struct SignalCode {
0146     const llvm::StringLiteral m_description;
0147     const SignalCodePrintOption m_print_option;
0148   };
0149
0150   // The StringRefs in Signal are either backed by string literals or reside in
0151   // persistent storage (e.g. a StringSet).
0152   struct Signal {
0153     llvm::StringRef m_name;
0154     llvm::StringRef m_alias;
0155     llvm::StringRef m_description;
0156     std::map<int32_t, SignalCode> m_codes;
0157     uint32_t m_hit_count = 0;
0158     bool m_suppress : 1, m_stop : 1, m_notify : 1;
0159     bool m_default_suppress : 1, m_default_stop : 1, m_default_notify : 1;
0160
0161     Signal(llvm::StringRef name, bool default_suppress, bool default_stop,
0162            bool default_notify, llvm::StringRef description,
0163            llvm::StringRef alias);
0164
0165     ~Signal() = default;
0166     void Reset(bool reset_stop, bool reset_notify, bool reset_suppress);
0167   };
0168
0169   llvm::StringRef GetShortName(llvm::StringRef name) const;
0170
0171   virtual void Reset();
0172
0173   typedef std::map<int32_t, Signal> collection;
0174
0175   collection m_signals;
0176
0177   // This version gets incremented every time something is changing in this
0178   // class, including when we call AddSignal from the constructor. So after the
0179   // object is constructed m_version is going to be > 0 if it has at least one
0180   // signal registered in it.
0181   uint64_t m_version = 0;
0182
0183   // GDBRemote signals need to be copyable.
0184   UnixSignals(const UnixSignals &rhs);
0185
0186   const UnixSignals &operator=(const UnixSignals &rhs) = delete;
0187 };
0188
0189 } // Namespace lldb
0190 #endif // LLDB_TARGET_UNIXSIGNALS_H