Skip to content

Commit e91786a

Browse files
[gdbremote] Document MultiMemRead packet in protocol extensions (#162675)
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
1 parent cac8bdb commit e91786a

File tree

1 file changed

+51
-0
lines changed

1 file changed

+51
-0
lines changed

lldb/docs/resources/lldbgdbremote.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -738,6 +738,57 @@ This is a performance optimization, which speeds up debugging by avoiding
738738
multiple round-trips for retrieving thread information. The information from this
739739
packet can be retrieved using a combination of `qThreadStopInfo` and `m` packets.
740740
741+
### MultiMemRead
742+
743+
Read memory from multiple memory ranges.
744+
745+
This packet has one argument:
746+
747+
* `ranges`: a list of pairs of numbers, formatted in base-16. Each pair is
748+
separated by a `,`, as is each number in each pair. The first number of the
749+
pair denotes the base address of the memory read, the second denotes the number
750+
of bytes to be read. The list must end with a `;`.
751+
752+
The reply packet starts with a comma-separated list of numbers formatted in
753+
base-16, denoting how many bytes were read from each range, in the same order
754+
as the request packet. The list is followed by a `;`, followed by a sequence of
755+
bytes containing binary encoded data for all memory that was read. The length
756+
of the binary encodeed data, after being decoded as required by the GDB remote
757+
protocol, must be equal to the sum of the numbers provided at the start of the
758+
reply. The order of the binary data is the same as the order of the ranges in
759+
the request packet.
760+
761+
If some part of a range is not readable, the stub may perform a partial read of
762+
a prefix of the range. In other words, partial reads will only ever be from the
763+
start of the range, never the middle or end. Support for partial reads depends
764+
on the debug stub.
765+
766+
If, by applying the rules above, the stub has read zero bytes from a range, it
767+
must return a length of zero for that range in the reply packet; no bytes for
768+
this memory range are included in the sequence of bytes that follows.
769+
770+
A stub that supports this packet must include `MultiMemRead+` in the reply to
771+
`qSupported`.
772+
773+
```
774+
send packet: $MultiMemRead:ranges:100a00,4,200200,a0,400000,4;
775+
read packet: $4,0,2;<binary encoding of abcd1000><binary encoding of eeff>
776+
```
777+
778+
In the example above, the first read produced `abcd1000`, the read of `a0`
779+
bytes from address `200200` failed to read any bytes, and the third read
780+
produced two bytes – `eeff` – out of the four requested.
781+
782+
```
783+
send packet: $MultiMemRead:ranges:100a00,0;
784+
read packet: $0;
785+
```
786+
787+
In the example above, a read of zero bytes was requested.
788+
789+
**Priority to Implement:** Only required for performance, the debugger will
790+
fall back to doing separate read requests if this packet is unavailable.
791+
741792
## QEnvironment:NAME=VALUE
742793
743794
Setup the environment up for a new child process that will soon be

0 commit comments

Comments
 (0)