217 lines · plain
1Testing LLDB using QEMU2=======================3 4QEMU system mode emulation5--------------------------6 7QEMU can be used to test LLDB in an emulation environment in the absence of8actual hardware. This page describes instructions to help setup a QEMU emulation9environment for testing LLDB.10 11The scripts under llvm-project/lldb/scripts/lldb-test-qemu can quickly help12setup a virtual LLDB testing environment using QEMU. The scripts currently work13with Arm or AArch64, but support for other architectures can be added easily.14 15* **setup.sh** is used to build the Linux kernel image and QEMU system emulation executable(s) from source.16* **rootfs.sh** is used to generate Ubuntu root file system images to be used for QEMU system mode emulation.17* **run-qemu.sh** utilizes QEMU to boot a Linux kernel image with a root file system image.18 19Once we have booted our kernel we can run lldb-server in emulation environment.20Ubuntu Bionic/Focal x86_64 host was used to test these scripts instructions in this21document. Please update it according to your host distribution/architecture.22 23.. note::24 Instructions on this page and QEMU helper scripts are verified on a Ubuntu Bionic/Focal (x86_64) host. Moreover, scripts require sudo/root permissions for installing dependencies and setting up QEMU host/guest network.25 26Given below are some examples of common use-cases of LLDB QEMU testing27helper scripts:28 29Create Ubuntu root file system image for QEMU system emulation with rootfs.sh30--------------------------------------------------------------------------------31 32**Example:** generate Ubuntu Bionic (armhf) rootfs image of size 1 GB33::34 35 $ bash rootfs.sh --arch armhf --distro bionic --size 1G36 37**Example:** generate Ubuntu Focal (arm64) rootfs image of size 2 GB38::39 40 $ bash rootfs.sh --arch arm64 --distro focal --size 2G41 42rootfs.sh has been tested for generating Ubuntu Bionic and Focal images but they can be used to generate rootfs images of other Debian Linux distribution.43 44rootfs.sh defaults username of generated image to your current username on host computer.45 46 47Build QEMU or cross compile Linux kernel from source using setup.sh48-----------------------------------------------------------------------49 50**Example:** Build QEMU binaries and Arm/AArch64 Linux kernel image51::52 53$ bash setup.sh --qemu --kernel arm54$ bash setup.sh --qemu --kernel arm6455 56**Example:** Build Linux kernel image only57::58 59$ bash setup.sh --kernel arm60$ bash setup.sh --kernel arm6461 62**Example:** Build qemu-system-arm and qemu-system-aarch64 binaries.63::64 65$ bash setup.sh --qemu66 67**Example:** Remove qemu.git, linux.git and linux.build from working directory68::69 70$ bash setup.sh --clean71 72 73Run QEMU Arm or AArch64 system emulation using run-qemu.sh74----------------------------------------------------------75run-qemu.sh has following dependencies:76 77* Follow https://wiki.qemu.org/Documentation/Networking/NAT and set up bridge78 networking for QEMU.79 80* Make sure /etc/qemu-ifup script is available with executable permissions.81 82* QEMU binaries must be built from source using setup.sh or provided via --qemu83 commandline argument.84 85* Linux kernel image must be built from source using setup.sh or provided via86 --kernel commandline argument.87 88* linux.build and qemu.git folder must be present in current directory if89 setup.sh was used to build Linux kernel and QEMU binaries.90 91* --sve option will enable AArch64 SVE mode.92 93* --sme option will enable AArch64 SME mode (SME requires SVE, so this will also94 be enabled).95 96* --mte option will enable AArch64 MTE (memory tagging) mode97 (can be used on its own or in addition to --sve).98 99 100**Example:** Run QEMU Arm or AArch64 system emulation using run-qemu.sh101::102 103 $ sudo bash run-qemu.sh --arch arm --rootfs <path of rootfs image>104 $ sudo bash run-qemu.sh --arch arm64 --rootfs <path of rootfs image>105 106**Example:** Run QEMU with kernel image and qemu binary provided using commandline107::108 109 $ sudo bash run-qemu.sh --arch arm64 --rootfs <path of rootfs image> \110 --kernel <path of Linux kernel image> --qemu <path of QEMU binary>111 112 113Steps for running lldb-server in QEMU system emulation environment114------------------------------------------------------------------115 116Using Bridge Networking117***********************118 119* Make sure bridge networking is enabled between host machine and QEMU VM120 121* Find out ip address assigned to eth0 in emulation environment122 123* Setup ssh access between host machine and emulation environment124 125* Login emulation environment and install dependencies126 127::128 129 $ sudo apt install python-dev libedit-dev libncurses5-dev libexpat1-dev130 131* Cross compile LLDB server for AArch64 Linux: Please visit https://lldb.llvm.org/resources/build.html for instructions on how to cross compile LLDB server.132 133* Transfer LLDB server executable to emulation environment134 135::136 137 $ scp lldb-server username@ip-address-of-emulation-environment:/home/username138 139* Run lldb-server inside QEMU VM140 141* Try connecting to lldb-server running inside QEMU VM with selected ip:port142 143Without Bridge Networking144*************************145 146Without bridge networking you will have to forward individual ports from the VM147to the host (refer to QEMU's manuals for the specific options).148 149* At least one to connect to the intial ``lldb-server``.150* One more if you want to use ``lldb-server`` in ``platform mode``, and have it151 start a ``gdbserver`` instance for you.152 153If you are doing either of the latter 2 you should also restrict what ports154``lldb-server tries`` to use, otherwise it will randomly pick one that is almost155certainly not forwarded. An example of this is shown below.156 157::158 159 $ lldb-server platform --server --listen 0.0.0.0:54321 --gdbserver-port 49140160 161The result of this is that:162 163* ``lldb-server`` platform mode listens externally on port ``54321``.164 165* When it is asked to start a new gdbserver mode instance, it will use the port166 ``49140``.167 168Your VM configuration should have ports ``54321`` and ``49140`` forwarded for169this to work.170 171QEMU user mode emulation172------------------------173 174Serious testing of LLDB should be done using system mode emulation. The following175is presented for information only and is not a supported testing configuration176supported by the LLDB project.177 178However, it is possible to run the test suite against user mode QEMU if you just179want to test a specific aspect of ``lldb`` and are ok ignoring a lot of expected180failures. This method can also be adapted for simulators with a qemu-like command181line interface.182 183(``lldb-server`` cannot be tested using user mode QEMU because that does not184emulate the debugging system calls that ``lldb-server`` tries to make)185 186Change ``LLDB_TEST_USER_ARGS`` to choose the ``qemu-user`` platform and187configure it for your architecture. The example below is for AArch64 and assumes188that ``qemu-aarch64`` is installed and on your path.189 190If you need to override how the ``qemu-user`` platform finds the QEMU binary,191look up the rest of the platform's settings in LLDB.192 193::194 195 -DLLDB_TEST_USER_ARGS="--platform-name;qemu-user;--setting;platform.plugin.qemu-user.architecture=aarch64;--arch;aarch64"196 197Also set ``LLDB_TEST_COMPILER`` to something that can target the emulated198architecture. Then you should be able to run ``ninja check-lldb`` and it will199run the tests on QEMU user automatically.200 201You will see a number of failures compared to a normal test run. Reasons for202this can be, but are not limited to:203 204* QEMU's built-in debug stub acting differently and supporting different205 features to different extents, when compared to ``lldb-server``. We try to206 be compatible but LLDB is not regularly tested with QEMU user.207 208* Tests that spawn new processes to attach to. QEMU user only emulates a single209 process.210 211* Watchpoints. Either these are not emulated or behave differently to real212 hardware. Add ``--skip-category;watchpoint`` to ``-DLLDB_TEST_USER_ARGS`` to213 skip those.214 215* Lack of memory region information due to QEMU communicating this in the216 GDB server format which LLDB does not use.217