Skip to content

Commit e5f4dc8

Browse files
[gdbremote] Document MultiMemRead packet in protocol extensions (llvm#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 (cherry picked from commit e91786a)
1 parent 372021f commit e5f4dc8

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

0 commit comments

Comments
 (0)