[Lldb-commits] [lldb] [lldb[Docs] Reduce title noise in packets doc (PR #90183)
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Fri Apr 26 02:14:08 PDT 2024
https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/90183
This removes the "Brief" and "Description" subtitles and merges the text of both so that the contents listing is clearer.
>From 97468a99808fa0562f6c157b8a2703c48acc5ebc Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Thu, 25 Apr 2024 09:14:51 +0100
Subject: [PATCH 1/2] [lldb][docs] Remove "Brief" subheading from packet docs
This is just noise that clutters up the contents table.
---
lldb/docs/resources/lldbgdbremote.md | 128 ---------------------------
1 file changed, 128 deletions(-)
diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index 05e4f714f7f704..bc632c8af859e0 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -27,8 +27,6 @@ standard GDB remote protocol packets.
## QStartNoAckMode
-### Brief
-
Try to enable no ACK mode to skip sending ACKs and NACKs.
### Priority To Implement
@@ -54,8 +52,6 @@ send packet: +
## QSupported
-### Brief
-
Query the GDB remote server for features it supports
### Priority To Implement
@@ -99,8 +95,6 @@ In the example above, three lldb extensions are shown:
## "A" - launch args packet
-### Brief
-
Launch a program using the supplied arguments
### Priority To Implement
@@ -132,8 +126,6 @@ debugging.
## qLaunchSuccess
-### Brief
-
Check whether launching a process with the `A` packet succeeded.
### Description
@@ -148,8 +140,6 @@ High, launching processes is a key part of LLDB's platform mode.
## QEnvironment:NAME=VALUE
-### Brief
-
Setup the environment up for a new child process that will soon be
launched using the "A" packet.
@@ -179,8 +169,6 @@ 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.
@@ -206,8 +194,6 @@ 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
@@ -236,8 +222,6 @@ 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.
@@ -260,8 +244,6 @@ 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
@@ -280,8 +262,6 @@ This packet must be sent _prior_ to sending a "A" packet.
## qGetWorkingDir
-### Brief
-
Get the current working directory of the platform stub in
ASCII hex encoding.
@@ -294,8 +274,6 @@ send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f546573745
## QSetDisableASLR:\<bool\>
-### Brief
-
Enable or disable ASLR on the next "A" packet.
### Priority To Implement
@@ -319,8 +297,6 @@ 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.
@@ -341,8 +317,6 @@ 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.
@@ -376,8 +350,6 @@ read packet: {"name":<name>, "description":<description>}/E<error code>;AAAAAAAA
## 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.
@@ -530,8 +502,6 @@ 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.
@@ -583,8 +553,6 @@ read packet: OK/E<error code>;AAAAAAAAA
## jLLDBTraceGetState
-### Brief
-
Get the current state of the process and its threads being traced by
a given trace technology. The response is a JSON object with custom
information depending on the trace technology. In case of errors, an
@@ -690,8 +658,6 @@ read packet: {...object}/E<error code>;AAAAAAAAA
## jLLDBTraceGetBinaryData
-### Brief
-
Get binary data given a trace technology and a data identifier.
The input is specified as a JSON object and the response has the same format
as the "binary memory read" (aka "x") packet. In case of failures, an error
@@ -722,8 +688,6 @@ read packet: <binary data>/E<error code>;AAAAAAAAA
## qRegisterInfo\<hex-reg-id\>
-### Brief
-
Discover register information from the remote GDB server.
### Priority To Implement
@@ -1013,8 +977,6 @@ The keys and values are detailed below:
## qPlatform_shell
-### Brief
-
Run a command in a shell on the connected remote machine.
### Priority To Implement
@@ -1045,8 +1007,6 @@ drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
## qPlatform_mkdir
-### Brief
-
Creates a new directory on the connected remote machine.
### Priority To Implement
@@ -1070,8 +1030,6 @@ Reply:
## vFile:chmod / qPlatform_chmod
-### Brief
-
Change the permissions of a file on the connected remote machine.
### Priority To Implement
@@ -1090,8 +1048,6 @@ Reply:
## qHostInfo
-### Brief
-
Get information about the host we are remotely connected to.
### Priority To Implement
@@ -1149,8 +1105,6 @@ Key value pairs are one of:
## qGDBServerVersion
-### Brief
-
Get version information about this implementation of the gdb-remote
protocol.
@@ -1194,8 +1148,6 @@ Suggested key names:
## qProcessInfo
-### Brief
-
Get information about the process we are currently debugging.
### Priority To Implement
@@ -1249,8 +1201,6 @@ Key value pairs include:
## qShlibInfoAddr
-### Brief
-
Get an address where the dynamic linker stores information about
where shared libraries are loaded.
@@ -1280,8 +1230,6 @@ read packet: $7fff5fc40040#00
## qThreadStopInfo\<tid\>
-### Brief
-
Get information about why a thread, whose ID is `<tid>`, is stopped.
### Priority To Implement
@@ -1306,8 +1254,6 @@ to implement better multi-threaded debugging support.
## QThreadSuffixSupported
-### Brief
-
Try to enable thread suffix support for the `g`, `G`, `p`, and `P` packets.
### Priority To Implement
@@ -1361,8 +1307,6 @@ allocate memory so we can run JITed code.
## _M\<size\>,\<permissions\>
-### Brief
-
Allocate memory on the remote target with the specified size and
permissions.
@@ -1397,8 +1341,6 @@ is just the address of the newly allocated memory as raw big endian hex bytes.
## _m\<addr\>
-### Brief
-
Deallocate memory that was previously allocated using an allocate
memory pack.
@@ -1418,8 +1360,6 @@ empty response if not supported.
## qMemoryRegionInfo:\<addr\>
-### Brief
-
Get information about the address range that contains `<addr>`.
### Priority To Implement
@@ -1490,8 +1430,6 @@ for this region.
## "x" - Binary memory read
-### Brief
-
Like the `m` (read) and `M` (write) packets, this is a partner to the
`X` (write binary data) packet, `x`.
@@ -1546,8 +1484,6 @@ D
## QSaveRegisterState / QSaveRegisterState;thread:XXXX;
-### Brief
-
The `QSaveRegisterState` packet tells the remote debugserver to save
all registers and return a non-zero unique integer ID that
represents these save registers. If thread suffixes are enabled the
@@ -1576,8 +1512,6 @@ for the `QRestoreRegisterState` is added.
## QRestoreRegisterState:\<save_id\> / QRestoreRegisterState:\<save_id\>;thread:XXXX;
-### Brief
-
The `QRestoreRegisterState` packet tells the remote debugserver to
restore all registers using the `save_id` which is an unsigned
integer that was returned from a previous call to
@@ -1601,8 +1535,6 @@ for the `QSaveRegisterState` is added.
## qFileLoadAddress:\<file_path\>
-### Brief
-
Get the load address of a memory mapped file.
The load address is defined as the address of the first memory
region what contains data mapped from the specified file.
@@ -1620,8 +1552,6 @@ some object file in the rendezvous data structure.
## qModuleInfo:\<module_path\>;\<arch triple\>
-### Brief
-
Get information for a module by given module path and architecture.
### Response
@@ -1636,8 +1566,6 @@ UUID directly from inferior's memory.
## jModulesInfo:[{"file":"...",triple:"..."}, ...]
-### Brief
-
Get information for a list of modules by given module path and
architecture.
@@ -1664,8 +1592,6 @@ the communication link has a non-negligible latency.
## Stop reply packet extensions
-### Brief
-
This section describes some of the additional information you can
specify in stop reply packets that help LLDB to know more detailed
information about your threads.
@@ -1880,8 +1806,6 @@ your debug session more reliable and informative.
## qfProcessInfo / qsProcessInfo (Platform Extension)
-### Brief
-
Get the first process info (`qfProcessInfo`) or subsequent process
info (`qsProcessInfo`) for one or more processes on the remote
platform. The first call gets the first match and subsequent calls
@@ -1935,8 +1859,6 @@ read packet: $E04#00
## qPathComplete (Platform Extension)
-### Brief
-
Get a list of matched disk files/directories by passing a boolean flag
and a partial path.
@@ -1958,8 +1880,6 @@ Paths denoting a directory should end with a directory separator (`/` or `\`.
## qKillSpawnedProcess (Platform Extension)
-### Brief
-
Kill a process running on the target system.
### Example
@@ -1972,8 +1892,6 @@ The request packet has the process ID in base 10.
## qLaunchGDBServer (Platform Extension)
-### Brief
-
Have the remote platform launch a GDB server.
### Priority To Implement
@@ -2007,8 +1925,6 @@ to attach to in case zero was specified as the "port" in the sent command.
## qProcessInfoPID:PID (Platform Extension)
-### Brief
-
Have the remote platform get detailed information on a process by
ID. PID is specified as a decimal integer.
@@ -2039,8 +1955,6 @@ read packet: $pid:60050;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c64
## vAttachName
-### Brief
-
Same as `vAttach`, except instead of a `pid` you send a process name.
### Priority To Implement
@@ -2051,8 +1965,6 @@ it if attaching to a process by name makes sense for your environment.
## vAttachWait
-### Brief
-
Same as `vAttachName`, except that the stub should wait for the next instance
of a process by that name to be launched and attach to that.
@@ -2063,8 +1975,6 @@ gracefully if the packet is not supported.
## qAttachOrWaitSupported
-### Brief
-
This is a binary "is it supported" query. Return OK if you support
`vAttachOrWait`.
@@ -2076,8 +1986,6 @@ will do the right thing.
## vAttachOrWait
-### Brief
-
Same as `vAttachWait`, except that the stub will attach to a process
by name if it exists, and if it does not, it will wait for a process
of that name to appear and attach to it.
@@ -2094,8 +2002,6 @@ support this packet.
## jThreadExtendedInfo
-### Brief
-
This packet, which takes its arguments as JSON and sends its reply as
JSON, allows the gdb remote stub to provide additional information
about a given thread.
@@ -2157,8 +2063,6 @@ jThreadExtendedInfo:{"thread":612910}]
## QEnableCompression
-### Brief
-
This packet enables compression of the packets that the debug stub sends to lldb.
If the debug stub can support compression, it indictes this in the reply of the
"qSupported" packet. For example:
@@ -2218,8 +2122,6 @@ Example compression algorithms that may be used include:
## jGetLoadedDynamicLibrariesInfos
-### Brief
-
This packet asks the remote debug stub to send the details about libraries
being added/removed from the process as a performance optimization.
@@ -2313,8 +2215,6 @@ executable loaded.
## jThreadsInfo
-### Brief
-
Ask for the server for thread stop information of all threads.
### Priority To Implement
@@ -2381,8 +2281,6 @@ iOS now don't require us to read any memory!
## jGetSharedCacheInfo
-### Brief
-
This packet asks the remote debug stub to send the details about the inferior's
shared cache. The shared cache is a collection of common libraries/frameworks that
are mapped into every process at the same address on Darwin systems, and can be
@@ -2402,8 +2300,6 @@ them from the inferior process.
## qQueryGDBServer
-### Brief
-
Ask the platform for the list of gdbservers we have to connect
### Priority To Implement
@@ -2432,8 +2328,6 @@ Example packet:
## QSetDetachOnError
-### Brief
-
Sets what the server should do when the communication channel with LLDB
goes down. Either kill the inferior process (`0`) or remove breakpoints and
detach (`1`).
@@ -2451,8 +2345,6 @@ breakpoints and detach from the inferior.
## jGetDyldProcessState
-### Brief
-
This packet fetches the process launch state, as reported by libdyld on
Darwin systems, most importantly to indicate when the system libraries
have initialized sufficiently to safely call utility functions.
@@ -2476,8 +2368,6 @@ mismatches or extensions.
### vFile:size
-#### Brief
-
Get the size of a file on the target system, filename in ASCII hex.
#### Example
@@ -2492,8 +2382,6 @@ response is `F` followed by the file size in base 16.
### vFile:mode
-#### Brief
-
Get the mode bits of a file on the target system, filename in ASCII hex.
#### Example
@@ -2509,8 +2397,6 @@ correspond to `0755` in octal.
### vFile:unlink
-#### Brief
-
Remove a file on the target system.
#### Example
@@ -2527,8 +2413,6 @@ value of errno if unlink failed.
### vFile:symlink
-#### Brief
-
Create a symbolic link (symlink, soft-link) on the target system.
#### Example
@@ -2544,8 +2428,6 @@ optionally followed by the value of errno if it failed, also base 16.
### vFile:open
-#### Brief
-
Open a file on the remote system and return the file descriptor of it.
#### Example
@@ -2568,8 +2450,6 @@ response is `F` followed by the opened file descriptor in base 16.
### vFile:close
-#### Brief
-
Close a previously opened file descriptor.
#### Example
@@ -2584,8 +2464,6 @@ errno is base 16.
### vFile:pread
-#### Brief
-
Read data from an opened file descriptor.
#### Example
@@ -2605,8 +2483,6 @@ semicolon, followed by the data in the binary-escaped-data encoding.
### vFile:pwrite
-#### Brief
-
Write data to a previously opened file descriptor.
#### Example
@@ -2625,8 +2501,6 @@ Response is `F`, followed by the number of bytes written (base 16).
### vFile:MD5
-#### Brief
-
Generate an MD5 hash of the file at the given path.
#### Example
@@ -2648,8 +2522,6 @@ or failed to hash.
### vFile:exists
-#### Brief
-
Check whether the file at the given path exists.
#### Example
>From 68c54fbdc11455b8d24d995eb6f9a883ba3add3e Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 26 Apr 2024 10:12:19 +0100
Subject: [PATCH 2/2] remove "Description" titles
---
lldb/docs/resources/lldbgdbremote.md | 401 +++++++++++----------------
1 file changed, 168 insertions(+), 233 deletions(-)
diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index bc632c8af859e0..a9fa2a432b7009 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -29,14 +29,6 @@ standard GDB remote protocol packets.
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.
-
-### 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
@@ -50,15 +42,15 @@ read packet: $OK#9a
send packet: +
```
-## QSupported
-
-Query the GDB remote server for features it supports
-
### Priority To Implement
-Optional.
+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
+## QSupported
+
+Query the GDB remote server for features it supports
QSupported is a standard GDB Remote Serial Protocol packet, but
there are several additions to the response that lldb can parse.
@@ -92,19 +84,14 @@ In the example above, three lldb extensions are shown:
watchpoints, up to a pointer size, `sizeof(void*)`, a reasonable
baseline assumption.
+### Priority To Implement
+
+Optional.
## "A" - launch args packet
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.
-
-### 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:
@@ -124,12 +111,16 @@ 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.
+### 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.
+
## qLaunchSuccess
Check whether launching a process with the `A` packet succeeded.
-### Description
-
Returns the status of the last attempt to launch a process.
Either `OK` if no error ocurred, or `E` followed by a string
describing the error.
@@ -151,14 +142,6 @@ 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):
```
@@ -167,6 +150,12 @@ read packet: $OK#00
```
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 launch a target after
+making a connection to a GDB server that isn't already connected to
+an inferior process.
+
## QEnvironmentHexEncoded:HEX-ENCODING(NAME=VALUE)
Setup the environment up for a new child process that will soon be
@@ -176,14 +165,6 @@ 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):
```
@@ -192,6 +173,12 @@ read packet: $OK#00
```
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 launch a target after
+making a connection to a GDB server that isn't already connected to
+an inferior process.
+
## QEnableErrorStrings
This packet enables reporting of Error strings in remote packet
@@ -225,14 +212,6 @@ read packet: $OK#00
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.
-
-### 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:
```
@@ -242,17 +221,16 @@ QSetSTDERR:<ascii-hex-path>
```
These packets must be sent _prior_ to sending a "A" packet.
-## QSetWorkingDir:\<ascii-hex-path\>
-
-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.
-### Description
+
+## QSetWorkingDir:\<ascii-hex-path\>
+
+Set the working directory prior to sending an "A" packet.
Or specify the working directory:
```
@@ -260,6 +238,12 @@ QSetWorkingDir:<ascii-hex-path>
```
This packet must be sent _prior_ to sending a "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.
+
## qGetWorkingDir
Get the current working directory of the platform stub in
@@ -276,15 +260,6 @@ send: 2f4170706c65496e7465726e616c2f6c6c64622f73657474696e67732f342f546573745
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).
-
-### Description
-
Or control if ASLR is enabled/disabled:
```
send packet: QSetDisableASLR:1
@@ -295,6 +270,13 @@ read packet: OK
```
This packet must be sent _prior_ to sending a "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).
+
## QListThreadsInStopReply
Enable the `threads:` and `thread-pcs:` data in the question-mark packet
@@ -690,25 +672,6 @@ read packet: <binary data>/E<error code>;AAAAAAAAA
Discover register information from the remote GDB server.
-### Priority To Implement
-
-High. Any target that can self describe its registers, should do so.
-This means if new registers are ever added to a remote target, they
-will get picked up automatically, and allows registers to change
-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,
-`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
-gdb RSP stubs whereas `qRegisterInfo` was an lldb-only design.
-`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
@@ -974,17 +937,26 @@ The keys and values are detailed below:
modifying the CPSR register can cause the r8 - r14 and cpsr value to
change depending on if the mode has changed.
+### Priority To Implement
-## qPlatform_shell
-
-Run a command in a shell on the connected remote machine.
+High. Any target that can self describe its registers, should do so.
+This means if new registers are ever added to a remote target, they
+will get picked up automatically, and allows registers to change
+depending on the actual CPU type that is used.
-### Priority To Implement
+NB: `qRegisterInfo` is deprecated in favor of the standard gdb remote
+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
+gdb RSP stubs whereas `qRegisterInfo` was an lldb-only design.
+`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.
-High. This command allows LLDB clients to run arbitrary shell
-commands on a remote host.
+## qPlatform_shell
-### Description
+Run a command in a shell on the connected remote machine.
The request consists of the command to be executed encoded in ASCII characters
converted into hex bytes.
@@ -1005,16 +977,14 @@ drwxrwxr-x 5 username groupname 4096 Aug 15 21:36 source.cpp
-rw-r--r-- 1 username groupname 3190 Aug 12 16:46 Makefile
```
-## qPlatform_mkdir
-
-Creates a new directory on the connected remote machine.
-
### Priority To Implement
-Low. This command allows LLDB clients to create new directories on
-a remote host.
+High. This command allows LLDB clients to run arbitrary shell
+commands on a remote host.
-### Description
+## qPlatform_mkdir
+
+Creates a new directory on the connected remote machine.
Request: `qPlatform_mkdir:<hex-file-mode>,<ascii-hex-path>`
@@ -1027,18 +997,15 @@ Reply:
(mkdir called successfully and returned with the given return code)
* `Exx` (An error occurred)
+### Priority To Implement
+
+Low. This command allows LLDB clients to create new directories on
+a remote host.
## vFile:chmod / qPlatform_chmod
Change the permissions of a file on the connected remote machine.
-### Priority To Implement
-
-Low. This command allows LLDB clients to change the permissions of
-a file on the remote host.
-
-### Description
-
Request: `qPlatform_chmod:<hex-file-mode>,<ascii-hex-path>`
Reply:
@@ -1046,17 +1013,13 @@ Reply:
(chmod called successfully and returned with the given return code)
* `Exx` (An error occurred)
-## qHostInfo
-
-Get information about the host we are remotely connected to.
-
### Priority To Implement
-High. This packet is usually very easy to implement and can help
-LLDB select the correct plug-ins for the job based on the target
-triple information that is supplied.
+Low.
-### Description
+## qHostInfo
+
+Get information about the host we are remotely connected to.
LLDB supports a host info call that gets all sorts of details of the system
that is being debugged:
@@ -1103,18 +1066,16 @@ Key value pairs are one of:
AArch64 can have different page table setups for low and high
memory, and therefore a different number of bits used for addressing.
-## qGDBServerVersion
-
-Get version information about this implementation of the gdb-remote
-protocol.
-
### Priority To Implement
High. This packet is usually very easy to implement and can help
-LLDB to work around bugs in a server's implementation when they
-are found.
+LLDB select the correct plug-ins for the job based on the target
+triple information that is supplied.
-### Description
+## qGDBServerVersion
+
+Get version information about this implementation of the gdb-remote
+protocol.
The goal of this packet is to provide enough information about an
implementation of the gdb-remote-protocol server that lldb can
@@ -1146,6 +1107,12 @@ Suggested key names:
* `major_version`: major version number
* `minor_version`: minor version number
+### Priority To Implement
+
+High. This packet is usually very easy to implement and can help
+LLDB to work around bugs in a server's implementation when they
+are found.
+
## qProcessInfo
Get information about the process we are currently debugging.
@@ -1163,8 +1130,6 @@ process to know what you're working with.
All numeric fields return base 16 numbers without any "0x" prefix.
-### Description
-
An i386 process:
```
send packet: $qProcessInfo#00
@@ -1204,19 +1169,6 @@ Key value pairs include:
Get an address where the dynamic linker stores information about
where shared libraries are loaded.
-### Priority To Implement
-
-High if you have a dynamic loader plug-in in LLDB for your target
-triple (see the "qHostInfo" packet) that can use this information.
-Many times address load randomization can make it hard to detect
-where the dynamic loader binary and data structures are located and
-some platforms know, or can find out where this information is.
-
-Low if you have a debug target where all object and symbol files
-contain static load addresses.
-
-### Description
-
LLDB and GDB both support the `qShlibInfoAddr` packet which is a hint to each
debugger as to where to find the dynamic loader information. For darwin
binaries that run in user land this is the address of the `all_image_infos`
@@ -1228,10 +1180,29 @@ send packet: $qShlibInfoAddr#00
read packet: $7fff5fc40040#00
```
+### Priority To Implement
+
+High if you have a dynamic loader plug-in in LLDB for your target
+triple (see the "qHostInfo" packet) that can use this information.
+Many times address load randomization can make it hard to detect
+where the dynamic loader binary and data structures are located and
+some platforms know, or can find out where this information is.
+
+Low if you have a debug target where all object and symbol files
+contain static load addresses.
+
## qThreadStopInfo\<tid\>
Get information about why a thread, whose ID is `<tid>`, is stopped.
+LLDB tries to use the `qThreadStopInfo` packet which is formatted as
+`qThreadStopInfo%x` where `%x` is the hex thread ID. This requests information
+about why a thread is stopped. The response is the same as the stop reply
+packets and tells us what happened to the other threads. The standard GDB
+remote packets love to think that there is only _one_ reason that _one_ thread
+stops at a time. This allows us to see why all threads stopped and allows us
+to implement better multi-threaded debugging support.
+
### Priority To Implement
High if you need to support multi-threaded or multi-core debugging.
@@ -1242,32 +1213,10 @@ threads (live system debug) / cores (JTAG) in your program have
stopped and allows LLDB to display and control your program
correctly.
-### Description
-
-LLDB tries to use the `qThreadStopInfo` packet which is formatted as
-`qThreadStopInfo%x` where `%x` is the hex thread ID. This requests information
-about why a thread is stopped. The response is the same as the stop reply
-packets and tells us what happened to the other threads. The standard GDB
-remote packets love to think that there is only _one_ reason that _one_ thread
-stops at a time. This allows us to see why all threads stopped and allows us
-to implement better multi-threaded debugging support.
-
## QThreadSuffixSupported
Try to enable thread suffix support for the `g`, `G`, `p`, and `P` packets.
-### Priority To Implement
-
-High. Adding a thread suffix allows us to read and write registers
-more efficiently and stops us from having to select a thread with
-one packet and then read registers with a second packet. It also
-makes sure that no errors can occur where the debugger thinks it
-already has a thread selected (see the `Hg` packet from the standard
-GDB remote protocol documentation) yet the remote GDB server actually
-has another thread selected.
-
-### Description
-
When reading thread registers, you currently need to set the current
thread, then read the registers. This is kind of cumbersome, so we added the
ability to query if the remote GDB server supports adding a `thread:<tid>;`
@@ -1305,19 +1254,20 @@ read packet: ....
We also added support for allocating and deallocating memory. We use this to
allocate memory so we can run JITed code.
-## _M\<size\>,\<permissions\>
-
-Allocate memory on the remote target with the specified size and
-permissions.
-
### Priority To Implement
-High if you want LLDB to be able to JIT code and run that code. JIT
-code also needs data which is also allocated and tracked.
+High. Adding a thread suffix allows us to read and write registers
+more efficiently and stops us from having to select a thread with
+one packet and then read registers with a second packet. It also
+makes sure that no errors can occur where the debugger thinks it
+already has a thread selected (see the `Hg` packet from the standard
+GDB remote protocol documentation) yet the remote GDB server actually
+has another thread selected.
-Low if you don't support running JIT'ed code.
+## _M\<size\>,\<permissions\>
-### Description
+Allocate memory on the remote target with the specified size and
+permissions.
The allocate memory packet starts with `_M<size>,<permissions>`. It returns a
raw big endian address value, or an empty response for unimplemented, or `EXX` for an error
@@ -1339,11 +1289,6 @@ You request a size and give the permissions. This packet does NOT need to be
implemented if you don't want to support running JITed code. The return value
is just the address of the newly allocated memory as raw big endian hex bytes.
-## _m\<addr\>
-
-Deallocate memory that was previously allocated using an allocate
-memory pack.
-
### Priority To Implement
High if you want LLDB to be able to JIT code and run that code. JIT
@@ -1351,28 +1296,26 @@ code also needs data which is also allocated and tracked.
Low if you don't support running JIT'ed code.
-### Description
+## _m\<addr\>
+
+Deallocate memory that was previously allocated using an allocate
+memory pack.
The deallocate memory packet is `_m<addr>` where you pass in the address you
got back from a previous call to the allocate memory packet. It returns `OK`
if the memory was successfully deallocated, or `EXX`" for an error, or an
empty response if not supported.
-## qMemoryRegionInfo:\<addr\>
+### Priority To Implement
-Get information about the address range that contains `<addr>`.
+High if you want LLDB to be able to JIT code and run that code. JIT
+code also needs data which is also allocated and tracked.
-### Priority To Implement
+Low if you don't support running JIT'ed code.
-Medium. This is nice to have, but it isn't necessary. It helps LLDB
-do stack unwinding when we branch into memory that isn't executable.
-If we can detect that the code we are stopped in isn't executable,
-then we can recover registers for stack frames above the current
-frame. Otherwise we must assume we are in some JIT'ed code (not JIT
-code that LLDB has made) and assume that no registers are available
-in higher stack frames.
+## qMemoryRegionInfo:\<addr\>
-### Description
+Get information about the address range that contains `<addr>`.
We added a way to get information for a memory region. The packet is:
```
@@ -1428,6 +1371,16 @@ For instance, with a macOS process which has nothing mapped in the first
The lack of `permissions:` indicates that none of read/write/execute are valid
for this region.
+### Priority To Implement
+
+Medium. This is nice to have, but it isn't necessary. It helps LLDB
+do stack unwinding when we branch into memory that isn't executable.
+If we can detect that the code we are stopped in isn't executable,
+then we can recover registers for stack frames above the current
+frame. Otherwise we must assume we are in some JIT'ed code (not JIT
+code that LLDB has made) and assume that no registers are available
+in higher stack frames.
+
## "x" - Binary memory read
Like the `m` (read) and `M` (write) packets, this is a partner to the
@@ -1462,8 +1415,6 @@ transport layer is assumed.
## Detach and stay stopped
-### Description
-
We extended the "D" packet to specify that the monitor should keep the
target suspended on detach. The normal behavior is to resume execution
on detach. We will send:
@@ -1596,8 +1547,6 @@ This section describes some of the additional information you can
specify in stop reply packets that help LLDB to know more detailed
information about your threads.
-### Description
-
Standard GDB remote stop reply packets are reply packets sent in
response to a packet that made the program run. They come in the
following forms:
@@ -1812,11 +1761,9 @@ platform. The first call gets the first match and subsequent calls
to `qsProcessInfo` gets the subsequent matches. Return an error `EXX`,
where `XX` are two hex digits, when no more matches are available.
-### Priority To Implement
-Required. The `qfProcessInfo` packet can be followed by a `:` and
+ The `qfProcessInfo` packet can be followed by a `:` and
some key value pairs. The key value pairs in the command are:
-
* `name` - `ascii-hex` -
An ASCII hex string that contains the name of the process that will be matched.
* `name_match` - `enum` -
@@ -1857,6 +1804,10 @@ send packet: $qsProcessInfo#00
read packet: $E04#00
```
+### Priority To Implement
+
+Required.
+
## qPathComplete (Platform Extension)
Get a list of matched disk files/directories by passing a boolean flag
@@ -1894,9 +1845,7 @@ The request packet has the process ID in base 10.
Have the remote platform launch a GDB server.
-### Priority To Implement
-
-Required. The `qLaunchGDBServer` packet must be followed by a `:` and
+The `qLaunchGDBServer` packet must be followed by a `:` and
some key value pairs. The key value pairs in the command are:
* `port` - `integer` -
A string value containing the decimal port ID or zero if the port should be
@@ -1904,11 +1853,6 @@ some key value pairs. The key value pairs in the command are:
* `host` - `integer` -
The host that connections should be limited to when the GDB server is connected to.
-### Description
-
-The response consists of key/value pairs where the key is separated from the
-values with colons and each pair is terminated with a semi colon.
-
Sample packet/response:
```
send packet: $qLaunchGDBServer:port:0;host:lldb.apple.com;#00
@@ -1922,18 +1866,15 @@ process was separately launched.
The `port` key/value pair in the response lets clients know what port number
to attach to in case zero was specified as the "port" in the sent command.
+### Priority To Implement
+
+Required.
## qProcessInfoPID:PID (Platform Extension)
Have the remote platform get detailed information on a process by
ID. PID is specified as a decimal integer.
-### Priority To Implement
-
-Optional.
-
-### Description
-
The response consists of key/value pairs where the key is separated from the
values with colons and each pair is terminated with a semi colon.
@@ -1953,6 +1894,10 @@ send packet: $qProcessInfoPID:60050#00
read packet: $pid:60050;ppid:59948;uid:7746;gid:11;euid:7746;egid:11;name:6c6c6462;triple:x86_64-apple-macosx;#00
```
+### Priority To Implement
+
+Optional.
+
## vAttachName
Same as `vAttach`, except instead of a `pid` you send a process name.
@@ -2006,14 +1951,6 @@ This packet, which takes its arguments as JSON and sends its reply as
JSON, allows the gdb remote stub to provide additional information
about a given thread.
-### Priority To Implement
-
-Low. This packet is only needed if the gdb remote stub wants to
-provide interesting additional information about a thread for the
-user.
-
-### Description
-
This packet takes its arguments in [JSON](http://www.json.org).
At a minimum, a thread must be specified, for example:
```
@@ -2061,6 +1998,12 @@ like:
jThreadExtendedInfo:{"thread":612910}]
```
+### Priority To Implement
+
+Low. This packet is only needed if the gdb remote stub wants to
+provide interesting additional information about a thread for the
+user.
+
## QEnableCompression
This packet enables compression of the packets that the debug stub sends to lldb.
@@ -2195,8 +2138,6 @@ STUB REPLIES: ${"images":
}
```
-### Description
-
This is similar to the `qXfer:libraries:read` packet, and it could
be argued that it should be merged into that packet. A separate
packet was created primarily because lldb needs to specify the
@@ -2217,14 +2158,6 @@ executable loaded.
Ask for the server for thread stop information of all threads.
-### Priority To Implement
-
-Low. This is a performance optimization, which speeds up debugging by avoiding
-multiple round-trips for retrieving thread information. The information from this
-packet can be retrieved using a combination of `qThreadStopInfo` and `m` packets.
-
-### Description
-
The data in this packet is very similar to the stop reply packets, but is packaged in
JSON and uses JSON arrays where applicable. The JSON output looks like:
```
@@ -2279,6 +2212,12 @@ On macOS with debugserver, we expedite the frame pointer backchain for a thread
the previous FP and PC), and follow the backchain. Most backtraces on macOS and
iOS now don't require us to read any memory!
+### Priority To Implement
+
+Low. This is a performance optimization, which speeds up debugging by avoiding
+multiple round-trips for retrieving thread information. The information from this
+packet can be retrieved using a combination of `qThreadStopInfo` and `m` packets.
+
## jGetSharedCacheInfo
This packet asks the remote debug stub to send the details about the inferior's
@@ -2302,13 +2241,6 @@ them from the inferior process.
Ask the platform for the list of gdbservers we have to connect
-### Priority To Implement
-
-Low. The packet is required to support connecting to gdbserver started
-by the platform instance automatically.
-
-### Description
-
If the remote platform automatically started one or more gdbserver instance (without
lldb asking it) then it have to return the list of port number or socket name for
each of them what can be used by lldb to connect to those instances.
@@ -2326,23 +2258,26 @@ Example packet:
]
```
+### Priority To Implement
+
+Low. The packet is required to support connecting to gdbserver started
+by the platform instance automatically.
+
## QSetDetachOnError
Sets what the server should do when the communication channel with LLDB
goes down. Either kill the inferior process (`0`) or remove breakpoints and
detach (`1`).
+The data in this packet is a single a character, which should be `0` if the
+inferior process should be killed, or `1` if the server should remove all
+breakpoints and detach from the inferior.
+
### Priority To Implement
Low. Only required if the target wants to keep the inferior process alive
when the communication channel goes down.
-### Description
-
-The data in this packet is a single a character, which should be `0` if the
-inferior process should be killed, or `1` if the server should remove all
-breakpoints and detach from the inferior.
-
## jGetDyldProcessState
This packet fetches the process launch state, as reported by libdyld on
More information about the lldb-commits
mailing list