[Lldb-commits] [lldb] [lldb] Document some more packets (PR #92124)

[David Spickett via lldb-commits]

https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/92124

Comparing a bit of the mock GDB server code to what was in the document I found these:
* QLaunchArch
* qSpeedTest
* qSymbol

qSymbol is the most mysterious but it did have some examples in a comment so I've adapted that.

>From 0da56876f1d421c14b7af493da826e49ed272e6f Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Tue, 14 May 2024 10:47:33 +0100
Subject: [PATCH] [lldb] Document some more packets

Comparing a bit of the mock GDB server code to what was in the
document I found these.

qSymbol is the most mysterious but it did have some examples
in a comment so I've adapted that.
---
 lldb/docs/resources/lldbgdbremote.md | 87 ++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index 1467723fb79dc..7076a75032dae 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -867,6 +867,22 @@ 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.
 
+## QLaunchArch
+
+Set the architecture to use when launching a process for hosts that can run
+multiple architecture slices that are contained in a single universal program
+file.
+
+```
+send packet: $QLaunchArch:<architecture>
+```
+
+The response is `OK` if the value in `<architecture>` was recognised as valid
+and will be used for the next launch request. `E63` if not.
+
+**Priority To Implement:** Only required for hosts that support program files
+that contain code for multiple architectures.
+
 ## QListThreadsInStopReply
 
 Enable the `threads:` and `thread-pcs:` data in the question-mark packet
@@ -1883,6 +1899,77 @@ 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.
 
+## qSpeedTest
+
+Test the maximum speed at which packets can be sent and received.
+
+```
+send packet: qSpeedTest:response_size:<response size>;
+read packet: data:<response data>
+```
+
+`<response size>` is a hex encoded unsigned number up to 64 bits in size.
+The remote will respond with `data:` followed by a block of `a` characters
+whose size should match `<response size>`, if the connection is stable.
+
+If there is an error parsing the packet, the response is `E79`.
+
+This packet is used by LLDB to discover how reliable the connection is by
+varying the amount of data requested by `<response size>` and checking whether
+the expected amount and values were received.
+
+**Priority to Implemment:** Not required for debugging on the same host, otherwise
+low unless you know your connection quality is variable.
+
+## qSymbol
+
+Notify the remote that LLDB is ready to do symbol lookups on behalf of the
+debug server. The response is the symbol name the debug server wants to know the
+value of, or `OK` if the debug server does not need to know any more symbol values.
+
+The exchange always begins with:
+```
+send packet: qSymbol::
+```
+
+The `::` are delimiters for fields that may be filled in future responses. These
+delimiters must be included even in the first packet sent.
+
+The debug server can reply one of two ways. If it doesn't need any symbol values:
+```
+read packet: OK
+```
+
+If it does need a symbol value, it includes the ASCII hex encoded name of the
+symbol:
+```
+read packet: qSymbol:6578616D706C65
+```
+
+This should be looked up by LLDB then sent back to the server. Include the name
+again, with the vaue as a hex number:
+```
+read packet: qSymbol:6578616D706C65:CAFEF00D
+```
+
+If LLDB cannot find the value, it should respond with only the name. Note that
+the second `:` is not included here, whereas it is in the initial packet.
+```
+read packet: qSymbol:6578616D706C65
+```
+
+If LLDB is asked for any symbols that it cannot find, it should send the
+initial `qSymbol::` again at any point where new libraries are loaded. In case
+the symbol can now be resolved.
+
+If the debug server has requested all the symbols it wants, the final response
+will be `OK` (whether they were all found or not).
+
+If LLDB did find all the symbols and recieves an `OK` it does not need to send
+`qSymbol::` again during the debug session.
+
+**Priority To Implement:** Low, this is rarely used.
+
 ## qThreadStopInfo\<tid\>
 
 Get information about why a thread, whose ID is `<tid>`, is stopped.