lldb/Breakpoint/BreakpointResolver.h

0001 //===-- BreakpointResolver.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_BREAKPOINT_BREAKPOINTRESOLVER_H
0010 #define LLDB_BREAKPOINT_BREAKPOINTRESOLVER_H
0011
0012 #include "lldb/Breakpoint/Breakpoint.h"
0013 #include "lldb/Core/Address.h"
0014 #include "lldb/Core/SearchFilter.h"
0015 #include "lldb/Utility/ConstString.h"
0016 #include "lldb/Utility/FileSpec.h"
0017 #include "lldb/Utility/RegularExpression.h"
0018 #include "lldb/lldb-private.h"
0019 #include <optional>
0020
0021 namespace lldb_private {
0022
0023 /// \class BreakpointResolver BreakpointResolver.h
0024 /// "lldb/Breakpoint/BreakpointResolver.h" This class works with SearchFilter
0025 /// to resolve logical breakpoints to their of concrete breakpoint locations.
0026
0027 /// General Outline:
0028 /// The BreakpointResolver is a Searcher.  In that protocol, the SearchFilter
0029 /// asks the question "At what depth of the symbol context descent do you want
0030 /// your callback to get called?" of the filter.  The resolver answers this
0031 /// question (in the GetDepth method) and provides the resolution callback.
0032 /// Each Breakpoint has a BreakpointResolver, and it calls either
0033 /// ResolveBreakpoint or ResolveBreakpointInModules to tell it to look for new
0034 /// breakpoint locations.
0035
0036 class BreakpointResolver : public Searcher {
0037   friend class Breakpoint;
0038
0039 public:
0040   /// The breakpoint resolver need to have a breakpoint for "ResolveBreakpoint
0041   /// to make sense.  It can be constructed without a breakpoint, but you have
0042   /// to call SetBreakpoint before ResolveBreakpoint.
0043   ///
0044   /// \param[in] bkpt
0045   ///   The breakpoint that owns this resolver.
0046   /// \param[in] resolverType
0047   ///   The concrete breakpoint resolver type for this breakpoint.
0048   BreakpointResolver(const lldb::BreakpointSP &bkpt,
0049                      unsigned char resolverType,
0050                      lldb::addr_t offset = 0);
0051
0052   /// The Destructor is virtual, all significant breakpoint resolvers derive
0053   /// from this class.
0054   ~BreakpointResolver() override;
0055
0056   /// This sets the breakpoint for this resolver.
0057   ///
0058   /// \param[in] bkpt
0059   ///   The breakpoint that owns this resolver.
0060   void SetBreakpoint(const lldb::BreakpointSP &bkpt);
0061
0062   /// This gets the breakpoint for this resolver.
0063   lldb::BreakpointSP GetBreakpoint() const {
0064     auto breakpoint_sp = m_breakpoint.expired() ? lldb::BreakpointSP() :
0065                                                   m_breakpoint.lock();
0066     assert(breakpoint_sp);
0067     return breakpoint_sp;
0068   }
0069
0070   /// This updates the offset for this breakpoint.  All the locations
0071   /// currently set for this breakpoint will have their offset adjusted when
0072   /// this is called.
0073   ///
0074   /// \param[in] offset
0075   ///   The offset to add to all locations.
0076   void SetOffset(lldb::addr_t offset);
0077
0078   lldb::addr_t GetOffset() const { return m_offset; }
0079
0080   /// In response to this method the resolver scans all the modules in the
0081   /// breakpoint's target, and adds any new locations it finds.
0082   ///
0083   /// \param[in] filter
0084   ///   The filter that will manage the search for this resolver.
0085   virtual void ResolveBreakpoint(SearchFilter &filter);
0086
0087   /// In response to this method the resolver scans the modules in the module
0088   /// list \a modules, and adds any new locations it finds.
0089   ///
0090   /// \param[in] filter
0091   ///   The filter that will manage the search for this resolver.
0092   virtual void ResolveBreakpointInModules(SearchFilter &filter,
0093                                           ModuleList &modules);
0094
0095   /// Prints a canonical description for the breakpoint to the stream \a s.
0096   ///
0097   /// \param[in] s
0098   ///   Stream to which the output is copied.
0099   void GetDescription(Stream *s) override = 0;
0100
0101   /// Standard "Dump" method.  At present it does nothing.
0102   virtual void Dump(Stream *s) const = 0;
0103
0104   /// This section handles serializing and deserializing from StructuredData
0105   /// objects.
0106
0107   static lldb::BreakpointResolverSP
0108   CreateFromStructuredData(const StructuredData::Dictionary &resolver_dict,
0109                            Status &error);
0110
0111   virtual StructuredData::ObjectSP SerializeToStructuredData() {
0112     return StructuredData::ObjectSP();
0113   }
0114
0115   static const char *GetSerializationKey() { return "BKPTResolver"; }
0116
0117   static const char *GetSerializationSubclassKey() { return "Type"; }
0118
0119   static const char *GetSerializationSubclassOptionsKey() { return "Options"; }
0120
0121   StructuredData::DictionarySP
0122   WrapOptionsDict(StructuredData::DictionarySP options_dict_sp);
0123
0124   /// An enumeration for keeping track of the concrete subclass that is
0125   /// actually instantiated. Values of this enumeration are kept in the
0126   /// BreakpointResolver's SubclassID field. They are used for concrete type
0127   /// identification.
0128   enum ResolverTy {
0129     FileLineResolver = 0, // This is an instance of BreakpointResolverFileLine
0130     AddressResolver,      // This is an instance of BreakpointResolverAddress
0131     NameResolver,         // This is an instance of BreakpointResolverName
0132     FileRegexResolver,
0133     PythonResolver,
0134     ExceptionResolver,
0135     LastKnownResolverType = ExceptionResolver,
0136     UnknownResolver
0137   };
0138
0139   // Translate the Ty to name for serialization, the "+2" is one for size vrs.
0140   // index, and one for UnknownResolver.
0141   static const char *g_ty_to_name[LastKnownResolverType + 2];
0142
0143   /// getResolverID - Return an ID for the concrete type of this object.  This
0144   /// is used to implement the LLVM classof checks.  This should not be used
0145   /// for any other purpose, as the values may change as LLDB evolves.
0146   unsigned getResolverID() const { return SubclassID; }
0147
0148   enum ResolverTy GetResolverTy() {
0149     if (SubclassID > ResolverTy::LastKnownResolverType)
0150       return ResolverTy::UnknownResolver;
0151     else
0152       return (enum ResolverTy)SubclassID;
0153   }
0154
0155   const char *GetResolverName() { return ResolverTyToName(GetResolverTy()); }
0156
0157   static const char *ResolverTyToName(enum ResolverTy);
0158
0159   static ResolverTy NameToResolverTy(llvm::StringRef name);
0160
0161   virtual lldb::BreakpointResolverSP
0162   CopyForBreakpoint(lldb::BreakpointSP &breakpoint) = 0;
0163
0164 protected:
0165   // Used for serializing resolver options:
0166   // The options in this enum and the strings in the g_option_names must be
0167   // kept in sync.
0168   enum class OptionNames : uint32_t {
0169     AddressOffset = 0,
0170     ExactMatch,
0171     FileName,
0172     Inlines,
0173     LanguageName,
0174     LineNumber,
0175     Column,
0176     ModuleName,
0177     NameMaskArray,
0178     Offset,
0179     PythonClassName,
0180     RegexString,
0181     ScriptArgs,
0182     SectionName,
0183     SearchDepth,
0184     SkipPrologue,
0185     SymbolNameArray,
0186     LastOptionName
0187   };
0188   static const char
0189       *g_option_names[static_cast<uint32_t>(OptionNames::LastOptionName)];
0190
0191   virtual void NotifyBreakpointSet() {};
0192
0193 public:
0194   static const char *GetKey(OptionNames enum_value) {
0195     return g_option_names[static_cast<uint32_t>(enum_value)];
0196   }
0197
0198 protected:
0199   /// Takes a symbol context list of matches which supposedly represent the
0200   /// same file and line number in a CU, and find the nearest actual line
0201   /// number that matches, and then filter down the matching addresses to
0202   /// unique entries, and skip the prologue if asked to do so, and then set
0203   /// breakpoint locations in this breakpoint for all the resultant addresses.
0204   /// When \p column is nonzero the \p line and \p column args are used to
0205   /// filter the results to find the first breakpoint >= (line, column).
0206   void SetSCMatchesByLine(SearchFilter &filter, SymbolContextList &sc_list,
0207                           bool skip_prologue, llvm::StringRef log_ident,
0208                           uint32_t line = 0,
0209                           std::optional<uint16_t> column = std::nullopt);
0210   void SetSCMatchesByLine(SearchFilter &, SymbolContextList &, bool,
0211                           const char *) = delete;
0212
0213   lldb::BreakpointLocationSP AddLocation(Address loc_addr,
0214                                          bool *new_location = nullptr);
0215
0216 private:
0217   /// Helper for \p SetSCMatchesByLine.
0218   void AddLocation(SearchFilter &filter, const SymbolContext &sc,
0219                    bool skip_prologue, llvm::StringRef log_ident);
0220
0221   lldb::BreakpointWP m_breakpoint; // This is the breakpoint we add locations to.
0222   lldb::addr_t m_offset;    // A random offset the user asked us to add to any
0223                             // breakpoints we set.
0224
0225   // Subclass identifier (for llvm isa/dyn_cast)
0226   const unsigned char SubclassID;
0227   BreakpointResolver(const BreakpointResolver &) = delete;
0228   const BreakpointResolver &operator=(const BreakpointResolver &) = delete;
0229 };
0230
0231 } // namespace lldb_private
0232
0233 #endif // LLDB_BREAKPOINT_BREAKPOINTRESOLVER_H