Lines Matching +full:docs +full:- +full:lldb +full:- +full:man
4 This page details various ways to debug LLDB itself and other LLDB tools. If
5 you want to know how to use LLDB in general, please refer to
8 As LLDB is generally split into 2 tools, ``lldb`` and ``lldb-server``
12 In this document we refer to the initial ``lldb`` as the "debugger" and the
16 ----------------------
18 To build LLDB with debugging information add the following to your CMake
23 -DCMAKE_BUILD_TYPE=Debug \
24 -DLLDB_EXPORT_ALL_SYMBOLS=ON
26 Note that the ``lldb`` you will use to do the debugging does not itself need to
33 configurations. This will make LLDB fail earlier instead of continuing with
36 Debugging ``lldb``
37 ------------------
39 The simplest scenario is where we want to debug a local execution of ``lldb``
44 ./bin/lldb test_program
46 LLDB is like any other program, so you can use the same approach.
50 ./bin/lldb -- ./bin/lldb /tmp/test.o
52 That's it. At least, that's the minimum. There's nothing special about LLDB
62 (lldb) run
63 Process 1741640 launched: '<...>/bin/lldb' (aarch64)
67 (lldb) target create "/tmp/test.o"
71 ``(lldb)`` prompt because as far as it knows it hasn't changed state. A quick
77 (lldb) Process 1742266 stopped and restarted: thread 1 received signal: SIGCHLD
79 * thread #1, name = 'lldb', stop reason = signal SIGSTOP
81 (lldb) c
85 (lldb)
92 to debug LLDB. Perhaps an IDE like Xcode or Visual Studio Code. Something which
93 runs LLDB under the hood so you don't have to type in commands to the debugger
100 $ ./bin/lldb -o "settings set prompt \"(lldb debugger) \"" -- \
101 ./bin/lldb -o "settings set prompt \"(lldb inferior) \"" /tmp/test.o
103 (lldb) settings set prompt "(lldb debugger) "
104 (lldb debugger) run
106 (lldb) settings set prompt "(lldb inferior) "
107 (lldb inferior)
117 $ ./bin/lldb /tmp/test.o
120 $ ./bin/lldb ./bin/lldb --attach-pid $(pidof lldb)
125 Generally you will want to hit some breakpoint in the inferior ``lldb``. To place
135 If you are doing this with ``lldb-server`` and find your breakpoint is never
137 ``lldb-server``. There are cases where code only used by ``lldb`` ends up
138 linked into ``lldb-server``, so the debugger can break there but the breakpoint
141 Debugging ``lldb-server``
142 -------------------------
145 ``lldb-server``. The spirit of these instructions applies but the specifics will
148 We suggest you read :doc:`/use/remote` before attempting to debug ``lldb-server``
153 The ``lldb-server`` options for your situation will depend on what part of it
156 ``lldb-server`` during the following command:
160 $ ./bin/lldb /tmp/test.o
162 We can treat ``lldb-server`` as we treated ``lldb`` before, running it under
163 ``lldb``. The equivalent to having ``lldb`` launch the ``lldb-server`` for us is
164 to start ``lldb-server`` in the ``gdbserver`` mode.
166 The following commands recreate that, while debugging ``lldb-server``:
170 $ ./bin/lldb -- ./bin/lldb-server gdbserver :1234 /tmp/test.o
171 (lldb) target create "./bin/lldb-server"
172 Current executable set to '<...>/bin/lldb-server' (aarch64).
174 Process 1742485 launched: '<...>/bin/lldb-server' (aarch64)
178 $ ./bin/lldb /tmp/test.o -o "gdb-remote 1234"
180 Note that the first ``lldb`` is the one debugging ``lldb-server``. The second
181 ``lldb`` is debugging ``/tmp/test.o`` and is only used to trigger the
182 interesting code path in ``lldb-server``.
185 predictable way, or change the prompt of one or both copies of ``lldb``.
187 If you are debugging a scenario where the ``lldb-server`` starts in ``platform``
192 In theory it should be possible to use LLDB's
193 ``target.process.follow-fork-mode`` or GDB's ``follow-fork-mode`` to
198 Another option is to let ``lldb-server`` start up, then attach to the process
203 Output From ``lldb-server``
206 As ``lldb-server`` often launches subprocesses, output messages may be hidden
209 You can tell it to enable logging using the ``--log-channels`` option. For
210 example ``--log-channels "posix ptrace"``. However that is not passed on to the
216 In these cases consider interactive debugging ``lldb-server`` or
224 $ strace -ff -o log -p $(pidof lldb-server)
226 This will log all syscalls made by ``lldb-server`` and processes that it forks.
227 ``-ff`` tells ``strace`` to trace child processes and write the results to a
228 separate file for each process, named using the prefix given by ``-o``.
234 log.<N>:execve("<...>/lldb-server", [<...> "gdbserver", <...>) = 0
237 ----------------
239 If you want to debug part of LLDB running on a remote machine, the principals
243 In the example below we're debugging an ``lldb-server`` ``gdbserver`` mode
246 For simplicity we'll use the same ``lldb-server`` as the debug server
248 (as in, GDB's debug server program) or a system installed ``lldb-server`` if you
254 $ <...>/bin/lldb-server gdbserver 0.0.0.0:54322 -- \
255 <...>/bin/lldb-server gdbserver 0.0.0.0:54321 -- /tmp/test.o
259 ``lldb`` to, to debug the second ``lldb-server``.
261 To trigger behaviour in the second ``lldb-server``, we will connect a second
262 ``lldb`` to port 54321 of the remote.
269 --------------------------------------------|--------------------
270 lldb A debugs lldb-server on port 54322 -> | lldb-server A
272 lldb B debugs /tmp/test.o on port 54321 -> | lldb-server B
276 You would use ``lldb A`` to place a breakpoint in the code you're interested in,
277 then ``lldb B`` to trigger ``lldb-server B`` to go into that code and hit the
278 breakpoint. ``lldb-server A`` is only here to let us debug ``lldb-server B``
282 -----------------------------
284 LLDB mostly follows the `GDB Remote Protocol <https://sourceware.org/gdb/onlinedocs/gdb/Remote-Prot…
285 . Where there are differences it tries to handle both LLDB and GDB behaviour.
287 LLDB does have extensions to the protocol which are documented in
288 `lldb-gdb-remote.txt <https://github.com/llvm/llvm-project/blob/main/lldb/docs/lldb-gdb-remote.txt>…
289 and `lldb/docs/lldb-platform-packets.txt <https://github.com/llvm/llvm-project/blob/main/lldb/docs/…
294 If you just want to observe packets, you can enable the ``gdb-remote packets``
299 (lldb) log enable gdb-remote packets
300 (lldb) run
301 lldb < 1> send packet: +
302 lldb history[1] tid=0x264bfd < 1> send packet: +
303 lldb < 19> send packet: $QStartNoAckMode#b0
304 lldb < 1> read packet: +
306 You can do this on the ``lldb-server`` end as well by passing the option
307 ``--log-channels "gdb-remote packets"``. Then you'll see both sides of the
315 You can enable this logging even when you are connecting to an ``lldb-server``
321 Say you want to make ``lldb`` send a packet to ``lldb-server``, then debug
322 how the latter builds its response. Maybe even see how ``lldb`` handles it once
325 That all takes time, so LLDB will likely time out and think the remote has gone
326 away. You can change the ``plugin.process.gdb-remote.packet-timeout`` setting
329 Here's an example, first we'll start an ``lldb-server`` being debugged by
330 ``lldb``. Placing a breakpoint on a packet handler we know will be hit once
331 another ``lldb`` connects.
335 $ lldb -- lldb-server gdbserver :1234 -- /tmp/test.o
337 (lldb) b GDBRemoteCommunicationServerCommon::Handle_qSupported
339 (lldb) run
342 Next we connect another ``lldb`` to this, with a timeout of 5 minutes:
346 $ lldb /tmp/test.o
348 (lldb) settings set plugin.process.gdb-remote.packet-timeout 300
349 (lldb) gdb-remote 1234
351 Doing so triggers the breakpoint in ``lldb-server``, bringing us back into
352 ``lldb``. Now we've got 5 minutes to do whatever we need before LLDB decides
357 * thread #1, name = 'lldb-server', stop reason = breakpoint 1.1
358 frame #0: 0x0000aaaaaacc6848 lldb-server<...>
359 …lldb-server`lldb_private::process_gdb_remote::GDBRemoteCommunicationServerCommon::Handle_qSupporte…
360 -> 0xaaaaaacc6848 <+0>: sub sp, sp, #0xc0
362 (lldb)
364 Once you're done simply ``continue`` the ``lldb-server``. Back in the other
365 ``lldb``, the connection process will continue as normal.
371 frame #0: 0x0000fffff7fcd100 ld-2.31.so`_start
372 ld-2.31.so`_start:
373 -> 0xfffff7fcd100 <+0>: mov x0, sp
375 (lldb)
378 -------------
380 This section covers reducing a bug that happens in LLDB itself, or where you
381 suspect that LLDB causes something else to behave abnormally.
402 * Reproducing the issue without using the LLDB test runner.
412 * Use a `released version of LLDB <https://github.com/llvm/llvm-project/releases>`_.
414 * If on MacOS, try the system ``lldb``.
421 * Start a virtual machine running a different version. ``qemu-system`` is
445 in C/C++. LLDB tends to try to fit other languages into a C/C++ mould, so
452 * Use ``qemu-system`` to emulate other operating systems e.g. FreeBSD.
456 * Use `QEMU user space emulation <https://www.qemu.org/docs/master/user/main.html>`_
457 to quickly test other architectures. Note that ``lldb-server`` cannot be used
461 space emulation for just ``lldb``, ``qemu-system`` for testing
462 ``lldb-server``).
465 ``lldb-server``. For example if you wanted to debug ``lldb`` running
466 inside ``qemu-user-s390x`` you would connect to the GDB stub provided
469 The same applies if you want to see how ``lldb`` would debug a test
471 you're not using ``lldb-server``, but this is fine for features that
472 are mostly implemented in ``lldb``.
474 If you are running a full system using ``qemu-system``, you likely
475 want to connect to the ``lldb-server`` running within the userspace
488 Sometimes you will find ``lldb-server`` doing something with ptrace that causes
489 a problem. Your reproducer involves running ``lldb`` as well, this is not going
497 We'll remove the LLDB dependency by making a smaller standalone program that
501 The program presented `here <https://eli.thegreenplace.net/2011/01/23/how-debuggers-work-part-1>`_
502 (`source <https://github.com/eliben/code-for-blog/blob/master/2011/simple_tracer.c>`_)
504 `the LLDB examples folder <https://github.com/llvm/llvm-project/tree/main/lldb/examples/ptrace_exam…
508 LLDB and then you'll find the equivalent constants in the same LLDB functions
511 Once that is running as expected we can convert ``lldb-server``'s into calls in
512 this program. To get a log of those, run ``lldb-server`` with
513 ``--log-channels "posix ptrace"``. You'll see output like:
517 $ lldb-server gdbserver :1234 --log-channels "posix ptrace" -- /tmp/test.o
526 …to use a combination of the `ptrace documentation <https://man7.org/linux/man-pages/man2/ptrace.2.…
540 First, go to the ``lldb-server`` terminal and press enter a few times to put
543 Then go to your ``lldb`` and:
547 (lldb) register read tpidr
550 You'll see this from ``lldb-server``:
556 If you don't see that, it may be because ``lldb`` has cached it. The easiest way
577 Doing it this way instead of exactly copying what LLDB does will save a few
588 it is included because this more cloesly matches what ``lldb`` does).
595 Finally, that "thing" is the ptrace calls you got from the ``lldb-server`` logs.
597 need any part of LLDB.
600 ---------------