1 //===-- SBProcess.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_SBProcess_h_ 10 #define LLDB_SBProcess_h_ 11 12 #include "lldb/API/SBDefines.h" 13 #include "lldb/API/SBError.h" 14 #include "lldb/API/SBProcessInfo.h" 15 #include "lldb/API/SBQueue.h" 16 #include "lldb/API/SBTarget.h" 17 #include <stdio.h> 18 19 namespace lldb { 20 21 class SBEvent; 22 23 class LLDB_API SBProcess { 24 public: 25 /// Broadcaster event bits definitions. 26 FLAGS_ANONYMOUS_ENUM(){eBroadcastBitStateChanged = (1 << 0), 27 eBroadcastBitInterrupt = (1 << 1), 28 eBroadcastBitSTDOUT = (1 << 2), 29 eBroadcastBitSTDERR = (1 << 3), 30 eBroadcastBitProfileData = (1 << 4), 31 eBroadcastBitStructuredData = (1 << 5)}; 32 33 SBProcess(); 34 35 SBProcess(const lldb::SBProcess &rhs); 36 37 const lldb::SBProcess &operator=(const lldb::SBProcess &rhs); 38 39 SBProcess(const lldb::ProcessSP &process_sp); 40 41 ~SBProcess(); 42 43 static const char *GetBroadcasterClassName(); 44 45 const char *GetPluginName(); 46 47 // DEPRECATED: use GetPluginName() 48 const char *GetShortPluginName(); 49 50 void Clear(); 51 52 explicit operator bool() const; 53 54 bool IsValid() const; 55 56 lldb::SBTarget GetTarget() const; 57 58 lldb::ByteOrder GetByteOrder() const; 59 60 size_t PutSTDIN(const char *src, size_t src_len); 61 62 size_t GetSTDOUT(char *dst, size_t dst_len) const; 63 64 size_t GetSTDERR(char *dst, size_t dst_len) const; 65 66 size_t GetAsyncProfileData(char *dst, size_t dst_len) const; 67 68 void ReportEventState(const lldb::SBEvent &event, FILE *out) const; 69 70 void ReportEventState(const lldb::SBEvent &event, SBFile file) const; 71 72 void ReportEventState(const lldb::SBEvent &event, FileSP file) const; 73 74 void AppendEventStateReport(const lldb::SBEvent &event, 75 lldb::SBCommandReturnObject &result); 76 77 /// Remote connection related functions. These will fail if the 78 /// process is not in eStateConnected. They are intended for use 79 /// when connecting to an externally managed debugserver instance. 80 bool RemoteAttachToProcessWithID(lldb::pid_t pid, lldb::SBError &error); 81 82 bool RemoteLaunch(char const **argv, char const **envp, 83 const char *stdin_path, const char *stdout_path, 84 const char *stderr_path, const char *working_directory, 85 uint32_t launch_flags, bool stop_at_entry, 86 lldb::SBError &error); 87 88 // Thread related functions 89 uint32_t GetNumThreads(); 90 91 lldb::SBThread GetThreadAtIndex(size_t index); 92 93 lldb::SBThread GetThreadByID(lldb::tid_t sb_thread_id); 94 95 lldb::SBThread GetThreadByIndexID(uint32_t index_id); 96 97 lldb::SBThread GetSelectedThread() const; 98 99 // Function for lazily creating a thread using the current OS plug-in. This 100 // function will be removed in the future when there are APIs to create 101 // SBThread objects through the interface and add them to the process through 102 // the SBProcess API. 103 lldb::SBThread CreateOSPluginThread(lldb::tid_t tid, lldb::addr_t context); 104 105 bool SetSelectedThread(const lldb::SBThread &thread); 106 107 bool SetSelectedThreadByID(lldb::tid_t tid); 108 109 bool SetSelectedThreadByIndexID(uint32_t index_id); 110 111 // Queue related functions 112 uint32_t GetNumQueues(); 113 114 lldb::SBQueue GetQueueAtIndex(size_t index); 115 116 // Stepping related functions 117 118 lldb::StateType GetState(); 119 120 int GetExitStatus(); 121 122 const char *GetExitDescription(); 123 124 /// Gets the process ID 125 /// 126 /// Returns the process identifier for the process as it is known 127 /// on the system on which the process is running. For unix systems 128 /// this is typically the same as if you called "getpid()" in the 129 /// process. 130 /// 131 /// \return 132 /// Returns LLDB_INVALID_PROCESS_ID if this object does not 133 /// contain a valid process object, or if the process has not 134 /// been launched. Returns a valid process ID if the process is 135 /// valid. 136 lldb::pid_t GetProcessID(); 137 138 /// Gets the unique ID associated with this process object 139 /// 140 /// Unique IDs start at 1 and increment up with each new process 141 /// instance. Since starting a process on a system might always 142 /// create a process with the same process ID, there needs to be a 143 /// way to tell two process instances apart. 144 /// 145 /// \return 146 /// Returns a non-zero integer ID if this object contains a 147 /// valid process object, zero if this object does not contain 148 /// a valid process object. 149 uint32_t GetUniqueID(); 150 151 uint32_t GetAddressByteSize() const; 152 153 lldb::SBError Destroy(); 154 155 lldb::SBError Continue(); 156 157 lldb::SBError Stop(); 158 159 lldb::SBError Kill(); 160 161 lldb::SBError Detach(); 162 163 lldb::SBError Detach(bool keep_stopped); 164 165 lldb::SBError Signal(int signal); 166 167 lldb::SBUnixSignals GetUnixSignals(); 168 169 void SendAsyncInterrupt(); 170 171 uint32_t GetStopID(bool include_expression_stops = false); 172 173 /// Gets the stop event corresponding to stop ID. 174 // 175 /// Note that it wasn't fully implemented and tracks only the stop 176 /// event for the last natural stop ID. 177 /// 178 /// \param [in] stop_id 179 /// The ID of the stop event to return. 180 /// 181 /// \return 182 /// The stop event corresponding to stop ID. 183 lldb::SBEvent GetStopEventForStopID(uint32_t stop_id); 184 185 size_t ReadMemory(addr_t addr, void *buf, size_t size, lldb::SBError &error); 186 187 size_t WriteMemory(addr_t addr, const void *buf, size_t size, 188 lldb::SBError &error); 189 190 size_t ReadCStringFromMemory(addr_t addr, void *buf, size_t size, 191 lldb::SBError &error); 192 193 uint64_t ReadUnsignedFromMemory(addr_t addr, uint32_t byte_size, 194 lldb::SBError &error); 195 196 lldb::addr_t ReadPointerFromMemory(addr_t addr, lldb::SBError &error); 197 198 // Events 199 static lldb::StateType GetStateFromEvent(const lldb::SBEvent &event); 200 201 static bool GetRestartedFromEvent(const lldb::SBEvent &event); 202 203 static size_t GetNumRestartedReasonsFromEvent(const lldb::SBEvent &event); 204 205 static const char * 206 GetRestartedReasonAtIndexFromEvent(const lldb::SBEvent &event, size_t idx); 207 208 static lldb::SBProcess GetProcessFromEvent(const lldb::SBEvent &event); 209 210 static bool GetInterruptedFromEvent(const lldb::SBEvent &event); 211 212 static lldb::SBStructuredData 213 GetStructuredDataFromEvent(const lldb::SBEvent &event); 214 215 static bool EventIsProcessEvent(const lldb::SBEvent &event); 216 217 static bool EventIsStructuredDataEvent(const lldb::SBEvent &event); 218 219 lldb::SBBroadcaster GetBroadcaster() const; 220 221 static const char *GetBroadcasterClass(); 222 223 bool GetDescription(lldb::SBStream &description); 224 225 /// Start Tracing with the given SBTraceOptions. 226 /// 227 /// \param[in] options 228 /// Class containing trace options like trace buffer size, meta 229 /// data buffer size, TraceType and any custom parameters 230 /// {formatted as a JSON Dictionary}. In case of errors in 231 /// formatting, an error would be reported. 232 /// It must be noted that tracing options such as buffer sizes 233 /// or other custom parameters passed maybe invalid for some 234 /// trace technologies. In such cases the trace implementations 235 /// could choose to either throw an error or could round off to 236 /// the nearest valid options to start tracing if the passed 237 /// value is not supported. To obtain the actual used trace 238 /// options please use the GetTraceConfig API. For the custom 239 /// parameters, only the parameters recognized by the target 240 /// would be used and others would be ignored. 241 /// 242 /// \param[out] error 243 /// An error explaining what went wrong. 244 /// 245 /// \return 246 /// A SBTrace instance, which should be used 247 /// to get the trace data or other trace related operations. 248 lldb::SBTrace StartTrace(SBTraceOptions &options, lldb::SBError &error); 249 250 uint32_t GetNumSupportedHardwareWatchpoints(lldb::SBError &error) const; 251 252 /// Load a shared library into this process. 253 /// 254 /// \param[in] remote_image_spec 255 /// The path for the shared library on the target what you want 256 /// to load. 257 /// 258 /// \param[out] error 259 /// An error object that gets filled in with any errors that 260 /// might occur when trying to load the shared library. 261 /// 262 /// \return 263 /// A token that represents the shared library that can be 264 /// later used to unload the shared library. A value of 265 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared 266 /// library can't be opened. 267 uint32_t LoadImage(lldb::SBFileSpec &remote_image_spec, lldb::SBError &error); 268 269 /// Load a shared library into this process. 270 /// 271 /// \param[in] local_image_spec 272 /// The file spec that points to the shared library that you 273 /// want to load if the library is located on the host. The 274 /// library will be copied over to the location specified by 275 /// remote_image_spec or into the current working directory with 276 /// the same filename if the remote_image_spec isn't specified. 277 /// 278 /// \param[in] remote_image_spec 279 /// If local_image_spec is specified then the location where the 280 /// library should be copied over from the host. If 281 /// local_image_spec isn't specified, then the path for the 282 /// shared library on the target what you want to load. 283 /// 284 /// \param[out] error 285 /// An error object that gets filled in with any errors that 286 /// might occur when trying to load the shared library. 287 /// 288 /// \return 289 /// A token that represents the shared library that can be 290 /// later used to unload the shared library. A value of 291 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared 292 /// library can't be opened. 293 uint32_t LoadImage(const lldb::SBFileSpec &local_image_spec, 294 const lldb::SBFileSpec &remote_image_spec, 295 lldb::SBError &error); 296 297 /// Load a shared library into this process, starting with a 298 /// library name and a list of paths, searching along the list of 299 /// paths till you find a matching library. 300 /// 301 /// \param[in] image_spec 302 /// The name of the shared library that you want to load. 303 /// If image_spec is a relative path, the relative path will be 304 /// appended to the search paths. 305 /// If the image_spec is an absolute path, just the basename is used. 306 /// 307 /// \param[in] paths 308 /// A list of paths to search for the library whose basename is 309 /// local_spec. 310 /// 311 /// \param[out] loaded_path 312 /// If the library was found along the paths, this will store the 313 /// full path to the found library. 314 /// 315 /// \param[out] error 316 /// An error object that gets filled in with any errors that 317 /// might occur when trying to search for the shared library. 318 /// 319 /// \return 320 /// A token that represents the shared library that can be 321 /// later passed to UnloadImage. A value of 322 /// LLDB_INVALID_IMAGE_TOKEN will be returned if the shared 323 /// library can't be opened. 324 uint32_t LoadImageUsingPaths(const lldb::SBFileSpec &image_spec, 325 SBStringList &paths, 326 lldb::SBFileSpec &loaded_path, 327 lldb::SBError &error); 328 329 lldb::SBError UnloadImage(uint32_t image_token); 330 331 lldb::SBError SendEventData(const char *data); 332 333 /// Return the number of different thread-origin extended backtraces 334 /// this process can support. 335 /// 336 /// When the process is stopped and you have an SBThread, lldb may be 337 /// able to show a backtrace of when that thread was originally created, 338 /// or the work item was enqueued to it (in the case of a libdispatch 339 /// queue). 340 /// 341 /// \return 342 /// The number of thread-origin extended backtrace types that may be 343 /// available. 344 uint32_t GetNumExtendedBacktraceTypes(); 345 346 /// Return the name of one of the thread-origin extended backtrace 347 /// methods. 348 /// 349 /// \param [in] idx 350 /// The index of the name to return. They will be returned in 351 /// the order that the user will most likely want to see them. 352 /// e.g. if the type at index 0 is not available for a thread, 353 /// see if the type at index 1 provides an extended backtrace. 354 /// 355 /// \return 356 /// The name at that index. 357 const char *GetExtendedBacktraceTypeAtIndex(uint32_t idx); 358 359 lldb::SBThreadCollection GetHistoryThreads(addr_t addr); 360 361 bool IsInstrumentationRuntimePresent(InstrumentationRuntimeType type); 362 363 /// Save the state of the process in a core file (or mini dump on Windows). 364 lldb::SBError SaveCore(const char *file_name); 365 366 /// Query the address load_addr and store the details of the memory 367 /// region that contains it in the supplied SBMemoryRegionInfo object. 368 /// To iterate over all memory regions use GetMemoryRegionList. 369 /// 370 /// \param[in] load_addr 371 /// The address to be queried. 372 /// 373 /// \param[out] region_info 374 /// A reference to an SBMemoryRegionInfo object that will contain 375 /// the details of the memory region containing load_addr. 376 /// 377 /// \return 378 /// An error object describes any errors that occurred while 379 /// querying load_addr. 380 lldb::SBError GetMemoryRegionInfo(lldb::addr_t load_addr, 381 lldb::SBMemoryRegionInfo ®ion_info); 382 383 /// Return the list of memory regions within the process. 384 /// 385 /// \return 386 /// A list of all witin the process memory regions. 387 lldb::SBMemoryRegionInfoList GetMemoryRegions(); 388 389 /// Return information about the process. 390 /// 391 /// Valid process info will only be returned when the process is 392 /// alive, use SBProcessInfo::IsValid() to check returned info is 393 /// valid. 394 lldb::SBProcessInfo GetProcessInfo(); 395 396 protected: 397 friend class SBAddress; 398 friend class SBBreakpoint; 399 friend class SBBreakpointLocation; 400 friend class SBCommandInterpreter; 401 friend class SBDebugger; 402 friend class SBExecutionContext; 403 friend class SBFunction; 404 friend class SBModule; 405 friend class SBTarget; 406 friend class SBThread; 407 friend class SBValue; 408 friend class lldb_private::QueueImpl; 409 410 lldb::ProcessSP GetSP() const; 411 412 void SetSP(const lldb::ProcessSP &process_sp); 413 414 lldb::ProcessWP m_opaque_wp; 415 }; 416 417 } // namespace lldb 418 419 #endif // LLDB_SBProcess_h_ 420