1 //===-- TargetList.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 LLDB_TARGET_TARGETLIST_H 10 #define LLDB_TARGET_TARGETLIST_H 11 12 #include <mutex> 13 #include <vector> 14 15 #include "lldb/Target/Target.h" 16 #include "lldb/Utility/Broadcaster.h" 17 18 namespace lldb_private { 19 20 class TargetList : public Broadcaster { 21 private: 22 friend class Debugger; 23 24 /// Constructor 25 /// 26 /// The constructor for the target list is private. Clients can 27 /// get ahold of of the one and only target list through the 28 /// lldb_private::Debugger::GetSharedInstance().GetTargetList(). 29 /// 30 /// \see static TargetList& lldb_private::Debugger::GetTargetList(). 31 TargetList(Debugger &debugger); 32 33 public: 34 /// Broadcaster event bits definitions. 35 enum { eBroadcastBitInterrupt = (1 << 0) }; 36 37 // These two functions fill out the Broadcaster interface: 38 39 static ConstString &GetStaticBroadcasterClass(); 40 GetBroadcasterClass()41 ConstString &GetBroadcasterClass() const override { 42 return GetStaticBroadcasterClass(); 43 } 44 45 /// Create a new Target. 46 /// 47 /// Clients must use this function to create a Target. This allows 48 /// a global list of targets to be maintained in a central location 49 /// so signal handlers and other global functions can use it to 50 /// locate an appropriate target to deliver asynchronous information 51 /// to. 52 /// 53 /// \param[in] debugger 54 /// The debugger to associate this target with 55 /// 56 /// \param[in] user_exe_path 57 /// The main executable file for a debug target. This value 58 /// can be empty and the file can be set later using: 59 /// Target::SetExecutableModule (ModuleSP&) 60 /// 61 /// \param[in] triple_str 62 /// A target triple string to be used for the target. This can 63 /// be nullptr if the triple is not known or when attaching to a 64 /// process. 65 /// 66 /// \param[in] get_dependent_modules 67 /// Track down the dependent modules for an executable and 68 /// load those into the module list. 69 /// 70 /// \param[in] platform_options 71 /// A pointer to the platform options to use when creating this 72 /// target. If this value is nullptr, then the currently selected 73 /// platform will be used. 74 /// 75 /// \param[out] target_sp 76 /// A shared pointer to a target that will be filled in if 77 /// this call is successful. 78 /// 79 /// \return 80 /// An error object that indicates success or failure 81 Status CreateTarget(Debugger &debugger, llvm::StringRef user_exe_path, 82 llvm::StringRef triple_str, 83 LoadDependentFiles get_dependent_modules, 84 const OptionGroupPlatform *platform_options, 85 lldb::TargetSP &target_sp); 86 87 /// Create a new Target. 88 /// 89 /// Same as the function above, but used when you already know the 90 /// platform you will be using 91 Status CreateTarget(Debugger &debugger, llvm::StringRef user_exe_path, 92 const ArchSpec &arch, 93 LoadDependentFiles get_dependent_modules, 94 lldb::PlatformSP &platform_sp, lldb::TargetSP &target_sp); 95 96 /// Delete a Target object from the list. 97 /// 98 /// When clients are done with the Target objects, this function 99 /// should be called to release the memory associated with a target 100 /// object. 101 /// 102 /// \param[in] target_sp 103 /// The shared pointer to a target. 104 /// 105 /// \return 106 /// Returns \b true if the target was successfully removed from 107 /// from this target list, \b false otherwise. The client will 108 /// be left with the last remaining shared pointer to the target 109 /// in \a target_sp which can then be properly released. 110 bool DeleteTarget(lldb::TargetSP &target_sp); 111 112 int GetNumTargets() const; 113 114 lldb::TargetSP GetTargetAtIndex(uint32_t index) const; 115 116 uint32_t GetIndexOfTarget(lldb::TargetSP target_sp) const; 117 118 /// Find the target that contains has an executable whose path 119 /// matches \a exe_file_spec, and whose architecture matches 120 /// \a arch_ptr if arch_ptr is not nullptr. 121 /// 122 /// \param[in] exe_file_spec 123 /// A file spec containing a basename, or a full path (directory 124 /// and basename). If \a exe_file_spec contains only a filename 125 /// (empty GetDirectory() value) then matching will be done 126 /// solely based on the filenames and directories won't be 127 /// compared. If \a exe_file_spec contains a filename and a 128 /// directory, then both must match. 129 /// 130 /// \param[in] exe_arch_ptr 131 /// If not nullptr then the architecture also needs to match, else 132 /// the architectures will be compared. 133 /// 134 /// \return 135 /// A shared pointer to a target object. The returned shared 136 /// pointer will contain nullptr if no target objects have a 137 /// executable whose full or partial path matches 138 /// with a matching process ID. 139 lldb::TargetSP FindTargetWithExecutableAndArchitecture( 140 const FileSpec &exe_file_spec, 141 const ArchSpec *exe_arch_ptr = nullptr) const; 142 143 /// Find the target that contains a process with process ID \a 144 /// pid. 145 /// 146 /// \param[in] pid 147 /// The process ID to search our target list for. 148 /// 149 /// \return 150 /// A shared pointer to a target object. The returned shared 151 /// pointer will contain nullptr if no target objects own a process 152 /// with a matching process ID. 153 lldb::TargetSP FindTargetWithProcessID(lldb::pid_t pid) const; 154 155 lldb::TargetSP FindTargetWithProcess(lldb_private::Process *process) const; 156 157 lldb::TargetSP GetTargetSP(Target *target) const; 158 159 /// Send an async interrupt to one or all processes. 160 /// 161 /// Find the target that contains the process with process ID \a 162 /// pid and send a LLDB_EVENT_ASYNC_INTERRUPT event to the process's 163 /// event queue. 164 /// 165 /// \param[in] pid 166 /// The process ID to search our target list for, if \a pid is 167 /// LLDB_INVALID_PROCESS_ID, then the interrupt will be sent to 168 /// all processes. 169 /// 170 /// \return 171 /// The number of async interrupts sent. 172 uint32_t SendAsyncInterrupt(lldb::pid_t pid = LLDB_INVALID_PROCESS_ID); 173 174 uint32_t SignalIfRunning(lldb::pid_t pid, int signo); 175 176 void SetSelectedTarget(uint32_t index); 177 178 void SetSelectedTarget(const lldb::TargetSP &target); 179 180 lldb::TargetSP GetSelectedTarget(); 181 182 protected: 183 typedef std::vector<lldb::TargetSP> collection; 184 // Member variables. 185 collection m_target_list; 186 mutable std::recursive_mutex m_target_list_mutex; 187 uint32_t m_selected_target_idx; 188 189 private: 190 static Status CreateTargetInternal( 191 Debugger &debugger, llvm::StringRef user_exe_path, 192 llvm::StringRef triple_str, LoadDependentFiles load_dependent_files, 193 const OptionGroupPlatform *platform_options, lldb::TargetSP &target_sp); 194 195 static Status CreateTargetInternal(Debugger &debugger, 196 llvm::StringRef user_exe_path, 197 const ArchSpec &arch, 198 LoadDependentFiles get_dependent_modules, 199 lldb::PlatformSP &platform_sp, 200 lldb::TargetSP &target_sp); 201 202 void AddTargetInternal(lldb::TargetSP target_sp, bool do_select); 203 204 void SetSelectedTargetInternal(uint32_t index); 205 206 TargetList(const TargetList &) = delete; 207 const TargetList &operator=(const TargetList &) = delete; 208 }; 209 210 } // namespace lldb_private 211 212 #endif // LLDB_TARGET_TARGETLIST_H 213