[Lldb-commits] [lldb] 21030b9 - [lldb][Docs] Add section on using QEMU without bridge networking

[David Spickett via lldb-commits]

Author: David Spickett
Date: 2023-10-06T15:28:10+01:00
New Revision: 21030b9ab4487d845e29792063f5666d8c4b8e09

URL: https://github.com/llvm/llvm-project/commit/21030b9ab4487d845e29792063f5666d8c4b8e09
DIFF: https://github.com/llvm/llvm-project/commit/21030b9ab4487d845e29792063f5666d8c4b8e09.diff

LOG: [lldb][Docs] Add section on using QEMU without bridge networking

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.

Added: 
    

Modified: 
    lldb/docs/resources/test.rst
    lldb/docs/use/qemu-testing.rst

Removed: 
    


################################################################################
diff  --git a/lldb/docs/resources/test.rst b/lldb/docs/resources/test.rst
index ddade269d5d4aba..3c9e24dde8fd454 100644
--- a/lldb/docs/resources/test.rst
+++ b/lldb/docs/resources/test.rst
@@ -589,9 +589,9 @@ Running tests in QEMU System Emulation Environment
 ``````````````````````````````````````````````````
 
 QEMU can be used to test LLDB in an emulation environment in the absence of
-actual hardware. `QEMU based testing <https://lldb.llvm.org/use/qemu-testing.html>`_
-page describes how to setup an emulation environment using QEMU helper scripts
-found under llvm-project/lldb/scripts/lldb-test-qemu. These scripts currently
+actual hardware. :doc:`/use/qemu-testing` describes how to setup an
+emulation environment using QEMU helper scripts found in
+``llvm-project/lldb/scripts/lldb-test-qemu``. These scripts currently
 work with Arm or AArch64, but support for other architectures can be added easily.
 
 Debugging Test Failures

diff  --git a/lldb/docs/use/qemu-testing.rst b/lldb/docs/use/qemu-testing.rst
index 1a4433a991ff711..6e282141864cc1d 100644
--- a/lldb/docs/use/qemu-testing.rst
+++ b/lldb/docs/use/qemu-testing.rst
@@ -113,6 +113,9 @@ run-qemu.sh has following dependencies:
 Steps for running lldb-server in QEMU system emulation environment
 ------------------------------------------------------------------
 
+Using Bridge Networking
+***********************
+
 * Make sure bridge networking is enabled between host machine and QEMU VM
 
 * Find out ip address assigned to eth0 in emulation environment
@@ -136,3 +139,39 @@ Steps for running lldb-server in QEMU system emulation environment
 * Run lldb-server inside QEMU VM
 
 * Try connecting to lldb-server running inside QEMU VM with selected ip:port
+
+Without Bridge Networking
+*************************
+
+Without bridge networking you will have to forward individual ports from the VM
+to the host (refer to QEMU's manuals for the specific options).
+
+* At least one to connect to the intial ``lldb-server``.
+* One more if you want to use ``lldb-server`` in ``platform mode``, and have it
+  start a ``gdbserver`` instance for you.
+* A bunch more if you want to run tests against the ``lldb-server`` platform.
+
+If you are doing either of the latter 2 you should also restrict what ports
+``lldb-server tries`` to use, otherwise it will randomly pick one that is almost
+certainly not forwarded. An example of this is shown below.
+
+::
+
+  $ lldb-server plaform --server --listen 0.0.0.0:54321 \
+    --min-gdbserver-port 49140 --max-gdbserver-port 49150
+
+The result of this is that:
+
+* ``lldb-server`` platform mode listens externally on port ``54321``.
+
+* When it is asked to start a new gdbserver mode instance, it will use a port
+  in the range ``49140`` to ``49150``.
+
+Your VM configuration should have ports ``54321``, and ``49140`` to ``49150``
+forwarded for this to work.
+
+.. note::
+  These options are used to create a "port map" within ``lldb-server``.
+  Unfortunately this map is not shared across all the processes it may create,
+  and across a few uses you may run out of valid ports. To work around this,
+  restart the platform every so often, especially after running a set of tests.