* [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals
@ 2020-11-12 14:40 Peter Maydell
2020-11-12 14:40 ` [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual Peter Maydell
` (9 more replies)
0 siblings, 10 replies; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
Currently we have a handful of rST documents that are sat in the top
level docs/ directory and do not get built into the manuals. These
are a legacy from the period after we'd decided we wanted rST format
documentation but before we'd set up the manual structure. This
patchset moves them all into at least plausibly suitable places in
the manual set:
* virtio-net-failover, cpu-hotplug, virtio-pmem all go into the
system manual
* microvm goes into the system manual, but first we have to create a
structure in target-i386.rst that lets us have a list of multiple
machine types (along the pattern that target-arm.rst does)
* pr-manager.rst goes into the system manual, but the part of it
documenting the qemu-pr-helper executable needs to go into the
tools manual
If anybody who cares about the x86 machine models would like to
create some documentation of the others ("q35", "isapc", "xenpv",
"xenfv") you now have a place for it to live :-)
Since there's no good way to cross-reference between different
manuals there is no direct link between the pr-manager.rst and the
qemu-pr-helper.rst; my proposal for fixing that is the recent "build
a single manual, not five" RFC.
thanks
-- PMM
Peter Maydell (9):
docs: Move virtio-net-failover.rst into the system manual
docs: Move cpu-hotplug.rst into the system manual
docs: Move virtio-pmem.rst into the system manual
docs/system/virtio-pmem.rst: Fix minor style issues
docs: Split out 'pc' machine model docs into their own file
docs: Move microvm.rst into the system manual
docs: Move pr-manager.rst into the system manual
docs: Split qemu-pr-helper documentation into tools manual
docs/system/pr-manager.rst: Fix minor docs nits
docs/meson.build | 1 +
docs/{ => system}/cpu-hotplug.rst | 0
docs/{ => system/i386}/microvm.rst | 5 +-
docs/system/i386/pc.rst | 7 ++
docs/system/index.rst | 4 +
docs/{ => system}/pr-manager.rst | 44 ++---------
docs/system/target-i386.rst | 19 +++--
docs/{ => system}/virtio-net-failover.rst | 0
docs/system/virtio-pmem.rst | 75 +++++++++++++++++++
docs/tools/conf.py | 2 +
docs/tools/index.rst | 1 +
docs/tools/qemu-pr-helper.rst | 90 +++++++++++++++++++++++
docs/virtio-pmem.rst | 76 -------------------
13 files changed, 204 insertions(+), 120 deletions(-)
rename docs/{ => system}/cpu-hotplug.rst (100%)
rename docs/{ => system/i386}/microvm.rst (98%)
create mode 100644 docs/system/i386/pc.rst
rename docs/{ => system}/pr-manager.rst (68%)
rename docs/{ => system}/virtio-net-failover.rst (100%)
create mode 100644 docs/system/virtio-pmem.rst
create mode 100644 docs/tools/qemu-pr-helper.rst
delete mode 100644 docs/virtio-pmem.rst
--
2.20.1
^ permalink raw reply [flat|nested] 21+ messages in thread
* [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:08 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 2/9] docs: Move cpu-hotplug.rst " Peter Maydell
` (8 subsequent siblings)
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
The virtio-net-failover documentation is currently orphan and
not included in any manual; move it into the system manual,
immediately following the general network emulation section.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/system/index.rst | 1 +
docs/{ => system}/virtio-net-failover.rst | 0
2 files changed, 1 insertion(+)
rename docs/{ => system}/virtio-net-failover.rst (100%)
diff --git a/docs/system/index.rst b/docs/system/index.rst
index c0f685b818e..d0613cd5f72 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -21,6 +21,7 @@ Contents:
monitor
images
net
+ virtio-net-failover
usb
ivshmem
linuxboot
diff --git a/docs/virtio-net-failover.rst b/docs/system/virtio-net-failover.rst
similarity index 100%
rename from docs/virtio-net-failover.rst
rename to docs/system/virtio-net-failover.rst
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 2/9] docs: Move cpu-hotplug.rst into the system manual
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
2020-11-12 14:40 ` [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:10 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 3/9] docs: Move virtio-pmem.rst " Peter Maydell
` (7 subsequent siblings)
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
The cpu-hotplug.rst documentation is currently orphan and not
included in any manual; move it into the system manual.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/{ => system}/cpu-hotplug.rst | 0
docs/system/index.rst | 1 +
2 files changed, 1 insertion(+)
rename docs/{ => system}/cpu-hotplug.rst (100%)
diff --git a/docs/cpu-hotplug.rst b/docs/system/cpu-hotplug.rst
similarity index 100%
rename from docs/cpu-hotplug.rst
rename to docs/system/cpu-hotplug.rst
diff --git a/docs/system/index.rst b/docs/system/index.rst
index d0613cd5f72..0f0f6d2e99d 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -29,6 +29,7 @@ Contents:
tls
gdb
managed-startup
+ cpu-hotplug
targets
security
deprecated
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 3/9] docs: Move virtio-pmem.rst into the system manual
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
2020-11-12 14:40 ` [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual Peter Maydell
2020-11-12 14:40 ` [for-5.2 2/9] docs: Move cpu-hotplug.rst " Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:17 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues Peter Maydell
` (6 subsequent siblings)
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/system/index.rst | 1 +
docs/{ => system}/virtio-pmem.rst | 0
2 files changed, 1 insertion(+)
rename docs/{ => system}/virtio-pmem.rst (100%)
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 0f0f6d2e99d..2a5155c67dc 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -30,6 +30,7 @@ Contents:
gdb
managed-startup
cpu-hotplug
+ virtio-pmem
targets
security
deprecated
diff --git a/docs/virtio-pmem.rst b/docs/system/virtio-pmem.rst
similarity index 100%
rename from docs/virtio-pmem.rst
rename to docs/system/virtio-pmem.rst
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
` (2 preceding siblings ...)
2020-11-12 14:40 ` [for-5.2 3/9] docs: Move virtio-pmem.rst " Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:23 ` Alex Bennée
2020-11-19 14:17 ` Pankaj Gupta
2020-11-12 14:40 ` [for-5.2 5/9] docs: Split out 'pc' machine model docs into their own file Peter Maydell
` (5 subsequent siblings)
9 siblings, 2 replies; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
The virtio-pmem documentation has some minor style issues we hadn't
noticed since we weren't rendering it in our docs:
* Sphinx doesn't complain about overlong title-underlining the
way it complains about too-short underlining, but it looks odd;
make the underlines of the top level title the right length
* Indent of paragraphs makes them render as blockquotes;
remove the indent so they just render as normal text
* Leading 'o' isn't rst markup, so it just renders as a literal
"o"; reformat as a subsection heading instead
* "QEMU" in the document title and section headings are a bit
odd and unnecessary since this is the QEMU manual; delete
or rephrase them
* There's no need to specify what QEMU version the device first
appeared in.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/system/virtio-pmem.rst | 55 ++++++++++++++++++-------------------
1 file changed, 27 insertions(+), 28 deletions(-)
diff --git a/docs/system/virtio-pmem.rst b/docs/system/virtio-pmem.rst
index 4bf5d004432..e5f91eff1c2 100644
--- a/docs/system/virtio-pmem.rst
+++ b/docs/system/virtio-pmem.rst
@@ -1,38 +1,37 @@
-========================
-QEMU virtio pmem
-========================
+===========
+virtio pmem
+===========
- This document explains the setup and usage of the virtio pmem device
- which is available since QEMU v4.1.0.
-
- The virtio pmem device is a paravirtualized persistent memory device
- on regular (i.e non-NVDIMM) storage.
+This document explains the setup and usage of the virtio pmem device.
+The virtio pmem device is a paravirtualized persistent memory device
+on regular (i.e non-NVDIMM) storage.
Usecase
--------
- Virtio pmem allows to bypass the guest page cache and directly use
- host page cache. This reduces guest memory footprint as the host can
- make efficient memory reclaim decisions under memory pressure.
+Virtio pmem allows to bypass the guest page cache and directly use
+host page cache. This reduces guest memory footprint as the host can
+make efficient memory reclaim decisions under memory pressure.
-o How does virtio-pmem compare to the nvdimm emulation supported by QEMU?
+How does virtio-pmem compare to the nvdimm emulation?
+-----------------------------------------------------
- NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not
- persist the guest writes as there are no defined semantics in the device
- specification. The virtio pmem device provides guest write persistence
- on non-NVDIMM host storage.
+NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not
+persist the guest writes as there are no defined semantics in the device
+specification. The virtio pmem device provides guest write persistence
+on non-NVDIMM host storage.
virtio pmem usage
-----------------
- A virtio pmem device backed by a memory-backend-file can be created on
- the QEMU command line as in the following example::
+A virtio pmem device backed by a memory-backend-file can be created on
+the QEMU command line as in the following example::
-object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G
-device virtio-pmem-pci,memdev=mem1,id=nv1
- where:
+where:
- "object memory-backend-file,id=mem1,share,mem-path=<image>, size=<image size>"
creates a backend file with the specified size.
@@ -40,8 +39,8 @@ virtio pmem usage
- "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem
pci device whose storage is provided by above memory backend device.
- Multiple virtio pmem devices can be created if multiple pairs of "-object"
- and "-device" are provided.
+Multiple virtio pmem devices can be created if multiple pairs of "-object"
+and "-device" are provided.
Hotplug
-------
@@ -59,14 +58,14 @@ the guest::
Guest Data Persistence
----------------------
- Guest data persistence on non-NVDIMM requires guest userspace applications
- to perform fsync/msync. This is different from a real nvdimm backend where
- no additional fsync/msync is required. This is to persist guest writes in
- host backing file which otherwise remains in host page cache and there is
- risk of losing the data in case of power failure.
+Guest data persistence on non-NVDIMM requires guest userspace applications
+to perform fsync/msync. This is different from a real nvdimm backend where
+no additional fsync/msync is required. This is to persist guest writes in
+host backing file which otherwise remains in host page cache and there is
+risk of losing the data in case of power failure.
- With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides
- a hint to application to perform fsync for write persistence.
+With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides
+a hint to application to perform fsync for write persistence.
Limitations
------------
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 5/9] docs: Split out 'pc' machine model docs into their own file
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
` (3 preceding siblings ...)
2020-11-12 14:40 ` [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:26 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 6/9] docs: Move microvm.rst into the system manual Peter Maydell
` (4 subsequent siblings)
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
Currently target-i386.rst includes the documentation of the 'pc'
machine model inline. Split it out into its own file, in a
similar way to target-i386.rst; this gives us a place to put
documentation of other i386 machine models, such as 'microvm'.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/system/i386/pc.rst | 7 +++++++
docs/system/target-i386.rst | 18 +++++++++++++-----
2 files changed, 20 insertions(+), 5 deletions(-)
create mode 100644 docs/system/i386/pc.rst
diff --git a/docs/system/i386/pc.rst b/docs/system/i386/pc.rst
new file mode 100644
index 00000000000..d543c11a5cd
--- /dev/null
+++ b/docs/system/i386/pc.rst
@@ -0,0 +1,7 @@
+i440fx PC (``pc-i440fx``, ``pc``)
+=================================
+
+Peripherals
+~~~~~~~~~~~
+
+.. include:: ../target-i386-desc.rst.inc
diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst
index 51be03d881f..1612ddba907 100644
--- a/docs/system/target-i386.rst
+++ b/docs/system/target-i386.rst
@@ -1,14 +1,22 @@
.. _QEMU-PC-System-emulator:
-x86 (PC) System emulator
-------------------------
+x86 System emulator
+-------------------
.. _pcsys_005fdevices:
-Peripherals
-~~~~~~~~~~~
+Board-specific documentation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. include:: target-i386-desc.rst.inc
+..
+ This table of contents should be kept sorted alphabetically
+ by the title text of each file, which isn't the same ordering
+ as an alphabetical sort by filename.
+
+.. toctree::
+ :maxdepth: 1
+
+ i386/pc
.. include:: cpu-models-x86.rst.inc
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 6/9] docs: Move microvm.rst into the system manual
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
` (4 preceding siblings ...)
2020-11-12 14:40 ` [for-5.2 5/9] docs: Split out 'pc' machine model docs into their own file Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:30 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 7/9] docs: Move pr-manager.rst " Peter Maydell
` (3 subsequent siblings)
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
Now that target-i386.rst has a place to list documentation of
machines other than the 'pc' machine, we have a place we can
move the microvm documentation to.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/{ => system/i386}/microvm.rst | 5 ++---
docs/system/target-i386.rst | 1 +
2 files changed, 3 insertions(+), 3 deletions(-)
rename docs/{ => system/i386}/microvm.rst (98%)
diff --git a/docs/microvm.rst b/docs/system/i386/microvm.rst
similarity index 98%
rename from docs/microvm.rst
rename to docs/system/i386/microvm.rst
index fcf41fc1f6f..1675e37d3e7 100644
--- a/docs/microvm.rst
+++ b/docs/system/i386/microvm.rst
@@ -1,6 +1,5 @@
-====================
-microvm Machine Type
-====================
+'microvm' virtual platform (``microvm``)
+========================================
``microvm`` is a machine type inspired by ``Firecracker`` and
constructed after its machine model.
diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst
index 1612ddba907..22ba5ce2c0f 100644
--- a/docs/system/target-i386.rst
+++ b/docs/system/target-i386.rst
@@ -16,6 +16,7 @@ Board-specific documentation
.. toctree::
:maxdepth: 1
+ i386/microvm
i386/pc
.. include:: cpu-models-x86.rst.inc
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 7/9] docs: Move pr-manager.rst into the system manual
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
` (5 preceding siblings ...)
2020-11-12 14:40 ` [for-5.2 6/9] docs: Move microvm.rst into the system manual Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:31 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 8/9] docs: Split qemu-pr-helper documentation into tools manual Peter Maydell
` (2 subsequent siblings)
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
Move the pr-manager documentation into the system manual.
Some of it (the documentation of the pr-manager-helper tool)
should be in tools, but we will split it up after moving it.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/system/index.rst | 1 +
docs/{ => system}/pr-manager.rst | 0
2 files changed, 1 insertion(+)
rename docs/{ => system}/pr-manager.rst (100%)
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 2a5155c67dc..e5a35817a24 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -31,6 +31,7 @@ Contents:
managed-startup
cpu-hotplug
virtio-pmem
+ pr-manager
targets
security
deprecated
diff --git a/docs/pr-manager.rst b/docs/system/pr-manager.rst
similarity index 100%
rename from docs/pr-manager.rst
rename to docs/system/pr-manager.rst
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 8/9] docs: Split qemu-pr-helper documentation into tools manual
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
` (6 preceding siblings ...)
2020-11-12 14:40 ` [for-5.2 7/9] docs: Move pr-manager.rst " Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:32 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 9/9] docs/system/pr-manager.rst: Fix minor docs nits Peter Maydell
2020-11-12 18:33 ` [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Alex Bennée
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
Split the documentation of the qemu-pr-helper binary into the tools
manual, and give it a manpage like our other standalone executables.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/meson.build | 1 +
docs/system/pr-manager.rst | 38 ++-------------
docs/tools/conf.py | 2 +
docs/tools/index.rst | 1 +
docs/tools/qemu-pr-helper.rst | 90 +++++++++++++++++++++++++++++++++++
5 files changed, 99 insertions(+), 33 deletions(-)
create mode 100644 docs/tools/qemu-pr-helper.rst
diff --git a/docs/meson.build b/docs/meson.build
index bf8204a08fa..ebd85d59f98 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -60,6 +60,7 @@ if build_docs
'tools': {
'qemu-img.1': (have_tools ? 'man1' : ''),
'qemu-nbd.8': (have_tools ? 'man8' : ''),
+ 'qemu-pr-helper.8': (have_tools ? 'man8' : ''),
'qemu-trace-stap.1': (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''),
'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''),
'virtiofsd.1': (have_virtiofsd ? 'man1' : ''),
diff --git a/docs/system/pr-manager.rst b/docs/system/pr-manager.rst
index 9b1de198b1b..3f5b9f94dcd 100644
--- a/docs/system/pr-manager.rst
+++ b/docs/system/pr-manager.rst
@@ -50,39 +50,11 @@ Alternatively, using ``-blockdev``::
-blockdev node-name=hd,driver=raw,file.driver=host_device,file.filename=/dev/sdb,file.pr-manager=helper0
-device scsi-block,drive=hd
-----------------------------------
-Invoking :program:`qemu-pr-helper`
-----------------------------------
-
-QEMU provides an implementation of the persistent reservation helper,
-called :program:`qemu-pr-helper`. The helper should be started as a
-system service and supports the following option:
-
--d, --daemon run in the background
--q, --quiet decrease verbosity
--v, --verbose increase verbosity
--f, --pidfile=path PID file when running as a daemon
--k, --socket=path path to the socket
--T, --trace=trace-opts tracing options
-
-By default, the socket and PID file are placed in the runtime state
-directory, for example :file:`/var/run/qemu-pr-helper.sock` and
-:file:`/var/run/qemu-pr-helper.pid`. The PID file is not created
-unless :option:`-d` is passed too.
-
-:program:`qemu-pr-helper` can also use the systemd socket activation
-protocol. In this case, the systemd socket unit should specify a
-Unix stream socket, like this::
-
- [Socket]
- ListenStream=/var/run/qemu-pr-helper.sock
-
-After connecting to the socket, :program:`qemu-pr-helper`` can optionally drop
-root privileges, except for those capabilities that are needed for
-its operation. To do this, add the following options:
-
--u, --user=user user to drop privileges to
--g, --group=group group to drop privileges to
+You will also need to ensure that the helper program
+:command:`qemu-pr-helper` is running, and that it has been
+set up to use the same socket filename as your QEMU commandline
+specifies. See the qemu-pr-helper documentation or manpage for
+further details.
---------------------------------------------
Multipath devices and persistent reservations
diff --git a/docs/tools/conf.py b/docs/tools/conf.py
index 9052d17d6d4..4760d36ff2a 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -22,6 +22,8 @@ man_pages = [
['Fabrice Bellard'], 1),
('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
['Anthony Liguori <anthony@codemonkey.ws>'], 8),
+ ('qemu-pr-helper', 'qemu-pr-helper', 'QEMU persistent reservation helper',
+ [], 8),
('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
[], 1),
('virtfs-proxy-helper', 'virtfs-proxy-helper',
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index 232ce9f3e46..b99f86c7c66 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -12,6 +12,7 @@ Contents:
qemu-img
qemu-nbd
+ qemu-pr-helper
qemu-trace-stap
virtfs-proxy-helper
virtiofsd
diff --git a/docs/tools/qemu-pr-helper.rst b/docs/tools/qemu-pr-helper.rst
new file mode 100644
index 00000000000..ac036180ac1
--- /dev/null
+++ b/docs/tools/qemu-pr-helper.rst
@@ -0,0 +1,90 @@
+QEMU persistent reservation helper
+==================================
+
+Synopsis
+--------
+
+**qemu-pr-helper** [*OPTION*]
+
+Description
+-----------
+
+Implements the persistent reservation helper for QEMU.
+
+SCSI persistent reservations allow restricting access to block devices
+to specific initiators in a shared storage setup. When implementing
+clustering of virtual machines, it is a common requirement for virtual
+machines to send persistent reservation SCSI commands. However,
+the operating system restricts sending these commands to unprivileged
+programs because incorrect usage can disrupt regular operation of the
+storage fabric. QEMU's SCSI passthrough devices ``scsi-block``
+and ``scsi-generic`` support passing guest persistent reservation
+requests to a privileged external helper program. :program:`qemu-pr-helper`
+is that external helper; it creates a socket which QEMU can
+connect to to communicate with it.
+
+If you want to run VMs in a setup like this, this helper should be
+started as a system service, and you should read the QEMU manual
+section on "persistent reservation managers" to find out how to
+configure QEMU to connect to the socket created by
+:program:`qemu-pr-helper`.
+
+After connecting to the socket, :program:`qemu-pr-helper` can
+optionally drop root privileges, except for those capabilities that
+are needed for its operation.
+
+:program:`qemu-pr-helper` can also use the systemd socket activation
+protocol. In this case, the systemd socket unit should specify a
+Unix stream socket, like this::
+
+ [Socket]
+ ListenStream=/var/run/qemu-pr-helper.sock
+
+Options
+-------
+
+.. program:: qemu-pr-helper
+
+.. option:: -d, --daemon
+
+ run in the background (and create a PID file)
+
+.. option:: -q, --quiet
+
+ decrease verbosity
+
+.. option:: -v, --verbose
+
+ increase verbosity
+
+.. option:: -f, --pidfile=PATH
+
+ PID file when running as a daemon. By default the PID file
+ is created in the system runtime state directory, for example
+ :file:`/var/run/qemu-pr-helper.pid`.
+
+.. option:: -k, --socket=PATH
+
+ path to the socket. By default the socket is created in
+ the system runtime state directory, for example
+ :file:`/var/run/qemu-pr-helper.sock`.
+
+.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
+
+ .. include:: ../qemu-option-trace.rst.inc
+
+.. option:: -u, --user=USER
+
+ user to drop privileges to
+
+.. option:: -g, --group=GROUP
+
+ group to drop privileges to
+
+.. option:: -h, --help
+
+ Display a help message and exit.
+
+.. option:: -V, --version
+
+ Display version information and exit.
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* [for-5.2 9/9] docs/system/pr-manager.rst: Fix minor docs nits
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
` (7 preceding siblings ...)
2020-11-12 14:40 ` [for-5.2 8/9] docs: Split qemu-pr-helper documentation into tools manual Peter Maydell
@ 2020-11-12 14:40 ` Peter Maydell
2020-11-12 18:32 ` Alex Bennée
2020-11-12 18:33 ` [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Alex Bennée
9 siblings, 1 reply; 21+ messages in thread
From: Peter Maydell @ 2020-11-12 14:40 UTC (permalink / raw)
To: qemu-devel
Fix a couple of nits in pr-manager.rst:
* the title marker for the top level heading is overlength
* stray capital 'R' in the middle of a sentence
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
docs/system/pr-manager.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/system/pr-manager.rst b/docs/system/pr-manager.rst
index 3f5b9f94dcd..b19a0c15e66 100644
--- a/docs/system/pr-manager.rst
+++ b/docs/system/pr-manager.rst
@@ -1,8 +1,8 @@
-======================================
+===============================
Persistent reservation managers
-======================================
+===============================
-SCSI persistent Reservations allow restricting access to block devices
+SCSI persistent reservations allow restricting access to block devices
to specific initiators in a shared storage setup. When implementing
clustering of virtual machines, it is a common requirement for virtual
machines to send persistent reservation SCSI commands. However,
--
2.20.1
^ permalink raw reply related [flat|nested] 21+ messages in thread
* Re: [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual
2020-11-12 14:40 ` [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual Peter Maydell
@ 2020-11-12 18:08 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:08 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> The virtio-net-failover documentation is currently orphan and
> not included in any manual; move it into the system manual,
> immediately following the general network emulation section.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 2/9] docs: Move cpu-hotplug.rst into the system manual
2020-11-12 14:40 ` [for-5.2 2/9] docs: Move cpu-hotplug.rst " Peter Maydell
@ 2020-11-12 18:10 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:10 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> The cpu-hotplug.rst documentation is currently orphan and not
> included in any manual; move it into the system manual.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 3/9] docs: Move virtio-pmem.rst into the system manual
2020-11-12 14:40 ` [for-5.2 3/9] docs: Move virtio-pmem.rst " Peter Maydell
@ 2020-11-12 18:17 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:17 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues
2020-11-12 14:40 ` [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues Peter Maydell
@ 2020-11-12 18:23 ` Alex Bennée
2020-11-19 14:17 ` Pankaj Gupta
1 sibling, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:23 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> The virtio-pmem documentation has some minor style issues we hadn't
> noticed since we weren't rendering it in our docs:
>
> * Sphinx doesn't complain about overlong title-underlining the
> way it complains about too-short underlining, but it looks odd;
> make the underlines of the top level title the right length
>
> * Indent of paragraphs makes them render as blockquotes;
> remove the indent so they just render as normal text
>
> * Leading 'o' isn't rst markup, so it just renders as a literal
> "o"; reformat as a subsection heading instead
>
> * "QEMU" in the document title and section headings are a bit
> odd and unnecessary since this is the QEMU manual; delete
> or rephrase them
>
> * There's no need to specify what QEMU version the device first
> appeared in.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> docs/system/virtio-pmem.rst | 55 ++++++++++++++++++-------------------
> 1 file changed, 27 insertions(+), 28 deletions(-)
>
> diff --git a/docs/system/virtio-pmem.rst b/docs/system/virtio-pmem.rst
> index 4bf5d004432..e5f91eff1c2 100644
> --- a/docs/system/virtio-pmem.rst
> +++ b/docs/system/virtio-pmem.rst
> @@ -1,38 +1,37 @@
>
> -========================
> -QEMU virtio pmem
> -========================
> +===========
> +virtio pmem
> +===========
>
> - This document explains the setup and usage of the virtio pmem device
> - which is available since QEMU v4.1.0.
> -
> - The virtio pmem device is a paravirtualized persistent memory device
> - on regular (i.e non-NVDIMM) storage.
> +This document explains the setup and usage of the virtio pmem device.
> +The virtio pmem device is a paravirtualized persistent memory device
> +on regular (i.e non-NVDIMM) storage.
>
> Usecase
> --------
nit: but we didn't fix this while we were at it?
Anyway:
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 5/9] docs: Split out 'pc' machine model docs into their own file
2020-11-12 14:40 ` [for-5.2 5/9] docs: Split out 'pc' machine model docs into their own file Peter Maydell
@ 2020-11-12 18:26 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:26 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> Currently target-i386.rst includes the documentation of the 'pc'
> machine model inline. Split it out into its own file, in a
> similar way to target-i386.rst; this gives us a place to put
> documentation of other i386 machine models, such as 'microvm'.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 6/9] docs: Move microvm.rst into the system manual
2020-11-12 14:40 ` [for-5.2 6/9] docs: Move microvm.rst into the system manual Peter Maydell
@ 2020-11-12 18:30 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:30 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> Now that target-i386.rst has a place to list documentation of
> machines other than the 'pc' machine, we have a place we can
> move the microvm documentation to.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
That said the x86 section runs straight into board models and I feel it
would be nice if we could persuade the x86 guys to write a bit of
pre-amble similar to what we have for Arm that explains the status of
KVM and TCG for x86 guests and the point of i440 and q35 models.
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 7/9] docs: Move pr-manager.rst into the system manual
2020-11-12 14:40 ` [for-5.2 7/9] docs: Move pr-manager.rst " Peter Maydell
@ 2020-11-12 18:31 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:31 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> Move the pr-manager documentation into the system manual.
> Some of it (the documentation of the pr-manager-helper tool)
> should be in tools, but we will split it up after moving it.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 8/9] docs: Split qemu-pr-helper documentation into tools manual
2020-11-12 14:40 ` [for-5.2 8/9] docs: Split qemu-pr-helper documentation into tools manual Peter Maydell
@ 2020-11-12 18:32 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:32 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> Split the documentation of the qemu-pr-helper binary into the tools
> manual, and give it a manpage like our other standalone executables.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 9/9] docs/system/pr-manager.rst: Fix minor docs nits
2020-11-12 14:40 ` [for-5.2 9/9] docs/system/pr-manager.rst: Fix minor docs nits Peter Maydell
@ 2020-11-12 18:32 ` Alex Bennée
0 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:32 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> Fix a couple of nits in pr-manager.rst:
> * the title marker for the top level heading is overlength
> * stray capital 'R' in the middle of a sentence
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
` (8 preceding siblings ...)
2020-11-12 14:40 ` [for-5.2 9/9] docs/system/pr-manager.rst: Fix minor docs nits Peter Maydell
@ 2020-11-12 18:33 ` Alex Bennée
9 siblings, 0 replies; 21+ messages in thread
From: Alex Bennée @ 2020-11-12 18:33 UTC (permalink / raw)
To: Peter Maydell; +Cc: qemu-devel
Peter Maydell <peter.maydell@linaro.org> writes:
> Currently we have a handful of rST documents that are sat in the top
> level docs/ directory and do not get built into the manuals. These
> are a legacy from the period after we'd decided we wanted rST format
> documentation but before we'd set up the manual structure. This
> patchset moves them all into at least plausibly suitable places in
> the manual set:
>
> * virtio-net-failover, cpu-hotplug, virtio-pmem all go into the
> system manual
> * microvm goes into the system manual, but first we have to create a
> structure in target-i386.rst that lets us have a list of multiple
> machine types (along the pattern that target-arm.rst does)
> * pr-manager.rst goes into the system manual, but the part of it
> documenting the qemu-pr-helper executable needs to go into the
> tools manual
>
> If anybody who cares about the x86 machine models would like to
> create some documentation of the others ("q35", "isapc", "xenpv",
> "xenfv") you now have a place for it to live :-)
I should have read the cover letter ;-)
Anyway I also ran a build through rtd:
https://qemu-stsquad.readthedocs.io/en/docs-review/index.html
--
Alex Bennée
^ permalink raw reply [flat|nested] 21+ messages in thread
* Re: [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues
2020-11-12 14:40 ` [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues Peter Maydell
2020-11-12 18:23 ` Alex Bennée
@ 2020-11-19 14:17 ` Pankaj Gupta
1 sibling, 0 replies; 21+ messages in thread
From: Pankaj Gupta @ 2020-11-19 14:17 UTC (permalink / raw)
To: Peter Maydell; +Cc: Qemu Developers
> The virtio-pmem documentation has some minor style issues we hadn't
> noticed since we weren't rendering it in our docs:
>
> * Sphinx doesn't complain about overlong title-underlining the
> way it complains about too-short underlining, but it looks odd;
> make the underlines of the top level title the right length
>
> * Indent of paragraphs makes them render as blockquotes;
> remove the indent so they just render as normal text
>
> * Leading 'o' isn't rst markup, so it just renders as a literal
> "o"; reformat as a subsection heading instead
>
> * "QEMU" in the document title and section headings are a bit
> odd and unnecessary since this is the QEMU manual; delete
> or rephrase them
>
> * There's no need to specify what QEMU version the device first
> appeared in.
>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> docs/system/virtio-pmem.rst | 55 ++++++++++++++++++-------------------
> 1 file changed, 27 insertions(+), 28 deletions(-)
>
> diff --git a/docs/system/virtio-pmem.rst b/docs/system/virtio-pmem.rst
> index 4bf5d004432..e5f91eff1c2 100644
> --- a/docs/system/virtio-pmem.rst
> +++ b/docs/system/virtio-pmem.rst
> @@ -1,38 +1,37 @@
>
> -========================
> -QEMU virtio pmem
> -========================
> +===========
> +virtio pmem
> +===========
>
> - This document explains the setup and usage of the virtio pmem device
> - which is available since QEMU v4.1.0.
> -
> - The virtio pmem device is a paravirtualized persistent memory device
> - on regular (i.e non-NVDIMM) storage.
> +This document explains the setup and usage of the virtio pmem device.
> +The virtio pmem device is a paravirtualized persistent memory device
> +on regular (i.e non-NVDIMM) storage.
>
> Usecase
> --------
>
> - Virtio pmem allows to bypass the guest page cache and directly use
> - host page cache. This reduces guest memory footprint as the host can
> - make efficient memory reclaim decisions under memory pressure.
> +Virtio pmem allows to bypass the guest page cache and directly use
> +host page cache. This reduces guest memory footprint as the host can
> +make efficient memory reclaim decisions under memory pressure.
>
> -o How does virtio-pmem compare to the nvdimm emulation supported by QEMU?
> +How does virtio-pmem compare to the nvdimm emulation?
> +-----------------------------------------------------
>
> - NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not
> - persist the guest writes as there are no defined semantics in the device
> - specification. The virtio pmem device provides guest write persistence
> - on non-NVDIMM host storage.
> +NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not
> +persist the guest writes as there are no defined semantics in the device
> +specification. The virtio pmem device provides guest write persistence
> +on non-NVDIMM host storage.
>
> virtio pmem usage
> -----------------
>
> - A virtio pmem device backed by a memory-backend-file can be created on
> - the QEMU command line as in the following example::
> +A virtio pmem device backed by a memory-backend-file can be created on
> +the QEMU command line as in the following example::
>
> -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G
> -device virtio-pmem-pci,memdev=mem1,id=nv1
>
> - where:
> +where:
>
> - "object memory-backend-file,id=mem1,share,mem-path=<image>, size=<image size>"
> creates a backend file with the specified size.
> @@ -40,8 +39,8 @@ virtio pmem usage
> - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem
> pci device whose storage is provided by above memory backend device.
>
> - Multiple virtio pmem devices can be created if multiple pairs of "-object"
> - and "-device" are provided.
> +Multiple virtio pmem devices can be created if multiple pairs of "-object"
> +and "-device" are provided.
>
> Hotplug
> -------
> @@ -59,14 +58,14 @@ the guest::
> Guest Data Persistence
> ----------------------
>
> - Guest data persistence on non-NVDIMM requires guest userspace applications
> - to perform fsync/msync. This is different from a real nvdimm backend where
> - no additional fsync/msync is required. This is to persist guest writes in
> - host backing file which otherwise remains in host page cache and there is
> - risk of losing the data in case of power failure.
> +Guest data persistence on non-NVDIMM requires guest userspace applications
> +to perform fsync/msync. This is different from a real nvdimm backend where
> +no additional fsync/msync is required. This is to persist guest writes in
> +host backing file which otherwise remains in host page cache and there is
> +risk of losing the data in case of power failure.
>
> - With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides
> - a hint to application to perform fsync for write persistence.
> +With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides
> +a hint to application to perform fsync for write persistence.
>
> Limitations
> ------------
Reviewed-by: Pankaj Gupta <pankaj.gupta@cloud.ionos.com>
^ permalink raw reply [flat|nested] 21+ messages in thread
end of thread, other threads:[~2020-11-19 14:18 UTC | newest]
Thread overview: 21+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-12 14:40 [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Peter Maydell
2020-11-12 14:40 ` [for-5.2 1/9] docs: Move virtio-net-failover.rst into the system manual Peter Maydell
2020-11-12 18:08 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 2/9] docs: Move cpu-hotplug.rst " Peter Maydell
2020-11-12 18:10 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 3/9] docs: Move virtio-pmem.rst " Peter Maydell
2020-11-12 18:17 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 4/9] docs/system/virtio-pmem.rst: Fix minor style issues Peter Maydell
2020-11-12 18:23 ` Alex Bennée
2020-11-19 14:17 ` Pankaj Gupta
2020-11-12 14:40 ` [for-5.2 5/9] docs: Split out 'pc' machine model docs into their own file Peter Maydell
2020-11-12 18:26 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 6/9] docs: Move microvm.rst into the system manual Peter Maydell
2020-11-12 18:30 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 7/9] docs: Move pr-manager.rst " Peter Maydell
2020-11-12 18:31 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 8/9] docs: Split qemu-pr-helper documentation into tools manual Peter Maydell
2020-11-12 18:32 ` Alex Bennée
2020-11-12 14:40 ` [for-5.2 9/9] docs/system/pr-manager.rst: Fix minor docs nits Peter Maydell
2020-11-12 18:32 ` Alex Bennée
2020-11-12 18:33 ` [for-5.2 0/9] docs: Move orphan top-level .rst files into manuals Alex Bennée
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.