Comparing a bit of the mock GDB server code to what was in the document
I found these:
* QLaunchArch
* qSpeedTest
* qSymbol
qSymbol is the most mysterious but it did have some examples in a
comment so I've adapted that.
Fixes#47549
`lldb-server`'s platform mode seems to have an issue with its
`--min-gdbserver-port` `--max-gdbserver-port` flags (and probably the
`--gdbserver-port` flag, but I didn't test it).
How the platform code seems to work is that it listens on a port, and
whenever there's an incoming connection, it forks the process to handle
the connection. To handle the port flags, the main process uses an
instance of the helper class
`GDBRemoteCommunicationServerPlatform::PortMap`, that can be configured
and track usages of ports. The child process handling the platform
connection, can then use the port map to allocate a port for the
gdb-server connection it will make (this is another process it spawns).
However, in the current code, this works only once. After the first
connection is handled by forking a child process, the main platform
listener code loops around, and then 'forgets' about the port map. This
is because this code:
```cpp
GDBRemoteCommunicationServerPlatform platform(
acceptor_up->GetSocketProtocol(), acceptor_up->GetSocketScheme());
if (!gdbserver_portmap.empty()) {
platform.SetPortMap(std::move(gdbserver_portmap));
}
```
is within the connection listening loop. This results in the
`gdbserver_portmap` being moved into the platform object at the
beginning of the first iteration of the loop, but on the second
iteration, after the first fork, the next instance of the platform
object will not have its platform port mapped.
The result of this bug is that subsequent connections to the platform,
when spawning the gdb-remote connection, will be supplied a random port
- which isn't bounded by the `--min-gdbserver-port` and
`--max-gdbserver--port` parameters passed in by the user.
This PR fixes this issue by having the port map be maintained by the
parent platform listener process. On connection, the listener allocates
a single available port from the port map, associates the child process
pid with the port, and lets the connection handling child use that
single port number.
Additionally, when cleaning up child processes, the main listener
process tracks the child that exited to deallocate the previously
associated port, so it can be reused for a new connection.
This was last modified in 4fd3347d6e in
2021 and was made obsolete by the RST version that
edb874b231 added in 2019.
There are some differences but at this point, I'd bet the RST is the
correct one.
* Replace "we" with either "you" (when talking to the reader) or "lldb"
(when talking about the project).
* Refer to lldb as lldb not LLDB, to match what the user sees on
the command line (I am going to come back later and put the proper name in places where it's talking about the projects themselves)
* Remove a bunch of contractions for example "won't". Which don't (pun
intended) seem like a big deal at first but even I as a native English
speaker find the text clearer with them expanded.
* Use RST's plain text highlighting for keywords and command names.
* Split some very long lines for easier editing in future.
Adds support for applying LLVM formatting to variables.
The reason for this is to support cases such as the following.
Let's say you have two separate bytes that you want to print as a
combined hex value. Consider the following summary string:
```
${var.byte1%x}${var.byte2%x}
```
The output of this will be: `0x120x34`. That is, a `0x` prefix is
unconditionally applied to each byte. This is unlike printf formatting
where you must include the `0x` yourself.
Currently, there's no way to do this with summary strings, instead
you'll need a summary provider in python or c++.
This change introduces formatting support using LLVM's formatter system.
This allows users to achieve the desired custom formatting using:
```
${var.byte1:x-}${var.byte2:x-}
```
Here, each variable is suffixed with `:x-`. This is passed to the LLVM
formatter as `{0:x-}`. For integer values, `x` declares the output as
hex, and `-` declares that no `0x` prefix is to be used. Further, one
could write:
```
${var.byte1:x-2}${var.byte2:x-2}
```
Where the added `2` results in these bytes being written with a minimum
of 2 digits.
An alternative considered was to add a new format specifier that would
print hex values without the `0x` prefix. The reason that approach was
not taken is because in addition to forcing a `0x` prefix, hex values
are also forced to use leading zeros. This approach lets the user have
full control over formatting.
This removes various subtitles or converts them to bold text so that the
table of contents is less cluttered.
This includes "Example", "Notes", "Priority To Implement" and
"Response".
So we aren't describing the same packets twice. Basically turning the
platform doc into a list of cross links.
qLaunchSuccess was missing a description so I added one.
As before, script did most of the work, hand edits after that.
There's a lot more we can do dedupe this and the packets doc, this will
come in a follow up PR.
This document has never been on the website, unlike GDB's protocol docs.
It will be useful to have both available online to compare.
Markdown is easier to edit and preview in many editors (including Github
itself), so I've chosen that over RST. Plus, building the website takes
minutes and I lose the will to make nice edits when I have to deal with
that.
The standard dialiect lacks some things notably multi-line table cells,
so I've converted large tables into bullet point lists
so that we still get text wrapping. This is a downside but I think the
simplicity of Markdown outweighs this.
I have applied the plain text markers where I've noticed it and escaped
some HTML characters. There may be more changes needed but, it's
Markdown, so it's in theory a lot easier for someone to fix it!
RST is powerful but usually too powerful for 90% of what we need it for.
Markdown is easier to edit and can be previewed easily without building
the entire website.
This copies what llvm does already, making myst_parser optional if you
only want man pages.
Previously we had Markdown enabled in
8b95bd3310 but that got reverted. That did
this in a different way but I've gone with the standard llvm set this
time.
I intend the first Markdown pages to be the remote protocol extension
docs, as they are not in any set format right now.
https://discourse.llvm.org/t/running-lldb-in-a-container/76801/4 found
that the obvious way to use this variable doesn't work, despite what our
docs and examples say.
Perhaps in the past it did but now you need to use ";" as a separator to
make sure the final command line works properly.
For example "-A foo" becomes "-A foo" when python goes to run the runner
script. The script sees this as one command line element, not two. What
you actually want is "-A;foo" which we convert to "-A" "foo" which the
script sees as one option and one value for that option.
The "Script:" printout from dotest is misleading here because it does `"
".join(cmd)` so it looks like it's ok but in fact it's not.
I'm not changing that format though because printing the command as a
Python list is not useful outside of this specific situation.
Recently building libc++ requires building libunwind too. This updates
the LLDB instructions.
I noticed this recently and it was separately filed as
https://github.com/llvm/llvm-project/issues/84053
This explains a thing that hit me on FreeBSD because the base system
has an ncursesw at one version and I installed from pkg another
version that was simply ncurses (no wide char support).
For whatever reason, when we pass -lcurses to the linker it ends up
picking bits of both installs. This led to lldb crashing immediately
if you tried to use the `gui` command.
In a way that gave little information but I stumbled onto
https://github.com/vifm/vifm/issues/325 which is very similar.
```
ec2-user@freebsd:~/build-llvm $ ldd ./bin/lldb | grep curses
libncursesw.so.9 => /lib/libncursesw.so.9 (0x6a515206e000)
libncurses.so.6 => /usr/local/lib/libncurses.so.6 (0x6a5158e86000)
```
We should only see one version, and it and libpanel etc should
all have "w" or not have "w". This was not the case for my build.
What I can see from the CMake side seemed fine, it found the pkg
installed ncurses in /usr/local. Something else must decide that
-lcurses should pull in the other one.
Regardless, I don't know how to fix that but the solution for most
people is just not to add another ncurses if they already have one.
So I've added a note saying so, and how to check what your lldb
is using.
debugserver will not compress small packets; the overhead of the
compression header makes this useful for larger packets. I default to
384 bytes in debugserver, and added an option for lldb to request a
different cutoff. This option has never been used in lldb in the past
nine years, so I don't think there's any point to keeping it around.
debugserver on arm64 devices can manage both Byte Address Select
watchpoints (1-8 bytes) and MASK watchpoints (8 bytes-2 gigabytes). This
adds a SupportedWatchpointTypes key to the QSupported response from
debugserver with a list of these, so lldb can take full advantage of
them when creating larger regions with a single hardware watchpoint.
Also add documentation for this, and two other lldb extensions, to the
lldb-gdb-remote.txt documentation.
Re-enable TestLargeWatchpoint.py on Darwin systems when testing with the
in-tree built debugserver. I can remove the "in-tree built debugserver"
in the future when this new key is handled by an Xcode debugserver.
The Watchpoint and Breakpoint objects try to track the hardware index
that was used for them, if they are hardware wp/bp's. The majority of
our debugging goes over the gdb remote serial protocol, and when we set
the watchpoint/breakpoint, there is no (standard) way for the remote
stub to communicate to lldb which hardware index was used. We have an
lldb-extension packet to query the total number of watchpoint registers.
When a watchpoint is hit, there is an lldb extension to the stop reply
packet (documented in lldb-gdb-remote.txt) to describe the watchpoint
including its actual hardware index,
<addr within wp range> <wp hw index> <actual accessed address>
(the third field is specifically needed for MIPS). At this point, if the
stub reported these three fields (the stub is only required to provide
the first), we can know the actual hardware index for this watchpoint.
Breakpoints are worse; there's never any way for us to be notified about
which hardware index was used. Breakpoints got this as a side effect of
inherting from StoppointSite with Watchpoints.
We expose the watchpoint hardware index through "watchpoint list -v" and
through SBWatchpoint::GetHardwareIndex.
With my large watchpoint support, there is no *single* hardware index
that may be used for a watchpoint, it may need multiple resources. Also
I don't see what a user is supposed to do with this information, or an
IDE. Knowing the total number of watchpoint registers on the target, and
knowing how many Watchpoint Resources are currently in use, is helpful.
Knowing how many Watchpoint Resources
a single user-specified watchpoint needed to be implemented is useful.
But knowing which registers were used is an implementation detail and
not available until we hit the watchpoint when using gdb remote serial
protocol.
So given all that, I'm removing watchpoint hardware index numbers. I'm
changing the SB API to always return -1.
The instructions for running single tests in the LLDB test suite used an
older directory structure from before the LLVM project became a
monorepo. This commit updates the references to these directories.
This patch updates the documentation to match recent changes and make it
more clear. More specifically, the process for installing sphinx has
changed with the transition to myst with the requirements.txt in
llvm/docs being the preferred method for installation now. In addition,
the docs-lldb-html target is never generated if swig isn't installed, so
having something expliti in the documentation section (even if it is
mentioned as a dependency of lldb itself above) probably doesn't hurt.
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.
This adds a release note for all the SME support now in LLDB and a page
where I have documented the user experience (for want of a better term)
when using SVE and SME.
This includes things like which mode transitions can or cannot be
triggered from within LLDB. I hope this will serve to A: document what
I've implemented and B: be a user's guide to these extensions.
(though it is not a design document, read the commits and code for that
sort of detail)
Bridge network means that you can get to any port on the VM,
from the host, which is great. However it is quite involved to
setup in some cases, and I've certainly messed it up in the past.
An alternative is forwarding a block of ports and using some
hidden options to lldb-server to limit what it uses. This
commit documents that and the pitfall that the port list isn't shared.
The theory also works for Arm's FVP (which inspired me to write
this up) but since QEMU is the preferred option upstream, it goes
in that document.
Along the way I fixed a link to the QEMU page that used the URL
not a relative link to the document.
Running:
$ clang-format -i $(find -regex "\./lldb/.*\.c") $(find -regex
"\./lldb/.*\.cpp") $(find -regex "\./lldb/.*\.h")
Resulted in:
1602 files changed, 25090 insertions(+), 25849 deletions(-)
(note: this includes tests which we wouldn't format, just using this as
an example)
The vast majority of which were whitespace changes. So as far as
formatting we're not deviating from llvm for any reason other than not
churning old code.
Formatting aside, the major features of lldb (single line if, early
return) are all reflected in llvm's style. We differ mainly on variable
naming (proposed to change in
https://llvm.org/docs/Proposals/VariableNames.html anyway) and use of
asserts. Which was already documented.
This is a (rough) port of architecture/varformats.html page that got
lost during the migration to RST in edb874b. I'm not sure how much of
its content is still relevant today. However, the page is pretty
extensive and seems like it's worth preserving.
Neither actually linked anywhere, but I did find a good target for the
introduction.
For the architecture side I don't see a page that would fit, so I've
just removed the sentence.
The testing page already has some page about debugging failures.
I'm not linking directly to that section because:
* The earlier sections about running single tests and such
are just as useful for debugging in general.
* The new theme has a nice sidebar on the right that makes
it really easy to find what you want once on the page.
* We'll probably add more content to the testing page later.
In the LDDB documentation you have the following sentence:
"The --format (which you can shorten to -f) option accepts a format name."
The link points to the wrong place.
I pointed it to the table that precedes the Type summary section.
Reviewed By: DavidSpickett
Differential Revision: https://reviews.llvm.org/D151668
The issues link as it was was including PRs, so I've made that
issues only and only those in an open state.
Code review is now on Gtihub so same thing, PRs only, open state,
label lldb.
