From patchwork Tue Feb 25 15:41:20 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 1244373 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=linaro.org Authentication-Results: ozlabs.org; dkim=fail reason="signature verification failed" (2048-bit key; unprotected) header.d=linaro.org header.i=@linaro.org header.a=rsa-sha256 header.s=google header.b=ORhFPc79; dkim-atps=neutral Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 48RjrJ08l6z9sPK for ; Wed, 26 Feb 2020 02:43:11 +1100 (AEDT) Received: from localhost ([::1]:59215 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6cMX-0006Pb-Pw for incoming@patchwork.ozlabs.org; Tue, 25 Feb 2020 10:43:09 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:33976) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j6cKy-0003Hy-Hm for qemu-devel@nongnu.org; Tue, 25 Feb 2020 10:41:33 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j6cKv-0000xg-WC for qemu-devel@nongnu.org; Tue, 25 Feb 2020 10:41:32 -0500 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:36423) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j6cKv-0000x5-PM for qemu-devel@nongnu.org; Tue, 25 Feb 2020 10:41:29 -0500 Received: by mail-wm1-x344.google.com with SMTP id p17so3627351wma.1 for ; Tue, 25 Feb 2020 07:41:29 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=1FKjE5sNT4q2ywmJDIndXZQ5U1oyDqrNzleV/UagBxk=; b=ORhFPc790Qw3mdfKxucjlwr81Rzin/Mv0DIpW7/anPyGO+ug8BIb17MY3iCdUa/56O SivZgc8MUvAyEsTHuoGeueu1qXIzJ6lkWj/lm9dL6TnEERLsDV7y0wK22dZAwgYv8LYL /7ByIAivlGYtPo8PmLsz3qHn883T53EUgUUC4z/B4AZpmeIxMaVMDtJwqDda6iBYJ1NC /zu00RWA4Madjmjn8TZcl4p99+lbvz3BAC51Y9JZTc0UiXinTq26qfnxnPrzjFu3rlX8 4GyhieHluGa0LIyWyAZVtU07OTAsrN0QsC5YLgwLM2LTQEsMHRWdEg5MSgrSo8IhlDly gfjw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=1FKjE5sNT4q2ywmJDIndXZQ5U1oyDqrNzleV/UagBxk=; b=Y0KNoTNTVF/iS+5rxjOtJ30I3P8Y/kY2hl8zvimi/ArsEJmi6eomuTRL4QsswIaXp5 hkCoxaZA5B6xq4HrLz++UejiiooH6377/aezUAlS+ZlnoxdE7adJxU58XREK2HhGgd30 nmgYCAKmkgFt/bO8pFUPS8zH/OixDR+35raKhnArWOyNfH2MuLZmhVfX1c6jVEqXAa+y O2SlsJgOrCUvPfeK4R3xi7r1SK1+kxsGLpExmY/VdvVRdD0YbTKOoSZpSmFgb0ntc5uI DsxgY/VlsvVNU5Ptp6kxYPnttfeI63zzTWk8Pl9Mk5yEszPxPcDBI697l2LmEyOH5rGG KV/Q== X-Gm-Message-State: APjAAAX2+MyQhJWjS+tB4IlFp2B3GcuuChbpfTs5GL4fuEy/BfhZRfh/ qLkhm8q0dAr8Mbiq/68v1NqhDfNCEiIEKA== X-Google-Smtp-Source: APXvYqzopQSytfqZ04vAIWxRIzeDZP1kCEtbT7vfb8q+0AUnYeNL49hCJjYjdAiqKkI5tCVZH2Qa6w== X-Received: by 2002:a7b:c779:: with SMTP id x25mr5935534wmk.77.1582645288350; Tue, 25 Feb 2020 07:41:28 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c9sm24438604wrq.44.2020.02.25.07.41.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 25 Feb 2020 07:41:27 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Subject: [PATCH 3/4] docs: Convert 'managed start up options' docs to rST Date: Tue, 25 Feb 2020 15:41:20 +0000 Message-Id: <20200225154121.21116-4-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200225154121.21116-1-peter.maydell@linaro.org> References: <20200225154121.21116-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::344 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: , Cc: Paolo Bonzini , Stefan Hajnoczi Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: "Qemu-devel" The only remaining content in qemu-tech.texi is a few paragraphs about managed start up options; move them to a new rST document in the system manual. In the process we fix one typo and format more option and command names as literal text, but make no significant changes to the content. Signed-off-by: Peter Maydell Reviewed-by: Aleksandar Markovic --- Makefile | 2 +- docs/system/index.rst | 1 + docs/system/managed-startup.rst | 35 +++++++++++++++++++++++++++ qemu-doc.texi | 3 --- qemu-tech.texi | 42 --------------------------------- 5 files changed, 37 insertions(+), 46 deletions(-) create mode 100644 docs/system/managed-startup.rst delete mode 100644 qemu-tech.texi diff --git a/Makefile b/Makefile index 5f0f803b471..28749d20401 100644 --- a/Makefile +++ b/Makefile @@ -1114,7 +1114,7 @@ txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \ qemu-options.texi \ - qemu-tech.texi qemu-option-trace.texi \ + qemu-option-trace.texi \ qemu-deprecated.texi qemu-monitor.texi \ qemu-monitor-info.texi \ docs/qemu-cpu-models.texi diff --git a/docs/system/index.rst b/docs/system/index.rst index 794e5d8de03..887bef92f40 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -14,5 +14,6 @@ Contents: .. toctree:: :maxdepth: 2 + managed-startup qemu-block-drivers security diff --git a/docs/system/managed-startup.rst b/docs/system/managed-startup.rst new file mode 100644 index 00000000000..9bcf98ea790 --- /dev/null +++ b/docs/system/managed-startup.rst @@ -0,0 +1,35 @@ +Managed start up options +======================== + +In system mode emulation, it's possible to create a VM in a paused +state using the ``-S`` command line option. In this state the machine +is completely initialized according to command line options and ready +to execute VM code but VCPU threads are not executing any code. The VM +state in this paused state depends on the way QEMU was started. It +could be in: + +- initial state (after reset/power on state) +- with direct kernel loading, the initial state could be amended to execute + code loaded by QEMU in the VM's RAM and with incoming migration +- with incoming migration, initial state will be amended with the migrated + machine state after migration completes + +This paused state is typically used by users to query machine state and/or +additionally configure the machine (by hotplugging devices) in runtime before +allowing VM code to run. + +However, at the ``-S`` pause point, it's impossible to configure options +that affect initial VM creation (like: ``-smp``/``-m``/``-numa`` ...) or +cold plug devices. The experimental ``--preconfig`` command line option +allows pausing QEMU before the initial VM creation, in a "preconfig" state, +where additional queries and configuration can be performed via QMP +before moving on to the resulting configuration startup. In the +preconfig state, QEMU only allows a limited set of commands over the +QMP monitor, where the commands do not depend on an initialized +machine, including but not limited to: + +- ``qmp_capabilities`` +- ``query-qmp-schema`` +- ``query-commands`` +- ``query-status`` +- ``x-exit-preconfig`` diff --git a/qemu-doc.texi b/qemu-doc.texi index c11b1a5d5ad..7798e072a1c 100644 --- a/qemu-doc.texi +++ b/qemu-doc.texi @@ -40,7 +40,6 @@ * QEMU System emulator for non PC targets:: * QEMU User space emulator:: * System requirements:: -* Implementation notes:: * Deprecated features:: * Recently removed features:: * Supported build platforms:: @@ -2835,8 +2834,6 @@ added with Linux 4.5 which is supported by the major distros. And even if RHEL7 has kernel 3.10, KVM there has the required functionality there to make it close to a 4.5 or newer kernel. -@include qemu-tech.texi - @include qemu-deprecated.texi @node Supported build platforms diff --git a/qemu-tech.texi b/qemu-tech.texi deleted file mode 100644 index 35da6a40af1..00000000000 --- a/qemu-tech.texi +++ /dev/null @@ -1,42 +0,0 @@ -@node Implementation notes -@appendix Implementation notes - -@menu -* Managed start up options:: -@end menu - -@node Managed start up options -@section Managed start up options - -In system mode emulation, it's possible to create a VM in a paused state using -the -S command line option. In this state the machine is completely initialized -according to command line options and ready to execute VM code but VCPU threads -are not executing any code. The VM state in this paused state depends on the way -QEMU was started. It could be in: -@table @asis -@item initial state (after reset/power on state) -@item with direct kernel loading, the initial state could be amended to execute -code loaded by QEMU in the VM's RAM and with incoming migration -@item with incoming migration, initial state will by amended with the migrated -machine state after migration completes. -@end table - -This paused state is typically used by users to query machine state and/or -additionally configure the machine (by hotplugging devices) in runtime before -allowing VM code to run. - -However, at the -S pause point, it's impossible to configure options that affect -initial VM creation (like: -smp/-m/-numa ...) or cold plug devices. The -experimental --preconfig command line option allows pausing QEMU -before the initial VM creation, in a ``preconfig'' state, where additional -queries and configuration can be performed via QMP before moving on to -the resulting configuration startup. In the preconfig state, QEMU only allows -a limited set of commands over the QMP monitor, where the commands do not -depend on an initialized machine, including but not limited to: -@table @asis -@item qmp_capabilities -@item query-qmp-schema -@item query-commands -@item query-status -@item x-exit-preconfig -@end table