1 | //===-- Process.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_PROCESS_H |
10 | #define LLDB_TARGET_PROCESS_H |
11 | |
12 | #include "lldb/Host/Config.h" |
13 | |
14 | #include <climits> |
15 | |
16 | #include <chrono> |
17 | #include <list> |
18 | #include <memory> |
19 | #include <mutex> |
20 | #include <optional> |
21 | #include <string> |
22 | #include <unordered_set> |
23 | #include <vector> |
24 | |
25 | #include "lldb/Breakpoint/BreakpointSite.h" |
26 | #include "lldb/Breakpoint/StopPointSiteList.h" |
27 | #include "lldb/Breakpoint/WatchpointResource.h" |
28 | #include "lldb/Core/LoadedModuleInfoList.h" |
29 | #include "lldb/Core/PluginInterface.h" |
30 | #include "lldb/Core/SourceManager.h" |
31 | #include "lldb/Core/ThreadSafeValue.h" |
32 | #include "lldb/Core/ThreadedCommunication.h" |
33 | #include "lldb/Core/UserSettingsController.h" |
34 | #include "lldb/Host/HostThread.h" |
35 | #include "lldb/Host/ProcessLaunchInfo.h" |
36 | #include "lldb/Host/ProcessRunLock.h" |
37 | #include "lldb/Symbol/ObjectFile.h" |
38 | #include "lldb/Target/ExecutionContextScope.h" |
39 | #include "lldb/Target/InstrumentationRuntime.h" |
40 | #include "lldb/Target/Memory.h" |
41 | #include "lldb/Target/MemoryTagManager.h" |
42 | #include "lldb/Target/QueueList.h" |
43 | #include "lldb/Target/ThreadList.h" |
44 | #include "lldb/Target/ThreadPlanStack.h" |
45 | #include "lldb/Target/Trace.h" |
46 | #include "lldb/Utility/ArchSpec.h" |
47 | #include "lldb/Utility/Broadcaster.h" |
48 | #include "lldb/Utility/Event.h" |
49 | #include "lldb/Utility/Listener.h" |
50 | #include "lldb/Utility/NameMatches.h" |
51 | #include "lldb/Utility/ProcessInfo.h" |
52 | #include "lldb/Utility/Status.h" |
53 | #include "lldb/Utility/StructuredData.h" |
54 | #include "lldb/Utility/TraceGDBRemotePackets.h" |
55 | #include "lldb/Utility/UnimplementedError.h" |
56 | #include "lldb/Utility/UserIDResolver.h" |
57 | #include "lldb/lldb-private.h" |
58 | |
59 | #include "llvm/ADT/AddressRanges.h" |
60 | #include "llvm/ADT/ArrayRef.h" |
61 | #include "llvm/Support/Error.h" |
62 | #include "llvm/Support/Threading.h" |
63 | #include "llvm/Support/VersionTuple.h" |
64 | |
65 | namespace lldb_private { |
66 | |
67 | template <typename B, typename S> struct Range; |
68 | |
69 | class ProcessExperimentalProperties : public Properties { |
70 | public: |
71 | ProcessExperimentalProperties(); |
72 | }; |
73 | |
74 | class ProcessProperties : public Properties { |
75 | public: |
76 | // Pass nullptr for "process" if the ProcessProperties are to be the global |
77 | // copy |
78 | ProcessProperties(lldb_private::Process *process); |
79 | |
80 | ~ProcessProperties() override; |
81 | |
82 | bool GetDisableMemoryCache() const; |
83 | uint64_t GetMemoryCacheLineSize() const; |
84 | Args GetExtraStartupCommands() const; |
85 | void SetExtraStartupCommands(const Args &args); |
86 | FileSpec GetPythonOSPluginPath() const; |
87 | uint32_t GetVirtualAddressableBits() const; |
88 | void SetVirtualAddressableBits(uint32_t bits); |
89 | uint32_t GetHighmemVirtualAddressableBits() const; |
90 | void SetHighmemVirtualAddressableBits(uint32_t bits); |
91 | void SetPythonOSPluginPath(const FileSpec &file); |
92 | bool GetIgnoreBreakpointsInExpressions() const; |
93 | void SetIgnoreBreakpointsInExpressions(bool ignore); |
94 | bool GetUnwindOnErrorInExpressions() const; |
95 | void SetUnwindOnErrorInExpressions(bool ignore); |
96 | bool GetStopOnSharedLibraryEvents() const; |
97 | void SetStopOnSharedLibraryEvents(bool stop); |
98 | bool GetDisableLangRuntimeUnwindPlans() const; |
99 | void SetDisableLangRuntimeUnwindPlans(bool disable); |
100 | bool GetDetachKeepsStopped() const; |
101 | void SetDetachKeepsStopped(bool keep_stopped); |
102 | bool GetWarningsOptimization() const; |
103 | bool GetWarningsUnsupportedLanguage() const; |
104 | bool GetStopOnExec() const; |
105 | std::chrono::seconds GetUtilityExpressionTimeout() const; |
106 | std::chrono::seconds GetInterruptTimeout() const; |
107 | bool GetOSPluginReportsAllThreads() const; |
108 | void SetOSPluginReportsAllThreads(bool does_report); |
109 | bool GetSteppingRunsAllThreads() const; |
110 | FollowForkMode GetFollowForkMode() const; |
111 | |
112 | protected: |
113 | Process *m_process; // Can be nullptr for global ProcessProperties |
114 | std::unique_ptr<ProcessExperimentalProperties> m_experimental_properties_up; |
115 | }; |
116 | |
117 | // ProcessAttachInfo |
118 | // |
119 | // Describes any information that is required to attach to a process. |
120 | |
121 | class ProcessAttachInfo : public ProcessInstanceInfo { |
122 | public: |
123 | ProcessAttachInfo() = default; |
124 | |
125 | ProcessAttachInfo(const ProcessLaunchInfo &launch_info) |
126 | : m_resume_count(0), m_wait_for_launch(false), m_ignore_existing(true), |
127 | m_continue_once_attached(false), m_detach_on_error(true), |
128 | m_async(false) { |
129 | ProcessInfo::operator=(launch_info); |
130 | SetProcessPluginName(launch_info.GetProcessPluginName()); |
131 | SetResumeCount(launch_info.GetResumeCount()); |
132 | m_detach_on_error = launch_info.GetDetachOnError(); |
133 | } |
134 | |
135 | bool GetWaitForLaunch() const { return m_wait_for_launch; } |
136 | |
137 | void SetWaitForLaunch(bool b) { m_wait_for_launch = b; } |
138 | |
139 | bool GetAsync() const { return m_async; } |
140 | |
141 | void SetAsync(bool b) { m_async = b; } |
142 | |
143 | bool GetIgnoreExisting() const { return m_ignore_existing; } |
144 | |
145 | void SetIgnoreExisting(bool b) { m_ignore_existing = b; } |
146 | |
147 | bool GetContinueOnceAttached() const { return m_continue_once_attached; } |
148 | |
149 | void SetContinueOnceAttached(bool b) { m_continue_once_attached = b; } |
150 | |
151 | uint32_t GetResumeCount() const { return m_resume_count; } |
152 | |
153 | void SetResumeCount(uint32_t c) { m_resume_count = c; } |
154 | |
155 | llvm::StringRef GetProcessPluginName() const { |
156 | return llvm::StringRef(m_plugin_name); |
157 | } |
158 | |
159 | void SetProcessPluginName(llvm::StringRef plugin) { |
160 | m_plugin_name = std::string(plugin); |
161 | } |
162 | |
163 | void Clear() { |
164 | ProcessInstanceInfo::Clear(); |
165 | m_plugin_name.clear(); |
166 | m_resume_count = 0; |
167 | m_wait_for_launch = false; |
168 | m_ignore_existing = true; |
169 | m_continue_once_attached = false; |
170 | } |
171 | |
172 | bool ProcessInfoSpecified() const { |
173 | if (GetExecutableFile()) |
174 | return true; |
175 | if (GetProcessID() != LLDB_INVALID_PROCESS_ID) |
176 | return true; |
177 | if (GetParentProcessID() != LLDB_INVALID_PROCESS_ID) |
178 | return true; |
179 | return false; |
180 | } |
181 | |
182 | bool GetDetachOnError() const { return m_detach_on_error; } |
183 | |
184 | void SetDetachOnError(bool enable) { m_detach_on_error = enable; } |
185 | |
186 | lldb::ListenerSP GetListenerForProcess(Debugger &debugger); |
187 | |
188 | protected: |
189 | std::string m_plugin_name; |
190 | uint32_t m_resume_count = 0; // How many times do we resume after launching |
191 | bool m_wait_for_launch = false; |
192 | bool m_ignore_existing = true; |
193 | bool m_continue_once_attached = false; // Supports the use-case scenario of |
194 | // immediately continuing the process |
195 | // once attached. |
196 | bool m_detach_on_error = |
197 | true; // If we are debugging remotely, instruct the stub to |
198 | // detach rather than killing the target on error. |
199 | bool m_async = |
200 | false; // Use an async attach where we start the attach and return |
201 | // immediately (used by GUI programs with --waitfor so they can |
202 | // call SBProcess::Stop() to cancel attach) |
203 | }; |
204 | |
205 | // This class tracks the Modification state of the process. Things that can |
206 | // currently modify the program are running the program (which will up the |
207 | // StopID) and writing memory (which will up the MemoryID.) |
208 | // FIXME: Should we also include modification of register states? |
209 | |
210 | class ProcessModID { |
211 | friend bool operator==(const ProcessModID &lhs, const ProcessModID &rhs); |
212 | |
213 | public: |
214 | ProcessModID() = default; |
215 | |
216 | ProcessModID(const ProcessModID &rhs) |
217 | : m_stop_id(rhs.m_stop_id), m_memory_id(rhs.m_memory_id) {} |
218 | |
219 | const ProcessModID &operator=(const ProcessModID &rhs) { |
220 | if (this != &rhs) { |
221 | m_stop_id = rhs.m_stop_id; |
222 | m_memory_id = rhs.m_memory_id; |
223 | } |
224 | return *this; |
225 | } |
226 | |
227 | ~ProcessModID() = default; |
228 | |
229 | uint32_t BumpStopID() { |
230 | const uint32_t prev_stop_id = m_stop_id++; |
231 | if (!IsLastResumeForUserExpression()) |
232 | m_last_natural_stop_id++; |
233 | return prev_stop_id; |
234 | } |
235 | |
236 | void BumpMemoryID() { m_memory_id++; } |
237 | |
238 | void BumpResumeID() { |
239 | m_resume_id++; |
240 | if (m_running_user_expression > 0) |
241 | m_last_user_expression_resume = m_resume_id; |
242 | } |
243 | |
244 | bool IsRunningUtilityFunction() const { |
245 | return m_running_utility_function > 0; |
246 | } |
247 | |
248 | uint32_t GetStopID() const { return m_stop_id; } |
249 | uint32_t GetLastNaturalStopID() const { return m_last_natural_stop_id; } |
250 | uint32_t GetMemoryID() const { return m_memory_id; } |
251 | uint32_t GetResumeID() const { return m_resume_id; } |
252 | uint32_t GetLastUserExpressionResumeID() const { |
253 | return m_last_user_expression_resume; |
254 | } |
255 | |
256 | bool MemoryIDEqual(const ProcessModID &compare) const { |
257 | return m_memory_id == compare.m_memory_id; |
258 | } |
259 | |
260 | bool StopIDEqual(const ProcessModID &compare) const { |
261 | return m_stop_id == compare.m_stop_id; |
262 | } |
263 | |
264 | void SetInvalid() { m_stop_id = UINT32_MAX; } |
265 | |
266 | bool IsValid() const { return m_stop_id != UINT32_MAX; } |
267 | |
268 | bool IsLastResumeForUserExpression() const { |
269 | // If we haven't yet resumed the target, then it can't be for a user |
270 | // expression... |
271 | if (m_resume_id == 0) |
272 | return false; |
273 | |
274 | return m_resume_id == m_last_user_expression_resume; |
275 | } |
276 | |
277 | bool IsRunningExpression() const { |
278 | // Don't return true if we are no longer running an expression: |
279 | if (m_running_user_expression || m_running_utility_function) |
280 | return true; |
281 | return false; |
282 | } |
283 | |
284 | void SetRunningUserExpression(bool on) { |
285 | if (on) |
286 | m_running_user_expression++; |
287 | else |
288 | m_running_user_expression--; |
289 | } |
290 | |
291 | void SetRunningUtilityFunction(bool on) { |
292 | if (on) |
293 | m_running_utility_function++; |
294 | else { |
295 | assert(m_running_utility_function > 0 && |
296 | "Called SetRunningUtilityFunction(false) without calling " |
297 | "SetRunningUtilityFunction(true) before?" ); |
298 | m_running_utility_function--; |
299 | } |
300 | } |
301 | |
302 | void SetStopEventForLastNaturalStopID(lldb::EventSP event_sp) { |
303 | m_last_natural_stop_event = std::move(event_sp); |
304 | } |
305 | |
306 | lldb::EventSP GetStopEventForStopID(uint32_t stop_id) const { |
307 | if (stop_id == m_last_natural_stop_id) |
308 | return m_last_natural_stop_event; |
309 | return lldb::EventSP(); |
310 | } |
311 | |
312 | private: |
313 | uint32_t m_stop_id = 0; |
314 | uint32_t m_last_natural_stop_id = 0; |
315 | uint32_t m_resume_id = 0; |
316 | uint32_t m_memory_id = 0; |
317 | uint32_t m_last_user_expression_resume = 0; |
318 | uint32_t m_running_user_expression = false; |
319 | uint32_t m_running_utility_function = 0; |
320 | lldb::EventSP m_last_natural_stop_event; |
321 | }; |
322 | |
323 | inline bool operator==(const ProcessModID &lhs, const ProcessModID &rhs) { |
324 | if (lhs.StopIDEqual(compare: rhs) && lhs.MemoryIDEqual(compare: rhs)) |
325 | return true; |
326 | else |
327 | return false; |
328 | } |
329 | |
330 | inline bool operator!=(const ProcessModID &lhs, const ProcessModID &rhs) { |
331 | return (!lhs.StopIDEqual(compare: rhs) || !lhs.MemoryIDEqual(compare: rhs)); |
332 | } |
333 | |
334 | /// \class Process Process.h "lldb/Target/Process.h" |
335 | /// A plug-in interface definition class for debugging a process. |
336 | class Process : public std::enable_shared_from_this<Process>, |
337 | public ProcessProperties, |
338 | public Broadcaster, |
339 | public ExecutionContextScope, |
340 | public PluginInterface { |
341 | friend class FunctionCaller; // For WaitForStateChangeEventsPrivate |
342 | friend class Debugger; // For PopProcessIOHandler and ProcessIOHandlerIsActive |
343 | friend class DynamicLoader; // For LoadOperatingSystemPlugin |
344 | friend class ProcessEventData; |
345 | friend class StopInfo; |
346 | friend class Target; |
347 | friend class ThreadList; |
348 | |
349 | public: |
350 | /// Broadcaster event bits definitions. |
351 | enum { |
352 | eBroadcastBitStateChanged = (1 << 0), |
353 | eBroadcastBitInterrupt = (1 << 1), |
354 | eBroadcastBitSTDOUT = (1 << 2), |
355 | eBroadcastBitSTDERR = (1 << 3), |
356 | eBroadcastBitProfileData = (1 << 4), |
357 | eBroadcastBitStructuredData = (1 << 5), |
358 | }; |
359 | // This is all the event bits the public process broadcaster broadcasts. |
360 | // The process shadow listener signs up for all these bits... |
361 | static constexpr int g_all_event_bits = |
362 | eBroadcastBitStateChanged | eBroadcastBitInterrupt | eBroadcastBitSTDOUT | |
363 | eBroadcastBitSTDERR | eBroadcastBitProfileData | |
364 | eBroadcastBitStructuredData; |
365 | |
366 | enum { |
367 | eBroadcastInternalStateControlStop = (1 << 0), |
368 | eBroadcastInternalStateControlPause = (1 << 1), |
369 | eBroadcastInternalStateControlResume = (1 << 2) |
370 | }; |
371 | |
372 | typedef Range<lldb::addr_t, lldb::addr_t> LoadRange; |
373 | // We use a read/write lock to allow on or more clients to access the process |
374 | // state while the process is stopped (reader). We lock the write lock to |
375 | // control access to the process while it is running (readers, or clients |
376 | // that want the process stopped can block waiting for the process to stop, |
377 | // or just try to lock it to see if they can immediately access the stopped |
378 | // process. If the try read lock fails, then the process is running. |
379 | typedef ProcessRunLock::ProcessRunLocker StopLocker; |
380 | |
381 | // These two functions fill out the Broadcaster interface: |
382 | |
383 | static ConstString &GetStaticBroadcasterClass(); |
384 | |
385 | static constexpr llvm::StringRef AttachSynchronousHijackListenerName = |
386 | "lldb.internal.Process.AttachSynchronous.hijack" ; |
387 | static constexpr llvm::StringRef LaunchSynchronousHijackListenerName = |
388 | "lldb.internal.Process.LaunchSynchronous.hijack" ; |
389 | static constexpr llvm::StringRef ResumeSynchronousHijackListenerName = |
390 | "lldb.internal.Process.ResumeSynchronous.hijack" ; |
391 | |
392 | ConstString &GetBroadcasterClass() const override { |
393 | return GetStaticBroadcasterClass(); |
394 | } |
395 | |
396 | /// A notification structure that can be used by clients to listen |
397 | /// for changes in a process's lifetime. |
398 | /// |
399 | /// \see RegisterNotificationCallbacks (const Notifications&) @see |
400 | /// UnregisterNotificationCallbacks (const Notifications&) |
401 | typedef struct { |
402 | void *baton; |
403 | void (*initialize)(void *baton, Process *process); |
404 | void (*process_state_changed)(void *baton, Process *process, |
405 | lldb::StateType state); |
406 | } Notifications; |
407 | |
408 | class ProcessEventData : public EventData { |
409 | friend class Process; |
410 | |
411 | public: |
412 | ProcessEventData(); |
413 | ProcessEventData(const lldb::ProcessSP &process, lldb::StateType state); |
414 | |
415 | ~ProcessEventData() override; |
416 | |
417 | static llvm::StringRef GetFlavorString(); |
418 | |
419 | llvm::StringRef GetFlavor() const override; |
420 | |
421 | lldb::ProcessSP GetProcessSP() const { return m_process_wp.lock(); } |
422 | |
423 | lldb::StateType GetState() const { return m_state; } |
424 | bool GetRestarted() const { return m_restarted; } |
425 | |
426 | size_t GetNumRestartedReasons() { return m_restarted_reasons.size(); } |
427 | |
428 | const char *GetRestartedReasonAtIndex(size_t idx) { |
429 | return ((idx < m_restarted_reasons.size()) |
430 | ? m_restarted_reasons[idx].c_str() |
431 | : nullptr); |
432 | } |
433 | |
434 | bool GetInterrupted() const { return m_interrupted; } |
435 | |
436 | void Dump(Stream *s) const override; |
437 | |
438 | virtual bool ShouldStop(Event *event_ptr, bool &found_valid_stopinfo); |
439 | |
440 | void DoOnRemoval(Event *event_ptr) override; |
441 | |
442 | static const Process::ProcessEventData * |
443 | GetEventDataFromEvent(const Event *event_ptr); |
444 | |
445 | static lldb::ProcessSP GetProcessFromEvent(const Event *event_ptr); |
446 | |
447 | static lldb::StateType GetStateFromEvent(const Event *event_ptr); |
448 | |
449 | static bool GetRestartedFromEvent(const Event *event_ptr); |
450 | |
451 | static size_t GetNumRestartedReasons(const Event *event_ptr); |
452 | |
453 | static const char *GetRestartedReasonAtIndex(const Event *event_ptr, |
454 | size_t idx); |
455 | |
456 | static void AddRestartedReason(Event *event_ptr, const char *reason); |
457 | |
458 | static void SetRestartedInEvent(Event *event_ptr, bool new_value); |
459 | |
460 | static bool GetInterruptedFromEvent(const Event *event_ptr); |
461 | |
462 | static void SetInterruptedInEvent(Event *event_ptr, bool new_value); |
463 | |
464 | static bool SetUpdateStateOnRemoval(Event *event_ptr); |
465 | |
466 | private: |
467 | void SetUpdateStateOnRemoval() { m_update_state++; } |
468 | |
469 | void SetRestarted(bool new_value) { m_restarted = new_value; } |
470 | |
471 | void SetInterrupted(bool new_value) { m_interrupted = new_value; } |
472 | |
473 | void AddRestartedReason(const char *reason) { |
474 | m_restarted_reasons.push_back(x: reason); |
475 | } |
476 | |
477 | lldb::ProcessWP m_process_wp; |
478 | lldb::StateType m_state = lldb::eStateInvalid; |
479 | std::vector<std::string> m_restarted_reasons; |
480 | bool m_restarted = false; // For "eStateStopped" events, this is true if the |
481 | // target was automatically restarted. |
482 | int m_update_state = 0; |
483 | bool m_interrupted = false; |
484 | |
485 | ProcessEventData(const ProcessEventData &) = delete; |
486 | const ProcessEventData &operator=(const ProcessEventData &) = delete; |
487 | }; |
488 | |
489 | /// Destructor. |
490 | /// |
491 | /// The destructor is virtual since this class is designed to be inherited |
492 | /// from by the plug-in instance. |
493 | ~Process() override; |
494 | |
495 | static void SettingsInitialize(); |
496 | |
497 | static void SettingsTerminate(); |
498 | |
499 | static ProcessProperties &GetGlobalProperties(); |
500 | |
501 | /// Find a Process plug-in that can debug \a module using the currently |
502 | /// selected architecture. |
503 | /// |
504 | /// Scans all loaded plug-in interfaces that implement versions of the |
505 | /// Process plug-in interface and returns the first instance that can debug |
506 | /// the file. |
507 | /// |
508 | /// \see Process::CanDebug () |
509 | static lldb::ProcessSP FindPlugin(lldb::TargetSP target_sp, |
510 | llvm::StringRef plugin_name, |
511 | lldb::ListenerSP listener_sp, |
512 | const FileSpec *crash_file_path, |
513 | bool can_connect); |
514 | |
515 | /// Static function that can be used with the \b host function |
516 | /// Host::StartMonitoringChildProcess (). |
517 | /// |
518 | /// This function can be used by lldb_private::Process subclasses when they |
519 | /// want to watch for a local process and have its exit status automatically |
520 | /// set when the host child process exits. Subclasses should call |
521 | /// Host::StartMonitoringChildProcess () with: |
522 | /// callback = Process::SetHostProcessExitStatus |
523 | /// pid = Process::GetID() |
524 | /// monitor_signals = false |
525 | static bool |
526 | SetProcessExitStatus(lldb::pid_t pid, // The process ID we want to monitor |
527 | bool exited, |
528 | int signo, // Zero for no signal |
529 | int status); // Exit value of process if signal is zero |
530 | |
531 | lldb::ByteOrder GetByteOrder() const; |
532 | |
533 | uint32_t GetAddressByteSize() const; |
534 | |
535 | /// Returns the pid of the process or LLDB_INVALID_PROCESS_ID if there is |
536 | /// no known pid. |
537 | lldb::pid_t GetID() const { return m_pid; } |
538 | |
539 | /// Sets the stored pid. |
540 | /// |
541 | /// This does not change the pid of underlying process. |
542 | void SetID(lldb::pid_t new_pid) { m_pid = new_pid; } |
543 | |
544 | uint32_t GetUniqueID() const { return m_process_unique_id; } |
545 | |
546 | /// Check if a plug-in instance can debug the file in \a module. |
547 | /// |
548 | /// Each plug-in is given a chance to say whether it can debug the file in |
549 | /// \a module. If the Process plug-in instance can debug a file on the |
550 | /// current system, it should return \b true. |
551 | /// |
552 | /// \return |
553 | /// Returns \b true if this Process plug-in instance can |
554 | /// debug the executable, \b false otherwise. |
555 | virtual bool CanDebug(lldb::TargetSP target, |
556 | bool plugin_specified_by_name) = 0; |
557 | |
558 | /// This object is about to be destroyed, do any necessary cleanup. |
559 | /// |
560 | /// Subclasses that override this method should always call this superclass |
561 | /// method. |
562 | /// If you are running Finalize in your Process subclass Destructor, pass |
563 | /// \b true. If we are in the destructor, shared_from_this will no longer |
564 | /// work, so we have to avoid doing anything that might trigger that. |
565 | virtual void Finalize(bool destructing); |
566 | |
567 | /// Return whether this object is valid (i.e. has not been finalized.) |
568 | /// |
569 | /// \return |
570 | /// Returns \b true if this Process has not been finalized |
571 | /// and \b false otherwise. |
572 | bool IsValid() const { return !m_finalizing; } |
573 | |
574 | /// Return a multi-word command object that can be used to expose plug-in |
575 | /// specific commands. |
576 | /// |
577 | /// This object will be used to resolve plug-in commands and can be |
578 | /// triggered by a call to: |
579 | /// |
580 | /// (lldb) process command <args> |
581 | /// |
582 | /// \return |
583 | /// A CommandObject which can be one of the concrete subclasses |
584 | /// of CommandObject like CommandObjectRaw, CommandObjectParsed, |
585 | /// or CommandObjectMultiword. |
586 | virtual CommandObject *GetPluginCommandObject() { return nullptr; } |
587 | |
588 | /// The underlying plugin might store the low-level communication history for |
589 | /// this session. Dump it into the provided stream. |
590 | virtual void DumpPluginHistory(Stream &s) { return; } |
591 | |
592 | /// Launch a new process. |
593 | /// |
594 | /// Launch a new process by spawning a new process using the target object's |
595 | /// executable module's file as the file to launch. |
596 | /// |
597 | /// This function is not meant to be overridden by Process subclasses. It |
598 | /// will first call Process::WillLaunch (Module *) and if that returns \b |
599 | /// true, Process::DoLaunch (Module*, char const *[],char const *[],const |
600 | /// char *,const char *, const char *) will be called to actually do the |
601 | /// launching. If DoLaunch returns \b true, then Process::DidLaunch() will |
602 | /// be called. |
603 | /// |
604 | /// \param[in] launch_info |
605 | /// Details regarding the environment, STDIN/STDOUT/STDERR |
606 | /// redirection, working path, etc. related to the requested launch. |
607 | /// |
608 | /// \return |
609 | /// An error object. Call GetID() to get the process ID if |
610 | /// the error object is success. |
611 | virtual Status Launch(ProcessLaunchInfo &launch_info); |
612 | |
613 | virtual Status LoadCore(); |
614 | |
615 | virtual Status DoLoadCore() { |
616 | Status error; |
617 | error.SetErrorStringWithFormatv( |
618 | format: "error: {0} does not support loading core files." , args: GetPluginName()); |
619 | return error; |
620 | } |
621 | |
622 | /// The "ShadowListener" for a process is just an ordinary Listener that |
623 | /// listens for all the Process event bits. It's convenient because you can |
624 | /// specify it in the LaunchInfo or AttachInfo, so it will get events from |
625 | /// the very start of the process. |
626 | void SetShadowListener(lldb::ListenerSP shadow_listener_sp) { |
627 | if (shadow_listener_sp) |
628 | AddListener(listener_sp: shadow_listener_sp, event_mask: g_all_event_bits); |
629 | } |
630 | |
631 | // FUTURE WORK: GetLoadImageUtilityFunction are the first use we've |
632 | // had of having other plugins cache data in the Process. This is handy for |
633 | // long-living plugins - like the Platform - which manage interactions whose |
634 | // lifetime is governed by the Process lifetime. If we find we need to do |
635 | // this more often, we should construct a general solution to the problem. |
636 | // The consensus suggestion was that we have a token based registry in the |
637 | // Process. Some undecided questions are (1) who manages the tokens. It's |
638 | // probably best that you add the element and get back a token that |
639 | // represents it. That will avoid collisions. But there may be some utility |
640 | // in the registerer controlling the token? (2) whether the thing added |
641 | // should be simply owned by Process, and just go away when it does (3) |
642 | // whether the registree should be notified of the Process' demise. |
643 | // |
644 | // We are postponing designing this till we have at least a second use case. |
645 | /// Get the cached UtilityFunction that assists in loading binary images |
646 | /// into the process. |
647 | /// |
648 | /// \param[in] platform |
649 | /// The platform fetching the UtilityFunction. |
650 | /// \param[in] factory |
651 | /// A function that will be called only once per-process in a |
652 | /// thread-safe way to create the UtilityFunction if it has not |
653 | /// been initialized yet. |
654 | /// |
655 | /// \return |
656 | /// The cached utility function or null if the platform is not the |
657 | /// same as the target's platform. |
658 | UtilityFunction *GetLoadImageUtilityFunction( |
659 | Platform *platform, |
660 | llvm::function_ref<std::unique_ptr<UtilityFunction>()> factory); |
661 | |
662 | /// Get the dynamic loader plug-in for this process. |
663 | /// |
664 | /// The default action is to let the DynamicLoader plug-ins check the main |
665 | /// executable and the DynamicLoader will select itself automatically. |
666 | /// Subclasses can override this if inspecting the executable is not |
667 | /// desired, or if Process subclasses can only use a specific DynamicLoader |
668 | /// plug-in. |
669 | virtual DynamicLoader *GetDynamicLoader(); |
670 | |
671 | void SetDynamicLoader(lldb::DynamicLoaderUP dyld); |
672 | |
673 | // Returns AUXV structure found in many ELF-based environments. |
674 | // |
675 | // The default action is to return an empty data buffer. |
676 | // |
677 | // \return |
678 | // A data extractor containing the contents of the AUXV data. |
679 | virtual DataExtractor GetAuxvData(); |
680 | |
681 | /// Sometimes processes know how to retrieve and load shared libraries. This |
682 | /// is normally done by DynamicLoader plug-ins, but sometimes the connection |
683 | /// to the process allows retrieving this information. The dynamic loader |
684 | /// plug-ins can use this function if they can't determine the current |
685 | /// shared library load state. |
686 | /// |
687 | /// \return |
688 | /// A status object indicating if the operation was sucessful or not. |
689 | virtual llvm::Error LoadModules() { |
690 | return llvm::make_error<llvm::StringError>(Args: "Not implemented." , |
691 | Args: llvm::inconvertibleErrorCode()); |
692 | } |
693 | |
694 | /// Query remote GDBServer for a detailed loaded library list |
695 | /// \return |
696 | /// The list of modules currently loaded by the process, or an error. |
697 | virtual llvm::Expected<LoadedModuleInfoList> GetLoadedModuleList() { |
698 | return llvm::createStringError(EC: llvm::inconvertibleErrorCode(), |
699 | Msg: "Not implemented" ); |
700 | } |
701 | |
702 | /// Save core dump into the specified file. |
703 | /// |
704 | /// \param[in] outfile |
705 | /// Path to store core dump in. |
706 | /// |
707 | /// \return |
708 | /// true if saved successfully, false if saving the core dump |
709 | /// is not supported by the plugin, error otherwise. |
710 | virtual llvm::Expected<bool> SaveCore(llvm::StringRef outfile); |
711 | |
712 | struct CoreFileMemoryRange { |
713 | llvm::AddressRange range; /// The address range to save into the core file. |
714 | uint32_t lldb_permissions; /// A bit set of lldb::Permissions bits. |
715 | |
716 | bool operator==(const CoreFileMemoryRange &rhs) const { |
717 | return range == rhs.range && lldb_permissions == rhs.lldb_permissions; |
718 | } |
719 | |
720 | bool operator!=(const CoreFileMemoryRange &rhs) const { |
721 | return !(*this == rhs); |
722 | } |
723 | |
724 | bool operator<(const CoreFileMemoryRange &rhs) const { |
725 | if (range < rhs.range) |
726 | return true; |
727 | if (range == rhs.range) |
728 | return lldb_permissions < rhs.lldb_permissions; |
729 | return false; |
730 | } |
731 | }; |
732 | |
733 | using CoreFileMemoryRanges = std::vector<CoreFileMemoryRange>; |
734 | |
735 | /// Helper function for Process::SaveCore(...) that calculates the address |
736 | /// ranges that should be saved. This allows all core file plug-ins to save |
737 | /// consistent memory ranges given a \a core_style. |
738 | Status CalculateCoreFileSaveRanges(lldb::SaveCoreStyle core_style, |
739 | CoreFileMemoryRanges &ranges); |
740 | |
741 | protected: |
742 | virtual JITLoaderList &GetJITLoaders(); |
743 | |
744 | public: |
745 | /// Get the system architecture for this process. |
746 | virtual ArchSpec GetSystemArchitecture() { return {}; } |
747 | |
748 | /// Get the system runtime plug-in for this process. |
749 | /// |
750 | /// \return |
751 | /// Returns a pointer to the SystemRuntime plugin for this Process |
752 | /// if one is available. Else returns nullptr. |
753 | virtual SystemRuntime *GetSystemRuntime(); |
754 | |
755 | /// Attach to an existing process using the process attach info. |
756 | /// |
757 | /// This function is not meant to be overridden by Process subclasses. It |
758 | /// will first call WillAttach (lldb::pid_t) or WillAttach (const char *), |
759 | /// and if that returns \b true, DoAttach (lldb::pid_t) or DoAttach (const |
760 | /// char *) will be called to actually do the attach. If DoAttach returns \b |
761 | /// true, then Process::DidAttach() will be called. |
762 | /// |
763 | /// \param[in] attach_info |
764 | /// The process attach info. |
765 | /// |
766 | /// \return |
767 | /// Returns \a pid if attaching was successful, or |
768 | /// LLDB_INVALID_PROCESS_ID if attaching fails. |
769 | virtual Status Attach(ProcessAttachInfo &attach_info); |
770 | |
771 | /// Attach to a remote system via a URL |
772 | /// |
773 | /// \param[in] remote_url |
774 | /// The URL format that we are connecting to. |
775 | /// |
776 | /// \return |
777 | /// Returns an error object. |
778 | virtual Status ConnectRemote(llvm::StringRef remote_url); |
779 | |
780 | bool GetShouldDetach() const { return m_should_detach; } |
781 | |
782 | void SetShouldDetach(bool b) { m_should_detach = b; } |
783 | |
784 | /// Get the image vector for the current process. |
785 | /// |
786 | /// \return |
787 | /// The constant reference to the member m_image_tokens. |
788 | const std::vector<lldb::addr_t>& GetImageTokens() { return m_image_tokens; } |
789 | |
790 | /// Get the image information address for the current process. |
791 | /// |
792 | /// Some runtimes have system functions that can help dynamic loaders locate |
793 | /// the dynamic loader information needed to observe shared libraries being |
794 | /// loaded or unloaded. This function is in the Process interface (as |
795 | /// opposed to the DynamicLoader interface) to ensure that remote debugging |
796 | /// can take advantage of this functionality. |
797 | /// |
798 | /// \return |
799 | /// The address of the dynamic loader information, or |
800 | /// LLDB_INVALID_ADDRESS if this is not supported by this |
801 | /// interface. |
802 | virtual lldb::addr_t GetImageInfoAddress(); |
803 | |
804 | /// Called when the process is about to broadcast a public stop. |
805 | /// |
806 | /// There are public and private stops. Private stops are when the process |
807 | /// is doing things like stepping and the client doesn't need to know about |
808 | /// starts and stop that implement a thread plan. Single stepping over a |
809 | /// source line in code might end up being implemented by one or more |
810 | /// process starts and stops. Public stops are when clients will be notified |
811 | /// that the process is stopped. These events typically trigger UI updates |
812 | /// (thread stack frames to be displayed, variables to be displayed, and |
813 | /// more). This function can be overriden and allows process subclasses to |
814 | /// do something before the eBroadcastBitStateChanged event is sent to |
815 | /// public clients. |
816 | virtual void WillPublicStop() {} |
817 | |
818 | /// Register for process and thread notifications. |
819 | /// |
820 | /// Clients can register notification callbacks by filling out a |
821 | /// Process::Notifications structure and calling this function. |
822 | /// |
823 | /// \param[in] callbacks |
824 | /// A structure that contains the notification baton and |
825 | /// callback functions. |
826 | /// |
827 | /// \see Process::Notifications |
828 | void RegisterNotificationCallbacks(const Process::Notifications &callbacks); |
829 | |
830 | /// Unregister for process and thread notifications. |
831 | /// |
832 | /// Clients can unregister notification callbacks by passing a copy of the |
833 | /// original baton and callbacks in \a callbacks. |
834 | /// |
835 | /// \param[in] callbacks |
836 | /// A structure that contains the notification baton and |
837 | /// callback functions. |
838 | /// |
839 | /// \return |
840 | /// Returns \b true if the notification callbacks were |
841 | /// successfully removed from the process, \b false otherwise. |
842 | /// |
843 | /// \see Process::Notifications |
844 | bool UnregisterNotificationCallbacks(const Process::Notifications &callbacks); |
845 | |
846 | //================================================================== |
847 | // Built in Process Control functions |
848 | //================================================================== |
849 | /// Resumes all of a process's threads as configured using the Thread run |
850 | /// control functions. |
851 | /// |
852 | /// Threads for a process should be updated with one of the run control |
853 | /// actions (resume, step, or suspend) that they should take when the |
854 | /// process is resumed. If no run control action is given to a thread it |
855 | /// will be resumed by default. |
856 | /// |
857 | /// This function is not meant to be overridden by Process subclasses. This |
858 | /// function will take care of disabling any breakpoints that threads may be |
859 | /// stopped at, single stepping, and re-enabling breakpoints, and enabling |
860 | /// the basic flow control that the plug-in instances need not worry about. |
861 | /// |
862 | /// N.B. This function also sets the Write side of the Run Lock, which is |
863 | /// unset when the corresponding stop event is pulled off the Public Event |
864 | /// Queue. If you need to resume the process without setting the Run Lock, |
865 | /// use PrivateResume (though you should only do that from inside the |
866 | /// Process class. |
867 | /// |
868 | /// \return |
869 | /// Returns an error object. |
870 | /// |
871 | /// \see Thread:Resume() |
872 | /// \see Thread:Step() |
873 | /// \see Thread:Suspend() |
874 | Status Resume(); |
875 | |
876 | /// Resume a process, and wait for it to stop. |
877 | Status ResumeSynchronous(Stream *stream); |
878 | |
879 | /// Halts a running process. |
880 | /// |
881 | /// This function is not meant to be overridden by Process subclasses. If |
882 | /// the process is successfully halted, a eStateStopped process event with |
883 | /// GetInterrupted will be broadcast. If false, we will halt the process |
884 | /// with no events generated by the halt. |
885 | /// |
886 | /// \param[in] clear_thread_plans |
887 | /// If true, when the process stops, clear all thread plans. |
888 | /// |
889 | /// \param[in] use_run_lock |
890 | /// Whether to release the run lock after the stop. |
891 | /// |
892 | /// \return |
893 | /// Returns an error object. If the error is empty, the process is |
894 | /// halted. |
895 | /// otherwise the halt has failed. |
896 | Status Halt(bool clear_thread_plans = false, bool use_run_lock = true); |
897 | |
898 | /// Detaches from a running or stopped process. |
899 | /// |
900 | /// This function is not meant to be overridden by Process subclasses. |
901 | /// |
902 | /// \param[in] keep_stopped |
903 | /// If true, don't resume the process on detach. |
904 | /// |
905 | /// \return |
906 | /// Returns an error object. |
907 | Status Detach(bool keep_stopped); |
908 | |
909 | /// Kills the process and shuts down all threads that were spawned to track |
910 | /// and monitor the process. |
911 | /// |
912 | /// This function is not meant to be overridden by Process subclasses. |
913 | /// |
914 | /// \param[in] force_kill |
915 | /// Whether lldb should force a kill (instead of a detach) from |
916 | /// the inferior process. Normally if lldb launched a binary and |
917 | /// Destory is called, lldb kills it. If lldb attached to a |
918 | /// running process and Destory is called, lldb detaches. If |
919 | /// this behavior needs to be over-ridden, this is the bool that |
920 | /// can be used. |
921 | /// |
922 | /// \return |
923 | /// Returns an error object. |
924 | Status Destroy(bool force_kill); |
925 | |
926 | /// Sends a process a UNIX signal \a signal. |
927 | /// |
928 | /// This function is not meant to be overridden by Process subclasses. |
929 | /// |
930 | /// \return |
931 | /// Returns an error object. |
932 | Status Signal(int signal); |
933 | |
934 | void SetUnixSignals(lldb::UnixSignalsSP &&signals_sp); |
935 | |
936 | const lldb::UnixSignalsSP &GetUnixSignals(); |
937 | |
938 | //================================================================== |
939 | // Plug-in Process Control Overrides |
940 | //================================================================== |
941 | |
942 | /// Called before attaching to a process. |
943 | /// |
944 | /// \return |
945 | /// Returns an error object. |
946 | Status WillAttachToProcessWithID(lldb::pid_t pid); |
947 | |
948 | /// Called before attaching to a process. |
949 | /// |
950 | /// Allow Process plug-ins to execute some code before attaching a process. |
951 | /// |
952 | /// \return |
953 | /// Returns an error object. |
954 | virtual Status DoWillAttachToProcessWithID(lldb::pid_t pid) { |
955 | return Status(); |
956 | } |
957 | |
958 | /// Called before attaching to a process. |
959 | /// |
960 | /// \return |
961 | /// Returns an error object. |
962 | Status WillAttachToProcessWithName(const char *process_name, |
963 | bool wait_for_launch); |
964 | |
965 | /// Called before attaching to a process. |
966 | /// |
967 | /// Allow Process plug-ins to execute some code before attaching a process. |
968 | /// |
969 | /// \return |
970 | /// Returns an error object. |
971 | virtual Status DoWillAttachToProcessWithName(const char *process_name, |
972 | bool wait_for_launch) { |
973 | return Status(); |
974 | } |
975 | |
976 | /// Attach to a remote system via a URL |
977 | /// |
978 | /// \param[in] remote_url |
979 | /// The URL format that we are connecting to. |
980 | /// |
981 | /// \return |
982 | /// Returns an error object. |
983 | virtual Status DoConnectRemote(llvm::StringRef remote_url) { |
984 | Status error; |
985 | error.SetErrorString("remote connections are not supported" ); |
986 | return error; |
987 | } |
988 | |
989 | /// Attach to an existing process using a process ID. |
990 | /// |
991 | /// \param[in] pid |
992 | /// The process ID that we should attempt to attach to. |
993 | /// |
994 | /// \param[in] attach_info |
995 | /// Information on how to do the attach. For example, GetUserID() |
996 | /// will return the uid to attach as. |
997 | /// |
998 | /// \return |
999 | /// Returns a successful Status attaching was successful, or |
1000 | /// an appropriate (possibly platform-specific) error code if |
1001 | /// attaching fails. |
1002 | /// hanming : need flag |
1003 | virtual Status DoAttachToProcessWithID(lldb::pid_t pid, |
1004 | const ProcessAttachInfo &attach_info) { |
1005 | Status error; |
1006 | error.SetErrorStringWithFormatv( |
1007 | format: "error: {0} does not support attaching to a process by pid" , |
1008 | args: GetPluginName()); |
1009 | return error; |
1010 | } |
1011 | |
1012 | /// Attach to an existing process using a partial process name. |
1013 | /// |
1014 | /// \param[in] process_name |
1015 | /// The name of the process to attach to. |
1016 | /// |
1017 | /// \param[in] attach_info |
1018 | /// Information on how to do the attach. For example, GetUserID() |
1019 | /// will return the uid to attach as. |
1020 | /// |
1021 | /// \return |
1022 | /// Returns a successful Status attaching was successful, or |
1023 | /// an appropriate (possibly platform-specific) error code if |
1024 | /// attaching fails. |
1025 | virtual Status |
1026 | DoAttachToProcessWithName(const char *process_name, |
1027 | const ProcessAttachInfo &attach_info) { |
1028 | Status error; |
1029 | error.SetErrorString("attach by name is not supported" ); |
1030 | return error; |
1031 | } |
1032 | |
1033 | /// Called after attaching a process. |
1034 | /// |
1035 | /// \param[in] process_arch |
1036 | /// If you can figure out the process architecture after attach, fill it |
1037 | /// in here. |
1038 | /// |
1039 | /// Allow Process plug-ins to execute some code after attaching to a |
1040 | /// process. |
1041 | virtual void DidAttach(ArchSpec &process_arch) { process_arch.Clear(); } |
1042 | |
1043 | /// Called after a process re-execs itself. |
1044 | /// |
1045 | /// Allow Process plug-ins to execute some code after a process has exec'ed |
1046 | /// itself. Subclasses typically should override DoDidExec() as the |
1047 | /// lldb_private::Process class needs to remove its dynamic loader, runtime, |
1048 | /// ABI and other plug-ins, as well as unload all shared libraries. |
1049 | virtual void DidExec(); |
1050 | |
1051 | /// Subclasses of Process should implement this function if they need to do |
1052 | /// anything after a process exec's itself. |
1053 | virtual void DoDidExec() {} |
1054 | |
1055 | /// Called after a reported fork. |
1056 | virtual void DidFork(lldb::pid_t child_pid, lldb::tid_t child_tid) {} |
1057 | |
1058 | /// Called after a reported vfork. |
1059 | virtual void DidVFork(lldb::pid_t child_pid, lldb::tid_t child_tid) {} |
1060 | |
1061 | /// Called after reported vfork completion. |
1062 | virtual void DidVForkDone() {} |
1063 | |
1064 | /// Called before launching to a process. |
1065 | /// \return |
1066 | /// Returns an error object. |
1067 | Status WillLaunch(Module *module); |
1068 | |
1069 | /// Called before launching to a process. |
1070 | /// |
1071 | /// Allow Process plug-ins to execute some code before launching a process. |
1072 | /// |
1073 | /// \return |
1074 | /// Returns an error object. |
1075 | virtual Status DoWillLaunch(Module *module) { return Status(); } |
1076 | |
1077 | /// Launch a new process. |
1078 | /// |
1079 | /// Launch a new process by spawning a new process using \a exe_module's |
1080 | /// file as the file to launch. Launch details are provided in \a |
1081 | /// launch_info. |
1082 | /// |
1083 | /// \param[in] exe_module |
1084 | /// The module from which to extract the file specification and |
1085 | /// launch. |
1086 | /// |
1087 | /// \param[in] launch_info |
1088 | /// Details (e.g. arguments, stdio redirection, etc.) for the |
1089 | /// requested launch. |
1090 | /// |
1091 | /// \return |
1092 | /// An Status instance indicating success or failure of the |
1093 | /// operation. |
1094 | virtual Status DoLaunch(Module *exe_module, ProcessLaunchInfo &launch_info) { |
1095 | Status error; |
1096 | error.SetErrorStringWithFormatv( |
1097 | format: "error: {0} does not support launching processes" , args: GetPluginName()); |
1098 | return error; |
1099 | } |
1100 | |
1101 | /// Called after launching a process. |
1102 | /// |
1103 | /// Allow Process plug-ins to execute some code after launching a process. |
1104 | virtual void DidLaunch() {} |
1105 | |
1106 | /// Called before resuming to a process. |
1107 | /// |
1108 | /// Allow Process plug-ins to execute some code before resuming a process. |
1109 | /// |
1110 | /// \return |
1111 | /// Returns an error object. |
1112 | virtual Status WillResume() { return Status(); } |
1113 | |
1114 | /// Resumes all of a process's threads as configured using the Thread run |
1115 | /// control functions. |
1116 | /// |
1117 | /// Threads for a process should be updated with one of the run control |
1118 | /// actions (resume, step, or suspend) that they should take when the |
1119 | /// process is resumed. If no run control action is given to a thread it |
1120 | /// will be resumed by default. |
1121 | /// |
1122 | /// \return |
1123 | /// Returns \b true if the process successfully resumes using |
1124 | /// the thread run control actions, \b false otherwise. |
1125 | /// |
1126 | /// \see Thread:Resume() |
1127 | /// \see Thread:Step() |
1128 | /// \see Thread:Suspend() |
1129 | virtual Status DoResume() { |
1130 | Status error; |
1131 | error.SetErrorStringWithFormatv( |
1132 | format: "error: {0} does not support resuming processes" , args: GetPluginName()); |
1133 | return error; |
1134 | } |
1135 | |
1136 | /// Called after resuming a process. |
1137 | /// |
1138 | /// Allow Process plug-ins to execute some code after resuming a process. |
1139 | virtual void DidResume() {} |
1140 | |
1141 | /// Called before halting to a process. |
1142 | /// |
1143 | /// Allow Process plug-ins to execute some code before halting a process. |
1144 | /// |
1145 | /// \return |
1146 | /// Returns an error object. |
1147 | virtual Status WillHalt() { return Status(); } |
1148 | |
1149 | /// Halts a running process. |
1150 | /// |
1151 | /// DoHalt must produce one and only one stop StateChanged event if it |
1152 | /// actually stops the process. If the stop happens through some natural |
1153 | /// event (for instance a SIGSTOP), then forwarding that event will do. |
1154 | /// Otherwise, you must generate the event manually. This function is called |
1155 | /// from the context of the private state thread. |
1156 | /// |
1157 | /// \param[out] caused_stop |
1158 | /// If true, then this Halt caused the stop, otherwise, the |
1159 | /// process was already stopped. |
1160 | /// |
1161 | /// \return |
1162 | /// Returns \b true if the process successfully halts, \b false |
1163 | /// otherwise. |
1164 | virtual Status DoHalt(bool &caused_stop) { |
1165 | Status error; |
1166 | error.SetErrorStringWithFormatv( |
1167 | format: "error: {0} does not support halting processes" , args: GetPluginName()); |
1168 | return error; |
1169 | } |
1170 | |
1171 | /// Called after halting a process. |
1172 | /// |
1173 | /// Allow Process plug-ins to execute some code after halting a process. |
1174 | virtual void DidHalt() {} |
1175 | |
1176 | /// Called before detaching from a process. |
1177 | /// |
1178 | /// Allow Process plug-ins to execute some code before detaching from a |
1179 | /// process. |
1180 | /// |
1181 | /// \return |
1182 | /// Returns an error object. |
1183 | virtual Status WillDetach() { return Status(); } |
1184 | |
1185 | /// Detaches from a running or stopped process. |
1186 | /// |
1187 | /// \return |
1188 | /// Returns \b true if the process successfully detaches, \b |
1189 | /// false otherwise. |
1190 | virtual Status DoDetach(bool keep_stopped) { |
1191 | Status error; |
1192 | error.SetErrorStringWithFormatv( |
1193 | format: "error: {0} does not support detaching from processes" , |
1194 | args: GetPluginName()); |
1195 | return error; |
1196 | } |
1197 | |
1198 | /// Called after detaching from a process. |
1199 | /// |
1200 | /// Allow Process plug-ins to execute some code after detaching from a |
1201 | /// process. |
1202 | virtual void DidDetach() {} |
1203 | |
1204 | virtual bool DetachRequiresHalt() { return false; } |
1205 | |
1206 | /// Called before sending a signal to a process. |
1207 | /// |
1208 | /// Allow Process plug-ins to execute some code before sending a signal to a |
1209 | /// process. |
1210 | /// |
1211 | /// \return |
1212 | /// Returns no error if it is safe to proceed with a call to |
1213 | /// Process::DoSignal(int), otherwise an error describing what |
1214 | /// prevents the signal from being sent. |
1215 | virtual Status WillSignal() { return Status(); } |
1216 | |
1217 | /// Sends a process a UNIX signal \a signal. |
1218 | /// |
1219 | /// \return |
1220 | /// Returns an error object. |
1221 | virtual Status DoSignal(int signal) { |
1222 | Status error; |
1223 | error.SetErrorStringWithFormatv( |
1224 | format: "error: {0} does not support sending signals to processes" , |
1225 | args: GetPluginName()); |
1226 | return error; |
1227 | } |
1228 | |
1229 | virtual Status WillDestroy() { return Status(); } |
1230 | |
1231 | virtual Status DoDestroy() = 0; |
1232 | |
1233 | virtual void DidDestroy() {} |
1234 | |
1235 | virtual bool DestroyRequiresHalt() { return true; } |
1236 | |
1237 | /// Called after sending a signal to a process. |
1238 | /// |
1239 | /// Allow Process plug-ins to execute some code after sending a signal to a |
1240 | /// process. |
1241 | virtual void DidSignal() {} |
1242 | |
1243 | /// Currently called as part of ShouldStop. |
1244 | /// FIXME: Should really happen when the target stops before the |
1245 | /// event is taken from the queue... |
1246 | /// |
1247 | /// This callback is called as the event |
1248 | /// is about to be queued up to allow Process plug-ins to execute some code |
1249 | /// prior to clients being notified that a process was stopped. Common |
1250 | /// operations include updating the thread list, invalidating any thread |
1251 | /// state (registers, stack, etc) prior to letting the notification go out. |
1252 | /// |
1253 | virtual void RefreshStateAfterStop() = 0; |
1254 | |
1255 | /// Sometimes the connection to a process can detect the host OS version |
1256 | /// that the process is running on. The current platform should be checked |
1257 | /// first in case the platform is connected, but clients can fall back onto |
1258 | /// this function if the platform fails to identify the host OS version. The |
1259 | /// platform should be checked first in case you are running a simulator |
1260 | /// platform that might itself be running natively, but have different |
1261 | /// heuristics for figuring out which OS is emulating. |
1262 | /// |
1263 | /// \return |
1264 | /// Returns the version tuple of the host OS. In case of failure an empty |
1265 | /// VersionTuple is returner. |
1266 | virtual llvm::VersionTuple GetHostOSVersion() { return llvm::VersionTuple(); } |
1267 | |
1268 | /// \return the macCatalyst version of the host OS. |
1269 | virtual llvm::VersionTuple GetHostMacCatalystVersion() { return {}; } |
1270 | |
1271 | /// Get the target object pointer for this module. |
1272 | /// |
1273 | /// \return |
1274 | /// A Target object pointer to the target that owns this |
1275 | /// module. |
1276 | Target &GetTarget() { return *m_target_wp.lock(); } |
1277 | |
1278 | /// Get the const target object pointer for this module. |
1279 | /// |
1280 | /// \return |
1281 | /// A const Target object pointer to the target that owns this |
1282 | /// module. |
1283 | const Target &GetTarget() const { return *m_target_wp.lock(); } |
1284 | |
1285 | /// Flush all data in the process. |
1286 | /// |
1287 | /// Flush the memory caches, all threads, and any other cached data in the |
1288 | /// process. |
1289 | /// |
1290 | /// This function can be called after a world changing event like adding a |
1291 | /// new symbol file, or after the process makes a large context switch (from |
1292 | /// boot ROM to booted into an OS). |
1293 | void Flush(); |
1294 | |
1295 | /// Get accessor for the current process state. |
1296 | /// |
1297 | /// \return |
1298 | /// The current state of the process. |
1299 | /// |
1300 | /// \see lldb::StateType |
1301 | lldb::StateType GetState(); |
1302 | |
1303 | lldb::ExpressionResults |
1304 | RunThreadPlan(ExecutionContext &exe_ctx, lldb::ThreadPlanSP &thread_plan_sp, |
1305 | const EvaluateExpressionOptions &options, |
1306 | DiagnosticManager &diagnostic_manager); |
1307 | |
1308 | static const char *ExecutionResultAsCString(lldb::ExpressionResults result); |
1309 | |
1310 | void GetStatus(Stream &ostrm); |
1311 | |
1312 | size_t GetThreadStatus(Stream &ostrm, bool only_threads_with_stop_reason, |
1313 | uint32_t start_frame, uint32_t num_frames, |
1314 | uint32_t num_frames_with_source, |
1315 | bool stop_format); |
1316 | |
1317 | void SendAsyncInterrupt(); |
1318 | |
1319 | // Notify this process class that modules got loaded. |
1320 | // |
1321 | // If subclasses override this method, they must call this version before |
1322 | // doing anything in the subclass version of the function. |
1323 | virtual void ModulesDidLoad(ModuleList &module_list); |
1324 | |
1325 | /// Retrieve the list of shared libraries that are loaded for this process |
1326 | /// This method is used on pre-macOS 10.12, pre-iOS 10, pre-tvOS 10, pre- |
1327 | /// watchOS 3 systems. The following two methods are for newer versions of |
1328 | /// those OSes. |
1329 | /// |
1330 | /// For certain platforms, the time it takes for the DynamicLoader plugin to |
1331 | /// read all of the shared libraries out of memory over a slow communication |
1332 | /// channel may be too long. In that instance, the gdb-remote stub may be |
1333 | /// able to retrieve the necessary information about the solibs out of |
1334 | /// memory and return a concise summary sufficient for the DynamicLoader |
1335 | /// plugin. |
1336 | /// |
1337 | /// \param [in] image_list_address |
1338 | /// The address where the table of shared libraries is stored in memory, |
1339 | /// if that is appropriate for this platform. Else this may be |
1340 | /// passed as LLDB_INVALID_ADDRESS. |
1341 | /// |
1342 | /// \param [in] image_count |
1343 | /// The number of shared libraries that are present in this process, if |
1344 | /// that is appropriate for this platofrm Else this may be passed as |
1345 | /// LLDB_INVALID_ADDRESS. |
1346 | /// |
1347 | /// \return |
1348 | /// A StructuredDataSP object which, if non-empty, will contain the |
1349 | /// information the DynamicLoader needs to get the initial scan of |
1350 | /// solibs resolved. |
1351 | virtual lldb_private::StructuredData::ObjectSP |
1352 | GetLoadedDynamicLibrariesInfos(lldb::addr_t image_list_address, |
1353 | lldb::addr_t image_count) { |
1354 | return StructuredData::ObjectSP(); |
1355 | } |
1356 | |
1357 | // On macOS 10.12, tvOS 10, iOS 10, watchOS 3 and newer, debugserver can |
1358 | // return the full list of loaded shared libraries without needing any input. |
1359 | virtual lldb_private::StructuredData::ObjectSP |
1360 | GetLoadedDynamicLibrariesInfos() { |
1361 | return StructuredData::ObjectSP(); |
1362 | } |
1363 | |
1364 | // On macOS 10.12, tvOS 10, iOS 10, watchOS 3 and newer, debugserver can |
1365 | // return information about binaries given their load addresses. |
1366 | virtual lldb_private::StructuredData::ObjectSP GetLoadedDynamicLibrariesInfos( |
1367 | const std::vector<lldb::addr_t> &load_addresses) { |
1368 | return StructuredData::ObjectSP(); |
1369 | } |
1370 | |
1371 | // Get information about the library shared cache, if that exists |
1372 | // |
1373 | // On macOS 10.12, tvOS 10, iOS 10, watchOS 3 and newer, debugserver can |
1374 | // return information about the library shared cache (a set of standard |
1375 | // libraries that are loaded at the same location for all processes on a |
1376 | // system) in use. |
1377 | virtual lldb_private::StructuredData::ObjectSP GetSharedCacheInfo() { |
1378 | return StructuredData::ObjectSP(); |
1379 | } |
1380 | |
1381 | // Get information about the launch state of the process, if possible. |
1382 | // |
1383 | // On Darwin systems, libdyld can report on process state, most importantly |
1384 | // the startup stages where the system library is not yet initialized. |
1385 | virtual lldb_private::StructuredData::ObjectSP |
1386 | GetDynamicLoaderProcessState() { |
1387 | return {}; |
1388 | } |
1389 | |
1390 | /// Print a user-visible warning about a module being built with |
1391 | /// optimization |
1392 | /// |
1393 | /// Prints a async warning message to the user one time per Module where a |
1394 | /// function is found that was compiled with optimization, per Process. |
1395 | /// |
1396 | /// \param [in] sc |
1397 | /// A SymbolContext with eSymbolContextFunction and eSymbolContextModule |
1398 | /// pre-computed. |
1399 | void PrintWarningOptimization(const SymbolContext &sc); |
1400 | |
1401 | /// Print a user-visible warning about a function written in a |
1402 | /// language that this version of LLDB doesn't support. |
1403 | /// |
1404 | /// \see PrintWarningOptimization |
1405 | void PrintWarningUnsupportedLanguage(const SymbolContext &sc); |
1406 | |
1407 | virtual bool GetProcessInfo(ProcessInstanceInfo &info); |
1408 | |
1409 | /// Get the exit status for a process. |
1410 | /// |
1411 | /// \return |
1412 | /// The process's return code, or -1 if the current process |
1413 | /// state is not eStateExited. |
1414 | int GetExitStatus(); |
1415 | |
1416 | /// Get a textual description of what the process exited. |
1417 | /// |
1418 | /// \return |
1419 | /// The textual description of why the process exited, or nullptr |
1420 | /// if there is no description available. |
1421 | const char *GetExitDescription(); |
1422 | |
1423 | virtual void DidExit() {} |
1424 | |
1425 | lldb::addr_t GetCodeAddressMask(); |
1426 | lldb::addr_t GetDataAddressMask(); |
1427 | |
1428 | lldb::addr_t GetHighmemCodeAddressMask(); |
1429 | lldb::addr_t GetHighmemDataAddressMask(); |
1430 | |
1431 | void SetCodeAddressMask(lldb::addr_t code_address_mask); |
1432 | void SetDataAddressMask(lldb::addr_t data_address_mask); |
1433 | |
1434 | void SetHighmemCodeAddressMask(lldb::addr_t code_address_mask); |
1435 | void SetHighmemDataAddressMask(lldb::addr_t data_address_mask); |
1436 | |
1437 | /// Some targets might use bits in a code address to indicate a mode switch, |
1438 | /// ARM uses bit zero to signify a code address is thumb, so any ARM ABI |
1439 | /// plug-ins would strip those bits. |
1440 | /// Or use the high bits to authenticate a pointer value. |
1441 | lldb::addr_t FixCodeAddress(lldb::addr_t pc); |
1442 | lldb::addr_t FixDataAddress(lldb::addr_t pc); |
1443 | |
1444 | /// Use this method when you do not know, or do not care what kind of address |
1445 | /// you are fixing. On platforms where there would be a difference between the |
1446 | /// two types, it will pick the safest option. |
1447 | /// |
1448 | /// Its purpose is to signal that no specific choice was made and provide an |
1449 | /// alternative to randomly picking FixCode/FixData address. Which could break |
1450 | /// platforms where there is a difference (only Arm Thumb at this time). |
1451 | lldb::addr_t FixAnyAddress(lldb::addr_t pc); |
1452 | |
1453 | /// Get the Modification ID of the process. |
1454 | /// |
1455 | /// \return |
1456 | /// The modification ID of the process. |
1457 | ProcessModID GetModID() const { return m_mod_id; } |
1458 | |
1459 | const ProcessModID &GetModIDRef() const { return m_mod_id; } |
1460 | |
1461 | uint32_t GetStopID() const { return m_mod_id.GetStopID(); } |
1462 | |
1463 | uint32_t GetResumeID() const { return m_mod_id.GetResumeID(); } |
1464 | |
1465 | uint32_t GetLastUserExpressionResumeID() const { |
1466 | return m_mod_id.GetLastUserExpressionResumeID(); |
1467 | } |
1468 | |
1469 | uint32_t GetLastNaturalStopID() const { |
1470 | return m_mod_id.GetLastNaturalStopID(); |
1471 | } |
1472 | |
1473 | lldb::EventSP GetStopEventForStopID(uint32_t stop_id) const { |
1474 | return m_mod_id.GetStopEventForStopID(stop_id); |
1475 | } |
1476 | |
1477 | /// Set accessor for the process exit status (return code). |
1478 | /// |
1479 | /// Sometimes a child exits and the exit can be detected by global functions |
1480 | /// (signal handler for SIGCHLD for example). This accessor allows the exit |
1481 | /// status to be set from an external source. |
1482 | /// |
1483 | /// Setting this will cause a eStateExited event to be posted to the process |
1484 | /// event queue. |
1485 | /// |
1486 | /// \param[in] exit_status |
1487 | /// The value for the process's return code. |
1488 | /// |
1489 | /// \param[in] exit_string |
1490 | /// A StringRef containing the reason for exiting. May be empty. |
1491 | /// |
1492 | /// \return |
1493 | /// Returns \b false if the process was already in an exited state, \b |
1494 | /// true otherwise. |
1495 | virtual bool SetExitStatus(int exit_status, llvm::StringRef exit_string); |
1496 | |
1497 | /// Check if a process is still alive. |
1498 | /// |
1499 | /// \return |
1500 | /// Returns \b true if the process is still valid, \b false |
1501 | /// otherwise. |
1502 | virtual bool IsAlive(); |
1503 | |
1504 | virtual bool IsLiveDebugSession() const { return true; }; |
1505 | |
1506 | /// Provide a way to retrieve the core dump file that is loaded for debugging. |
1507 | /// Only available if IsLiveDebugSession() returns true. |
1508 | /// |
1509 | /// \return |
1510 | /// File path to the core file. |
1511 | virtual FileSpec GetCoreFile() const { return {}; } |
1512 | |
1513 | /// Before lldb detaches from a process, it warns the user that they are |
1514 | /// about to lose their debug session. In some cases, this warning doesn't |
1515 | /// need to be emitted -- for instance, with core file debugging where the |
1516 | /// user can reconstruct the "state" by simply re-running the debugger on |
1517 | /// the core file. |
1518 | /// |
1519 | /// \return |
1520 | /// Returns \b true if the user should be warned about detaching from |
1521 | /// this process. |
1522 | virtual bool WarnBeforeDetach() const { return true; } |
1523 | |
1524 | /// Read of memory from a process. |
1525 | /// |
1526 | /// This function will read memory from the current process's address space |
1527 | /// and remove any traps that may have been inserted into the memory. |
1528 | /// |
1529 | /// This function is not meant to be overridden by Process subclasses, the |
1530 | /// subclasses should implement Process::DoReadMemory (lldb::addr_t, size_t, |
1531 | /// void *). |
1532 | /// |
1533 | /// \param[in] vm_addr |
1534 | /// A virtual load address that indicates where to start reading |
1535 | /// memory from. |
1536 | /// |
1537 | /// \param[out] buf |
1538 | /// A byte buffer that is at least \a size bytes long that |
1539 | /// will receive the memory bytes. |
1540 | /// |
1541 | /// \param[in] size |
1542 | /// The number of bytes to read. |
1543 | /// |
1544 | /// \param[out] error |
1545 | /// An error that indicates the success or failure of this |
1546 | /// operation. If error indicates success (error.Success()), |
1547 | /// then the value returned can be trusted, otherwise zero |
1548 | /// will be returned. |
1549 | /// |
1550 | /// \return |
1551 | /// The number of bytes that were actually read into \a buf. If |
1552 | /// the returned number is greater than zero, yet less than \a |
1553 | /// size, then this function will get called again with \a |
1554 | /// vm_addr, \a buf, and \a size updated appropriately. Zero is |
1555 | /// returned in the case of an error. |
1556 | virtual size_t ReadMemory(lldb::addr_t vm_addr, void *buf, size_t size, |
1557 | Status &error); |
1558 | |
1559 | /// Read of memory from a process. |
1560 | /// |
1561 | /// This function has the same semantics of ReadMemory except that it |
1562 | /// bypasses caching. |
1563 | /// |
1564 | /// \param[in] vm_addr |
1565 | /// A virtual load address that indicates where to start reading |
1566 | /// memory from. |
1567 | /// |
1568 | /// \param[out] buf |
1569 | /// A byte buffer that is at least \a size bytes long that |
1570 | /// will receive the memory bytes. |
1571 | /// |
1572 | /// \param[in] size |
1573 | /// The number of bytes to read. |
1574 | /// |
1575 | /// \param[out] error |
1576 | /// An error that indicates the success or failure of this |
1577 | /// operation. If error indicates success (error.Success()), |
1578 | /// then the value returned can be trusted, otherwise zero |
1579 | /// will be returned. |
1580 | /// |
1581 | /// \return |
1582 | /// The number of bytes that were actually read into \a buf. If |
1583 | /// the returned number is greater than zero, yet less than \a |
1584 | /// size, then this function will get called again with \a |
1585 | /// vm_addr, \a buf, and \a size updated appropriately. Zero is |
1586 | /// returned in the case of an error. |
1587 | size_t ReadMemoryFromInferior(lldb::addr_t vm_addr, void *buf, size_t size, |
1588 | Status &error); |
1589 | |
1590 | /// Read a NULL terminated C string from memory |
1591 | /// |
1592 | /// This function will read a cache page at a time until the NULL |
1593 | /// C string terminator is found. It will stop reading if the NULL |
1594 | /// termination byte isn't found before reading \a cstr_max_len bytes, and |
1595 | /// the results are always guaranteed to be NULL terminated (at most |
1596 | /// cstr_max_len - 1 bytes will be read). |
1597 | size_t ReadCStringFromMemory(lldb::addr_t vm_addr, char *cstr, |
1598 | size_t cstr_max_len, Status &error); |
1599 | |
1600 | size_t ReadCStringFromMemory(lldb::addr_t vm_addr, std::string &out_str, |
1601 | Status &error); |
1602 | |
1603 | /// Reads an unsigned integer of the specified byte size from process |
1604 | /// memory. |
1605 | /// |
1606 | /// \param[in] load_addr |
1607 | /// A load address of the integer to read. |
1608 | /// |
1609 | /// \param[in] byte_size |
1610 | /// The size in byte of the integer to read. |
1611 | /// |
1612 | /// \param[in] fail_value |
1613 | /// The value to return if we fail to read an integer. |
1614 | /// |
1615 | /// \param[out] error |
1616 | /// An error that indicates the success or failure of this |
1617 | /// operation. If error indicates success (error.Success()), |
1618 | /// then the value returned can be trusted, otherwise zero |
1619 | /// will be returned. |
1620 | /// |
1621 | /// \return |
1622 | /// The unsigned integer that was read from the process memory |
1623 | /// space. If the integer was smaller than a uint64_t, any |
1624 | /// unused upper bytes will be zero filled. If the process |
1625 | /// byte order differs from the host byte order, the integer |
1626 | /// value will be appropriately byte swapped into host byte |
1627 | /// order. |
1628 | uint64_t ReadUnsignedIntegerFromMemory(lldb::addr_t load_addr, |
1629 | size_t byte_size, uint64_t fail_value, |
1630 | Status &error); |
1631 | |
1632 | int64_t ReadSignedIntegerFromMemory(lldb::addr_t load_addr, size_t byte_size, |
1633 | int64_t fail_value, Status &error); |
1634 | |
1635 | lldb::addr_t ReadPointerFromMemory(lldb::addr_t vm_addr, Status &error); |
1636 | |
1637 | bool WritePointerToMemory(lldb::addr_t vm_addr, lldb::addr_t ptr_value, |
1638 | Status &error); |
1639 | |
1640 | /// Actually do the writing of memory to a process. |
1641 | /// |
1642 | /// \param[in] vm_addr |
1643 | /// A virtual load address that indicates where to start writing |
1644 | /// memory to. |
1645 | /// |
1646 | /// \param[in] buf |
1647 | /// A byte buffer that is at least \a size bytes long that |
1648 | /// contains the data to write. |
1649 | /// |
1650 | /// \param[in] size |
1651 | /// The number of bytes to write. |
1652 | /// |
1653 | /// \param[out] error |
1654 | /// An error value in case the memory write fails. |
1655 | /// |
1656 | /// \return |
1657 | /// The number of bytes that were actually written. |
1658 | virtual size_t DoWriteMemory(lldb::addr_t vm_addr, const void *buf, |
1659 | size_t size, Status &error) { |
1660 | error.SetErrorStringWithFormatv( |
1661 | format: "error: {0} does not support writing to processes" , args: GetPluginName()); |
1662 | return 0; |
1663 | } |
1664 | |
1665 | /// Write all or part of a scalar value to memory. |
1666 | /// |
1667 | /// The value contained in \a scalar will be swapped to match the byte order |
1668 | /// of the process that is being debugged. If \a size is less than the size |
1669 | /// of scalar, the least significant \a size bytes from scalar will be |
1670 | /// written. If \a size is larger than the byte size of scalar, then the |
1671 | /// extra space will be padded with zeros and the scalar value will be |
1672 | /// placed in the least significant bytes in memory. |
1673 | /// |
1674 | /// \param[in] vm_addr |
1675 | /// A virtual load address that indicates where to start writing |
1676 | /// memory to. |
1677 | /// |
1678 | /// \param[in] scalar |
1679 | /// The scalar to write to the debugged process. |
1680 | /// |
1681 | /// \param[in] size |
1682 | /// This value can be smaller or larger than the scalar value |
1683 | /// itself. If \a size is smaller than the size of \a scalar, |
1684 | /// the least significant bytes in \a scalar will be used. If |
1685 | /// \a size is larger than the byte size of \a scalar, then |
1686 | /// the extra space will be padded with zeros. If \a size is |
1687 | /// set to UINT32_MAX, then the size of \a scalar will be used. |
1688 | /// |
1689 | /// \param[out] error |
1690 | /// An error value in case the memory write fails. |
1691 | /// |
1692 | /// \return |
1693 | /// The number of bytes that were actually written. |
1694 | size_t WriteScalarToMemory(lldb::addr_t vm_addr, const Scalar &scalar, |
1695 | size_t size, Status &error); |
1696 | |
1697 | size_t ReadScalarIntegerFromMemory(lldb::addr_t addr, uint32_t byte_size, |
1698 | bool is_signed, Scalar &scalar, |
1699 | Status &error); |
1700 | |
1701 | /// Write memory to a process. |
1702 | /// |
1703 | /// This function will write memory to the current process's address space |
1704 | /// and maintain any traps that might be present due to software |
1705 | /// breakpoints. |
1706 | /// |
1707 | /// This function is not meant to be overridden by Process subclasses, the |
1708 | /// subclasses should implement Process::DoWriteMemory (lldb::addr_t, |
1709 | /// size_t, void *). |
1710 | /// |
1711 | /// \param[in] vm_addr |
1712 | /// A virtual load address that indicates where to start writing |
1713 | /// memory to. |
1714 | /// |
1715 | /// \param[in] buf |
1716 | /// A byte buffer that is at least \a size bytes long that |
1717 | /// contains the data to write. |
1718 | /// |
1719 | /// \param[in] size |
1720 | /// The number of bytes to write. |
1721 | /// |
1722 | /// \return |
1723 | /// The number of bytes that were actually written. |
1724 | // TODO: change this to take an ArrayRef<uint8_t> |
1725 | size_t WriteMemory(lldb::addr_t vm_addr, const void *buf, size_t size, |
1726 | Status &error); |
1727 | |
1728 | /// Actually allocate memory in the process. |
1729 | /// |
1730 | /// This function will allocate memory in the process's address space. This |
1731 | /// can't rely on the generic function calling mechanism, since that |
1732 | /// requires this function. |
1733 | /// |
1734 | /// \param[in] size |
1735 | /// The size of the allocation requested. |
1736 | /// |
1737 | /// \return |
1738 | /// The address of the allocated buffer in the process, or |
1739 | /// LLDB_INVALID_ADDRESS if the allocation failed. |
1740 | |
1741 | virtual lldb::addr_t DoAllocateMemory(size_t size, uint32_t permissions, |
1742 | Status &error) { |
1743 | error.SetErrorStringWithFormatv( |
1744 | format: "error: {0} does not support allocating in the debug process" , |
1745 | args: GetPluginName()); |
1746 | return LLDB_INVALID_ADDRESS; |
1747 | } |
1748 | |
1749 | virtual Status WriteObjectFile(std::vector<ObjectFile::LoadableData> entries); |
1750 | |
1751 | /// The public interface to allocating memory in the process. |
1752 | /// |
1753 | /// This function will allocate memory in the process's address space. This |
1754 | /// can't rely on the generic function calling mechanism, since that |
1755 | /// requires this function. |
1756 | /// |
1757 | /// \param[in] size |
1758 | /// The size of the allocation requested. |
1759 | /// |
1760 | /// \param[in] permissions |
1761 | /// Or together any of the lldb::Permissions bits. The permissions on |
1762 | /// a given memory allocation can't be changed after allocation. Note |
1763 | /// that a block that isn't set writable can still be written on from |
1764 | /// lldb, |
1765 | /// just not by the process itself. |
1766 | /// |
1767 | /// \param[in,out] error |
1768 | /// An error object to fill in if things go wrong. |
1769 | /// \return |
1770 | /// The address of the allocated buffer in the process, or |
1771 | /// LLDB_INVALID_ADDRESS if the allocation failed. |
1772 | lldb::addr_t AllocateMemory(size_t size, uint32_t permissions, Status &error); |
1773 | |
1774 | /// The public interface to allocating memory in the process, this also |
1775 | /// clears the allocated memory. |
1776 | /// |
1777 | /// This function will allocate memory in the process's address space. This |
1778 | /// can't rely on the generic function calling mechanism, since that |
1779 | /// requires this function. |
1780 | /// |
1781 | /// \param[in] size |
1782 | /// The size of the allocation requested. |
1783 | /// |
1784 | /// \param[in] permissions |
1785 | /// Or together any of the lldb::Permissions bits. The permissions on |
1786 | /// a given memory allocation can't be changed after allocation. Note |
1787 | /// that a block that isn't set writable can still be written on from |
1788 | /// lldb, |
1789 | /// just not by the process itself. |
1790 | /// |
1791 | /// \param[in,out] error |
1792 | /// An error object to fill in if things go wrong. |
1793 | /// |
1794 | /// \return |
1795 | /// The address of the allocated buffer in the process, or |
1796 | /// LLDB_INVALID_ADDRESS if the allocation failed. |
1797 | |
1798 | lldb::addr_t CallocateMemory(size_t size, uint32_t permissions, |
1799 | Status &error); |
1800 | |
1801 | /// If this architecture and process supports memory tagging, return a tag |
1802 | /// manager that can be used to maniupulate those memory tags. |
1803 | /// |
1804 | /// \return |
1805 | /// Either a valid pointer to a tag manager or an error describing why one |
1806 | /// could not be provided. |
1807 | llvm::Expected<const MemoryTagManager *> GetMemoryTagManager(); |
1808 | |
1809 | /// Read memory tags for the range addr to addr+len. It is assumed |
1810 | /// that this range has already been granule aligned. |
1811 | /// (see MemoryTagManager::MakeTaggedRange) |
1812 | /// |
1813 | /// This calls DoReadMemoryTags to do the target specific operations. |
1814 | /// |
1815 | /// \param[in] addr |
1816 | /// Start of memory range to read tags for. |
1817 | /// |
1818 | /// \param[in] len |
1819 | /// Length of memory range to read tags for (in bytes). |
1820 | /// |
1821 | /// \return |
1822 | /// If this architecture or process does not support memory tagging, |
1823 | /// an error saying so. |
1824 | /// If it does, either the memory tags or an error describing a |
1825 | /// failure to read or unpack them. |
1826 | virtual llvm::Expected<std::vector<lldb::addr_t>> |
1827 | ReadMemoryTags(lldb::addr_t addr, size_t len); |
1828 | |
1829 | /// Write memory tags for a range of memory. |
1830 | /// (calls DoWriteMemoryTags to do the target specific work) |
1831 | /// |
1832 | /// \param[in] addr |
1833 | /// The address to start writing tags from. It is assumed that this |
1834 | /// address is granule aligned. |
1835 | /// |
1836 | /// \param[in] len |
1837 | /// The size of the range to write tags for. It is assumed that this |
1838 | /// is some multiple of the granule size. This len can be different |
1839 | /// from (number of tags * granule size) in the case where you want |
1840 | /// lldb-server to repeat tags across the range. |
1841 | /// |
1842 | /// \param[in] tags |
1843 | /// Allocation tags to be written. Since lldb-server can repeat tags for a |
1844 | /// range, the number of tags doesn't have to match the number of granules |
1845 | /// in the range. (though most of the time it will) |
1846 | /// |
1847 | /// \return |
1848 | /// A Status telling you if the write succeeded or not. |
1849 | Status WriteMemoryTags(lldb::addr_t addr, size_t len, |
1850 | const std::vector<lldb::addr_t> &tags); |
1851 | |
1852 | /// Resolve dynamically loaded indirect functions. |
1853 | /// |
1854 | /// \param[in] address |
1855 | /// The load address of the indirect function to resolve. |
1856 | /// |
1857 | /// \param[out] error |
1858 | /// An error value in case the resolve fails. |
1859 | /// |
1860 | /// \return |
1861 | /// The address of the resolved function. |
1862 | /// LLDB_INVALID_ADDRESS if the resolution failed. |
1863 | virtual lldb::addr_t ResolveIndirectFunction(const Address *address, |
1864 | Status &error); |
1865 | |
1866 | /// Locate the memory region that contains load_addr. |
1867 | /// |
1868 | /// If load_addr is within the address space the process has mapped |
1869 | /// range_info will be filled in with the start and end of that range as |
1870 | /// well as the permissions for that range and range_info. GetMapped will |
1871 | /// return true. |
1872 | /// |
1873 | /// If load_addr is outside any mapped region then range_info will have its |
1874 | /// start address set to load_addr and the end of the range will indicate |
1875 | /// the start of the next mapped range or be set to LLDB_INVALID_ADDRESS if |
1876 | /// there are no valid mapped ranges between load_addr and the end of the |
1877 | /// process address space. |
1878 | /// |
1879 | /// GetMemoryRegionInfo calls DoGetMemoryRegionInfo. Override that function in |
1880 | /// process subclasses. |
1881 | /// |
1882 | /// \param[in] load_addr |
1883 | /// The load address to query the range_info for. May include non |
1884 | /// address bits, these will be removed by the ABI plugin if there is |
1885 | /// one. |
1886 | /// |
1887 | /// \param[out] range_info |
1888 | /// An range_info value containing the details of the range. |
1889 | /// |
1890 | /// \return |
1891 | /// An error value. |
1892 | Status GetMemoryRegionInfo(lldb::addr_t load_addr, |
1893 | MemoryRegionInfo &range_info); |
1894 | |
1895 | /// Obtain all the mapped memory regions within this process. |
1896 | /// |
1897 | /// \param[out] region_list |
1898 | /// A vector to contain MemoryRegionInfo objects for all mapped |
1899 | /// ranges. |
1900 | /// |
1901 | /// \return |
1902 | /// An error value. |
1903 | virtual Status |
1904 | GetMemoryRegions(lldb_private::MemoryRegionInfos ®ion_list); |
1905 | |
1906 | /// Get the number of watchpoints supported by this target. |
1907 | /// |
1908 | /// We may be able to determine the number of watchpoints available |
1909 | /// on this target; retrieve this value if possible. |
1910 | /// |
1911 | /// This number may be less than the number of watchpoints a user |
1912 | /// can specify. This is because a single user watchpoint may require |
1913 | /// multiple watchpoint slots to implement. Due to the size |
1914 | /// and/or alignment of objects. |
1915 | /// |
1916 | /// \return |
1917 | /// Returns the number of watchpoints, if available. |
1918 | virtual std::optional<uint32_t> GetWatchpointSlotCount() { |
1919 | return std::nullopt; |
1920 | } |
1921 | |
1922 | /// Whether lldb will be notified about watchpoints after |
1923 | /// the instruction has completed executing, or if the |
1924 | /// instruction is rolled back and it is notified before it |
1925 | /// executes. |
1926 | /// The default behavior is "exceptions received after instruction |
1927 | /// has executed", except for certain CPU architectures. |
1928 | /// Process subclasses may override this if they have additional |
1929 | /// information. |
1930 | /// |
1931 | /// \return |
1932 | /// Returns true for targets where lldb is notified after |
1933 | /// the instruction has completed executing. |
1934 | bool GetWatchpointReportedAfter(); |
1935 | |
1936 | lldb::ModuleSP ReadModuleFromMemory(const FileSpec &file_spec, |
1937 | lldb::addr_t , |
1938 | size_t size_to_read = 512); |
1939 | |
1940 | /// Attempt to get the attributes for a region of memory in the process. |
1941 | /// |
1942 | /// It may be possible for the remote debug server to inspect attributes for |
1943 | /// a region of memory in the process, such as whether there is a valid page |
1944 | /// of memory at a given address or whether that page is |
1945 | /// readable/writable/executable by the process. |
1946 | /// |
1947 | /// \param[in] load_addr |
1948 | /// The address of interest in the process. |
1949 | /// |
1950 | /// \param[out] permissions |
1951 | /// If this call returns successfully, this bitmask will have |
1952 | /// its Permissions bits set to indicate whether the region is |
1953 | /// readable/writable/executable. If this call fails, the |
1954 | /// bitmask values are undefined. |
1955 | /// |
1956 | /// \return |
1957 | /// Returns true if it was able to determine the attributes of the |
1958 | /// memory region. False if not. |
1959 | virtual bool GetLoadAddressPermissions(lldb::addr_t load_addr, |
1960 | uint32_t &permissions); |
1961 | |
1962 | /// Determines whether executing JIT-compiled code in this process is |
1963 | /// possible. |
1964 | /// |
1965 | /// \return |
1966 | /// True if execution of JIT code is possible; false otherwise. |
1967 | bool CanJIT(); |
1968 | |
1969 | /// Sets whether executing JIT-compiled code in this process is possible. |
1970 | /// |
1971 | /// \param[in] can_jit |
1972 | /// True if execution of JIT code is possible; false otherwise. |
1973 | void SetCanJIT(bool can_jit); |
1974 | |
1975 | /// Determines whether executing function calls using the interpreter is |
1976 | /// possible for this process. |
1977 | /// |
1978 | /// \return |
1979 | /// True if possible; false otherwise. |
1980 | bool CanInterpretFunctionCalls() { return m_can_interpret_function_calls; } |
1981 | |
1982 | /// Sets whether executing function calls using the interpreter is possible |
1983 | /// for this process. |
1984 | /// |
1985 | /// \param[in] can_interpret_function_calls |
1986 | /// True if possible; false otherwise. |
1987 | void SetCanInterpretFunctionCalls(bool can_interpret_function_calls) { |
1988 | m_can_interpret_function_calls = can_interpret_function_calls; |
1989 | } |
1990 | |
1991 | /// Sets whether executing code in this process is possible. This could be |
1992 | /// either through JIT or interpreting. |
1993 | /// |
1994 | /// \param[in] can_run_code |
1995 | /// True if execution of code is possible; false otherwise. |
1996 | void SetCanRunCode(bool can_run_code); |
1997 | |
1998 | /// Actually deallocate memory in the process. |
1999 | /// |
2000 | /// This function will deallocate memory in the process's address space that |
2001 | /// was allocated with AllocateMemory. |
2002 | /// |
2003 | /// \param[in] ptr |
2004 | /// A return value from AllocateMemory, pointing to the memory you |
2005 | /// want to deallocate. |
2006 | /// |
2007 | /// \return |
2008 | /// \b true if the memory was deallocated, \b false otherwise. |
2009 | virtual Status DoDeallocateMemory(lldb::addr_t ptr) { |
2010 | Status error; |
2011 | error.SetErrorStringWithFormatv( |
2012 | format: "error: {0} does not support deallocating in the debug process" , |
2013 | args: GetPluginName()); |
2014 | return error; |
2015 | } |
2016 | |
2017 | /// The public interface to deallocating memory in the process. |
2018 | /// |
2019 | /// This function will deallocate memory in the process's address space that |
2020 | /// was allocated with AllocateMemory. |
2021 | /// |
2022 | /// \param[in] ptr |
2023 | /// A return value from AllocateMemory, pointing to the memory you |
2024 | /// want to deallocate. |
2025 | /// |
2026 | /// \return |
2027 | /// \b true if the memory was deallocated, \b false otherwise. |
2028 | Status DeallocateMemory(lldb::addr_t ptr); |
2029 | |
2030 | /// Get any available STDOUT. |
2031 | /// |
2032 | /// Calling this method is a valid operation only if all of the following |
2033 | /// conditions are true: 1) The process was launched, and not attached to. |
2034 | /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The |
2035 | /// process was launched without supplying a valid file path |
2036 | /// for STDOUT. |
2037 | /// |
2038 | /// Note that the implementation will probably need to start a read thread |
2039 | /// in the background to make sure that the pipe is drained and the STDOUT |
2040 | /// buffered appropriately, to prevent the process from deadlocking trying |
2041 | /// to write to a full buffer. |
2042 | /// |
2043 | /// Events will be queued indicating that there is STDOUT available that can |
2044 | /// be retrieved using this function. |
2045 | /// |
2046 | /// \param[out] buf |
2047 | /// A buffer that will receive any STDOUT bytes that are |
2048 | /// currently available. |
2049 | /// |
2050 | /// \param[in] buf_size |
2051 | /// The size in bytes for the buffer \a buf. |
2052 | /// |
2053 | /// \return |
2054 | /// The number of bytes written into \a buf. If this value is |
2055 | /// equal to \a buf_size, another call to this function should |
2056 | /// be made to retrieve more STDOUT data. |
2057 | virtual size_t GetSTDOUT(char *buf, size_t buf_size, Status &error); |
2058 | |
2059 | /// Get any available STDERR. |
2060 | /// |
2061 | /// Calling this method is a valid operation only if all of the following |
2062 | /// conditions are true: 1) The process was launched, and not attached to. |
2063 | /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The |
2064 | /// process was launched without supplying a valid file path |
2065 | /// for STDERR. |
2066 | /// |
2067 | /// Note that the implementation will probably need to start a read thread |
2068 | /// in the background to make sure that the pipe is drained and the STDERR |
2069 | /// buffered appropriately, to prevent the process from deadlocking trying |
2070 | /// to write to a full buffer. |
2071 | /// |
2072 | /// Events will be queued indicating that there is STDERR available that can |
2073 | /// be retrieved using this function. |
2074 | /// |
2075 | /// \param[in] buf |
2076 | /// A buffer that will receive any STDERR bytes that are |
2077 | /// currently available. |
2078 | /// |
2079 | /// \param[out] buf_size |
2080 | /// The size in bytes for the buffer \a buf. |
2081 | /// |
2082 | /// \return |
2083 | /// The number of bytes written into \a buf. If this value is |
2084 | /// equal to \a buf_size, another call to this function should |
2085 | /// be made to retrieve more STDERR data. |
2086 | virtual size_t GetSTDERR(char *buf, size_t buf_size, Status &error); |
2087 | |
2088 | /// Puts data into this process's STDIN. |
2089 | /// |
2090 | /// Calling this method is a valid operation only if all of the following |
2091 | /// conditions are true: 1) The process was launched, and not attached to. |
2092 | /// 2) The process was not launched with eLaunchFlagDisableSTDIO. 3) The |
2093 | /// process was launched without supplying a valid file path |
2094 | /// for STDIN. |
2095 | /// |
2096 | /// \param[in] buf |
2097 | /// A buffer that contains the data to write to the process's STDIN. |
2098 | /// |
2099 | /// \param[in] buf_size |
2100 | /// The size in bytes for the buffer \a buf. |
2101 | /// |
2102 | /// \return |
2103 | /// The number of bytes written into \a buf. If this value is |
2104 | /// less than \a buf_size, another call to this function should |
2105 | /// be made to write the rest of the data. |
2106 | virtual size_t PutSTDIN(const char *buf, size_t buf_size, Status &error) { |
2107 | error.SetErrorString("stdin unsupported" ); |
2108 | return 0; |
2109 | } |
2110 | |
2111 | /// Get any available profile data. |
2112 | /// |
2113 | /// \param[out] buf |
2114 | /// A buffer that will receive any profile data bytes that are |
2115 | /// currently available. |
2116 | /// |
2117 | /// \param[out] buf_size |
2118 | /// The size in bytes for the buffer \a buf. |
2119 | /// |
2120 | /// \return |
2121 | /// The number of bytes written into \a buf. If this value is |
2122 | /// equal to \a buf_size, another call to this function should |
2123 | /// be made to retrieve more profile data. |
2124 | virtual size_t GetAsyncProfileData(char *buf, size_t buf_size, Status &error); |
2125 | |
2126 | // Process Breakpoints |
2127 | size_t GetSoftwareBreakpointTrapOpcode(BreakpointSite *bp_site); |
2128 | |
2129 | virtual Status EnableBreakpointSite(BreakpointSite *bp_site) { |
2130 | Status error; |
2131 | error.SetErrorStringWithFormatv( |
2132 | format: "error: {0} does not support enabling breakpoints" , args: GetPluginName()); |
2133 | return error; |
2134 | } |
2135 | |
2136 | virtual Status DisableBreakpointSite(BreakpointSite *bp_site) { |
2137 | Status error; |
2138 | error.SetErrorStringWithFormatv( |
2139 | format: "error: {0} does not support disabling breakpoints" , args: GetPluginName()); |
2140 | return error; |
2141 | } |
2142 | |
2143 | // This is implemented completely using the lldb::Process API. Subclasses |
2144 | // don't need to implement this function unless the standard flow of read |
2145 | // existing opcode, write breakpoint opcode, verify breakpoint opcode doesn't |
2146 | // work for a specific process plug-in. |
2147 | virtual Status EnableSoftwareBreakpoint(BreakpointSite *bp_site); |
2148 | |
2149 | // This is implemented completely using the lldb::Process API. Subclasses |
2150 | // don't need to implement this function unless the standard flow of |
2151 | // restoring original opcode in memory and verifying the restored opcode |
2152 | // doesn't work for a specific process plug-in. |
2153 | virtual Status DisableSoftwareBreakpoint(BreakpointSite *bp_site); |
2154 | |
2155 | StopPointSiteList<lldb_private::BreakpointSite> &GetBreakpointSiteList(); |
2156 | |
2157 | const StopPointSiteList<lldb_private::BreakpointSite> & |
2158 | GetBreakpointSiteList() const; |
2159 | |
2160 | void DisableAllBreakpointSites(); |
2161 | |
2162 | Status ClearBreakpointSiteByID(lldb::user_id_t break_id); |
2163 | |
2164 | lldb::break_id_t CreateBreakpointSite(const lldb::BreakpointLocationSP &owner, |
2165 | bool use_hardware); |
2166 | |
2167 | Status DisableBreakpointSiteByID(lldb::user_id_t break_id); |
2168 | |
2169 | Status EnableBreakpointSiteByID(lldb::user_id_t break_id); |
2170 | |
2171 | // BreakpointLocations use RemoveConstituentFromBreakpointSite to remove |
2172 | // themselves from the constituent's list of this breakpoint sites. |
2173 | void RemoveConstituentFromBreakpointSite(lldb::user_id_t site_id, |
2174 | lldb::user_id_t constituent_id, |
2175 | lldb::BreakpointSiteSP &bp_site_sp); |
2176 | |
2177 | // Process Watchpoints (optional) |
2178 | virtual Status EnableWatchpoint(lldb::WatchpointSP wp_sp, bool notify = true); |
2179 | |
2180 | virtual Status DisableWatchpoint(lldb::WatchpointSP wp_sp, |
2181 | bool notify = true); |
2182 | |
2183 | // Thread Queries |
2184 | |
2185 | /// Update the thread list. |
2186 | /// |
2187 | /// This method performs some general clean up before invoking |
2188 | /// \a DoUpdateThreadList, which should be implemented by each |
2189 | /// process plugin. |
2190 | /// |
2191 | /// \return |
2192 | /// \b true if the new thread list could be generated, \b false otherwise. |
2193 | bool UpdateThreadList(ThreadList &old_thread_list, |
2194 | ThreadList &new_thread_list); |
2195 | |
2196 | void UpdateThreadListIfNeeded(); |
2197 | |
2198 | ThreadList &GetThreadList() { return m_thread_list; } |
2199 | |
2200 | StopPointSiteList<lldb_private::WatchpointResource> & |
2201 | GetWatchpointResourceList() { |
2202 | return m_watchpoint_resource_list; |
2203 | } |
2204 | |
2205 | // When ExtendedBacktraces are requested, the HistoryThreads that are created |
2206 | // need an owner -- they're saved here in the Process. The threads in this |
2207 | // list are not iterated over - driver programs need to request the extended |
2208 | // backtrace calls starting from a root concrete thread one by one. |
2209 | ThreadList &GetExtendedThreadList() { return m_extended_thread_list; } |
2210 | |
2211 | ThreadList::ThreadIterable Threads() { return m_thread_list.Threads(); } |
2212 | |
2213 | uint32_t GetNextThreadIndexID(uint64_t thread_id); |
2214 | |
2215 | lldb::ThreadSP CreateOSPluginThread(lldb::tid_t tid, lldb::addr_t context); |
2216 | |
2217 | // Returns true if an index id has been assigned to a thread. |
2218 | bool HasAssignedIndexIDToThread(uint64_t sb_thread_id); |
2219 | |
2220 | // Given a thread_id, it will assign a more reasonable index id for display |
2221 | // to the user. If the thread_id has previously been assigned, the same index |
2222 | // id will be used. |
2223 | uint32_t AssignIndexIDToThread(uint64_t thread_id); |
2224 | |
2225 | // Queue Queries |
2226 | |
2227 | virtual void UpdateQueueListIfNeeded(); |
2228 | |
2229 | QueueList &GetQueueList() { |
2230 | UpdateQueueListIfNeeded(); |
2231 | return m_queue_list; |
2232 | } |
2233 | |
2234 | QueueList::QueueIterable Queues() { |
2235 | UpdateQueueListIfNeeded(); |
2236 | return m_queue_list.Queues(); |
2237 | } |
2238 | |
2239 | // Event Handling |
2240 | lldb::StateType GetNextEvent(lldb::EventSP &event_sp); |
2241 | |
2242 | // Returns the process state when it is stopped. If specified, event_sp_ptr |
2243 | // is set to the event which triggered the stop. If wait_always = false, and |
2244 | // the process is already stopped, this function returns immediately. If the |
2245 | // process is hijacked and use_run_lock is true (the default), then this |
2246 | // function releases the run lock after the stop. Setting use_run_lock to |
2247 | // false will avoid this behavior. |
2248 | // If we are waiting to stop that will return control to the user, |
2249 | // then we also want to run SelectMostRelevantFrame, which is controlled |
2250 | // by "select_most_relevant". |
2251 | lldb::StateType |
2252 | WaitForProcessToStop(const Timeout<std::micro> &timeout, |
2253 | lldb::EventSP *event_sp_ptr = nullptr, |
2254 | bool wait_always = true, |
2255 | lldb::ListenerSP hijack_listener = lldb::ListenerSP(), |
2256 | Stream *stream = nullptr, bool use_run_lock = true, |
2257 | SelectMostRelevant select_most_relevant = |
2258 | DoNoSelectMostRelevantFrame); |
2259 | |
2260 | uint32_t GetIOHandlerID() const { return m_iohandler_sync.GetValue(); } |
2261 | |
2262 | /// Waits for the process state to be running within a given msec timeout. |
2263 | /// |
2264 | /// The main purpose of this is to implement an interlock waiting for |
2265 | /// HandlePrivateEvent to push an IOHandler. |
2266 | /// |
2267 | /// \param[in] timeout |
2268 | /// The maximum time length to wait for the process to transition to the |
2269 | /// eStateRunning state. |
2270 | void SyncIOHandler(uint32_t iohandler_id, const Timeout<std::micro> &timeout); |
2271 | |
2272 | lldb::StateType GetStateChangedEvents( |
2273 | lldb::EventSP &event_sp, const Timeout<std::micro> &timeout, |
2274 | lldb::ListenerSP |
2275 | hijack_listener); // Pass an empty ListenerSP to use builtin listener |
2276 | |
2277 | /// Centralize the code that handles and prints descriptions for process |
2278 | /// state changes. |
2279 | /// |
2280 | /// \param[in] event_sp |
2281 | /// The process state changed event |
2282 | /// |
2283 | /// \param[in] stream |
2284 | /// The output stream to get the state change description |
2285 | /// |
2286 | /// \param[in,out] pop_process_io_handler |
2287 | /// If this value comes in set to \b true, then pop the Process IOHandler |
2288 | /// if needed. |
2289 | /// Else this variable will be set to \b true or \b false to indicate if |
2290 | /// the process |
2291 | /// needs to have its process IOHandler popped. |
2292 | /// |
2293 | /// \return |
2294 | /// \b true if the event describes a process state changed event, \b false |
2295 | /// otherwise. |
2296 | static bool |
2297 | HandleProcessStateChangedEvent(const lldb::EventSP &event_sp, Stream *stream, |
2298 | SelectMostRelevant select_most_relevant, |
2299 | bool &pop_process_io_handler); |
2300 | |
2301 | Event *PeekAtStateChangedEvents(); |
2302 | |
2303 | class ProcessEventHijacker { |
2304 | public: |
2305 | ProcessEventHijacker(Process &process, lldb::ListenerSP listener_sp) |
2306 | : m_process(process) { |
2307 | m_process.HijackProcessEvents(listener_sp: std::move(listener_sp)); |
2308 | } |
2309 | |
2310 | ~ProcessEventHijacker() { m_process.RestoreProcessEvents(); } |
2311 | |
2312 | private: |
2313 | Process &m_process; |
2314 | }; |
2315 | |
2316 | friend class ProcessEventHijacker; |
2317 | friend class ProcessProperties; |
2318 | /// If you need to ensure that you and only you will hear about some public |
2319 | /// event, then make a new listener, set to listen to process events, and |
2320 | /// then call this with that listener. Then you will have to wait on that |
2321 | /// listener explicitly for events (rather than using the GetNextEvent & |
2322 | /// WaitFor* calls above. Be sure to call RestoreProcessEvents when you are |
2323 | /// done. |
2324 | /// |
2325 | /// \param[in] listener_sp |
2326 | /// This is the new listener to whom all process events will be delivered. |
2327 | /// |
2328 | /// \return |
2329 | /// Returns \b true if the new listener could be installed, |
2330 | /// \b false otherwise. |
2331 | bool HijackProcessEvents(lldb::ListenerSP listener_sp); |
2332 | |
2333 | /// Restores the process event broadcasting to its normal state. |
2334 | /// |
2335 | void RestoreProcessEvents(); |
2336 | |
2337 | bool StateChangedIsHijackedForSynchronousResume(); |
2338 | |
2339 | bool StateChangedIsExternallyHijacked(); |
2340 | |
2341 | const lldb::ABISP &GetABI(); |
2342 | |
2343 | OperatingSystem *GetOperatingSystem() { return m_os_up.get(); } |
2344 | |
2345 | std::vector<LanguageRuntime *> GetLanguageRuntimes(); |
2346 | |
2347 | LanguageRuntime *GetLanguageRuntime(lldb::LanguageType language); |
2348 | |
2349 | bool IsPossibleDynamicValue(ValueObject &in_value); |
2350 | |
2351 | bool IsRunning() const; |
2352 | |
2353 | DynamicCheckerFunctions *GetDynamicCheckers() { |
2354 | return m_dynamic_checkers_up.get(); |
2355 | } |
2356 | |
2357 | void SetDynamicCheckers(DynamicCheckerFunctions *dynamic_checkers); |
2358 | |
2359 | /// Prune ThreadPlanStacks for unreported threads. |
2360 | /// |
2361 | /// \param[in] tid |
2362 | /// The tid whose Plan Stack we are seeking to prune. |
2363 | /// |
2364 | /// \return |
2365 | /// \b true if the TID is found or \b false if not. |
2366 | bool PruneThreadPlansForTID(lldb::tid_t tid); |
2367 | |
2368 | /// Prune ThreadPlanStacks for all unreported threads. |
2369 | void PruneThreadPlans(); |
2370 | |
2371 | /// Find the thread plan stack associated with thread with \a tid. |
2372 | /// |
2373 | /// \param[in] tid |
2374 | /// The tid whose Plan Stack we are seeking. |
2375 | /// |
2376 | /// \return |
2377 | /// Returns a ThreadPlan if the TID is found or nullptr if not. |
2378 | ThreadPlanStack *FindThreadPlans(lldb::tid_t tid); |
2379 | |
2380 | /// Dump the thread plans associated with thread with \a tid. |
2381 | /// |
2382 | /// \param[in,out] strm |
2383 | /// The stream to which to dump the output |
2384 | /// |
2385 | /// \param[in] tid |
2386 | /// The tid whose Plan Stack we are dumping |
2387 | /// |
2388 | /// \param[in] desc_level |
2389 | /// How much detail to dump |
2390 | /// |
2391 | /// \param[in] internal |
2392 | /// If \b true dump all plans, if false only user initiated plans |
2393 | /// |
2394 | /// \param[in] condense_trivial |
2395 | /// If true, only dump a header if the plan stack is just the base plan. |
2396 | /// |
2397 | /// \param[in] skip_unreported_plans |
2398 | /// If true, only dump a plan if it is currently backed by an |
2399 | /// lldb_private::Thread *. |
2400 | /// |
2401 | /// \return |
2402 | /// Returns \b true if TID was found, \b false otherwise |
2403 | bool DumpThreadPlansForTID(Stream &strm, lldb::tid_t tid, |
2404 | lldb::DescriptionLevel desc_level, bool internal, |
2405 | bool condense_trivial, bool skip_unreported_plans); |
2406 | |
2407 | /// Dump all the thread plans for this process. |
2408 | /// |
2409 | /// \param[in,out] strm |
2410 | /// The stream to which to dump the output |
2411 | /// |
2412 | /// \param[in] desc_level |
2413 | /// How much detail to dump |
2414 | /// |
2415 | /// \param[in] internal |
2416 | /// If \b true dump all plans, if false only user initiated plans |
2417 | /// |
2418 | /// \param[in] condense_trivial |
2419 | /// If true, only dump a header if the plan stack is just the base plan. |
2420 | /// |
2421 | /// \param[in] skip_unreported_plans |
2422 | /// If true, skip printing all thread plan stacks that don't currently |
2423 | /// have a backing lldb_private::Thread *. |
2424 | void DumpThreadPlans(Stream &strm, lldb::DescriptionLevel desc_level, |
2425 | bool internal, bool condense_trivial, |
2426 | bool skip_unreported_plans); |
2427 | |
2428 | /// Call this to set the lldb in the mode where it breaks on new thread |
2429 | /// creations, and then auto-restarts. This is useful when you are trying |
2430 | /// to run only one thread, but either that thread or the kernel is creating |
2431 | /// new threads in the process. If you stop when the thread is created, you |
2432 | /// can immediately suspend it, and keep executing only the one thread you |
2433 | /// intend. |
2434 | /// |
2435 | /// \return |
2436 | /// Returns \b true if we were able to start up the notification |
2437 | /// \b false otherwise. |
2438 | virtual bool StartNoticingNewThreads() { return true; } |
2439 | |
2440 | /// Call this to turn off the stop & notice new threads mode. |
2441 | /// |
2442 | /// \return |
2443 | /// Returns \b true if we were able to start up the notification |
2444 | /// \b false otherwise. |
2445 | virtual bool StopNoticingNewThreads() { return true; } |
2446 | |
2447 | void SetRunningUserExpression(bool on); |
2448 | void SetRunningUtilityFunction(bool on); |
2449 | |
2450 | // lldb::ExecutionContextScope pure virtual functions |
2451 | lldb::TargetSP CalculateTarget() override; |
2452 | |
2453 | lldb::ProcessSP CalculateProcess() override { return shared_from_this(); } |
2454 | |
2455 | lldb::ThreadSP CalculateThread() override { return lldb::ThreadSP(); } |
2456 | |
2457 | lldb::StackFrameSP CalculateStackFrame() override { |
2458 | return lldb::StackFrameSP(); |
2459 | } |
2460 | |
2461 | void CalculateExecutionContext(ExecutionContext &exe_ctx) override; |
2462 | |
2463 | void SetSTDIOFileDescriptor(int file_descriptor); |
2464 | |
2465 | // Add a permanent region of memory that should never be read or written to. |
2466 | // This can be used to ensure that memory reads or writes to certain areas of |
2467 | // memory never end up being sent to the DoReadMemory or DoWriteMemory |
2468 | // functions which can improve performance. |
2469 | void AddInvalidMemoryRegion(const LoadRange ®ion); |
2470 | |
2471 | // Remove a permanent region of memory that should never be read or written |
2472 | // to that was previously added with AddInvalidMemoryRegion. |
2473 | bool RemoveInvalidMemoryRange(const LoadRange ®ion); |
2474 | |
2475 | // If the setup code of a thread plan needs to do work that might involve |
2476 | // calling a function in the target, it should not do that work directly in |
2477 | // one of the thread plan functions (DidPush/WillResume) because such work |
2478 | // needs to be handled carefully. Instead, put that work in a |
2479 | // PreResumeAction callback, and register it with the process. It will get |
2480 | // done before the actual "DoResume" gets called. |
2481 | |
2482 | typedef bool(PreResumeActionCallback)(void *); |
2483 | |
2484 | void AddPreResumeAction(PreResumeActionCallback callback, void *baton); |
2485 | |
2486 | bool RunPreResumeActions(); |
2487 | |
2488 | void ClearPreResumeActions(); |
2489 | |
2490 | void ClearPreResumeAction(PreResumeActionCallback callback, void *baton); |
2491 | |
2492 | ProcessRunLock &GetRunLock(); |
2493 | |
2494 | bool CurrentThreadIsPrivateStateThread(); |
2495 | |
2496 | virtual Status SendEventData(const char *data) { |
2497 | Status return_error("Sending an event is not supported for this process." ); |
2498 | return return_error; |
2499 | } |
2500 | |
2501 | lldb::ThreadCollectionSP GetHistoryThreads(lldb::addr_t addr); |
2502 | |
2503 | lldb::InstrumentationRuntimeSP |
2504 | GetInstrumentationRuntime(lldb::InstrumentationRuntimeType type); |
2505 | |
2506 | /// Try to fetch the module specification for a module with the given file |
2507 | /// name and architecture. Process sub-classes have to override this method |
2508 | /// if they support platforms where the Platform object can't get the module |
2509 | /// spec for all module. |
2510 | /// |
2511 | /// \param[in] module_file_spec |
2512 | /// The file name of the module to get specification for. |
2513 | /// |
2514 | /// \param[in] arch |
2515 | /// The architecture of the module to get specification for. |
2516 | /// |
2517 | /// \param[out] module_spec |
2518 | /// The fetched module specification if the return value is |
2519 | /// \b true, unchanged otherwise. |
2520 | /// |
2521 | /// \return |
2522 | /// Returns \b true if the module spec fetched successfully, |
2523 | /// \b false otherwise. |
2524 | virtual bool GetModuleSpec(const FileSpec &module_file_spec, |
2525 | const ArchSpec &arch, ModuleSpec &module_spec); |
2526 | |
2527 | virtual void PrefetchModuleSpecs(llvm::ArrayRef<FileSpec> module_file_specs, |
2528 | const llvm::Triple &triple) {} |
2529 | |
2530 | /// Try to find the load address of a file. |
2531 | /// The load address is defined as the address of the first memory region |
2532 | /// what contains data mapped from the specified file. |
2533 | /// |
2534 | /// \param[in] file |
2535 | /// The name of the file whose load address we are looking for |
2536 | /// |
2537 | /// \param[out] is_loaded |
2538 | /// \b True if the file is loaded into the memory and false |
2539 | /// otherwise. |
2540 | /// |
2541 | /// \param[out] load_addr |
2542 | /// The load address of the file if it is loaded into the |
2543 | /// processes address space, LLDB_INVALID_ADDRESS otherwise. |
2544 | virtual Status GetFileLoadAddress(const FileSpec &file, bool &is_loaded, |
2545 | lldb::addr_t &load_addr) { |
2546 | return Status("Not supported" ); |
2547 | } |
2548 | |
2549 | /// Fetch process defined metadata. |
2550 | /// |
2551 | /// \return |
2552 | /// A StructuredDataSP object which, if non-empty, will contain the |
2553 | /// information related to the process. |
2554 | virtual StructuredData::DictionarySP GetMetadata() { return nullptr; } |
2555 | |
2556 | size_t AddImageToken(lldb::addr_t image_ptr); |
2557 | |
2558 | lldb::addr_t GetImagePtrFromToken(size_t token) const; |
2559 | |
2560 | void ResetImageToken(size_t token); |
2561 | |
2562 | /// Find the next branch instruction to set a breakpoint on |
2563 | /// |
2564 | /// When instruction stepping through a source line, instead of stepping |
2565 | /// through each instruction, we can put a breakpoint on the next branch |
2566 | /// instruction (within the range of instructions we are stepping through) |
2567 | /// and continue the process to there, yielding significant performance |
2568 | /// benefits over instruction stepping. |
2569 | /// |
2570 | /// \param[in] default_stop_addr |
2571 | /// The address of the instruction where lldb would put a |
2572 | /// breakpoint normally. |
2573 | /// |
2574 | /// \param[in] range_bounds |
2575 | /// The range which the breakpoint must be contained within. |
2576 | /// Typically a source line. |
2577 | /// |
2578 | /// \return |
2579 | /// The address of the next branch instruction, or the end of |
2580 | /// the range provided in range_bounds. If there are any |
2581 | /// problems with the disassembly or getting the instructions, |
2582 | /// the original default_stop_addr will be returned. |
2583 | Address AdvanceAddressToNextBranchInstruction(Address default_stop_addr, |
2584 | AddressRange range_bounds); |
2585 | |
2586 | /// Configure asynchronous structured data feature. |
2587 | /// |
2588 | /// Each Process type that supports using an asynchronous StructuredData |
2589 | /// feature should implement this to enable/disable/configure the feature. |
2590 | /// The default implementation here will always return an error indiciating |
2591 | /// the feature is unsupported. |
2592 | /// |
2593 | /// StructuredDataPlugin implementations will call this to configure a |
2594 | /// feature that has been reported as being supported. |
2595 | /// |
2596 | /// \param[in] type_name |
2597 | /// The StructuredData type name as previously discovered by |
2598 | /// the Process-derived instance. |
2599 | /// |
2600 | /// \param[in] config_sp |
2601 | /// Configuration data for the feature being enabled. This config |
2602 | /// data, which may be null, will be passed along to the feature |
2603 | /// to process. The feature will dictate whether this is a dictionary, |
2604 | /// an array or some other object. If the feature needs to be |
2605 | /// set up properly before it can be enabled, then the config should |
2606 | /// also take an enable/disable flag. |
2607 | /// |
2608 | /// \return |
2609 | /// Returns the result of attempting to configure the feature. |
2610 | virtual Status |
2611 | ConfigureStructuredData(llvm::StringRef type_name, |
2612 | const StructuredData::ObjectSP &config_sp); |
2613 | |
2614 | /// Broadcasts the given structured data object from the given plugin. |
2615 | /// |
2616 | /// StructuredDataPlugin instances can use this to optionally broadcast any |
2617 | /// of their data if they want to make it available for clients. The data |
2618 | /// will come in on the structured data event bit |
2619 | /// (eBroadcastBitStructuredData). |
2620 | /// |
2621 | /// \param[in] object_sp |
2622 | /// The structured data object to broadcast. |
2623 | /// |
2624 | /// \param[in] plugin_sp |
2625 | /// The plugin that will be reported in the event's plugin |
2626 | /// parameter. |
2627 | void BroadcastStructuredData(const StructuredData::ObjectSP &object_sp, |
2628 | const lldb::StructuredDataPluginSP &plugin_sp); |
2629 | |
2630 | /// Returns the StructuredDataPlugin associated with a given type name, if |
2631 | /// there is one. |
2632 | /// |
2633 | /// There will only be a plugin for a given StructuredDataType if the |
2634 | /// debugged process monitor claims that the feature is supported. This is |
2635 | /// one way to tell whether a feature is available. |
2636 | /// |
2637 | /// \return |
2638 | /// The plugin if one is available for the specified feature; |
2639 | /// otherwise, returns an empty shared pointer. |
2640 | lldb::StructuredDataPluginSP |
2641 | GetStructuredDataPlugin(llvm::StringRef type_name) const; |
2642 | |
2643 | virtual void *GetImplementation() { return nullptr; } |
2644 | |
2645 | virtual void ForceScriptedState(lldb::StateType state) {} |
2646 | |
2647 | SourceManager::SourceFileCache &GetSourceFileCache() { |
2648 | return m_source_file_cache; |
2649 | } |
2650 | |
2651 | protected: |
2652 | friend class Trace; |
2653 | |
2654 | /// Construct with a shared pointer to a target, and the Process listener. |
2655 | /// Uses the Host UnixSignalsSP by default. |
2656 | Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp); |
2657 | |
2658 | /// Construct with a shared pointer to a target, the Process listener, and |
2659 | /// the appropriate UnixSignalsSP for the process. |
2660 | Process(lldb::TargetSP target_sp, lldb::ListenerSP listener_sp, |
2661 | const lldb::UnixSignalsSP &unix_signals_sp); |
2662 | |
2663 | /// Get the processor tracing type supported for this process. |
2664 | /// Responses might be different depending on the architecture and |
2665 | /// capabilities of the underlying OS. |
2666 | /// |
2667 | /// \return |
2668 | /// The supported trace type or an \a llvm::Error if tracing is |
2669 | /// not supported for the inferior. |
2670 | virtual llvm::Expected<TraceSupportedResponse> TraceSupported(); |
2671 | |
2672 | /// Start tracing a process or its threads. |
2673 | /// |
2674 | /// \param[in] request |
2675 | /// JSON object with the information necessary to start tracing. In the |
2676 | /// case of gdb-remote processes, this JSON object should conform to the |
2677 | /// jLLDBTraceStart packet. |
2678 | /// |
2679 | /// \return |
2680 | /// \a llvm::Error::success if the operation was successful, or |
2681 | /// \a llvm::Error otherwise. |
2682 | virtual llvm::Error TraceStart(const llvm::json::Value &request) { |
2683 | return llvm::make_error<UnimplementedError>(); |
2684 | } |
2685 | |
2686 | /// Stop tracing a live process or its threads. |
2687 | /// |
2688 | /// \param[in] request |
2689 | /// The information determining which threads or process to stop tracing. |
2690 | /// |
2691 | /// \return |
2692 | /// \a llvm::Error::success if the operation was successful, or |
2693 | /// \a llvm::Error otherwise. |
2694 | virtual llvm::Error TraceStop(const TraceStopRequest &request) { |
2695 | return llvm::make_error<UnimplementedError>(); |
2696 | } |
2697 | |
2698 | /// Get the current tracing state of the process and its threads. |
2699 | /// |
2700 | /// \param[in] type |
2701 | /// Tracing technology type to consider. |
2702 | /// |
2703 | /// \return |
2704 | /// A JSON object string with custom data depending on the trace |
2705 | /// technology, or an \a llvm::Error in case of errors. |
2706 | virtual llvm::Expected<std::string> TraceGetState(llvm::StringRef type) { |
2707 | return llvm::make_error<UnimplementedError>(); |
2708 | } |
2709 | |
2710 | /// Get binary data given a trace technology and a data identifier. |
2711 | /// |
2712 | /// \param[in] request |
2713 | /// Object with the params of the requested data. |
2714 | /// |
2715 | /// \return |
2716 | /// A vector of bytes with the requested data, or an \a llvm::Error in |
2717 | /// case of failures. |
2718 | virtual llvm::Expected<std::vector<uint8_t>> |
2719 | TraceGetBinaryData(const TraceGetBinaryDataRequest &request) { |
2720 | return llvm::make_error<UnimplementedError>(); |
2721 | } |
2722 | |
2723 | // This calls a function of the form "void * (*)(void)". |
2724 | bool CallVoidArgVoidPtrReturn(const Address *address, |
2725 | lldb::addr_t &returned_func, |
2726 | bool trap_exceptions = false); |
2727 | |
2728 | /// Update the thread list following process plug-in's specific logic. |
2729 | /// |
2730 | /// This method should only be invoked by \a UpdateThreadList. |
2731 | /// |
2732 | /// \return |
2733 | /// \b true if the new thread list could be generated, \b false otherwise. |
2734 | virtual bool DoUpdateThreadList(ThreadList &old_thread_list, |
2735 | ThreadList &new_thread_list) = 0; |
2736 | |
2737 | /// Actually do the reading of memory from a process. |
2738 | /// |
2739 | /// Subclasses must override this function and can return fewer bytes than |
2740 | /// requested when memory requests are too large. This class will break up |
2741 | /// the memory requests and keep advancing the arguments along as needed. |
2742 | /// |
2743 | /// \param[in] vm_addr |
2744 | /// A virtual load address that indicates where to start reading |
2745 | /// memory from. |
2746 | /// |
2747 | /// \param[in] size |
2748 | /// The number of bytes to read. |
2749 | /// |
2750 | /// \param[out] buf |
2751 | /// A byte buffer that is at least \a size bytes long that |
2752 | /// will receive the memory bytes. |
2753 | /// |
2754 | /// \param[out] error |
2755 | /// An error that indicates the success or failure of this |
2756 | /// operation. If error indicates success (error.Success()), |
2757 | /// then the value returned can be trusted, otherwise zero |
2758 | /// will be returned. |
2759 | /// |
2760 | /// \return |
2761 | /// The number of bytes that were actually read into \a buf. |
2762 | /// Zero is returned in the case of an error. |
2763 | virtual size_t DoReadMemory(lldb::addr_t vm_addr, void *buf, size_t size, |
2764 | Status &error) = 0; |
2765 | |
2766 | /// DoGetMemoryRegionInfo is called by GetMemoryRegionInfo after it has |
2767 | /// removed non address bits from load_addr. Override this method in |
2768 | /// subclasses of Process. |
2769 | /// |
2770 | /// See GetMemoryRegionInfo for details of the logic. |
2771 | /// |
2772 | /// \param[in] load_addr |
2773 | /// The load address to query the range_info for. (non address bits |
2774 | /// removed) |
2775 | /// |
2776 | /// \param[out] range_info |
2777 | /// An range_info value containing the details of the range. |
2778 | /// |
2779 | /// \return |
2780 | /// An error value. |
2781 | virtual Status DoGetMemoryRegionInfo(lldb::addr_t load_addr, |
2782 | MemoryRegionInfo &range_info) { |
2783 | return Status("Process::DoGetMemoryRegionInfo() not supported" ); |
2784 | } |
2785 | |
2786 | /// Provide an override value in the subclass for lldb's |
2787 | /// CPU-based logic for whether watchpoint exceptions are |
2788 | /// received before or after an instruction executes. |
2789 | /// |
2790 | /// If a Process subclass needs to override this architecture-based |
2791 | /// result, it may do so by overriding this method. |
2792 | /// |
2793 | /// \return |
2794 | /// No boolean returned means there is no override of the |
2795 | /// default architecture-based behavior. |
2796 | /// true is returned for targets where watchpoints are reported |
2797 | /// after the instruction has completed. |
2798 | /// false is returned for targets where watchpoints are reported |
2799 | /// before the instruction executes. |
2800 | virtual std::optional<bool> DoGetWatchpointReportedAfter() { |
2801 | return std::nullopt; |
2802 | } |
2803 | |
2804 | lldb::StateType GetPrivateState(); |
2805 | |
2806 | /// The "private" side of resuming a process. This doesn't alter the state |
2807 | /// of m_run_lock, but just causes the process to resume. |
2808 | /// |
2809 | /// \return |
2810 | /// An Status object describing the success or failure of the resume. |
2811 | Status PrivateResume(); |
2812 | |
2813 | // Called internally |
2814 | void CompleteAttach(); |
2815 | |
2816 | // NextEventAction provides a way to register an action on the next event |
2817 | // that is delivered to this process. There is currently only one next event |
2818 | // action allowed in the process at one time. If a new "NextEventAction" is |
2819 | // added while one is already present, the old action will be discarded (with |
2820 | // HandleBeingUnshipped called after it is discarded.) |
2821 | // |
2822 | // If you want to resume the process as a result of a resume action, call |
2823 | // RequestResume, don't call Resume directly. |
2824 | class NextEventAction { |
2825 | public: |
2826 | enum EventActionResult { |
2827 | eEventActionSuccess, |
2828 | eEventActionRetry, |
2829 | eEventActionExit |
2830 | }; |
2831 | |
2832 | NextEventAction(Process *process) : m_process(process) {} |
2833 | |
2834 | virtual ~NextEventAction() = default; |
2835 | |
2836 | virtual EventActionResult PerformAction(lldb::EventSP &event_sp) = 0; |
2837 | virtual void HandleBeingUnshipped() {} |
2838 | virtual EventActionResult HandleBeingInterrupted() = 0; |
2839 | virtual const char *GetExitString() = 0; |
2840 | void RequestResume() { m_process->m_resume_requested = true; } |
2841 | |
2842 | protected: |
2843 | Process *m_process; |
2844 | }; |
2845 | |
2846 | void SetNextEventAction(Process::NextEventAction *next_event_action) { |
2847 | if (m_next_event_action_up) |
2848 | m_next_event_action_up->HandleBeingUnshipped(); |
2849 | |
2850 | m_next_event_action_up.reset(p: next_event_action); |
2851 | } |
2852 | |
2853 | // This is the completer for Attaching: |
2854 | class AttachCompletionHandler : public NextEventAction { |
2855 | public: |
2856 | AttachCompletionHandler(Process *process, uint32_t exec_count); |
2857 | |
2858 | ~AttachCompletionHandler() override = default; |
2859 | |
2860 | EventActionResult PerformAction(lldb::EventSP &event_sp) override; |
2861 | EventActionResult HandleBeingInterrupted() override; |
2862 | const char *GetExitString() override; |
2863 | |
2864 | private: |
2865 | uint32_t m_exec_count; |
2866 | std::string m_exit_string; |
2867 | }; |
2868 | |
2869 | bool PrivateStateThreadIsValid() const { |
2870 | lldb::StateType state = m_private_state.GetValue(); |
2871 | return state != lldb::eStateInvalid && state != lldb::eStateDetached && |
2872 | state != lldb::eStateExited && m_private_state_thread.IsJoinable(); |
2873 | } |
2874 | |
2875 | void ForceNextEventDelivery() { m_force_next_event_delivery = true; } |
2876 | |
2877 | /// Loads any plugins associated with asynchronous structured data and maps |
2878 | /// the relevant supported type name to the plugin. |
2879 | /// |
2880 | /// Processes can receive asynchronous structured data from the process |
2881 | /// monitor. This method will load and map any structured data plugins that |
2882 | /// support the given set of supported type names. Later, if any of these |
2883 | /// features are enabled, the process monitor is free to generate |
2884 | /// asynchronous structured data. The data must come in as a single \b |
2885 | /// StructuredData::Dictionary. That dictionary must have a string field |
2886 | /// named 'type', with a value that equals the relevant type name string |
2887 | /// (one of the values in \b supported_type_names). |
2888 | /// |
2889 | /// \param[in] supported_type_names |
2890 | /// An array of zero or more type names. Each must be unique. |
2891 | /// For each entry in the list, a StructuredDataPlugin will be |
2892 | /// searched for that supports the structured data type name. |
2893 | void MapSupportedStructuredDataPlugins( |
2894 | const StructuredData::Array &supported_type_names); |
2895 | |
2896 | /// Route the incoming structured data dictionary to the right plugin. |
2897 | /// |
2898 | /// The incoming structured data must be a dictionary, and it must have a |
2899 | /// key named 'type' that stores a string value. The string value must be |
2900 | /// the name of the structured data feature that knows how to handle it. |
2901 | /// |
2902 | /// \param[in] object_sp |
2903 | /// When non-null and pointing to a dictionary, the 'type' |
2904 | /// key's string value is used to look up the plugin that |
2905 | /// was registered for that structured data type. It then |
2906 | /// calls the following method on the StructuredDataPlugin |
2907 | /// instance: |
2908 | /// |
2909 | /// virtual void |
2910 | /// HandleArrivalOfStructuredData(Process &process, |
2911 | /// llvm::StringRef type_name, |
2912 | /// const StructuredData::ObjectSP |
2913 | /// &object_sp) |
2914 | /// |
2915 | /// \return |
2916 | /// True if the structured data was routed to a plugin; otherwise, |
2917 | /// false. |
2918 | bool RouteAsyncStructuredData(const StructuredData::ObjectSP object_sp); |
2919 | |
2920 | /// Check whether the process supports memory tagging. |
2921 | /// |
2922 | /// \return |
2923 | /// true if the process supports memory tagging, |
2924 | /// false otherwise. |
2925 | virtual bool SupportsMemoryTagging() { return false; } |
2926 | |
2927 | /// Does the final operation to read memory tags. E.g. sending a GDB packet. |
2928 | /// It assumes that ReadMemoryTags has checked that memory tagging is enabled |
2929 | /// and has expanded the memory range as needed. |
2930 | /// |
2931 | /// \param[in] addr |
2932 | /// Start of address range to read memory tags for. |
2933 | /// |
2934 | /// \param[in] len |
2935 | /// Length of the memory range to read tags for (in bytes). |
2936 | /// |
2937 | /// \param[in] type |
2938 | /// Type of tags to read (get this from a MemoryTagManager) |
2939 | /// |
2940 | /// \return |
2941 | /// The packed tag data received from the remote or an error |
2942 | /// if the read failed. |
2943 | virtual llvm::Expected<std::vector<uint8_t>> |
2944 | DoReadMemoryTags(lldb::addr_t addr, size_t len, int32_t type) { |
2945 | return llvm::createStringError( |
2946 | EC: llvm::inconvertibleErrorCode(), |
2947 | S: llvm::formatv(Fmt: "{0} does not support reading memory tags" , |
2948 | Vals: GetPluginName())); |
2949 | } |
2950 | |
2951 | /// Does the final operation to write memory tags. E.g. sending a GDB packet. |
2952 | /// It assumes that WriteMemoryTags has checked that memory tagging is enabled |
2953 | /// and has packed the tag data. |
2954 | /// |
2955 | /// \param[in] addr |
2956 | /// Start of address range to write memory tags for. |
2957 | /// |
2958 | /// \param[in] len |
2959 | /// Length of the memory range to write tags for (in bytes). |
2960 | /// |
2961 | /// \param[in] type |
2962 | /// Type of tags to read (get this from a MemoryTagManager) |
2963 | /// |
2964 | /// \param[in] tags |
2965 | /// Packed tags to be written. |
2966 | /// |
2967 | /// \return |
2968 | /// Status telling you whether the write succeeded. |
2969 | virtual Status DoWriteMemoryTags(lldb::addr_t addr, size_t len, int32_t type, |
2970 | const std::vector<uint8_t> &tags) { |
2971 | Status status; |
2972 | status.SetErrorStringWithFormatv(format: "{0} does not support writing memory tags" , |
2973 | args: GetPluginName()); |
2974 | return status; |
2975 | } |
2976 | |
2977 | // Type definitions |
2978 | typedef std::map<lldb::LanguageType, lldb::LanguageRuntimeSP> |
2979 | LanguageRuntimeCollection; |
2980 | |
2981 | struct PreResumeCallbackAndBaton { |
2982 | bool (*callback)(void *); |
2983 | void *baton; |
2984 | PreResumeCallbackAndBaton(PreResumeActionCallback in_callback, |
2985 | void *in_baton) |
2986 | : callback(in_callback), baton(in_baton) {} |
2987 | bool operator== (const PreResumeCallbackAndBaton &rhs) { |
2988 | return callback == rhs.callback && baton == rhs.baton; |
2989 | } |
2990 | }; |
2991 | |
2992 | // Member variables |
2993 | std::weak_ptr<Target> m_target_wp; ///< The target that owns this process. |
2994 | lldb::pid_t m_pid = LLDB_INVALID_PROCESS_ID; |
2995 | ThreadSafeValue<lldb::StateType> m_public_state; |
2996 | ThreadSafeValue<lldb::StateType> |
2997 | m_private_state; // The actual state of our process |
2998 | Broadcaster m_private_state_broadcaster; // This broadcaster feeds state |
2999 | // changed events into the private |
3000 | // state thread's listener. |
3001 | Broadcaster m_private_state_control_broadcaster; // This is the control |
3002 | // broadcaster, used to |
3003 | // pause, resume & stop the |
3004 | // private state thread. |
3005 | lldb::ListenerSP m_private_state_listener_sp; // This is the listener for the |
3006 | // private state thread. |
3007 | HostThread m_private_state_thread; ///< Thread ID for the thread that watches |
3008 | ///internal state events |
3009 | ProcessModID m_mod_id; ///< Tracks the state of the process over stops and |
3010 | ///other alterations. |
3011 | uint32_t m_process_unique_id; ///< Each lldb_private::Process class that is |
3012 | ///created gets a unique integer ID that |
3013 | ///increments with each new instance |
3014 | uint32_t m_thread_index_id; ///< Each thread is created with a 1 based index |
3015 | ///that won't get re-used. |
3016 | std::map<uint64_t, uint32_t> m_thread_id_to_index_id_map; |
3017 | int m_exit_status; ///< The exit status of the process, or -1 if not set. |
3018 | std::string m_exit_string; ///< A textual description of why a process exited. |
3019 | std::mutex m_exit_status_mutex; ///< Mutex so m_exit_status m_exit_string can |
3020 | ///be safely accessed from multiple threads |
3021 | std::recursive_mutex m_thread_mutex; |
3022 | ThreadList m_thread_list_real; ///< The threads for this process as are known |
3023 | ///to the protocol we are debugging with |
3024 | ThreadList m_thread_list; ///< The threads for this process as the user will |
3025 | ///see them. This is usually the same as |
3026 | ///< m_thread_list_real, but might be different if there is an OS plug-in |
3027 | ///creating memory threads |
3028 | ThreadPlanStackMap m_thread_plans; ///< This is the list of thread plans for |
3029 | /// threads in m_thread_list, as well as |
3030 | /// threads we knew existed, but haven't |
3031 | /// determined that they have died yet. |
3032 | ThreadList |
3033 | m_extended_thread_list; ///< Constituent for extended threads that may be |
3034 | /// generated, cleared on natural stops |
3035 | uint32_t m_extended_thread_stop_id; ///< The natural stop id when |
3036 | ///extended_thread_list was last updated |
3037 | QueueList |
3038 | m_queue_list; ///< The list of libdispatch queues at a given stop point |
3039 | uint32_t m_queue_list_stop_id; ///< The natural stop id when queue list was |
3040 | ///last fetched |
3041 | StopPointSiteList<lldb_private::WatchpointResource> |
3042 | m_watchpoint_resource_list; ///< Watchpoint resources currently in use. |
3043 | std::vector<Notifications> m_notifications; ///< The list of notifications |
3044 | ///that this process can deliver. |
3045 | std::vector<lldb::addr_t> m_image_tokens; |
3046 | StopPointSiteList<lldb_private::BreakpointSite> |
3047 | m_breakpoint_site_list; ///< This is the list of breakpoint |
3048 | /// locations we intend to insert in |
3049 | /// the target. |
3050 | lldb::DynamicLoaderUP m_dyld_up; |
3051 | lldb::JITLoaderListUP m_jit_loaders_up; |
3052 | lldb::DynamicCheckerFunctionsUP m_dynamic_checkers_up; ///< The functions used |
3053 | /// by the expression |
3054 | /// parser to validate |
3055 | /// data that |
3056 | /// expressions use. |
3057 | lldb::OperatingSystemUP m_os_up; |
3058 | lldb::SystemRuntimeUP m_system_runtime_up; |
3059 | lldb::UnixSignalsSP |
3060 | m_unix_signals_sp; /// This is the current signal set for this process. |
3061 | lldb::ABISP m_abi_sp; |
3062 | lldb::IOHandlerSP m_process_input_reader; |
3063 | mutable std::mutex m_process_input_reader_mutex; |
3064 | ThreadedCommunication m_stdio_communication; |
3065 | std::recursive_mutex m_stdio_communication_mutex; |
3066 | bool m_stdin_forward; /// Remember if stdin must be forwarded to remote debug |
3067 | /// server |
3068 | std::string m_stdout_data; |
3069 | std::string m_stderr_data; |
3070 | std::recursive_mutex m_profile_data_comm_mutex; |
3071 | std::vector<std::string> m_profile_data; |
3072 | Predicate<uint32_t> m_iohandler_sync; |
3073 | MemoryCache m_memory_cache; |
3074 | AllocatedMemoryCache m_allocated_memory_cache; |
3075 | bool m_should_detach; /// Should we detach if the process object goes away |
3076 | /// with an explicit call to Kill or Detach? |
3077 | LanguageRuntimeCollection m_language_runtimes; |
3078 | std::recursive_mutex m_language_runtimes_mutex; |
3079 | InstrumentationRuntimeCollection m_instrumentation_runtimes; |
3080 | std::unique_ptr<NextEventAction> m_next_event_action_up; |
3081 | std::vector<PreResumeCallbackAndBaton> m_pre_resume_actions; |
3082 | ProcessRunLock m_public_run_lock; |
3083 | ProcessRunLock m_private_run_lock; |
3084 | bool m_currently_handling_do_on_removals; |
3085 | bool m_resume_requested; // If m_currently_handling_event or |
3086 | // m_currently_handling_do_on_removals are true, |
3087 | // Resume will only request a resume, using this |
3088 | // flag to check. |
3089 | |
3090 | /// This is set at the beginning of Process::Finalize() to stop functions |
3091 | /// from looking up or creating things during or after a finalize call. |
3092 | std::atomic<bool> m_finalizing; |
3093 | // When we are "Finalizing" we need to do some cleanup. But if the Finalize |
3094 | // call is coming in the Destructor, we can't do any actual work in the |
3095 | // process because that is likely to call "shared_from_this" which crashes |
3096 | // if run while destructing. We use this flag to determine that. |
3097 | std::atomic<bool> m_destructing; |
3098 | |
3099 | /// Mask for code an data addresses. The default value (0) means no mask is |
3100 | /// set. The bits set to 1 indicate bits that are NOT significant for |
3101 | /// addressing. |
3102 | /// The highmem versions are for targets where we may have different masks |
3103 | /// for low memory versus high memory addresses. |
3104 | /// @{ |
3105 | lldb::addr_t m_code_address_mask = 0; |
3106 | lldb::addr_t m_data_address_mask = 0; |
3107 | lldb::addr_t m_highmem_code_address_mask = 0; |
3108 | lldb::addr_t m_highmem_data_address_mask = 0; |
3109 | /// @} |
3110 | |
3111 | bool m_clear_thread_plans_on_stop; |
3112 | bool m_force_next_event_delivery; |
3113 | lldb::StateType m_last_broadcast_state; /// This helps with the Public event |
3114 | /// coalescing in |
3115 | /// ShouldBroadcastEvent. |
3116 | std::map<lldb::addr_t, lldb::addr_t> m_resolved_indirect_addresses; |
3117 | bool m_destroy_in_process; |
3118 | bool m_can_interpret_function_calls; // Some targets, e.g the OSX kernel, |
3119 | // don't support the ability to modify |
3120 | // the stack. |
3121 | std::mutex m_run_thread_plan_lock; |
3122 | llvm::StringMap<lldb::StructuredDataPluginSP> m_structured_data_plugin_map; |
3123 | |
3124 | enum { eCanJITDontKnow = 0, eCanJITYes, eCanJITNo } m_can_jit; |
3125 | |
3126 | std::unique_ptr<UtilityFunction> m_dlopen_utility_func_up; |
3127 | llvm::once_flag m_dlopen_utility_func_flag_once; |
3128 | |
3129 | /// Per process source file cache. |
3130 | SourceManager::SourceFileCache m_source_file_cache; |
3131 | |
3132 | size_t RemoveBreakpointOpcodesFromBuffer(lldb::addr_t addr, size_t size, |
3133 | uint8_t *buf) const; |
3134 | |
3135 | void SynchronouslyNotifyStateChanged(lldb::StateType state); |
3136 | |
3137 | void SetPublicState(lldb::StateType new_state, bool restarted); |
3138 | |
3139 | void SetPrivateState(lldb::StateType state); |
3140 | |
3141 | bool StartPrivateStateThread(bool is_secondary_thread = false); |
3142 | |
3143 | void StopPrivateStateThread(); |
3144 | |
3145 | void PausePrivateStateThread(); |
3146 | |
3147 | void ResumePrivateStateThread(); |
3148 | |
3149 | private: |
3150 | // The starts up the private state thread that will watch for events from the |
3151 | // debugee. Pass true for is_secondary_thread in the case where you have to |
3152 | // temporarily spin up a secondary state thread to handle events from a hand- |
3153 | // called function on the primary private state thread. |
3154 | |
3155 | lldb::thread_result_t RunPrivateStateThread(bool is_secondary_thread); |
3156 | |
3157 | protected: |
3158 | void HandlePrivateEvent(lldb::EventSP &event_sp); |
3159 | |
3160 | Status HaltPrivate(); |
3161 | |
3162 | lldb::StateType WaitForProcessStopPrivate(lldb::EventSP &event_sp, |
3163 | const Timeout<std::micro> &timeout); |
3164 | |
3165 | // This waits for both the state change broadcaster, and the control |
3166 | // broadcaster. If control_only, it only waits for the control broadcaster. |
3167 | |
3168 | bool GetEventsPrivate(lldb::EventSP &event_sp, |
3169 | const Timeout<std::micro> &timeout, bool control_only); |
3170 | |
3171 | lldb::StateType |
3172 | GetStateChangedEventsPrivate(lldb::EventSP &event_sp, |
3173 | const Timeout<std::micro> &timeout); |
3174 | |
3175 | size_t WriteMemoryPrivate(lldb::addr_t addr, const void *buf, size_t size, |
3176 | Status &error); |
3177 | |
3178 | void AppendSTDOUT(const char *s, size_t len); |
3179 | |
3180 | void AppendSTDERR(const char *s, size_t len); |
3181 | |
3182 | void BroadcastAsyncProfileData(const std::string &one_profile_data); |
3183 | |
3184 | static void STDIOReadThreadBytesReceived(void *baton, const void *src, |
3185 | size_t src_len); |
3186 | |
3187 | bool PushProcessIOHandler(); |
3188 | |
3189 | bool PopProcessIOHandler(); |
3190 | |
3191 | bool ProcessIOHandlerIsActive(); |
3192 | |
3193 | bool ProcessIOHandlerExists() const { |
3194 | std::lock_guard<std::mutex> guard(m_process_input_reader_mutex); |
3195 | return static_cast<bool>(m_process_input_reader); |
3196 | } |
3197 | |
3198 | Status StopForDestroyOrDetach(lldb::EventSP &exit_event_sp); |
3199 | |
3200 | virtual Status UpdateAutomaticSignalFiltering(); |
3201 | |
3202 | void LoadOperatingSystemPlugin(bool flush); |
3203 | |
3204 | private: |
3205 | Status DestroyImpl(bool force_kill); |
3206 | |
3207 | /// This is the part of the event handling that for a process event. It |
3208 | /// decides what to do with the event and returns true if the event needs to |
3209 | /// be propagated to the user, and false otherwise. If the event is not |
3210 | /// propagated, this call will most likely set the target to executing |
3211 | /// again. There is only one place where this call should be called, |
3212 | /// HandlePrivateEvent. Don't call it from anywhere else... |
3213 | /// |
3214 | /// \param[in] event_ptr |
3215 | /// This is the event we are handling. |
3216 | /// |
3217 | /// \return |
3218 | /// Returns \b true if the event should be reported to the |
3219 | /// user, \b false otherwise. |
3220 | bool ShouldBroadcastEvent(Event *event_ptr); |
3221 | |
3222 | void ControlPrivateStateThread(uint32_t signal); |
3223 | |
3224 | Status LaunchPrivate(ProcessLaunchInfo &launch_info, lldb::StateType &state, |
3225 | lldb::EventSP &event_sp); |
3226 | |
3227 | lldb::EventSP CreateEventFromProcessState(uint32_t event_type); |
3228 | |
3229 | Process(const Process &) = delete; |
3230 | const Process &operator=(const Process &) = delete; |
3231 | }; |
3232 | |
3233 | /// RAII guard that should be acquired when an utility function is called within |
3234 | /// a given process. |
3235 | class UtilityFunctionScope { |
3236 | Process *m_process; |
3237 | |
3238 | public: |
3239 | UtilityFunctionScope(Process *p) : m_process(p) { |
3240 | if (m_process) |
3241 | m_process->SetRunningUtilityFunction(true); |
3242 | } |
3243 | ~UtilityFunctionScope() { |
3244 | if (m_process) |
3245 | m_process->SetRunningUtilityFunction(false); |
3246 | } |
3247 | }; |
3248 | |
3249 | } // namespace lldb_private |
3250 | |
3251 | #endif // LLDB_TARGET_PROCESS_H |
3252 | |