[Lldb-commits] [lldb] [gdbremote] Document MultiMemRead packet in protocol extensions (PR #162675)

Sat Oct 11 06:54:02 PDT 2025

https://github.com/felipepiovezan updated https://github.com/llvm/llvm-project/pull/162675

>From f7e3f64b9aa513f6ca24627366482ff7fc19cac9 Mon Sep 17 00:00:00 2001
From: Felipe de Azevedo Piovezan <fpiovezan at apple.com>
Date: Wed, 8 Oct 2025 08:23:41 -0700
Subject: [PATCH 1/3] [gdbremote] Document MultiMemRead packet in protocol
 extensions

This adds a specification for the new packet discussed in the RFC [1].

[1]: https://discourse.llvm.org/t/rfc-a-new-vectorized-memory-read-packet/88441/12
---
 lldb/docs/resources/lldbgdbremote.md | 38 ++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index 36b95f1073ebc..d5e42890e14b1 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -2530,3 +2530,41 @@ read packet: $e0030100#b9
 
 **Priority to Implement:** Only required for Wasm support. Necessary to show
 variables.
+
+### MultiMemRead
+
+Read memory from multiple memory addresses.
+
+There are two arguments to the request:
+
+* `ranges`: a list of base-16 pairs of numbers. Each pair is separated by a
+`,`, as is each number in the pair. The first number of the pair denotes the
+base address of the memory read, the second denotes the number of bytes to be
+read.
+* `options`: an optional string of options. If present, it may be empty. If
+present, it is the last argument of the request.
+
+Both arguments must end with a `;`.
+
+The reply packet starts with a comma-separated list of base-16 numbers,
+denoting how many bytes were read from each address, followed by a `;`,
+followed by a sequence of bytes containing the memory data. The length of this
+sequence must be equal to the sum of the numbers provided at the start of the
+reply.
+
+If the stub is unable to read from any individual address, it should return a
+length of "zero" for that address in the reply packet.
+
+A stub that supports this packet should return `MultiMemRead+` in the reply to
+`qSupported`.
+
+```
+send packet: $MultiMemRead:ranges:100a00,4,200200,a0,400000,4;
+read packet: $4,0,2;<binary encoding of abcd1000><binary encoding of eeff>
+```
+
+In the example above, the first read produced `abcd1000`, the read of `a0`
+bytes from address `200200` failed, and the third read produced two bytes –
+`eeff` – out of the four requested.
+
+**Priority to Implement:** Only required for performance.

>From df6ec38809f7b9e63cdf6f8e4d28a7d95b5fe088 Mon Sep 17 00:00:00 2001
From: Felipe de Azevedo Piovezan <fpiovezan at apple.com>
Date: Fri, 10 Oct 2025 13:31:42 -0700
Subject: [PATCH 2/3] fixup! Place doc alphabetically

---
 lldb/docs/resources/lldbgdbremote.md | 76 ++++++++++++++--------------
 1 file changed, 38 insertions(+), 38 deletions(-)

diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index d5e42890e14b1..cc9ed7bae585e 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -735,6 +735,44 @@ 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.
 
+### MultiMemRead
+
+Read memory from multiple memory addresses.
+
+There are two arguments to the request:
+
+* `ranges`: a list of base-16 pairs of numbers. Each pair is separated by a
+`,`, as is each number in the pair. The first number of the pair denotes the
+base address of the memory read, the second denotes the number of bytes to be
+read.
+* `options`: an optional string of options. If present, it may be empty. If
+present, it is the last argument of the request.
+
+Both arguments must end with a `;`.
+
+The reply packet starts with a comma-separated list of base-16 numbers,
+denoting how many bytes were read from each address, followed by a `;`,
+followed by a sequence of bytes containing the memory data. The length of this
+sequence must be equal to the sum of the numbers provided at the start of the
+reply.
+
+If the stub is unable to read from any individual address, it should return a
+length of "zero" for that address in the reply packet.
+
+A stub that supports this packet should return `MultiMemRead+` in the reply to
+`qSupported`.
+
+```
+send packet: $MultiMemRead:ranges:100a00,4,200200,a0,400000,4;
+read packet: $4,0,2;<binary encoding of abcd1000><binary encoding of eeff>
+```
+
+In the example above, the first read produced `abcd1000`, the read of `a0`
+bytes from address `200200` failed, and the third read produced two bytes –
+`eeff` – out of the four requested.
+
+**Priority to Implement:** Only required for performance.
+
 ## QEnvironment:NAME=VALUE
 
 Setup the environment up for a new child process that will soon be
@@ -2530,41 +2568,3 @@ read packet: $e0030100#b9
 
 **Priority to Implement:** Only required for Wasm support. Necessary to show
 variables.
-
-### MultiMemRead
-
-Read memory from multiple memory addresses.
-
-There are two arguments to the request:
-
-* `ranges`: a list of base-16 pairs of numbers. Each pair is separated by a
-`,`, as is each number in the pair. The first number of the pair denotes the
-base address of the memory read, the second denotes the number of bytes to be
-read.
-* `options`: an optional string of options. If present, it may be empty. If
-present, it is the last argument of the request.
-
-Both arguments must end with a `;`.
-
-The reply packet starts with a comma-separated list of base-16 numbers,
-denoting how many bytes were read from each address, followed by a `;`,
-followed by a sequence of bytes containing the memory data. The length of this
-sequence must be equal to the sum of the numbers provided at the start of the
-reply.
-
-If the stub is unable to read from any individual address, it should return a
-length of "zero" for that address in the reply packet.
-
-A stub that supports this packet should return `MultiMemRead+` in the reply to
-`qSupported`.
-
-```
-send packet: $MultiMemRead:ranges:100a00,4,200200,a0,400000,4;
-read packet: $4,0,2;<binary encoding of abcd1000><binary encoding of eeff>
-```
-
-In the example above, the first read produced `abcd1000`, the read of `a0`
-bytes from address `200200` failed, and the third read produced two bytes –
-`eeff` – out of the four requested.
-
-**Priority to Implement:** Only required for performance.

>From 5acd41810b4b05b5780b0c8d9a936595af656a09 Mon Sep 17 00:00:00 2001
From: Felipe de Azevedo Piovezan <fpiovezan at apple.com>
Date: Sat, 11 Oct 2025 06:53:34 -0700
Subject: [PATCH 3/3] fixup! Address review comments

---
 lldb/docs/resources/lldbgdbremote.md | 52 +++++++++++++++++-----------
 1 file changed, 32 insertions(+), 20 deletions(-)

diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md
index cc9ed7bae585e..2657dd9c59020 100644
--- a/lldb/docs/resources/lldbgdbremote.md
+++ b/lldb/docs/resources/lldbgdbremote.md
@@ -737,29 +737,31 @@ packet can be retrieved using a combination of `qThreadStopInfo` and `m` packets
 
 ### MultiMemRead
 
-Read memory from multiple memory addresses.
+Read memory from multiple memory ranges.
 
-There are two arguments to the request:
+This packet has one argument:
 
-* `ranges`: a list of base-16 pairs of numbers. Each pair is separated by a
-`,`, as is each number in the pair. The first number of the pair denotes the
-base address of the memory read, the second denotes the number of bytes to be
-read.
-* `options`: an optional string of options. If present, it may be empty. If
-present, it is the last argument of the request.
+* `ranges`: a list of pairs of numbers, formatted in base-16. Each pair is
+separated by a `,`, as is each number in each pair. The first number of the
+pair denotes the base address of the memory read, the second denotes the number
+of bytes to be read. The list must end with a `;`.
 
-Both arguments must end with a `;`.
+The reply packet starts with a comma-separated list of numbers formatted in
+base-16, denoting how many bytes were read from each range, in the same order
+as the request packet. The list is followed by a `;`, followed by a sequence of
+bytes containing binary encoded data for all memory that was read. The length
+of this sequence must be equal to the sum of the numbers provided at the start
+of the reply. The order of the binary data is the same as the order of the
+ranges in the request packet.
 
-The reply packet starts with a comma-separated list of base-16 numbers,
-denoting how many bytes were read from each address, followed by a `;`,
-followed by a sequence of bytes containing the memory data. The length of this
-sequence must be equal to the sum of the numbers provided at the start of the
-reply.
+If an entire range is not readable, the stub may perform a partial read of a
+prefix of the range.
 
-If the stub is unable to read from any individual address, it should return a
-length of "zero" for that address in the reply packet.
+If the stub is unable to read any bytes from a particular range, it must return
+a length of "zero" for that range in the reply packet; no bytes for this memory
+range are included in the sequence of bytes that follows.
 
-A stub that supports this packet should return `MultiMemRead+` in the reply to
+A stub that supports this packet must include `MultiMemRead+` in the reply to
 `qSupported`.
 
 ```
@@ -768,10 +770,20 @@ read packet: $4,0,2;<binary encoding of abcd1000><binary encoding of eeff>
 ```
 
 In the example above, the first read produced `abcd1000`, the read of `a0`
-bytes from address `200200` failed, and the third read produced two bytes –
-`eeff` – out of the four requested.
+bytes from address `200200` failed to read any bytes, and the third read
+produced two bytes – `eeff` – out of the four requested.
 
-**Priority to Implement:** Only required for performance.
+```
+send packet: $MultiMemRead:ranges:100a00,0;
+read packet: $0;
+```
+
+In the example above, a read of zero bytes was requested. A zero-length request
+provides an alternative way of testing whether the stub supports
+`MultiMemRead`.
+
+**Priority to Implement:** Only required for performance, the debugger will
+fall back to doing separate read requests if this packet is unavailable.
 
 ## QEnvironment:NAME=VALUE
 

