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_
13 #include "GDBRemoteClientBase.h"
23 // Other libraries and framework includes
25 #include "lldb/Core/ArchSpec.h"
26 #include "lldb/Target/Process.h"
27 #include "lldb/Utility/StreamGDBRemote.h"
28 #include "lldb/Utility/StructuredData.h"
30 #include "llvm/ADT/Optional.h"
32 namespace lldb_private {
33 namespace process_gdb_remote {
35 class GDBRemoteCommunicationClient : public GDBRemoteClientBase {
37 GDBRemoteCommunicationClient();
39 ~GDBRemoteCommunicationClient() override;
41 //------------------------------------------------------------------
42 // After connecting, send the handshake to the server to make sure
43 // we are communicating with it.
44 //------------------------------------------------------------------
45 bool HandshakeWithServer(Status *error_ptr);
47 // For packets which specify a range of output to be returned,
48 // return all of the output via a series of request packets of the form
50 // <prefix><size>,<size>
51 // <prefix><size>*2,<size>
52 // <prefix><size>*3,<size>
54 // until a "$l..." packet is received, indicating the end.
55 // (size is in hex; this format is used by a standard gdbserver to
56 // return the given portion of the output specified by <prefix>;
57 // for example, "qXfer:libraries-svr4:read::fff,1000" means
58 // "return a chunk of the xml description file for shared
59 // library load addresses, where the chunk starts at offset 0xfff
60 // and continues for 0x1000 bytes").
61 // Concatenate the resulting server response packets together and
62 // return in response_string. If any packet fails, the return value
63 // indicates that failure and the returned string value is undefined.
65 SendPacketsAndConcatenateResponses(const char *send_payload_prefix,
66 std::string &response_string);
68 bool GetThreadSuffixSupported();
70 // This packet is usually sent first and the boolean return value
71 // indicates if the packet was send and any response was received
72 // even in the response is UNIMPLEMENTED. If the packet failed to
73 // get a response, then false is returned. This quickly tells us
74 // if we were able to connect and communicate with the remote GDB
76 bool QueryNoAckModeSupported();
78 void GetListThreadsInStopReplySupported();
80 lldb::pid_t GetCurrentProcessID(bool allow_lazy = true);
82 bool GetLaunchSuccess(std::string &error_str);
84 bool LaunchGDBServer(const char *remote_accept_hostname, lldb::pid_t &pid,
85 uint16_t &port, std::string &socket_name);
87 size_t QueryGDBServer(
88 std::vector<std::pair<uint16_t, std::string>> &connection_urls);
90 bool KillSpawnedProcess(lldb::pid_t pid);
92 //------------------------------------------------------------------
93 /// Sends a GDB remote protocol 'A' packet that delivers program
94 /// arguments to the remote server.
97 /// A NULL terminated array of const C strings to use as the
101 /// Zero if the response was "OK", a positive value if the
102 /// the response was "Exx" where xx are two hex digits, or
103 /// -1 if the call is unsupported or any other unexpected
104 /// response was received.
105 //------------------------------------------------------------------
106 int SendArgumentsPacket(const ProcessLaunchInfo &launch_info);
108 //------------------------------------------------------------------
109 /// Sends a "QEnvironment:NAME=VALUE" packet that will build up the
110 /// environment that will get used when launching an application
111 /// in conjunction with the 'A' packet. This function can be called
112 /// multiple times in a row in order to pass on the desired
113 /// environment that the inferior should be launched with.
115 /// @param[in] name_equal_value
116 /// A NULL terminated C string that contains a single environment
117 /// in the format "NAME=VALUE".
120 /// Zero if the response was "OK", a positive value if the
121 /// the response was "Exx" where xx are two hex digits, or
122 /// -1 if the call is unsupported or any other unexpected
123 /// response was received.
124 //------------------------------------------------------------------
125 int SendEnvironmentPacket(char const *name_equal_value);
127 int SendLaunchArchPacket(const char *arch);
129 int SendLaunchEventDataPacket(const char *data,
130 bool *was_supported = nullptr);
132 //------------------------------------------------------------------
133 /// Sends a "vAttach:PID" where PID is in hex.
136 /// A process ID for the remote gdb server to attach to.
138 /// @param[out] response
139 /// The response received from the gdb server. If the return
140 /// value is zero, \a response will contain a stop reply
144 /// Zero if the attach was successful, or an error indicating
146 //------------------------------------------------------------------
147 int SendAttach(lldb::pid_t pid, StringExtractorGDBRemote &response);
149 //------------------------------------------------------------------
150 /// Sends a GDB remote protocol 'I' packet that delivers stdin
151 /// data to the remote process.
154 /// A pointer to stdin data.
156 /// @param[in] data_len
157 /// The number of bytes available at \a data.
160 /// Zero if the attach was successful, or an error indicating
162 //------------------------------------------------------------------
163 int SendStdinNotification(const char *data, size_t data_len);
165 //------------------------------------------------------------------
166 /// Sets the path to use for stdin/out/err for a process
167 /// that will be launched with the 'A' packet.
170 /// The path to use for stdin/out/err
173 /// Zero if the for success, or an error code for failure.
174 //------------------------------------------------------------------
175 int SetSTDIN(const FileSpec &file_spec);
176 int SetSTDOUT(const FileSpec &file_spec);
177 int SetSTDERR(const FileSpec &file_spec);
179 //------------------------------------------------------------------
180 /// Sets the disable ASLR flag to \a enable for a process that will
181 /// be launched with the 'A' packet.
183 /// @param[in] enable
184 /// A boolean value indicating whether to disable ASLR or not.
187 /// Zero if the for success, or an error code for failure.
188 //------------------------------------------------------------------
189 int SetDisableASLR(bool enable);
191 //------------------------------------------------------------------
192 /// Sets the DetachOnError flag to \a enable for the process controlled by the
195 /// @param[in] enable
196 /// A boolean value indicating whether to detach on error or not.
199 /// Zero if the for success, or an error code for failure.
200 //------------------------------------------------------------------
201 int SetDetachOnError(bool enable);
203 //------------------------------------------------------------------
204 /// Sets the working directory to \a path for a process that will
205 /// be launched with the 'A' packet for non platform based
206 /// connections. If this packet is sent to a GDB server that
207 /// implements the platform, it will change the current working
208 /// directory for the platform process.
210 /// @param[in] working_dir
211 /// The path to a directory to use when launching our process
214 /// Zero if the for success, or an error code for failure.
215 //------------------------------------------------------------------
216 int SetWorkingDir(const FileSpec &working_dir);
218 //------------------------------------------------------------------
219 /// Gets the current working directory of a remote platform GDB
222 /// @param[out] working_dir
223 /// The current working directory on the remote platform.
226 /// Boolean for success
227 //------------------------------------------------------------------
228 bool GetWorkingDir(FileSpec &working_dir);
230 lldb::addr_t AllocateMemory(size_t size, uint32_t permissions);
232 bool DeallocateMemory(lldb::addr_t addr);
234 Status Detach(bool keep_stopped);
236 Status GetMemoryRegionInfo(lldb::addr_t addr, MemoryRegionInfo &range_info);
238 Status GetWatchpointSupportInfo(uint32_t &num);
240 Status GetWatchpointSupportInfo(uint32_t &num, bool &after,
241 const ArchSpec &arch);
243 Status GetWatchpointsTriggerAfterInstruction(bool &after,
244 const ArchSpec &arch);
246 const ArchSpec &GetHostArchitecture();
248 std::chrono::seconds GetHostDefaultPacketTimeout();
250 const ArchSpec &GetProcessArchitecture();
252 void GetRemoteQSupported();
254 bool GetVContSupported(char flavor);
256 bool GetpPacketSupported(lldb::tid_t tid);
258 bool GetxPacketSupported();
260 bool GetVAttachOrWaitSupported();
262 bool GetSyncThreadStateSupported();
264 void ResetDiscoverableSettings(bool did_exec);
266 bool GetHostInfo(bool force = false);
268 bool GetDefaultThreadId(lldb::tid_t &tid);
270 bool GetOSVersion(uint32_t &major, uint32_t &minor, uint32_t &update);
272 bool GetOSBuildString(std::string &s);
274 bool GetOSKernelDescription(std::string &s);
276 ArchSpec GetSystemArchitecture();
278 bool GetHostname(std::string &s);
280 lldb::addr_t GetShlibInfoAddr();
282 bool GetSupportsThreadSuffix();
284 bool GetProcessInfo(lldb::pid_t pid, ProcessInstanceInfo &process_info);
286 uint32_t FindProcesses(const ProcessInstanceInfoMatch &process_match_info,
287 ProcessInstanceInfoList &process_infos);
289 bool GetUserName(uint32_t uid, std::string &name);
291 bool GetGroupName(uint32_t gid, std::string &name);
293 bool HasFullVContSupport() { return GetVContSupported('A'); }
295 bool HasAnyVContSupport() { return GetVContSupported('a'); }
297 bool GetStopReply(StringExtractorGDBRemote &response);
299 bool GetThreadStopInfo(lldb::tid_t tid, StringExtractorGDBRemote &response);
301 bool SupportsGDBStoppointPacket(GDBStoppointType type) {
303 case eBreakpointSoftware:
304 return m_supports_z0;
305 case eBreakpointHardware:
306 return m_supports_z1;
307 case eWatchpointWrite:
308 return m_supports_z2;
309 case eWatchpointRead:
310 return m_supports_z3;
311 case eWatchpointReadWrite:
312 return m_supports_z4;
318 uint8_t SendGDBStoppointTypePacket(
319 GDBStoppointType type, // Type of breakpoint or watchpoint
320 bool insert, // Insert or remove?
321 lldb::addr_t addr, // Address of breakpoint or watchpoint
322 uint32_t length); // Byte Size of breakpoint or watchpoint
324 bool SetNonStopMode(const bool enable);
326 void TestPacketSpeed(const uint32_t num_packets, uint32_t max_send,
327 uint32_t max_recv, uint64_t recv_amount, bool json,
330 // This packet is for testing the speed of the interface only. Both
331 // the client and server need to support it, but this allows us to
332 // measure the packet speed without any other work being done on the
333 // other end and avoids any of that work affecting the packet send
334 // and response times.
335 bool SendSpeedTestPacket(uint32_t send_size, uint32_t recv_size);
337 bool SetCurrentThread(uint64_t tid);
339 bool SetCurrentThreadForRun(uint64_t tid);
341 bool GetQXferAuxvReadSupported();
343 void EnableErrorStringInPacket();
345 bool GetQXferLibrariesReadSupported();
347 bool GetQXferLibrariesSVR4ReadSupported();
349 uint64_t GetRemoteMaxPacketSize();
351 bool GetEchoSupported();
353 bool GetQPassSignalsSupported();
355 bool GetAugmentedLibrariesSVR4ReadSupported();
357 bool GetQXferFeaturesReadSupported();
359 LazyBool SupportsAllocDeallocMemory() // const
361 // Uncomment this to have lldb pretend the debug server doesn't respond to
362 // alloc/dealloc memory packets.
363 // m_supports_alloc_dealloc_memory = lldb_private::eLazyBoolNo;
364 return m_supports_alloc_dealloc_memory;
367 size_t GetCurrentThreadIDs(std::vector<lldb::tid_t> &thread_ids,
368 bool &sequence_mutex_unavailable);
370 lldb::user_id_t OpenFile(const FileSpec &file_spec, uint32_t flags,
371 mode_t mode, Status &error);
373 bool CloseFile(lldb::user_id_t fd, Status &error);
375 lldb::user_id_t GetFileSize(const FileSpec &file_spec);
377 Status GetFilePermissions(const FileSpec &file_spec,
378 uint32_t &file_permissions);
380 Status SetFilePermissions(const FileSpec &file_spec,
381 uint32_t file_permissions);
383 uint64_t ReadFile(lldb::user_id_t fd, uint64_t offset, void *dst,
384 uint64_t dst_len, Status &error);
386 uint64_t WriteFile(lldb::user_id_t fd, uint64_t offset, const void *src,
387 uint64_t src_len, Status &error);
389 Status CreateSymlink(const FileSpec &src, const FileSpec &dst);
391 Status Unlink(const FileSpec &file_spec);
393 Status MakeDirectory(const FileSpec &file_spec, uint32_t mode);
395 bool GetFileExists(const FileSpec &file_spec);
397 Status RunShellCommand(
398 const char *command, // Shouldn't be nullptr
399 const FileSpec &working_dir, // Pass empty FileSpec to use the current
401 int *status_ptr, // Pass nullptr if you don't want the process exit status
402 int *signo_ptr, // Pass nullptr if you don't want the signal that caused
403 // the process to exit
405 *command_output, // Pass nullptr if you don't want the command output
406 uint32_t timeout_sec); // Timeout in seconds to wait for shell program to
409 bool CalculateMD5(const FileSpec &file_spec, uint64_t &high, uint64_t &low);
411 lldb::DataBufferSP ReadRegister(
414 reg_num); // Must be the eRegisterKindProcessPlugin register number
416 lldb::DataBufferSP ReadAllRegisters(lldb::tid_t tid);
419 WriteRegister(lldb::tid_t tid,
420 uint32_t reg_num, // eRegisterKindProcessPlugin register number
421 llvm::ArrayRef<uint8_t> data);
423 bool WriteAllRegisters(lldb::tid_t tid, llvm::ArrayRef<uint8_t> data);
425 bool SaveRegisterState(lldb::tid_t tid, uint32_t &save_id);
427 bool RestoreRegisterState(lldb::tid_t tid, uint32_t save_id);
429 bool SyncThreadState(lldb::tid_t tid);
431 const char *GetGDBServerProgramName();
433 uint32_t GetGDBServerProgramVersion();
435 bool AvoidGPackets(ProcessGDBRemote *process);
437 StructuredData::ObjectSP GetThreadsInfo();
439 bool GetThreadExtendedInfoSupported();
441 bool GetLoadedDynamicLibrariesInfosSupported();
443 bool GetSharedCacheInfoSupported();
445 bool GetModuleInfo(const FileSpec &module_file_spec,
446 const ArchSpec &arch_spec, ModuleSpec &module_spec);
448 llvm::Optional<std::vector<ModuleSpec>>
449 GetModulesInfo(llvm::ArrayRef<FileSpec> module_file_specs,
450 const llvm::Triple &triple);
452 bool ReadExtFeature(const lldb_private::ConstString object,
453 const lldb_private::ConstString annex, std::string &out,
454 lldb_private::Status &err);
456 void ServeSymbolLookups(lldb_private::Process *process);
458 // Sends QPassSignals packet to the server with given signals to ignore.
459 Status SendSignalsToIgnore(llvm::ArrayRef<int32_t> signals);
461 //------------------------------------------------------------------
462 /// Return the feature set supported by the gdb-remote server.
464 /// This method returns the remote side's response to the qSupported
465 /// packet. The response is the complete string payload returned
469 /// The string returned by the server to the qSupported query.
470 //------------------------------------------------------------------
471 const std::string &GetServerSupportedFeatures() const {
472 return m_qSupported_response;
475 //------------------------------------------------------------------
476 /// Return the array of async JSON packet types supported by the remote.
478 /// This method returns the remote side's array of supported JSON
479 /// packet types as a list of type names. Each of the results are
480 /// expected to have an Enable{type_name} command to enable and configure
481 /// the related feature. Each type_name for an enabled feature will
482 /// possibly send async-style packets that contain a payload of a
483 /// binhex-encoded JSON dictionary. The dictionary will have a
484 /// string field named 'type', that contains the type_name of the
485 /// supported packet type.
487 /// There is a Plugin category called structured-data plugins.
488 /// A plugin indicates whether it knows how to handle a type_name.
489 /// If so, it can be used to process the async JSON packet.
492 /// The string returned by the server to the qSupported query.
493 //------------------------------------------------------------------
494 lldb_private::StructuredData::Array *GetSupportedStructuredDataPlugins();
496 //------------------------------------------------------------------
497 /// Configure a StructuredData feature on the remote end.
499 /// @see \b Process::ConfigureStructuredData(...) for details.
500 //------------------------------------------------------------------
502 ConfigureRemoteStructuredData(const ConstString &type_name,
503 const StructuredData::ObjectSP &config_sp);
505 lldb::user_id_t SendStartTracePacket(const TraceOptions &options,
508 Status SendStopTracePacket(lldb::user_id_t uid, lldb::tid_t thread_id);
510 Status SendGetDataPacket(lldb::user_id_t uid, lldb::tid_t thread_id,
511 llvm::MutableArrayRef<uint8_t> &buffer,
514 Status SendGetMetaDataPacket(lldb::user_id_t uid, lldb::tid_t thread_id,
515 llvm::MutableArrayRef<uint8_t> &buffer,
518 Status SendGetTraceConfigPacket(lldb::user_id_t uid, TraceOptions &options);
521 LazyBool m_supports_not_sending_acks;
522 LazyBool m_supports_thread_suffix;
523 LazyBool m_supports_threads_in_stop_reply;
524 LazyBool m_supports_vCont_all;
525 LazyBool m_supports_vCont_any;
526 LazyBool m_supports_vCont_c;
527 LazyBool m_supports_vCont_C;
528 LazyBool m_supports_vCont_s;
529 LazyBool m_supports_vCont_S;
530 LazyBool m_qHostInfo_is_valid;
531 LazyBool m_curr_pid_is_valid;
532 LazyBool m_qProcessInfo_is_valid;
533 LazyBool m_qGDBServerVersion_is_valid;
534 LazyBool m_supports_alloc_dealloc_memory;
535 LazyBool m_supports_memory_region_info;
536 LazyBool m_supports_watchpoint_support_info;
537 LazyBool m_supports_detach_stay_stopped;
538 LazyBool m_watchpoints_trigger_after_instruction;
539 LazyBool m_attach_or_wait_reply;
540 LazyBool m_prepare_for_reg_writing_reply;
541 LazyBool m_supports_p;
542 LazyBool m_supports_x;
543 LazyBool m_avoid_g_packets;
544 LazyBool m_supports_QSaveRegisterState;
545 LazyBool m_supports_qXfer_auxv_read;
546 LazyBool m_supports_qXfer_libraries_read;
547 LazyBool m_supports_qXfer_libraries_svr4_read;
548 LazyBool m_supports_qXfer_features_read;
549 LazyBool m_supports_augmented_libraries_svr4_read;
550 LazyBool m_supports_jThreadExtendedInfo;
551 LazyBool m_supports_jLoadedDynamicLibrariesInfos;
552 LazyBool m_supports_jGetSharedCacheInfo;
553 LazyBool m_supports_QPassSignals;
554 LazyBool m_supports_error_string_reply;
556 bool m_supports_qProcessInfoPID : 1, m_supports_qfProcessInfo : 1,
557 m_supports_qUserName : 1, m_supports_qGroupName : 1,
558 m_supports_qThreadStopInfo : 1, m_supports_z0 : 1, m_supports_z1 : 1,
559 m_supports_z2 : 1, m_supports_z3 : 1, m_supports_z4 : 1,
560 m_supports_QEnvironment : 1, m_supports_QEnvironmentHexEncoded : 1,
561 m_supports_qSymbol : 1, m_qSymbol_requests_done : 1,
562 m_supports_qModuleInfo : 1, m_supports_jThreadsInfo : 1,
563 m_supports_jModulesInfo : 1;
565 lldb::pid_t m_curr_pid;
566 lldb::tid_t m_curr_tid; // Current gdb remote protocol thread index for all
568 lldb::tid_t m_curr_tid_run; // Current gdb remote protocol thread index for
569 // continue, step, etc
571 uint32_t m_num_supported_hardware_watchpoints;
573 ArchSpec m_host_arch;
574 ArchSpec m_process_arch;
575 uint32_t m_os_version_major;
576 uint32_t m_os_version_minor;
577 uint32_t m_os_version_update;
578 std::string m_os_build;
579 std::string m_os_kernel;
580 std::string m_hostname;
581 std::string m_gdb_server_name; // from reply to qGDBServerVersion, empty if
582 // qGDBServerVersion is not supported
583 uint32_t m_gdb_server_version; // from reply to qGDBServerVersion, zero if
584 // qGDBServerVersion is not supported
585 std::chrono::seconds m_default_packet_timeout;
586 uint64_t m_max_packet_size; // as returned by qSupported
587 std::string m_qSupported_response; // the complete response to qSupported
589 bool m_supported_async_json_packets_is_valid;
590 lldb_private::StructuredData::ObjectSP m_supported_async_json_packets_sp;
592 bool GetCurrentProcessInfo(bool allow_lazy_pid = true);
594 bool GetGDBServerVersion();
596 // Given the list of compression types that the remote debug stub can support,
597 // possibly enable compression if we find an encoding we can handle.
598 void MaybeEnableCompression(std::vector<std::string> supported_compressions);
600 bool DecodeProcessInfoResponse(StringExtractorGDBRemote &response,
601 ProcessInstanceInfo &process_info);
603 void OnRunPacketSent(bool first) override;
605 PacketResult SendThreadSpecificPacketAndWaitForResponse(
606 lldb::tid_t tid, StreamString &&payload,
607 StringExtractorGDBRemote &response, bool send_async);
609 Status SendGetTraceDataPacket(StreamGDBRemote &packet, lldb::user_id_t uid,
610 lldb::tid_t thread_id,
611 llvm::MutableArrayRef<uint8_t> &buffer,
615 DISALLOW_COPY_AND_ASSIGN(GDBRemoteCommunicationClient);
618 } // namespace process_gdb_remote
619 } // namespace lldb_private
621 #endif // liblldb_GDBRemoteCommunicationClient_h_