[Lldb-commits] [lldb] [lldb][docs] Add register info problems to troubleshooting doc (PR #171806)
David Spickett via lldb-commits
lldb-commits at lists.llvm.org
Fri Dec 12 02:19:37 PST 2025
https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/171806
>From 4820a2164b145a27cc2d4a96d9c5537ba0024ff9 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Wed, 10 Dec 2025 16:48:13 +0000
Subject: [PATCH 1/6] [lldb][docs] Add register info problems to
troubleshooting doc
This new section talks about the ways we try to get
register information, how to find out what LLDB decides to do
and how to remedy that choice if needed.
It does not specifically mention the logging messages
and warnings I added in the LLDB. Since they'll see the
warning automatically, and if not, this document tells
them what log channels to generally look at.
All the methods have their place, so I've tried to present
this as a sliding scale of accuracy. Anyone doing userspace
debug with recent versions of LLDB will want XML working,
but it's not 100% required.
Target definition scripts are the least documented but
also most advanced. I have included them because they are
the first thing LLDB checks, but only briefly, as 99.9%
of users won't be using one.
---
lldb/docs/use/troubleshooting.rst | 142 ++++++++++++++++++++++++++++++
1 file changed, 142 insertions(+)
diff --git a/lldb/docs/use/troubleshooting.rst b/lldb/docs/use/troubleshooting.rst
index da2698c395e26..0ee7f94cd937e 100644
--- a/lldb/docs/use/troubleshooting.rst
+++ b/lldb/docs/use/troubleshooting.rst
@@ -153,3 +153,145 @@ Linux applies to Windows. To find dependencies like Python, you need to run
``dumpbin`` on ``liblldb.dll`` too.
On MacOS, use ``otool -l <path-to-lldb>``.
+
+Why Do I See More, Less, Or Different Registers Than I Expected?
+----------------------------------------------------------------
+
+The registers you see in LLDB are defined by information either provided by the
+debug server you are connected to, or in some cases, guessed by LLDB.
+
+If you are not seeing the registers you expect, the first step is to figure out
+which method is being used to read the register information. They are presented
+here in the order that LLDB will try them.
+
+Target Definition Script
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+These scripts tell LLDB what registers exist on the debug-server without having
+to ask it. You can check if you are using one by checking the setting:
+
+::
+
+ (lldb) settings show plugin.process.gdb-remote.target-definition-file
+
+In most cases you will not be using such a script.
+
+If you are using one, or want to write one, you can learn about them by reading
+the ``*_target_definition.py`` files in the
+`Python examples folder <https://github.com/llvm/llvm-project/tree/main/lldb/examples/python>`__.
+
+Target Description Format XML
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The first, and preferred, method is the debug server sending LLDB an XML
+document in the
+`Target Description Format <https://sourceware.org/gdb/current/onlinedocs/gdb.html/Target-Description-Format.html>`__.
+
+LLDB can only process this if XML parsing was enabled when it was built. A
+previous section of this document explains how to check this. If XML is not
+enabled and the debug server has offered an XML document, we highly recommend
+switching to a build of LLDB with XML parsing enabled.
+
+.. note::
+
+ If LLDB was offered an XML document but could not use it, you will see a
+ warning in your debug session to alert you to this situation.
+
+If your LLDB has XML support, next check whether the debug-server offered this
+XML document. Enable the GDB remote packet log, then connect to the debug-server
+as you normally would.
+
+::
+
+ (lldb) log enable gdb-remote packets
+
+This will produce a lot of output. Scroll back to just after you connected to
+the debug server. Look for lines like these:
+
+::
+ lldb < 104> send packet: $qSupported:xmlRegisters=<...>
+ lldb < 260> read packet: $<...>qXfer:features:read+<...>
+
+The ``sent`` packet is LLDB telling the debug server that it can parse XML
+definitions. The ``read`` (received) packet is the debug server telling LLDB
+that it is allowed to request Target Description XML.
+
+If you do not see either of these, then one or both of LLDB or the debug server
+does not support XML. This is not a fatal problem but may result in degraded
+register information.
+
+Switching to a debug server with XML support may not be possible. For example if
+you have hardware debug tools that cannot be changed. Consult your local experts
+for advice on this.
+
+If you did see those packets, scroll further down to confirm that the XML was
+read. You should see output that looks like an XML document:
+
+::
+
+ lldb < 43> send packet: $qXfer:features:read:target.xml<...>
+ lldb <27583> read packet: $l<?xml version="1.0"?>
+ <target version="1.0">
+ <...>
+
+Even if the XML document was read by LLDB, it, or parts of it may not be valid.
+LLDB is permissive when parsing, so you will not get a fatal error. You need to
+check the GDB Remote process log for details of any parsing problems:
+
+::
+
+ (lldb) log enable gdb-remote process
+
+.. note::
+ There will always be some messages about register information because we log
+ details of successful parsing too. If registers are present but presented in
+ an unexpected way, check these log messages to see if LLDB has misinterpreted
+ the register information.
+
+If those messages do not tell you what is wrong, your last option is to read the
+document yourself by copying it out of the ``gdb-remote packets`` output.
+Start by checking the basic XML structure of nested elements and begin/end markers
+are correct, then compare it to the Target Description specification.
+
+If reading XML is not possible, or it fails to produce any valid register
+information, LLDB falls back to the next method.
+
+qRegisterInfo
+^^^^^^^^^^^^^
+
+When XML reading fails, LLDB will try an ``lldb-server`` specific packet
+called ``qRegisterInfo``. This packet contains all the same register information
+as the XML would, except advanced formatting information. That information tells
+LLDB how to format registers as complex types like structures.
+
+So if you are using ``lldb`` connected to ``lldb-server`` or ``debugserver``,
+it is likely you will not notice the lack of XML. Connected to anything else,
+``qRegisterInfo`` will not work and LLDB will fall back to the final method.
+
+To check if LLDB is using ``qRegisterInfo`` you can check the
+``gdb-remote packets`` and ``gdb-remote process`` logs.
+
+Fallback Register Layouts
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The final method is that LLDB will assume that it can use the general register
+read packet and make an assumption about the offset of each register in the
+response.
+
+This is often done with older debug servers, or ones running with very limited
+resources such as those inside of operating system kernels.
+
+This requires that LLDB and the debug server be in sync which is not always
+the case if you are connecting LLDB to anything but ``lldb-server`` or
+``debugserver``. Work has been done to make LLDB more compatible, but it is
+impossible to predict what might be in use in the wild.
+
+Symptoms of a mismatch are missing, overlapping or incorrect register values.
+Often this will cause other features like backtracing to fail.
+
+In this case, assuming you cannot change the debug server, you do not have much
+choice but to find a debug client that does match up. Often GDB will work better,
+it has a longer history of compatability fixes.
+
+If you must use LLDB, you could patch it to match the debug server. The fallback
+layouts are stored in ``lldb/source/Plugins/Process/gdb-remote/GDBRemoteRegisterFallback.cpp``.
>From b9f6dde07eecb1dd00bf872d88ca53e16cdd59b8 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Thu, 11 Dec 2025 11:33:04 +0000
Subject: [PATCH 2/6] very few people should bother with a target definition
script
---
lldb/docs/use/troubleshooting.rst | 3 +++
1 file changed, 3 insertions(+)
diff --git a/lldb/docs/use/troubleshooting.rst b/lldb/docs/use/troubleshooting.rst
index 0ee7f94cd937e..b553da9ba7996 100644
--- a/lldb/docs/use/troubleshooting.rst
+++ b/lldb/docs/use/troubleshooting.rst
@@ -180,6 +180,9 @@ If you are using one, or want to write one, you can learn about them by reading
the ``*_target_definition.py`` files in the
`Python examples folder <https://github.com/llvm/llvm-project/tree/main/lldb/examples/python>`__.
+We reccomend that before attempting to write a target definition script to solve
+your issues, you look into the other methods first.
+
Target Description Format XML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>From 84a7f70d390c90b8cbc307d3c66d63d98b46f032 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Thu, 11 Dec 2025 11:34:12 +0000
Subject: [PATCH 3/6] not the first that lldb checks
---
lldb/docs/use/troubleshooting.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/lldb/docs/use/troubleshooting.rst b/lldb/docs/use/troubleshooting.rst
index b553da9ba7996..0ce1c8a3dbcd1 100644
--- a/lldb/docs/use/troubleshooting.rst
+++ b/lldb/docs/use/troubleshooting.rst
@@ -186,7 +186,7 @@ your issues, you look into the other methods first.
Target Description Format XML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-The first, and preferred, method is the debug server sending LLDB an XML
+The most commonly used method is the debug server sending LLDB an XML
document in the
`Target Description Format <https://sourceware.org/gdb/current/onlinedocs/gdb.html/Target-Description-Format.html>`__.
>From 61e052ab2ad9f87692026e9d4b2841dc501d868a Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Thu, 11 Dec 2025 11:36:36 +0000
Subject: [PATCH 4/6] spelling
---
lldb/docs/use/troubleshooting.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/lldb/docs/use/troubleshooting.rst b/lldb/docs/use/troubleshooting.rst
index 0ce1c8a3dbcd1..727c2d2a9946c 100644
--- a/lldb/docs/use/troubleshooting.rst
+++ b/lldb/docs/use/troubleshooting.rst
@@ -180,7 +180,7 @@ If you are using one, or want to write one, you can learn about them by reading
the ``*_target_definition.py`` files in the
`Python examples folder <https://github.com/llvm/llvm-project/tree/main/lldb/examples/python>`__.
-We reccomend that before attempting to write a target definition script to solve
+We recommend that before attempting to write a target definition script to solve
your issues, you look into the other methods first.
Target Description Format XML
>From 930b33ff5d3935fb9aaa6432b2c460d446f0e43a Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 12 Dec 2025 10:18:36 +0000
Subject: [PATCH 5/6] debug server
---
lldb/docs/use/troubleshooting.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/lldb/docs/use/troubleshooting.rst b/lldb/docs/use/troubleshooting.rst
index 727c2d2a9946c..7ff39613741eb 100644
--- a/lldb/docs/use/troubleshooting.rst
+++ b/lldb/docs/use/troubleshooting.rst
@@ -167,7 +167,7 @@ here in the order that LLDB will try them.
Target Definition Script
^^^^^^^^^^^^^^^^^^^^^^^^
-These scripts tell LLDB what registers exist on the debug-server without having
+These scripts tell LLDB what registers exist on the debug server without having
to ask it. You can check if you are using one by checking the setting:
::
@@ -200,8 +200,8 @@ switching to a build of LLDB with XML parsing enabled.
If LLDB was offered an XML document but could not use it, you will see a
warning in your debug session to alert you to this situation.
-If your LLDB has XML support, next check whether the debug-server offered this
-XML document. Enable the GDB remote packet log, then connect to the debug-server
+If your LLDB has XML support, next check whether the debug server offered this
+XML document. Enable the GDB remote packet log, then connect to the debug server
as you normally would.
::
>From 42b11bbb74beaf58b7344f7818310fb5ff4ce032 Mon Sep 17 00:00:00 2001
From: David Spickett <david.spickett at linaro.org>
Date: Fri, 12 Dec 2025 10:19:12 +0000
Subject: [PATCH 6/6] format as tip
---
lldb/docs/use/troubleshooting.rst | 6 ++++--
1 file changed, 4 insertions(+), 2 deletions(-)
diff --git a/lldb/docs/use/troubleshooting.rst b/lldb/docs/use/troubleshooting.rst
index 7ff39613741eb..377d9f81494fc 100644
--- a/lldb/docs/use/troubleshooting.rst
+++ b/lldb/docs/use/troubleshooting.rst
@@ -180,8 +180,10 @@ If you are using one, or want to write one, you can learn about them by reading
the ``*_target_definition.py`` files in the
`Python examples folder <https://github.com/llvm/llvm-project/tree/main/lldb/examples/python>`__.
-We recommend that before attempting to write a target definition script to solve
-your issues, you look into the other methods first.
+.. tip::
+
+ We recommend that before attempting to write a target definition script to solve
+ your issues, you look into the other methods first.
Target Description Format XML
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
More information about the lldb-commits
mailing list