[Lldb-commits] [lldb] [lldb] Update qRegisterInfo docs to recommend target.xml (PR #69853)

[Jason Molenda via lldb-commits]

https://github.com/jasonmolenda created https://github.com/llvm/llvm-project/pull/69853

Before target.xml, lldb had its own method for querying the remote stub of the registers it supports, qRegisterInfo. The gdb standard method of using a target.xml file to describe the available registers has become commonplace, and the lldb method for doing this is no longer needed.

Stubs should describe their registers to lldb, but it should be with the target.xml file.

>From c1e4ebf2f79a4ac21d097f6052808c7f60b06a4c Mon Sep 17 00:00:00 2001
From: Jason Molenda <jason at molenda.com>
Date: Sat, 21 Oct 2023 10:19:54 -0700
Subject: [PATCH] [lldb] Update qRegisterInfo docs to recommend target.xml

Before target.xml, lldb had its own method for querying
the remote stub of the registers it supports, qRegisterInfo.
The gdb standard method of using a target.xml file to
describe the available registers has become commonplace, and
the lldb method for doing this is no longer needed.

Stubs should describe their registers to lldb, but it should
be with the target.xml file.
---
 lldb/docs/lldb-gdb-remote.txt | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/lldb/docs/lldb-gdb-remote.txt b/lldb/docs/lldb-gdb-remote.txt
index 6eed70eab043fed..58269e4c2b688ba 100644
--- a/lldb/docs/lldb-gdb-remote.txt
+++ b/lldb/docs/lldb-gdb-remote.txt
@@ -581,11 +581,15 @@ read packet: <binary data>/E<error code>;AAAAAAAAA
 //  will get picked up automatically, and allows registers to change
 //  depending on the actual CPU type that is used.
 //
-//  NB: As of summer 2015, lldb can get register information from the
-//  "qXfer:features:read:target.xml" FSF gdb standard register packet
-//  where the stub provides register definitions in an XML file.
+//  NB: qRegisterInfo is deprecated in favor of the standard gdb remote
+//  serial protocol register description method, 
+//  "qXfer:features:read:target.xml".
 //  If qXfer:features:read:target.xml is supported, qRegisterInfo does
-//  not need to be implemented.
+//  not need to be implemented.  The target.xml format is used by most
+//  gdb RSP stubs whereas qRegisterInfo was an lldb-only design.
+//  qRegisterInfo requires one packet per register and can have undesirable
+//  performance costs at the start of a debug session, whereas target.xml
+//  may be able to describe all registers in a single packet.
 //----------------------------------------------------------------------
 
 With LLDB, for register information, remote GDB servers can add