From nobody Mon Feb 9 02:10:30 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=linaro.org ARC-Seal: i=1; a=rsa-sha256; t=1585906870; cv=none; d=zohomail.com; s=zohoarc; b=Zj5ySNAXbgyNr0Cw6M1vLd6LJRH+VlOKJR/wPVruDKwKva+DrS2+KhCzPOuvtGlxVmvqFYjZWlvvYUecTNtsf7aO9dEib7rm/35yZgXY8Mn827vsscGr1vClPOMyWBrNWC/rI6kUIgen2MmdUg5/sU0HZkEMs18jWb6uwrS/FZA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1585906870; h=Content-Transfer-Encoding:Date:From:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Sender:Subject:To; bh=urTdOG8/AKfDySZVWZoH4F9NK6OheNZjgqwxfBn3rfo=; b=HVwrWkdpRzJ8h35YtyL5iE8Ft8nG7aZr99XaPw81CXAgdYFkeEL/Qhh9Nvn0MJcQ/edJ6KthfbIDLFIF5xoouL8zeV4qnxy4KVfoW5fTqit0UzetkJWLdKOi/lHAy59YZpctRngsiG++GDZvvH9UI/OKgge9TAtlPqUdf8bCTd8= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 15859068708037.831249515314653; Fri, 3 Apr 2020 02:41:10 -0700 (PDT) Received: from localhost ([::1]:52802 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jKIp3-0001TM-A4 for importer@patchew.org; Fri, 03 Apr 2020 05:41:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:58507) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jKIoG-0000QO-D8 for qemu-devel@nongnu.org; Fri, 03 Apr 2020 05:40:21 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jKIoF-00037O-0x for qemu-devel@nongnu.org; Fri, 03 Apr 2020 05:40:20 -0400 Received: from mail-wr1-x433.google.com ([2a00:1450:4864:20::433]:38016) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1jKIoE-00036f-NG for qemu-devel@nongnu.org; Fri, 03 Apr 2020 05:40:18 -0400 Received: by mail-wr1-x433.google.com with SMTP id c7so7692901wrx.5 for ; Fri, 03 Apr 2020 02:40:18 -0700 (PDT) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id i1sm11043322wrq.89.2020.04.03.02.40.16 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 03 Apr 2020 02:40:16 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=urTdOG8/AKfDySZVWZoH4F9NK6OheNZjgqwxfBn3rfo=; b=O3s7tGe1kMfenrjwTUSS2NcDNxbBQImmp4gCUeR+g1Pz4YR4RzV2LbLiTMEcvQnSSG LZdknxd//Z3QSmUMBBrzvl8rFnKmTuHtr62vkvfptABrGjkscHBR+Cwgvewvx8VUmpBe N9scdlKd92rWAJoWLe66LKmXiYDUHo+5K3zgVLbu1qOYgVtWHwnqPHEdDpYgtl7/7G21 fmWUIIYY2DPjs4ukISFKExMpdywM5gRAXw44wkGjCM7em8Nf1smWDE7YCWrZh5zVaif7 vMFDhHaM2qoCI27Q5/6WVcfQvxPVHjOn8sUPaJFAw9t/JEZefQXgMM/45k0tBWxfn25k TeIg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:subject:date:message-id:mime-version :content-transfer-encoding; bh=urTdOG8/AKfDySZVWZoH4F9NK6OheNZjgqwxfBn3rfo=; b=e5ze6b5Mw6++EUvRUr/NpeUKwJk2Shakz7iMFgfeo5I02E2j7EK2TlSfxhlgaA/Jd3 N65xuN7RcSAKjRqfdLQeBAy58YyFfqSsp6O/LR5ShwwHhAMLsLG3g+q7FH7LwxAlpsjS RbiM6yLvepmyVQ0DnbyRhYxNf5ckAKjRHUxLx2VRiW0eM1VtSDtZOKm/CmL5z9iCzen6 clp4xkdWNlT/DSLqGdlW5MCgwkY2siCEaRM7fOmyWxbL44/7HZL4vGrfzQ4bzuGPLMzr KXX2oeyqL+xGf645R996ZcjrbOucpz+26dOkNaud612VPGkLpza11adf6eRHCd3g4pci wFSA== X-Gm-Message-State: AGi0Pua0aCs/xy2R9zvhbDMIUVt9Ijn9D5Vxj+YquGrpaFcZit5EiE0j MNnSSFRfh8P+YblFtiCeCQTjGa1RoPPkgA== X-Google-Smtp-Source: APiQypIyMHWBe3U8YKiTL0v3qbJrLKMBI+S3M8nbibUQ3/1RHSFtPRsQr4T60hRCVT7WSOqJQumuHQ== X-Received: by 2002:adf:e445:: with SMTP id t5mr8214267wrm.352.1585906816819; Fri, 03 Apr 2020 02:40:16 -0700 (PDT) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH for-5.0?] docs: Improve our gdbstub documentation Date: Fri, 3 Apr 2020 10:40:14 +0100 Message-Id: <20200403094014.9589-1-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::433 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: pass (identity @linaro.org) Content-Type: text/plain; charset="utf-8" The documentation of our -s and -gdb options is quite old; in particular it still claims that it will cause QEMU to stop and wait for the gdb connection, when this has not been true for some time: you also need to pass -S if you want to make QEMU not launch the guest on startup. Improve the documentation to mention this requirement in the executable's --help output, the documentation of the -gdb option in the manual, and in the "GDB usage" chapter. Includes some minor tweaks to these paragraphs of documentation since I was editing them anyway (such as dropping the description of our gdb support as "primitive"). Signed-off-by: Peter Maydell Reviewed-by: Alex Benn=C3=A9e Reviewed-by: Philippe Mathieu-Daud=C3=A9 Reviewed-by: Richard Henderson --- Maybe 5.0 material since it's just a docs improvement? docs/system/gdb.rst | 22 +++++++++++++++------- qemu-options.hx | 24 ++++++++++++++++++------ 2 files changed, 33 insertions(+), 13 deletions(-) diff --git a/docs/system/gdb.rst b/docs/system/gdb.rst index 639f814b32d..a40145fcf84 100644 --- a/docs/system/gdb.rst +++ b/docs/system/gdb.rst @@ -3,17 +3,25 @@ GDB usage --------- =20 -QEMU has a primitive support to work with gdb, so that you can do -'Ctrl-C' while the virtual machine is running and inspect its state. +QEMU supports working with gdb via gdb's remote-connection facility +(the "gdbstub"). This allows you to debug guest code in the same +way that you might with a low-level debug facility like JTAG +on real hardware. You can stop and start the virtual machine, +examine state like registers and memory, and set breakpoints and +watchpoints. =20 -In order to use gdb, launch QEMU with the '-s' option. It will wait for -a gdb connection: +In order to use gdb, launch QEMU with the ``-s`` and ``-S`` options. +The ``-s`` option will make QEMU listen for an incoming connection +from gdb on TCP port 1234, and ``-S`` will make QEMU not start the +guest until you tell it to from gdb. (If you want to specify which +TCP port to use or to use something other than TCP for the gdbstub +connection, use the ``-gdb dev`` option instead of ``-s``.) =20 .. parsed-literal:: =20 - |qemu_system| -s -kernel bzImage -hda rootdisk.img -append "root=3D/dev= /hda" - Connected to host network interface: tun0 - Waiting gdb connection on port 1234 + |qemu_system| -s -S -kernel bzImage -hda rootdisk.img -append "root=3D/= dev/hda" + +QEMU will launch but will silently wait for gdb to connect. =20 Then launch gdb on the 'vmlinux' executable:: =20 diff --git a/qemu-options.hx b/qemu-options.hx index 16debd03cb6..292d4e7c0ce 100644 --- a/qemu-options.hx +++ b/qemu-options.hx @@ -3680,14 +3680,26 @@ SRST ERST =20 DEF("gdb", HAS_ARG, QEMU_OPTION_gdb, \ - "-gdb dev wait for gdb connection on 'dev'\n", QEMU_ARCH_ALL) + "-gdb dev accept gdb connection on 'dev'. (QEMU defaults to sta= rting\n" + " the guest without waiting for gdb to connect; use -S = too\n" + " if you want it to not start execution.)\n", + QEMU_ARCH_ALL) SRST ``-gdb dev`` - Wait for gdb connection on device dev (see - :ref:`gdb_005fusage`). Typical connections will likely be - TCP-based, but also UDP, pseudo TTY, or even stdio are reasonable - use case. The latter is allowing to start QEMU from within gdb and - establish the connection via a pipe: + Accept a gdb connection on device dev (see + :ref:`gdb_005fusage`). Note that this option does not pause QEMU + execution -- if you want QEMU to not start the guest until you + connect with gdb and issue a ``continue`` command, you will need to + also pass the ``-S`` option to QEMU. + + The most usual configuration is to listen on a local TCP socket:: + + -gdb tcp::3117 + + but you can specify other backends; UDP, pseudo TTY, or even stdio + are all reasonable use cases. For example, a stdio connection + allows you to start QEMU from within gdb and establish the + connection via a pipe: =20 .. parsed-literal:: =20 --=20 2.20.1