llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT--> @llvm/pr-subscribers-lldb Author: David Spickett (DavidSpickett) <details> <summary>Changes</summary> If someone (aka me) wanted to convert this into another format (aka Markdown), these changes mean you can more easily script that conversion. --- Patch is 118.87 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/89587.diff 1 Files Affected: - (modified) lldb/docs/lldb-gdb-remote.txt (+960-933) ``````````diff diff --git a/lldb/docs/lldb-gdb-remote.txt b/lldb/docs/lldb-gdb-remote.txt index 6c29de61daba7e..15e32153354962 100644 --- a/lldb/docs/lldb-gdb-remote.txt +++ b/lldb/docs/lldb-gdb-remote.txt @@ -25,18 +25,20 @@ added above and beyond the standard GDB remote protocol packets. // 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. +// +// DESCRIPTION +// 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: + //---------------------------------------------------------------------- -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" @@ -46,38 +48,39 @@ send packet: + // // PRIORITY TO IMPLEMENT // Optional. +// +// DESCRIPTION +// 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. //---------------------------------------------------------------------- -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 // @@ -88,27 +91,28 @@ In the example above, three lldb extensions are shown: // 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. +// +// DESCRIPTION +// 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. //---------------------------------------------------------------------- -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" // @@ -116,28 +120,29 @@ debugging. // 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. +// 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. +// +// DESCRIPTION +// 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. //---------------------------------------------------------------------- -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)" // @@ -145,24 +150,25 @@ This packet can be sent one or more times _prior_ to sending a "A" packet. // 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. +// 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. +// +// DESCRIPTION +// 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. //---------------------------------------------------------------------- -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" // @@ -184,11 +190,12 @@ This packet can be sent one or more times _prior_ to sending a "A" packet. // PRIORITY TO IMPLEMENT // Low. Only needed if the remote target wants to provide strings that // are human readable along with an error code. +// +// EXAMPLE +// send packet: $QEnableErrorStrings +// read packet: $OK#00 //---------------------------------------------------------------------- -send packet: $QEnableErrorStrings -read packet: $OK#00 - //---------------------------------------------------------------------- // "QSetSTDIN:<ascii-hex-path>" // "QSetSTDOUT:<ascii-hex-path>" @@ -202,17 +209,18 @@ read packet: $OK#00 // 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. +// +// DESCRIPTION +// 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. //---------------------------------------------------------------------- -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>" // @@ -223,14 +231,15 @@ These packets must be sent _prior_ to sending a "A" packet. // 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. +// +// DESCRIPTION +// Or specify the working directory: +// +// QSetWorkingDir:<ascii-hex-path> +// +// This packet must be sent _prior_ to sending a "A" packet. //---------------------------------------------------------------------- -Or specify the working directory: - -QSetWorkingDir:<ascii-hex-path> - -This packet must be sent _prior_ to sending a "A" packet. - //---------------------------------------------------------------------- // "QSetDisableASLR:<bool>" // @@ -242,18 +251,19 @@ This packet must be sent _prior_ to sending a "A" packet. // 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). +// +// DESCRIPTION +// 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. //---------------------------------------------------------------------- -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 // @@ -267,11 +277,12 @@ This packet must be sent _prior_ to sending a "A" packet. // 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. +// +// EXAMPLE +// send packet: QListThreadsInStopReply +// read packet: OK //---------------------------------------------------------------------- -send packet: QListThreadsInStopReply -read packet: OK - //---------------------------------------------------------------------- // jLLDBTraceSupported // @@ -295,11 +306,12 @@ read packet: OK // 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. +// +// EXAMPLE +// send packet: jLLDBTraceSupported +// read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA //---------------------------------------------------------------------- -send packet: jLLDBTraceSupported -read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAAA - //---------------------------------------------------------------------- // jLLDBTraceStart // @@ -430,16 +442,17 @@ read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAA // 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. +// +// EXAMPLES +// 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 //---------------------------------------------------------------------- -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 // @@ -473,16 +486,17 @@ read packet: OK/E<error code>;AAAAAAAAA // // INTEL PT // Stopping a specific thread trace started with "process tracing" is allowed. +// +// EXAMPLES +// Process trace stopping: +// send packet: jLLDBTraceStop:{"type":<type>}] +// read packet: OK/E<error code>;AAAAAAAAA +// +// Thread trace stopping: +// send packet: jLLDBTraceStop:{"type":<type>,"tids":<tids>}] +// read packet: OK/E<error code>;AAAAAAAAA //---------------------------------------------------------------------- -Process trace stopping: -send packet: jLLDBTraceStop:{"type":<type>}] -read packet: OK/E<error code>;AAAAAAAAA - -Thread trace stopping: -send packet: jLLDBTraceStop:{"type":<type>,"tids":<tids>}] -read packet: OK/E<error code>;AAAAAAAAA - //---------------------------------------------------------------------- // jLLDBTraceGetState // @@ -567,7 +581,7 @@ read packet: OK/E<error code>;AAAAAAAAA // See the documentation of time_zero in // https://man7.org/linux/man-pages/man2/perf_event_open.2.html for more information about // the calculation and the meaning of the values in the schema below. -/// +// // Schema for this field: // // "tscPerfZeroConversion": { @@ -575,11 +589,12 @@ read packet: OK/E<error code>;AAAAAAAAA // "timeShift": <decimal integer>, // "timeZero": <decimal integer>, // } +// +// EXAMPLE +// send packet: jLLDBTraceGetState:{"type":<type>}] +// read packet: {...object}/E<error code>;AAAAAAAAA //---------------------------------------------------------------------- -send packet: jLLDBTraceGetState:{"type":<type>}] -read packet: {...object}/E<error code>;AAAAAAAAA - //---------------------------------------------------------------------- // jLLDBTraceGetBinaryData // @@ -602,11 +617,12 @@ read packet: {...object}/E<error code>;AAAAAAAAA // "tid"?: <Optional decimal>, // Tid in decimal if the data belongs to a thread. // } +// +// EXAMPLE +// send packet: jLLDBTraceGetBinaryData:{"type":<type>,"kind":<query>,"tid":<tid>,"offset":<offset>,"size":<size>}] +// read packet: <binary data>/E<error code>;AAAAAAAAA //---------------------------------------------------------------------- -send packet: jLLDBTraceGetBinaryData:{"type":<type>,"kind":<query>,"tid":<tid>,"offset":<offset>,"size":<size>}] -read packet: <binary data>/E<error code>;AAAAAAAAA - //---------------------------------------------------------------------- // "qRegisterInfo<hex-reg-id>" // @@ -620,7 +636,7 @@ read packet: <binary data>/E<error code>;AAAAAAAAA // depending on the actual CPU type that is used. // // NB: qRegisterInfo is deprecated in favor of the standard gdb remote -// serial protocol register description method, +// serial protocol register description method, // "qXfer:features:read:target.xml". // If qXfer:features:read:target.xml is supported, qRegisterInfo does // not need to be implemented. The target.xml format is used by most @@ -628,278 +644,279 @@ read packet: <binary data>/E<error code>;AAAAAAAAA // qRegisterInfo requires one packet per register and can have undesirable // performance costs at the start of a debug session, whereas target.xml // may be able to describe all registers in a single packet. +// +// DESCRIPTION +// With LLDB, for register information, remote GDB servers can add +// support for the "qRegisterInfoN" packet where "N" is a zero based +// base 16 register number that must start at zero and increase by one +// for each register that is supported. The response is done in typical +// GDB remote fashion where a series of "KEY:VALUE;" pairs are returned. +// An example for the x86_64 registers is included below: +// +// send packet: $qRegisterInfo0#00 +// read packet: $name:rax;bitsize:64;offset:0;encoding:uint;format:hex;set:General Purpose Registers;gcc:0;dwarf:0;#00 +// send packet: $qRegisterInfo1#00 +// read packet: $name:rbx;bitsize:64;offset:8;encoding:uint;format:hex;set:General Purpose Registers;gcc:3;dwarf:3;#00 +// ... [truncated] `````````` </details> https://github.com/llvm/llvm-project/pull/89587 _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
