| Message ID | 20200225154121.21116-4-peter.maydell@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Miscellaneous rST conversions | expand |
On Tuesday, February 25, 2020, Peter Maydell <peter.maydell@linaro.org> wrote: > 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 <peter.maydell@linaro.org> > --- FWIW: Reviewed-by: Aleksandar Markovic <amarkovic@wavecomp.com> > 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 > -- > 2.20.1 > > >
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
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 <peter.maydell@linaro.org> --- 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