1 //===-- GDBRemoteCommunicationClient.h --------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_GDBRemoteCommunicationClient_h_
11 #define liblldb_GDBRemoteCommunicationClient_h_
19 // Other libraries and framework includes
21 #include "lldb/Core/ArchSpec.h"
22 #include "lldb/Core/StructuredData.h"
23 #include "lldb/Target/Process.h"
25 #include "GDBRemoteCommunication.h"
27 namespace lldb_private {
28 namespace process_gdb_remote {
30 class GDBRemoteCommunicationClient : public GDBRemoteCommunication
33 GDBRemoteCommunicationClient();
35 ~GDBRemoteCommunicationClient() override;
37 //------------------------------------------------------------------
38 // After connecting, send the handshake to the server to make sure
39 // we are communicating with it.
40 //------------------------------------------------------------------
42 HandshakeWithServer (Error *error_ptr);
45 SendPacketAndWaitForResponse (const char *send_payload,
46 StringExtractorGDBRemote &response,
50 SendPacketAndWaitForResponse (const char *send_payload,
52 StringExtractorGDBRemote &response,
55 // For packets which specify a range of output to be returned,
56 // return all of the output via a series of request packets of the form
58 // <prefix><size>,<size>
59 // <prefix><size>*2,<size>
60 // <prefix><size>*3,<size>
62 // until a "$l..." packet is received, indicating the end.
63 // (size is in hex; this format is used by a standard gdbserver to
64 // return the given portion of the output specified by <prefix>;
65 // for example, "qXfer:libraries-svr4:read::fff,1000" means
66 // "return a chunk of the xml description file for shared
67 // library load addresses, where the chunk starts at offset 0xfff
68 // and continues for 0x1000 bytes").
69 // Concatenate the resulting server response packets together and
70 // return in response_string. If any packet fails, the return value
71 // indicates that failure and the returned string value is undefined.
73 SendPacketsAndConcatenateResponses (const char *send_payload_prefix,
74 std::string &response_string);
77 SendContinuePacketAndWaitForResponse (ProcessGDBRemote *process,
78 const char *packet_payload,
80 StringExtractorGDBRemote &response);
83 SendvContPacket (ProcessGDBRemote *process,
86 StringExtractorGDBRemote &response);
89 GetThreadSuffixSupported () override;
91 // This packet is usually sent first and the boolean return value
92 // indicates if the packet was send and any response was received
93 // even in the response is UNIMPLEMENTED. If the packet failed to
94 // get a response, then false is returned. This quickly tells us
95 // if we were able to connect and communicate with the remote GDB
98 QueryNoAckModeSupported ();
101 GetListThreadsInStopReplySupported ();
104 SendAsyncSignal (int signo);
107 SendInterrupt (Mutex::Locker &locker,
108 uint32_t seconds_to_wait_for_stop,
112 GetCurrentProcessID (bool allow_lazy = true);
115 GetLaunchSuccess (std::string &error_str);
118 LaunchGDBServer (const char *remote_accept_hostname,
121 std::string &socket_name);
124 QueryGDBServer (std::vector<std::pair<uint16_t, std::string>>& connection_urls);
127 KillSpawnedProcess (lldb::pid_t pid);
129 //------------------------------------------------------------------
130 /// Sends a GDB remote protocol 'A' packet that delivers program
131 /// arguments to the remote server.
134 /// A NULL terminated array of const C strings to use as the
138 /// Zero if the response was "OK", a positive value if the
139 /// the response was "Exx" where xx are two hex digits, or
140 /// -1 if the call is unsupported or any other unexpected
141 /// response was received.
142 //------------------------------------------------------------------
144 SendArgumentsPacket (const ProcessLaunchInfo &launch_info);
146 //------------------------------------------------------------------
147 /// Sends a "QEnvironment:NAME=VALUE" packet that will build up the
148 /// environment that will get used when launching an application
149 /// in conjunction with the 'A' packet. This function can be called
150 /// multiple times in a row in order to pass on the desired
151 /// environment that the inferior should be launched with.
153 /// @param[in] name_equal_value
154 /// A NULL terminated C string that contains a single environment
155 /// in the format "NAME=VALUE".
158 /// Zero if the response was "OK", a positive value if the
159 /// the response was "Exx" where xx are two hex digits, or
160 /// -1 if the call is unsupported or any other unexpected
161 /// response was received.
162 //------------------------------------------------------------------
164 SendEnvironmentPacket (char const *name_equal_value);
167 SendLaunchArchPacket (const char *arch);
170 SendLaunchEventDataPacket(const char *data, bool *was_supported = nullptr);
172 //------------------------------------------------------------------
173 /// Sends a "vAttach:PID" where PID is in hex.
176 /// A process ID for the remote gdb server to attach to.
178 /// @param[out] response
179 /// The response received from the gdb server. If the return
180 /// value is zero, \a response will contain a stop reply
184 /// Zero if the attach was successful, or an error indicating
186 //------------------------------------------------------------------
188 SendAttach (lldb::pid_t pid,
189 StringExtractorGDBRemote& response);
191 //------------------------------------------------------------------
192 /// Sends a GDB remote protocol 'I' packet that delivers stdin
193 /// data to the remote process.
196 /// A pointer to stdin data.
198 /// @param[in] data_len
199 /// The number of bytes available at \a data.
202 /// Zero if the attach was successful, or an error indicating
204 //------------------------------------------------------------------
206 SendStdinNotification(const char* data, size_t data_len);
208 //------------------------------------------------------------------
209 /// Sets the path to use for stdin/out/err for a process
210 /// that will be launched with the 'A' packet.
213 /// The path to use for stdin/out/err
216 /// Zero if the for success, or an error code for failure.
217 //------------------------------------------------------------------
219 SetSTDIN(const FileSpec &file_spec);
221 SetSTDOUT(const FileSpec &file_spec);
223 SetSTDERR(const FileSpec &file_spec);
225 //------------------------------------------------------------------
226 /// Sets the disable ASLR flag to \a enable for a process that will
227 /// be launched with the 'A' packet.
229 /// @param[in] enable
230 /// A boolean value indicating whether to disable ASLR or not.
233 /// Zero if the for success, or an error code for failure.
234 //------------------------------------------------------------------
236 SetDisableASLR (bool enable);
238 //------------------------------------------------------------------
239 /// Sets the DetachOnError flag to \a enable for the process controlled by the stub.
241 /// @param[in] enable
242 /// A boolean value indicating whether to detach on error or not.
245 /// Zero if the for success, or an error code for failure.
246 //------------------------------------------------------------------
248 SetDetachOnError (bool enable);
250 //------------------------------------------------------------------
251 /// Sets the working directory to \a path for a process that will
252 /// be launched with the 'A' packet for non platform based
253 /// connections. If this packet is sent to a GDB server that
254 /// implements the platform, it will change the current working
255 /// directory for the platform process.
257 /// @param[in] working_dir
258 /// The path to a directory to use when launching our process
261 /// Zero if the for success, or an error code for failure.
262 //------------------------------------------------------------------
264 SetWorkingDir(const FileSpec &working_dir);
266 //------------------------------------------------------------------
267 /// Gets the current working directory of a remote platform GDB
270 /// @param[out] working_dir
271 /// The current working directory on the remote platform.
274 /// Boolean for success
275 //------------------------------------------------------------------
277 GetWorkingDir(FileSpec &working_dir);
280 AllocateMemory (size_t size, uint32_t permissions);
283 DeallocateMemory (lldb::addr_t addr);
286 Detach (bool keep_stopped);
289 GetMemoryRegionInfo (lldb::addr_t addr, MemoryRegionInfo &range_info);
292 GetWatchpointSupportInfo (uint32_t &num);
295 GetWatchpointSupportInfo (uint32_t &num, bool& after, const ArchSpec &arch);
298 GetWatchpointsTriggerAfterInstruction (bool &after, const ArchSpec &arch);
301 GetHostArchitecture ();
304 GetHostDefaultPacketTimeout();
307 GetProcessArchitecture ();
310 GetRemoteQSupported();
313 GetVContSupported (char flavor);
316 GetpPacketSupported (lldb::tid_t tid);
319 GetxPacketSupported ();
322 GetVAttachOrWaitSupported ();
325 GetSyncThreadStateSupported();
328 ResetDiscoverableSettings (bool did_exec);
331 GetHostInfo (bool force = false);
334 GetDefaultThreadId (lldb::tid_t &tid);
337 GetOSVersion (uint32_t &major,
342 GetOSBuildString (std::string &s);
345 GetOSKernelDescription (std::string &s);
348 GetSystemArchitecture ();
351 GetHostname (std::string &s);
357 GetSupportsThreadSuffix ();
360 GetProcessInfo (lldb::pid_t pid, ProcessInstanceInfo &process_info);
363 FindProcesses (const ProcessInstanceInfoMatch &process_match_info,
364 ProcessInstanceInfoList &process_infos);
367 GetUserName (uint32_t uid, std::string &name);
370 GetGroupName (uint32_t gid, std::string &name);
373 HasFullVContSupport ()
375 return GetVContSupported ('A');
379 HasAnyVContSupport ()
381 return GetVContSupported ('a');
385 GetStopReply (StringExtractorGDBRemote &response);
388 GetThreadStopInfo (lldb::tid_t tid,
389 StringExtractorGDBRemote &response);
392 SupportsGDBStoppointPacket (GDBStoppointType type)
396 case eBreakpointSoftware: return m_supports_z0;
397 case eBreakpointHardware: return m_supports_z1;
398 case eWatchpointWrite: return m_supports_z2;
399 case eWatchpointRead: return m_supports_z3;
400 case eWatchpointReadWrite: return m_supports_z4;
401 default: return false;
406 SendGDBStoppointTypePacket (GDBStoppointType type, // Type of breakpoint or watchpoint
407 bool insert, // Insert or remove?
408 lldb::addr_t addr, // Address of breakpoint or watchpoint
409 uint32_t length); // Byte Size of breakpoint or watchpoint
412 SetNonStopMode (const bool enable);
415 TestPacketSpeed (const uint32_t num_packets, uint32_t max_send, uint32_t max_recv, bool json, Stream &strm);
417 // This packet is for testing the speed of the interface only. Both
418 // the client and server need to support it, but this allows us to
419 // measure the packet speed without any other work being done on the
420 // other end and avoids any of that work affecting the packet send
421 // and response times.
423 SendSpeedTestPacket (uint32_t send_size,
427 SetCurrentThread (uint64_t tid);
430 SetCurrentThreadForRun (uint64_t tid);
433 GetQXferAuxvReadSupported ();
436 GetQXferLibrariesReadSupported ();
439 GetQXferLibrariesSVR4ReadSupported ();
442 GetRemoteMaxPacketSize();
448 GetAugmentedLibrariesSVR4ReadSupported ();
451 GetQXferFeaturesReadSupported ();
454 SupportsAllocDeallocMemory () // const
456 // Uncomment this to have lldb pretend the debug server doesn't respond to alloc/dealloc memory packets.
457 // m_supports_alloc_dealloc_memory = lldb_private::eLazyBoolNo;
458 return m_supports_alloc_dealloc_memory;
462 GetCurrentThreadIDs (std::vector<lldb::tid_t> &thread_ids,
463 bool &sequence_mutex_unavailable);
466 GetInterruptWasSent () const
468 return m_interrupt_sent;
472 OpenFile (const FileSpec& file_spec, uint32_t flags, mode_t mode, Error &error);
475 CloseFile (lldb::user_id_t fd, Error &error);
478 GetFileSize (const FileSpec& file_spec);
481 GetFilePermissions(const FileSpec &file_spec, uint32_t &file_permissions);
484 SetFilePermissions(const FileSpec &file_spec, uint32_t file_permissions);
487 ReadFile (lldb::user_id_t fd,
494 WriteFile (lldb::user_id_t fd,
501 CreateSymlink(const FileSpec &src,
502 const FileSpec &dst);
505 Unlink(const FileSpec &file_spec);
508 MakeDirectory(const FileSpec &file_spec, uint32_t mode);
511 GetFileExists (const FileSpec& file_spec);
514 RunShellCommand(const char *command, // Shouldn't be nullptr
515 const FileSpec &working_dir, // Pass empty FileSpec to use the current working directory
516 int *status_ptr, // Pass nullptr if you don't want the process exit status
517 int *signo_ptr, // Pass nullptr if you don't want the signal that caused the process to exit
518 std::string *command_output, // Pass nullptr if you don't want the command output
519 uint32_t timeout_sec); // Timeout in seconds to wait for shell program to finish
522 CalculateMD5 (const FileSpec& file_spec, uint64_t &high, uint64_t &low);
525 HarmonizeThreadIdsForProfileData (ProcessGDBRemote *process,
526 StringExtractorGDBRemote &inputStringExtractor);
529 ReadRegister(lldb::tid_t tid,
531 StringExtractorGDBRemote &response);
534 ReadAllRegisters (lldb::tid_t tid,
535 StringExtractorGDBRemote &response);
538 SaveRegisterState (lldb::tid_t tid, uint32_t &save_id);
541 RestoreRegisterState (lldb::tid_t tid, uint32_t save_id);
544 GetGDBServerProgramName();
547 GetGDBServerProgramVersion();
550 AvoidGPackets(ProcessGDBRemote *process);
552 StructuredData::ObjectSP
556 GetThreadExtendedInfoSupported();
559 GetLoadedDynamicLibrariesInfosSupported();
562 GetModuleInfo (const FileSpec& module_file_spec,
563 const ArchSpec& arch_spec,
564 ModuleSpec &module_spec);
567 ReadExtFeature (const lldb_private::ConstString object,
568 const lldb_private::ConstString annex,
570 lldb_private::Error & err);
573 ServeSymbolLookups(lldb_private::Process *process);
576 LazyBool m_supports_not_sending_acks;
577 LazyBool m_supports_thread_suffix;
578 LazyBool m_supports_threads_in_stop_reply;
579 LazyBool m_supports_vCont_all;
580 LazyBool m_supports_vCont_any;
581 LazyBool m_supports_vCont_c;
582 LazyBool m_supports_vCont_C;
583 LazyBool m_supports_vCont_s;
584 LazyBool m_supports_vCont_S;
585 LazyBool m_qHostInfo_is_valid;
586 LazyBool m_curr_pid_is_valid;
587 LazyBool m_qProcessInfo_is_valid;
588 LazyBool m_qGDBServerVersion_is_valid;
589 LazyBool m_supports_alloc_dealloc_memory;
590 LazyBool m_supports_memory_region_info;
591 LazyBool m_supports_watchpoint_support_info;
592 LazyBool m_supports_detach_stay_stopped;
593 LazyBool m_watchpoints_trigger_after_instruction;
594 LazyBool m_attach_or_wait_reply;
595 LazyBool m_prepare_for_reg_writing_reply;
596 LazyBool m_supports_p;
597 LazyBool m_supports_x;
598 LazyBool m_avoid_g_packets;
599 LazyBool m_supports_QSaveRegisterState;
600 LazyBool m_supports_qXfer_auxv_read;
601 LazyBool m_supports_qXfer_libraries_read;
602 LazyBool m_supports_qXfer_libraries_svr4_read;
603 LazyBool m_supports_qXfer_features_read;
604 LazyBool m_supports_augmented_libraries_svr4_read;
605 LazyBool m_supports_jThreadExtendedInfo;
606 LazyBool m_supports_jLoadedDynamicLibrariesInfos;
609 m_supports_qProcessInfoPID:1,
610 m_supports_qfProcessInfo:1,
611 m_supports_qUserName:1,
612 m_supports_qGroupName:1,
613 m_supports_qThreadStopInfo:1,
619 m_supports_QEnvironment:1,
620 m_supports_QEnvironmentHexEncoded:1,
621 m_supports_qSymbol:1,
622 m_supports_jThreadsInfo:1;
624 lldb::pid_t m_curr_pid;
625 lldb::tid_t m_curr_tid; // Current gdb remote protocol thread index for all other operations
626 lldb::tid_t m_curr_tid_run; // Current gdb remote protocol thread index for continue, step, etc
628 uint32_t m_num_supported_hardware_watchpoints;
630 // If we need to send a packet while the target is running, the m_async_XXX
631 // member variables take care of making this happen.
633 Predicate<bool> m_async_packet_predicate;
634 std::string m_async_packet;
635 PacketResult m_async_result;
636 StringExtractorGDBRemote m_async_response;
637 int m_async_signal; // We were asked to deliver a signal to the inferior process.
638 bool m_interrupt_sent;
639 std::string m_partial_profile_data;
640 std::map<uint64_t, uint32_t> m_thread_id_to_used_usec_map;
642 ArchSpec m_host_arch;
643 ArchSpec m_process_arch;
644 uint32_t m_os_version_major;
645 uint32_t m_os_version_minor;
646 uint32_t m_os_version_update;
647 std::string m_os_build;
648 std::string m_os_kernel;
649 std::string m_hostname;
650 std::string m_gdb_server_name; // from reply to qGDBServerVersion, empty if qGDBServerVersion is not supported
651 uint32_t m_gdb_server_version; // from reply to qGDBServerVersion, zero if qGDBServerVersion is not supported
652 uint32_t m_default_packet_timeout;
653 uint64_t m_max_packet_size; // as returned by qSupported
656 SendPacketAndWaitForResponseNoLock (const char *payload,
657 size_t payload_length,
658 StringExtractorGDBRemote &response);
661 GetCurrentProcessInfo (bool allow_lazy_pid = true);
664 GetGDBServerVersion();
666 // Given the list of compression types that the remote debug stub can support,
667 // possibly enable compression if we find an encoding we can handle.
669 MaybeEnableCompression (std::vector<std::string> supported_compressions);
672 DecodeProcessInfoResponse (StringExtractorGDBRemote &response,
673 ProcessInstanceInfo &process_info);
676 DISALLOW_COPY_AND_ASSIGN (GDBRemoteCommunicationClient);
679 } // namespace process_gdb_remote
680 } // namespace lldb_private
682 #endif // liblldb_GDBRemoteCommunicationClient_h_