diff options
authorPeter Maydell <peter.maydell@linaro.org>2020-02-26 12:30:32 +0100
committerPeter Maydell <peter.maydell@linaro.org>2020-02-27 14:21:37 +0000
commitb47743f94db21d45e31866bc0045c7bd3f0ca601 (patch)
parent0b39fba0e21e845b4dcbe85aab1b6d900b940cda (diff)
docs/system: convert managed startup to rST.
Fix one typo in the process and format more option and command names as literal text, but make no significant changes to the content. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Message-id: 20200226113034.6741-17-pbonzini@redhat.com
2 files changed, 36 insertions, 0 deletions
diff --git a/docs/system/index.rst b/docs/system/index.rst
index d38addb2a0..b2263b70d8 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -13,4 +13,5 @@ Contents:
.. toctree::
:maxdepth: 2
+ managed-startup
diff --git a/docs/system/managed-startup.rst b/docs/system/managed-startup.rst
new file mode 100644
index 0000000000..9bcf98ea79
--- /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``