llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-lldb Author: David Spickett (DavidSpickett) <details> <summary>Changes</summary> This document has never been on the website, unlike GDB's protocol docs. It will be useful to have both available online to compare. Markdown is easier to edit and preview in many editors (including Github itself), so I've chosen that over RST. Plus, building the website takes minutes and I lose the will to make nice edits when I have to deal with that. The standard dialiect lacks some things notably multi-line table cells, so I've converted large tables into bullet point lists so that we still get text wrapping. This is a downside but I think the simplicity of Markdown outweighs this. I have applied the plain text markers where I've noticed it and escaped some HTML characters. There may be more changes needed but, it's Markdown, so it's in theory a lot easier for someone to fix it! --- Patch is 199.01 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/89718.diff 3 Files Affected: - (modified) lldb/docs/index.rst (+1) - (removed) lldb/docs/lldb-gdb-remote.txt (-2286) - (added) lldb/docs/resources/lldbgdbremote.md (+2399) ``````````diff diff --git a/lldb/docs/index.rst b/lldb/docs/index.rst index c378ab97d97bbb..6906566ea55e58 100644 --- a/lldb/docs/index.rst +++ b/lldb/docs/index.rst @@ -157,6 +157,7 @@ interesting areas to contribute to lldb. resources/sbapi resources/dataformatters resources/extensions + resources/lldbgdbremote resources/caveats resources/projects Public C++ API <https://lldb.llvm.org/cpp_reference/namespacelldb.html> diff --git a/lldb/docs/lldb-gdb-remote.txt b/lldb/docs/lldb-gdb-remote.txt deleted file mode 100644 index 6c29de61daba7e..00000000000000 --- a/lldb/docs/lldb-gdb-remote.txt +++ /dev/null @@ -1,2286 +0,0 @@ -LLDB has added new GDB server packets to better support multi-threaded and -remote debugging. Why? Normally you need to start the correct GDB and the -correct GDB server when debugging. If you have mismatch, then things go wrong -very quickly. LLDB makes extensive use of the GDB remote protocol and we -wanted to make sure that the experience was a bit more dynamic where we can -discover information about a remote target without having to know anything up -front. We also ran into performance issues with the existing GDB remote -protocol that can be overcome when using a reliable communications layer. -Some packets improve performance, others allow for remote process launching -(if you have an OS), and others allow us to dynamically figure out what -registers a thread might have. Again with GDB, both sides pre-agree on how the -registers will look (how many, their register number,name and offsets). We -prefer to be able to dynamically determine what kind of architecture, OS and -vendor we are debugging, as well as how things are laid out when it comes to -the thread register contexts. Below are the details on the new packets we have -added above and beyond the standard GDB remote protocol packets. - -//---------------------------------------------------------------------- -// "QStartNoAckMode" -// -// BRIEF -// Try to enable no ACK mode to skip sending ACKs and NACKs. -// -// PRIORITY TO IMPLEMENT -// High. Any GDB remote server that can implement this should if the -// connection is reliable. This improves packet throughput and increases -// the performance of the connection. -//---------------------------------------------------------------------- -Having to send an ACK/NACK after every packet slows things down a bit, so we -have a way to disable ACK packets to minimize the traffic for reliable -communication interfaces (like sockets). Below GDB or LLDB will send this -packet to try and disable ACKs. All lines that start with "send packet: " are -from GDB/LLDB, and all lines that start with "read packet: " are from the GDB -remote server: - -send packet: $QStartNoAckMode#b0 -read packet: + -read packet: $OK#9a -send packet: + - -//---------------------------------------------------------------------- -// "QSupported" -// -// BRIEF -// Query the GDB remote server for features it supports -// -// PRIORITY TO IMPLEMENT -// Optional. -//---------------------------------------------------------------------- - -QSupported is a standard GDB Remote Serial Protocol packet, but -there are several additions to the response that lldb can parse. -They are not all listed here. - -An example exchange: - -send packet: qSupported:xmlRegisters=i386,arm,mips,arc;multiprocess+;fork-events+;vfork-events+ - -read packet: qXfer:features:read+;PacketSize=20000;qEcho+;native-signals+;SupportedCompressions=lzfse,zlib-deflate,lz4,lzma;SupportedWatchpointTypes=aarch64-mask,aarch64-bas; - -In the example above, three lldb extensions are shown: - - PacketSize=20000 - The base 16 maximum packet size that the stub can handle. - SupportedCompressions=<item,item,...> - A list of compression types that the stub can use to compress packets - when the QEnableCompression packet is used to request one of them. - SupportedWatchpointTypes=<item,item,...> - A list of watchpoint types that this stub can manage. - Currently defined names are: - x86_64 64-bit x86-64 watchpoints - (1, 2, 4, 8 byte watchpoints aligned to those amounts) - aarch64-bas AArch64 Byte Address Select watchpoints - (any number of contiguous bytes within a doubleword) - aarch64-mask AArch64 MASK watchpoints - (any power-of-2 region of memory from 8 to 2GB, aligned) - If nothing is specified, lldb will default to sending power-of-2 - watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable - baseline assumption. - -//---------------------------------------------------------------------- -// "A" - launch args packet -// -// BRIEF -// Launch a program using the supplied arguments -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to launch a target after -// making a connection to a GDB server that isn't already connected to -// an inferior process. -//---------------------------------------------------------------------- - -We have added support for the "set program arguments" packet where we can -start a connection to a remote server and then later supply the path to the -executable and the arguments to use when executing: - -GDB remote docs for this: - -set program arguments(reserved) Aarglen,argnum,arg,... - -Where A is followed by the length in bytes of the hex encoded argument, -followed by an argument integer, and followed by the ASCII characters -converted into hex bytes foreach arg - -send packet: $A98,0,2f566f6c756d65732f776f726b2f67636c6179746f6e2f446f63756d656e74732f7372632f6174746163682f612e6f7574#00 -read packet: $OK#00 - -The above packet helps when you have remote debugging abilities where you -could launch a process on a remote host, this isn't needed for bare board -debugging. - -//---------------------------------------------------------------------- -// "QEnvironment:NAME=VALUE" -// -// BRIEF -// Setup the environment up for a new child process that will soon be -// launched using the "A" packet. -// -// NB: key/value pairs are sent as-is so gdb-remote protocol meta characters -// (e.g. '#' or '$') are not acceptable. If any non-printable or -// metacharacters are present in the strings, QEnvironmentHexEncoded -// should be used instead if it is available. If you don't want to -// scan the environment strings before sending, prefer -// the QEnvironmentHexEncoded packet over QEnvironment, if it is -// available. -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to launch a target after -// making a connection to a GDB server that isn't already connected to -// an inferior process. -//---------------------------------------------------------------------- - -Both GDB and LLDB support passing down environment variables. Is it ok to -respond with a "$#00" (unimplemented): - -send packet: $QEnvironment:ACK_COLOR_FILENAME=bold yellow#00 -read packet: $OK#00 - -This packet can be sent one or more times _prior_ to sending a "A" packet. - -//---------------------------------------------------------------------- -// "QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)" -// -// BRIEF -// Setup the environment up for a new child process that will soon be -// launched using the "A" packet. -// -// The only difference between this packet and QEnvironment is that the -// environment key-value pair is ascii hex encoded for transmission. -// This allows values with gdb-remote metacharacters like '#' to be sent. -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to launch a target after -// making a connection to a GDB server that isn't already connected to -// an inferior process. -//---------------------------------------------------------------------- - -Both GDB and LLDB support passing down environment variables. Is it ok to -respond with a "$#00" (unimplemented): - -send packet: $QEnvironment:41434b5f434f4c4f525f46494c454e414d453d626f6c642379656c6c6f77#00 -read packet: $OK#00 - -This packet can be sent one or more times _prior_ to sending a "A" packet. - -//---------------------------------------------------------------------- -// "QEnableErrorStrings" -// -// BRIEF -// This packet enables reporting of Error strings in remote packet -// replies from the server to client. If the server supports this -// feature, it should send an OK response. The client can expect the -// following error replies if this feature is enabled in the server -> -// -// EXX;AAAAAAAAA -// -// where AAAAAAAAA will be a hex encoded ASCII string. -// XX is hex encoded byte number. -// -// It must be noted that even if the client has enabled reporting -// strings in error replies, it must not expect error strings to all -// error replies. -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to provide strings that -// are human readable along with an error code. -//---------------------------------------------------------------------- - -send packet: $QEnableErrorStrings -read packet: $OK#00 - -//---------------------------------------------------------------------- -// "QSetSTDIN:<ascii-hex-path>" -// "QSetSTDOUT:<ascii-hex-path>" -// "QSetSTDERR:<ascii-hex-path>" -// -// BRIEF -// Setup where STDIN, STDOUT, and STDERR go prior to sending an "A" -// packet. -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to launch a target after -// making a connection to a GDB server that isn't already connected to -// an inferior process. -//---------------------------------------------------------------------- - -When launching a program through the GDB remote protocol with the "A" packet, -you might also want to specify where stdin/out/err go: - -QSetSTDIN:<ascii-hex-path> -QSetSTDOUT:<ascii-hex-path> -QSetSTDERR:<ascii-hex-path> - -These packets must be sent _prior_ to sending a "A" packet. - -//---------------------------------------------------------------------- -// "QSetWorkingDir:<ascii-hex-path>" -// -// BRIEF -// Set the working directory prior to sending an "A" packet. -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to launch a target after -// making a connection to a GDB server that isn't already connected to -// an inferior process. -//---------------------------------------------------------------------- - -Or specify the working directory: - -QSetWorkingDir:<ascii-hex-path> - -This packet must be sent _prior_ to sending a "A" packet. - -//---------------------------------------------------------------------- -// "QSetDisableASLR:<bool>" -// -// BRIEF -// Enable or disable ASLR on the next "A" packet. -// -// PRIORITY TO IMPLEMENT -// Low. Only needed if the remote target wants to launch a target after -// making a connection to a GDB server that isn't already connected to -// an inferior process and if the target supports disabling ASLR -// (Address space layout randomization). -//---------------------------------------------------------------------- - -Or control if ASLR is enabled/disabled: - -send packet: QSetDisableASLR:1 -read packet: OK - -send packet: QSetDisableASLR:0 -read packet: OK - -This packet must be sent _prior_ to sending a "A" packet. - -//---------------------------------------------------------------------- -// QListThreadsInStopReply -// -// BRIEF -// Enable the threads: and thread-pcs: data in the question-mark packet -// ("T packet") responses when the stub reports that a program has -// stopped executing. -// -// PRIORITY TO IMPLEMENT -// Performance. This is a performance benefit to lldb if the thread id's -// and thread pc values are provided to lldb in the T stop packet -- if -// they are not provided to lldb, lldb will likely need to send one to -// two packets per thread to fetch the data at every private stop. -//---------------------------------------------------------------------- - -send packet: QListThreadsInStopReply -read packet: OK - -//---------------------------------------------------------------------- -// jLLDBTraceSupported -// -// BRIEF -// Get the processor tracing type supported by the gdb-server for the current -// inferior. Responses might be different depending on the architecture and -// capabilities of the underlying OS. -// -// OUTPUT SCHEMA -// { -// "name": <string>, -// Tracing technology name, e.g. intel-pt, arm-etm. -// "description": <string>, -// Description for this technology. -// } -// -// If no tracing technology is supported for the inferior, or no process is -// running, then an error message is returned. -// -// NOTE -// This packet is used by Trace plug-ins (see lldb_private::Trace.h) to -// do live tracing. Specifically, the name of the plug-in should match the name -// of the tracing technology returned by this packet. -//---------------------------------------------------------------------- - -send packet: jLLDBTraceSupported -read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA - -//---------------------------------------------------------------------- -// jLLDBTraceStart -// -// BRIEF -// Start tracing a process or its threads using a provided tracing technology. -// The input and output are specified as JSON objects. In case of success, an OK -// response is returned, or an error otherwise. -// -// PROCESS TRACING -// This traces existing and future threads of the current process. An error is -// returned if the process is already being traced. -// -// THREAD TRACING -// This traces specific threads. -// -// INPUT SCHEMA -// { -// "type": <string>, -// Tracing technology name, e.g. intel-pt, arm-etm. -// -// /* thread tracing only */ -// "tids"?: [<decimal integer>], -// Individual threads to trace. -// -// ... other parameters specific to the provided tracing type -// } -// -// NOTES -// - If "tids" is not provided, then the operation is "process tracing", -// otherwise it's "thread tracing". -// - Each tracing technology can have different levels of support for "thread -// tracing" and "process tracing". -// -// INTEL-PT -// intel-pt supports both "thread tracing" and "process tracing". -// -// "Process tracing" is implemented in two different ways. If the -// "perCpuTracing" option is false, then each thread is traced individually -// but managed by the same "process trace" instance. This means that the -// amount of trace buffers used is proportional to the number of running -// threads. This is the recommended option unless the number of threads is -// huge. If "perCpuTracing" is true, then each cpu core is traced invidually -// instead of each thread, which uses a fixed number of trace buffers, but -// might result in less data available for less frequent threads. See -// "perCpuTracing" below for more information. -// -// Each actual intel pt trace buffer, either from "process tracing" or "thread -// tracing", is stored in an in-memory circular buffer, which keeps the most -// recent data. -// -// Additional params in the input schema: -// { -// "iptTraceSize": <decimal integer>, -// Size in bytes used by each individual per-thread or per-cpu trace -// buffer. It must be a power of 2 greater than or equal to 4096 (2^12) -// bytes. -// -// "enableTsc": <boolean>, -// Whether to enable TSC timestamps or not. This is supported on -// all devices that support intel-pt. A TSC timestamp is generated along -// with PSB (synchronization) packets, whose frequency can be configured -// with the "psbPeriod" parameter. -// -// "psbPeriod"?: <Optional decimal integer>, -// This value defines the period in which PSB packets will be generated. -// A PSB packet is a synchronization packet that contains a TSC -// timestamp and the current absolute instruction pointer. -// -// This parameter can only be used if -// -// /sys/bus/event_source/devices/intel_pt/caps/psb_cyc -// -// is 1. Otherwise, the PSB period will be defined by the processor. -// -// If supported, valid values for this period can be found in -/ -// /sys/bus/event_source/devices/intel_pt/caps/psb_periods -// -// which contains a hexadecimal number, whose bits represent valid -// values e.g. if bit 2 is set, then value 2 is valid. -// -// The psb_period value is converted to the approximate number of -// raw trace bytes between PSB packets as: -// -// 2 ^ (value + 11) -// -// e.g. value 3 means 16KiB between PSB packets. Defaults to -// 0 if supported. -// -// /* process tracing only */ -// "perCpuTracing": <boolean> -// Instead of having an individual trace buffer per thread, this option -// triggers the collection on a per cpu core basis. This effectively -// traces the entire activity on all cores. At decoding time, in order -// to correctly associate a decoded instruction with a thread, the -// context switch trace of each core is needed, as well as a record per -// cpu indicating which thread was running on each core when tracing -// started. These secondary traces are correlated with the intel-pt -// trace by comparing TSC timestamps. -// -// This option forces the capture of TSC timestamps (see "enableTsc"). -// -// Note: This option can't be used simulatenously with any other trace -// sessions because of its system-wide nature. -// -// /* process tracing only */ -// "processBufferSizeLimit": <decimal integer>, -// Maximum total buffer size per process in bytes. -// This limit applies to the sum of the sizes of all thread or cpu core -// buffers for the current process, excluding the ones started with -// "thread tracing". -// -// If "perCpuTracing" is false, whenever a thread is attempted to be -// traced due to "process tracing" and the limit would be reached, the -// process is stopped with a "tracing" reason along with a meaningful -// description, so that the user can retrace the process if needed. -// -// If "perCpuTracing" is true, then starting the system-wide trace -// session fails if all the individual per-cpu trace buffers require -// in total more memory that the limit impossed by this parameter. -// } -// -// Notes: -// - Modifying the parameters of an existing trace is not supported. The user -// needs to stop the trace and start a new one. -// - If "process tracing" is attempted and there are individual threads -// already being traced with "thread tracing", these traces are left -// unaffected and the threads not traced twice. -// - If "thread tracing" is attempted on a thread already being traced with -// either "thread tracing" or "process tracing", it fails. -//---------------------------------------------------------------------- - -Process tracing: -send packet: jLLDBTraceStart:{"type":<type>,...other params}] -read packet: OK/E<error code>;AAAAAAAAA - -Thread tracing: -send packet: jLLDBTraceStart:{"type":<type>,"tids":<tids>,...other params}] -read packet: OK/E<error code>;AAAAAAAAA - -//---------------------------------------------------------------------- -// jLLDBTraceStop -// -// BRIEF -// Stop tracing a process or its threads using a provided tracing technology. -// The input and output are specified as JSON objects. In case of success, an OK -// response is returned, or an error otherwise. -// -// PROCESS TRACE STOPPING -// Stopping a process trace stops the active traces initiated with -// "thread tracing". -// -// THREAD TRACE STOPPING -// This is a best effort request, which tries to stop as many traces as -// possible. -// -// INPUT SCHEMA -// The schema for the input is -// -// { -// "type": <string> -// Tracing technology name, e.g. intel-pt, arm-etm. -// -// /* thread trace stopping only */ -// "tids": [<decimal integer>] -// Individual thread traces to stop. -// } -// -// NOTES -// - If "tids" is not provided, then the operation is "process trace stopping". -// -// INTEL PT -// Stopping a specific thread trace started with "process tracing" is allowed. -//---------------------------------------------------------------------- - -Process trace stop... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/89718 _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
