1Testing LLDB using QEMU 2======================= 3 4.. contents:: 5 :local: 6 7QEMU system mode emulation 8-------------------------- 9 10QEMU can be used to test LLDB in an emulation environment in the absence of 11actual hardware. This page describes instructions to help setup a QEMU emulation 12environment for testing LLDB. 13 14The scripts under llvm-project/lldb/scripts/lldb-test-qemu can quickly help 15setup a virtual LLDB testing environment using QEMU. The scripts currently work 16with Arm or AArch64, but support for other architectures can be added easily. 17 18* **setup.sh** is used to build the Linux kernel image and QEMU system emulation executable(s) from source. 19* **rootfs.sh** is used to generate Ubuntu root file system images to be used for QEMU system mode emulation. 20* **run-qemu.sh** utilizes QEMU to boot a Linux kernel image with a root file system image. 21 22Once we have booted our kernel we can run lldb-server in emulation environment. 23Ubuntu Bionic/Focal x86_64 host was used to test these scripts instructions in this 24document. Please update it according to your host distribution/architecture. 25 26.. note:: 27 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. 28 29Given below are some examples of common use-cases of LLDB QEMU testing 30helper scripts: 31 32Create Ubuntu root file system image for QEMU system emulation with rootfs.sh 33-------------------------------------------------------------------------------- 34 35**Example:** generate Ubuntu Bionic (armhf) rootfs image of size 1 GB 36:: 37 38 $ bash rootfs.sh --arch armhf --distro bionic --size 1G 39 40**Example:** generate Ubuntu Focal (arm64) rootfs image of size 2 GB 41:: 42 43 $ bash rootfs.sh --arch arm64 --distro focal --size 2G 44 45rootfs.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. 46 47rootfs.sh defaults username of generated image to your current username on host computer. 48 49 50Build QEMU or cross compile Linux kernel from source using setup.sh 51----------------------------------------------------------------------- 52 53**Example:** Build QEMU binaries and Arm/AArch64 Linux kernel image 54:: 55 56$ bash setup.sh --qemu --kernel arm 57$ bash setup.sh --qemu --kernel arm64 58 59**Example:** Build Linux kernel image only 60:: 61 62$ bash setup.sh --kernel arm 63$ bash setup.sh --kernel arm64 64 65**Example:** Build qemu-system-arm and qemu-system-aarch64 binaries. 66:: 67 68$ bash setup.sh --qemu 69 70**Example:** Remove qemu.git, linux.git and linux.build from working directory 71:: 72 73$ bash setup.sh --clean 74 75 76Run QEMU Arm or AArch64 system emulation using run-qemu.sh 77---------------------------------------------------------- 78run-qemu.sh has following dependencies: 79 80* Follow https://wiki.qemu.org/Documentation/Networking/NAT and set up bridge 81 networking for QEMU. 82 83* Make sure /etc/qemu-ifup script is available with executable permissions. 84 85* QEMU binaries must be built from source using setup.sh or provided via --qemu 86 commandline argument. 87 88* Linux kernel image must be built from source using setup.sh or provided via 89 --kernel commandline argument. 90 91* linux.build and qemu.git folder must be present in current directory if 92 setup.sh was used to build Linux kernel and QEMU binaries. 93 94* --sve option will enable AArch64 SVE mode. 95 96* --mte option will enable AArch64 MTE (memory tagging) mode. 97 (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.sh 101:: 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 commandline 107:: 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 environment 114------------------------------------------------------------------ 115 116* Make sure bridge networking is enabled between host machine and QEMU VM 117 118* Find out ip address assigned to eth0 in emulation environment 119 120* Setup ssh access between host machine and emulation environment 121 122* Login emulation environment and install dependencies 123 124:: 125 126 $ sudo apt install python-dev libedit-dev libncurses5-dev libexpat1-dev 127 128* 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. 129 130* Transfer LLDB server executable to emulation environment 131 132:: 133 134 $ scp lldb-server username@ip-address-of-emulation-environment:/home/username 135 136* Run lldb-server inside QEMU VM 137 138* Try connecting to lldb-server running inside QEMU VM with selected ip:port 139