From f7e3f64b9aa513f6ca24627366482ff7fc19cac9 Mon Sep 17 00:00:00 2001 From: Felipe de Azevedo Piovezan Date: Wed, 8 Oct 2025 08:23:41 -0700 Subject: [PATCH 1/4] [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; +``` + +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 Date: Fri, 10 Oct 2025 13:31:42 -0700 Subject: [PATCH 2/4] 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; +``` + +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; -``` - -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 Date: Sat, 11 Oct 2025 06:53:34 -0700 Subject: [PATCH 3/4] 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; ``` 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 From 2d168ba66c8c4a3cf2c3e758836cb1d6491be1d4 Mon Sep 17 00:00:00 2001 From: Felipe de Azevedo Piovezan Date: Wed, 15 Oct 2025 07:25:53 -0700 Subject: [PATCH 4/4] fixup! Address review comments --- lldb/docs/resources/lldbgdbremote.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/lldb/docs/resources/lldbgdbremote.md b/lldb/docs/resources/lldbgdbremote.md index 2657dd9c59020..604cf1981666a 100644 --- a/lldb/docs/resources/lldbgdbremote.md +++ b/lldb/docs/resources/lldbgdbremote.md @@ -750,16 +750,19 @@ 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. +of the binary encodeed data, after being decoded as required by the GDB remote +protocol, 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. -If an entire range is not readable, the stub may perform a partial read of a -prefix of the range. +If some part of a range is not readable, the stub may perform a partial read of +a prefix of the range. In other words, partial reads will only ever be from the +start of the range, never the middle or end. Support for partial reads depends +on the debug stub. -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. +If, by applying the rules above, the stub has read zero bytes from a 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 must include `MultiMemRead+` in the reply to `qSupported`. @@ -778,9 +781,7 @@ 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`. +In the example above, a read of zero bytes was requested. **Priority to Implement:** Only required for performance, the debugger will fall back to doing separate read requests if this packet is unavailable.