* [PATCH v3 0/3] docs: add qemu-storage-daemon documentation
@ 2020-12-09 10:37 Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
` (2 more replies)
0 siblings, 3 replies; 9+ messages in thread
From: Stefan Hajnoczi @ 2020-12-09 10:37 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
Markus Armbruster, Stefan Hajnoczi, Laszlo Ersek
v3:
* Address Kevin's comments
v2:
* Drop block-core.json h2 header removal, add an h1 header to
storage-daemon/qapi/qapi-schema.json instead [Kevin]
* Add Examples section to man page [Kevin]
Add documentation for the qemu-storage-daemon program and its QMP commands.
The man page looks like this:
QEMU-STORAGE-DAEMON(1) QEMU QEMU-STORAGE-DAEMON(1)
NAME
qemu-storage-daemon - QEMU storage daemon
SYNOPSIS
qemu-storage-daemon [options]
DESCRIPTION
qemu-storage-daemon provides disk image functionality from
QEMU, qemu-img, and qemu-nbd in a long-running process con‐
trolled via QMP commands without running a virtual machine. It
can export disk images, run block job operations, and perform
other disk-related operations. The daemon is controlled via a
QMP monitor and initial configuration from the command-line.
The daemon offers the following subset of QEMU features:
• Block nodes
• Block jobs
• Block exports
• Throttle groups
• Character devices
• Crypto and secrets
• QMP
• IOThreads
Commands can be sent over a QEMU Monitor Protocol (QMP) connec‐
tion. See the qemu-storage-daemon-qmp-ref(7) manual page for a
description of the commands.
The daemon runs until it is stopped using the quit QMP command
or SIGINT/SIGHUP/SIGTERM.
Warning: Never modify images in use by a running virtual ma‐
chine or any other process; this may destroy the image. Also,
be aware that querying an image that is being modified by an‐
other process may encounter inconsistent state.
OPTIONS
Standard options:
-h, --help
Display help and exit
-V, --version
Display version information and exit
-T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
Specify tracing options.
[enable=]PATTERN
Immediately enable events matching PATTERN (either
event name or a globbing pattern). This option is
only available if QEMU has been compiled with the
simple, log or ftrace tracing backend. To specify
multiple events or patterns, specify the -trace op‐
tion multiple times.
Use -trace help to print a list of names of trace
points.
events=FILE
Immediately enable events listed in FILE. The file
must contain one event name (as listed in the
trace-events-all file) per line; globbing patterns
are accepted too. This option is only available if
QEMU has been compiled with the simple, log or ftrace
tracing backend.
file=FILE
Log output traces to FILE. This option is only
available if QEMU has been compiled with the simple
tracing backend.
--blockdev BLOCKDEVDEF
is a block node definition. See the qemu(1) manual page
for a description of block node properties and the
qemu-block-drivers(7) manual page for a description of
driver-specific parameters.
--chardev CHARDEVDEF
is a character device definition. See the qemu(1) manual
page for a description of character device properties. A
common character device definition configures a UNIX do‐
main socket:
--chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
--export [type=]nbd,id=<id>,node-name=<node-name>[,name=<ex‐
port-name>][,writable=on|off][,bitmap=<name>]
--export
[type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,log‐
ical-block-size=<block-size>][,num-queues=<num-queues>]
--export
[type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,log‐
ical-block-size=<block-size>][,num-queues=<num-queues>]
is a block export definition. node-name is the block
node that should be exported. writable determines
whether or not the export allows write requests for mod‐
ifying data (the default is off).
The nbd export type requires --nbd-server (see below).
name is the NBD export name. bitmap is the name of a
dirty bitmap reachable from the block node, so the NBD
client can use NBD_OPT_SET_META_CONTEXT with the meta‐
data context name "qemu:dirty-bitmap:BITMAP" to inspect
the bitmap.
The vhost-user-blk export type takes a vhost-user socket
address on which it accept incoming connections. Both
addr.type=unix,addr.path=<socket-path> for UNIX domain
sockets and addr.type=fd,addr.str=<fd> for file descrip‐
tor passing are supported. logical-block-size sets the
logical block size in bytes (the default is 512).
num-queues sets the number of virtqueues (the default is
1).
--monitor MONITORDEF
is a QMP monitor definition. See the qemu(1) manual page
for a description of QMP monitor properties. A common
QMP monitor definition configures a monitor on character
device char1:
--monitor chardev=char1
--nbd-server
addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-au‐
thz=<id>][,max-connections=<n>]
--nbd-server
addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-au‐
thz=<id>][,max-connections=<n>]
is a server for NBD exports. Both TCP and UNIX domain
sockets are supported. TLS encryption can be configured
using --object tls-creds-* and authz-* secrets (see be‐
low).
To configure an NBD server on UNIX domain socket path
/tmp/nbd.sock:
--nbd-server addr.type=unix,addr.path=/tmp/nbd.sock
--object help
--object <type>,help
--object <type>[,<property>=<value>...]
is a QEMU user creatable object definition. List object
types with help. List object properties with
<type>,help. See the qemu(1) manual page for a descrip‐
tion of the object properties.
EXAMPLES
Launch the daemon with QMP monitor socket qmp.sock so clients
can execute QMP commands:
$ qemu-storage-daemon \
--chardev socket,path=qmp.sock,server,nowait,id=char1 \
--monitor chardev=char1
Export raw image file disk.img over NBD UNIX domain socket
nbd.sock:
$ qemu-storage-daemon \
--blockdev driver=file,node-name=disk,filename=disk.img \
--nbd-server addr.type=unix,addr.path=nbd.sock \
--export type=nbd,id=export,node-name=disk,writable=on
Export a qcow2 image file disk.qcow2 as a vhosts-user-blk de‐
vice over UNIX domain socket vhost-user-blk.sock:
$ qemu-storage-daemon \
--blockdev driver=file,node-name=file,filename=disk.qcow2 \
--blockdev driver=qcow2,node-name=qcow2,file=file \
--export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
SEE ALSO
qemu(1), qemu-block-drivers(7), qemu-storage-daemon-qmp-ref(7)
COPYRIGHT
2020, The QEMU Project Developers
5.1.94 Dec 09, 2020 QEMU-STORAGE-DAEMON(1)
Stefan Hajnoczi (3):
docs: generate qemu-storage-daemon-qmp-ref(7) man page
docs: add qemu-storage-daemon(1) man page
MAINTAINERS: add Kevin Wolf as storage daemon maintainer
MAINTAINERS | 9 ++
docs/interop/index.rst | 1 +
docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 ++
docs/tools/index.rst | 1 +
docs/tools/qemu-storage-daemon.rst | 148 +++++++++++++++++++
storage-daemon/qapi/qapi-schema.json | 3 +
docs/interop/conf.py | 2 +
docs/meson.build | 1 +
docs/tools/conf.py | 2 +
9 files changed, 180 insertions(+)
create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst
create mode 100644 docs/tools/qemu-storage-daemon.rst
--
2.28.0
^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-12-09 10:37 [PATCH v3 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
@ 2020-12-09 10:38 ` Stefan Hajnoczi
2020-12-15 16:11 ` Kevin Wolf
2020-12-09 10:38 ` [PATCH v3 2/3] docs: add qemu-storage-daemon(1) " Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer Stefan Hajnoczi
2 siblings, 1 reply; 9+ messages in thread
From: Stefan Hajnoczi @ 2020-12-09 10:38 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
Markus Armbruster, Stefan Hajnoczi, Laszlo Ersek
Although individual qemu-storage-daemon QMP commands are identical to
QEMU QMP commands, qemu-storage-daemon only supports a subset of QEMU's
QMP commands. Generate a manual page of just the commands supported by
qemu-storage-daemon so that users know exactly what is available in
qemu-storage-daemon.
Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
block-core.json is at the h2 heading level.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
docs/interop/index.rst | 1 +
docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 +++++++++++++
storage-daemon/qapi/qapi-schema.json | 3 +++
docs/interop/conf.py | 2 ++
docs/meson.build | 1 +
5 files changed, 20 insertions(+)
create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst
diff --git a/docs/interop/index.rst b/docs/interop/index.rst
index cd78d679d8..95d56495f6 100644
--- a/docs/interop/index.rst
+++ b/docs/interop/index.rst
@@ -20,6 +20,7 @@ Contents:
qemu-ga
qemu-ga-ref
qemu-qmp-ref
+ qemu-storage-daemon-qmp-ref
vhost-user
vhost-user-gpu
vhost-vdpa
diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
new file mode 100644
index 0000000000..caf9dad23a
--- /dev/null
+++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
@@ -0,0 +1,13 @@
+QEMU Storage Daemon QMP Reference Manual
+========================================
+
+..
+ TODO: the old Texinfo manual used to note that this manual
+ is GPL-v2-or-later. We should make that reader-visible
+ both here and in our Sphinx manuals more generally.
+
+..
+ TODO: display the QEMU version, both here and in our Sphinx manuals
+ more generally.
+
+.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qapi-schema.json
index c6ad5ae1e3..28117c3aac 100644
--- a/storage-daemon/qapi/qapi-schema.json
+++ b/storage-daemon/qapi/qapi-schema.json
@@ -15,6 +15,9 @@
{ 'include': '../../qapi/pragma.json' }
+##
+# = Block devices
+##
{ 'include': '../../qapi/block-core.json' }
{ 'include': '../../qapi/block-export.json' }
{ 'include': '../../qapi/char.json' }
diff --git a/docs/interop/conf.py b/docs/interop/conf.py
index 2634ca3410..f4370aaa13 100644
--- a/docs/interop/conf.py
+++ b/docs/interop/conf.py
@@ -23,4 +23,6 @@ man_pages = [
[], 7),
('qemu-qmp-ref', 'qemu-qmp-ref', 'QEMU QMP Reference Manual',
[], 7),
+ ('qemu-storage-daemon-qmp-ref', 'qemu-storage-daemon-qmp-ref',
+ 'QEMU Storage Daemon QMP Reference Manual', [], 7),
]
diff --git a/docs/meson.build b/docs/meson.build
index ebd85d59f9..df5dc50485 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -56,6 +56,7 @@ if build_docs
'qemu-ga.8': (have_tools ? 'man8' : ''),
'qemu-ga-ref.7': 'man7',
'qemu-qmp-ref.7': 'man7',
+ 'qemu-storage-daemon-qmp-ref.7': (have_tools ? 'man7' : ''),
},
'tools': {
'qemu-img.1': (have_tools ? 'man1' : ''),
--
2.28.0
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH v3 2/3] docs: add qemu-storage-daemon(1) man page
2020-12-09 10:37 [PATCH v3 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
@ 2020-12-09 10:38 ` Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer Stefan Hajnoczi
2 siblings, 0 replies; 9+ messages in thread
From: Stefan Hajnoczi @ 2020-12-09 10:38 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
Markus Armbruster, Stefan Hajnoczi, Laszlo Ersek
Document the qemu-storage-daemon tool. Most of the command-line options
are identical to their QEMU counterparts. Perhaps Sphinx hxtool
integration could be extended to extract documentation for individual
command-line options so they can be shared. For now the
qemu-storage-daemon simply refers to the qemu(1) man page where the
command-line options are identical.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
---
docs/tools/index.rst | 1 +
docs/tools/qemu-storage-daemon.rst | 148 +++++++++++++++++++++++++++++
docs/tools/conf.py | 2 +
3 files changed, 151 insertions(+)
create mode 100644 docs/tools/qemu-storage-daemon.rst
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index b99f86c7c6..3a5829c17a 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -11,6 +11,7 @@ Contents:
:maxdepth: 2
qemu-img
+ qemu-storage-daemon
qemu-nbd
qemu-pr-helper
qemu-trace-stap
diff --git a/docs/tools/qemu-storage-daemon.rst b/docs/tools/qemu-storage-daemon.rst
new file mode 100644
index 0000000000..f63627eaf6
--- /dev/null
+++ b/docs/tools/qemu-storage-daemon.rst
@@ -0,0 +1,148 @@
+QEMU Storage Daemon
+===================
+
+Synopsis
+--------
+
+**qemu-storage-daemon** [options]
+
+Description
+-----------
+
+qemu-storage-daemon provides disk image functionality from QEMU, qemu-img, and
+qemu-nbd in a long-running process controlled via QMP commands without running
+a virtual machine. It can export disk images, run block job operations, and
+perform other disk-related operations. The daemon is controlled via a QMP
+monitor and initial configuration from the command-line.
+
+The daemon offers the following subset of QEMU features:
+
+* Block nodes
+* Block jobs
+* Block exports
+* Throttle groups
+* Character devices
+* Crypto and secrets
+* QMP
+* IOThreads
+
+Commands can be sent over a QEMU Monitor Protocol (QMP) connection. See the
+:manpage:`qemu-storage-daemon-qmp-ref(7)` manual page for a description of the
+commands.
+
+The daemon runs until it is stopped using the ``quit`` QMP command or
+SIGINT/SIGHUP/SIGTERM.
+
+**Warning:** Never modify images in use by a running virtual machine or any
+other process; this may destroy the image. Also, be aware that querying an
+image that is being modified by another process may encounter inconsistent
+state.
+
+Options
+-------
+
+.. program:: qemu-storage-daemon
+
+Standard options:
+
+.. option:: -h, --help
+
+ Display help and exit
+
+.. option:: -V, --version
+
+ Display version information and exit
+
+.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
+
+ .. include:: ../qemu-option-trace.rst.inc
+
+.. option:: --blockdev BLOCKDEVDEF
+
+ is a block node definition. See the :manpage:`qemu(1)` manual page for a
+ description of block node properties and the :manpage:`qemu-block-drivers(7)`
+ manual page for a description of driver-specific parameters.
+
+.. option:: --chardev CHARDEVDEF
+
+ is a character device definition. See the :manpage:`qemu(1)` manual page for
+ a description of character device properties. A common character device
+ definition configures a UNIX domain socket::
+
+ --chardev socket,id=char1,path=/tmp/qmp.sock,server,nowait
+
+.. option:: --export [type=]nbd,id=<id>,node-name=<node-name>[,name=<export-name>][,writable=on|off][,bitmap=<name>]
+ --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=unix,addr.path=<socket-path>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
+ --export [type=]vhost-user-blk,id=<id>,node-name=<node-name>,addr.type=fd,addr.str=<fd>[,writable=on|off][,logical-block-size=<block-size>][,num-queues=<num-queues>]
+
+ is a block export definition. ``node-name`` is the block node that should be
+ exported. ``writable`` determines whether or not the export allows write
+ requests for modifying data (the default is off).
+
+ The ``nbd`` export type requires ``--nbd-server`` (see below). ``name`` is
+ the NBD export name. ``bitmap`` is the name of a dirty bitmap reachable from
+ the block node, so the NBD client can use NBD_OPT_SET_META_CONTEXT with the
+ metadata context name "qemu:dirty-bitmap:BITMAP" to inspect the bitmap.
+
+ The ``vhost-user-blk`` export type takes a vhost-user socket address on which
+ it accept incoming connections. Both
+ ``addr.type=unix,addr.path=<socket-path>`` for UNIX domain sockets and
+ ``addr.type=fd,addr.str=<fd>`` for file descriptor passing are supported.
+ ``logical-block-size`` sets the logical block size in bytes (the default is
+ 512). ``num-queues`` sets the number of virtqueues (the default is 1).
+
+.. option:: --monitor MONITORDEF
+
+ is a QMP monitor definition. See the :manpage:`qemu(1)` manual page for
+ a description of QMP monitor properties. A common QMP monitor definition
+ configures a monitor on character device ``char1``::
+
+ --monitor chardev=char1
+
+.. option:: --nbd-server addr.type=inet,addr.host=<host>,addr.port=<port>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
+ --nbd-server addr.type=unix,addr.path=<path>[,tls-creds=<id>][,tls-authz=<id>][,max-connections=<n>]
+
+ is a server for NBD exports. Both TCP and UNIX domain sockets are supported.
+ TLS encryption can be configured using ``--object`` tls-creds-* and authz-*
+ secrets (see below).
+
+ To configure an NBD server on UNIX domain socket path ``/tmp/nbd.sock``::
+
+ --nbd-server addr.type=unix,addr.path=/tmp/nbd.sock
+
+.. option:: --object help
+ --object <type>,help
+ --object <type>[,<property>=<value>...]
+
+ is a QEMU user creatable object definition. List object types with ``help``.
+ List object properties with ``<type>,help``. See the :manpage:`qemu(1)`
+ manual page for a description of the object properties.
+
+Examples
+--------
+Launch the daemon with QMP monitor socket ``qmp.sock`` so clients can execute
+QMP commands::
+
+ $ qemu-storage-daemon \
+ --chardev socket,path=qmp.sock,server,nowait,id=char1 \
+ --monitor chardev=char1
+
+Export raw image file ``disk.img`` over NBD UNIX domain socket ``nbd.sock``::
+
+ $ qemu-storage-daemon \
+ --blockdev driver=file,node-name=disk,filename=disk.img \
+ --nbd-server addr.type=unix,addr.path=nbd.sock \
+ --export type=nbd,id=export,node-name=disk,writable=on
+
+Export a qcow2 image file ``disk.qcow2`` as a vhosts-user-blk device over UNIX
+domain socket ``vhost-user-blk.sock``::
+
+ $ qemu-storage-daemon \
+ --blockdev driver=file,node-name=file,filename=disk.qcow2 \
+ --blockdev driver=qcow2,node-name=qcow2,file=file \
+ --export type=vhost-user-blk,id=export,addr.type=unix,addr.path=vhost-user-blk.sock,node-name=qcow2
+
+See also
+--------
+
+:manpage:`qemu(1)`, :manpage:`qemu-block-drivers(7)`, :manpage:`qemu-storage-daemon-qmp-ref(7)`
diff --git a/docs/tools/conf.py b/docs/tools/conf.py
index 4760d36ff2..7072d99324 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -20,6 +20,8 @@ html_theme_options['description'] = \
man_pages = [
('qemu-img', 'qemu-img', u'QEMU disk image utility',
['Fabrice Bellard'], 1),
+ ('qemu-storage-daemon', 'qemu-storage-daemon', u'QEMU storage daemon',
+ [], 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',
--
2.28.0
^ permalink raw reply related [flat|nested] 9+ messages in thread
* [PATCH v3 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer
2020-12-09 10:37 [PATCH v3 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 2/3] docs: add qemu-storage-daemon(1) " Stefan Hajnoczi
@ 2020-12-09 10:38 ` Stefan Hajnoczi
2 siblings, 0 replies; 9+ messages in thread
From: Stefan Hajnoczi @ 2020-12-09 10:38 UTC (permalink / raw)
To: qemu-devel
Cc: Kevin Wolf, Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
Markus Armbruster, Stefan Hajnoczi, Laszlo Ersek
The MAINTAINERS file was not updated when the storage daemon was merged.
Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
Acked-by: Kevin Wolf <kwolf@redhat.com>
Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>
---
MAINTAINERS | 9 +++++++++
1 file changed, 9 insertions(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 68bc160f41..8676730cc9 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2146,6 +2146,15 @@ F: qobject/block-qdict.c
F: tests/check-block-qdict.c
T: git https://repo.or.cz/qemu/kevin.git block
+Storage daemon
+M: Kevin Wolf <kwolf@redhat.com>
+L: qemu-block@nongnu.org
+S: Supported
+F: storage-daemon/
+F: docs/interop/qemu-storage-daemon-qmp-ref.rst
+F: docs/tools/qemu-storage-daemon.rst
+T: git https://repo.or.cz/qemu/kevin.git block
+
Block I/O path
M: Stefan Hajnoczi <stefanha@redhat.com>
M: Fam Zheng <fam@euphon.net>
--
2.28.0
^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-12-09 10:38 ` [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
@ 2020-12-15 16:11 ` Kevin Wolf
2020-12-16 16:21 ` Stefan Hajnoczi
0 siblings, 1 reply; 9+ messages in thread
From: Kevin Wolf @ 2020-12-15 16:11 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
qemu-devel, Markus Armbruster, Laszlo Ersek
Am 09.12.2020 um 11:38 hat Stefan Hajnoczi geschrieben:
> Although individual qemu-storage-daemon QMP commands are identical to
> QEMU QMP commands, qemu-storage-daemon only supports a subset of QEMU's
> QMP commands. Generate a manual page of just the commands supported by
> qemu-storage-daemon so that users know exactly what is available in
> qemu-storage-daemon.
>
> Add an h1 heading in storage-daemon/qapi/qapi-schema.json so that
> block-core.json is at the h2 heading level.
>
> Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>
> ---
> docs/interop/index.rst | 1 +
> docs/interop/qemu-storage-daemon-qmp-ref.rst | 13 +++++++++++++
> storage-daemon/qapi/qapi-schema.json | 3 +++
> docs/interop/conf.py | 2 ++
> docs/meson.build | 1 +
> 5 files changed, 20 insertions(+)
> create mode 100644 docs/interop/qemu-storage-daemon-qmp-ref.rst
>
> diff --git a/docs/interop/index.rst b/docs/interop/index.rst
> index cd78d679d8..95d56495f6 100644
> --- a/docs/interop/index.rst
> +++ b/docs/interop/index.rst
> @@ -20,6 +20,7 @@ Contents:
> qemu-ga
> qemu-ga-ref
> qemu-qmp-ref
> + qemu-storage-daemon-qmp-ref
> vhost-user
> vhost-user-gpu
> vhost-vdpa
> diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> new file mode 100644
> index 0000000000..caf9dad23a
> --- /dev/null
> +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> @@ -0,0 +1,13 @@
> +QEMU Storage Daemon QMP Reference Manual
> +========================================
> +
> +..
> + TODO: the old Texinfo manual used to note that this manual
> + is GPL-v2-or-later. We should make that reader-visible
> + both here and in our Sphinx manuals more generally.
> +
> +..
> + TODO: display the QEMU version, both here and in our Sphinx manuals
> + more generally.
> +
> +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
Did you intend to actually merge the TODO comments like this into master
or was this meant to be resolved before you send the series?
Kevin
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-12-15 16:11 ` Kevin Wolf
@ 2020-12-16 16:21 ` Stefan Hajnoczi
2020-12-16 16:25 ` Peter Maydell
2020-12-16 17:59 ` Kevin Wolf
0 siblings, 2 replies; 9+ messages in thread
From: Stefan Hajnoczi @ 2020-12-16 16:21 UTC (permalink / raw)
To: Kevin Wolf
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
qemu-devel, Markus Armbruster, Laszlo Ersek
[-- Attachment #1: Type: text/plain, Size: 1210 bytes --]
On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > new file mode 100644
> > index 0000000000..caf9dad23a
> > --- /dev/null
> > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > @@ -0,0 +1,13 @@
> > +QEMU Storage Daemon QMP Reference Manual
> > +========================================
> > +
> > +..
> > + TODO: the old Texinfo manual used to note that this manual
> > + is GPL-v2-or-later. We should make that reader-visible
> > + both here and in our Sphinx manuals more generally.
> > +
> > +..
> > + TODO: display the QEMU version, both here and in our Sphinx manuals
> > + more generally.
> > +
> > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
>
> Did you intend to actually merge the TODO comments like this into master
> or was this meant to be resolved before you send the series?
Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
have these comments and I copied them when creating the file. I don't
intend to try to solve that in this series.
Would you like to keep the comments or should I drop them?
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-12-16 16:21 ` Stefan Hajnoczi
@ 2020-12-16 16:25 ` Peter Maydell
2020-12-16 17:59 ` Kevin Wolf
1 sibling, 0 replies; 9+ messages in thread
From: Peter Maydell @ 2020-12-16 16:25 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: Kevin Wolf, Daniel P. Berrangé,
Qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
QEMU Developers, Markus Armbruster, Laszlo Ersek
On Wed, 16 Dec 2020 at 16:21, Stefan Hajnoczi <stefanha@redhat.com> wrote:
>
> On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > new file mode 100644
> > > index 0000000000..caf9dad23a
> > > --- /dev/null
> > > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > @@ -0,0 +1,13 @@
> > > +QEMU Storage Daemon QMP Reference Manual
> > > +========================================
> > > +
> > > +..
> > > + TODO: the old Texinfo manual used to note that this manual
> > > + is GPL-v2-or-later. We should make that reader-visible
> > > + both here and in our Sphinx manuals more generally.
> > > +
> > > +..
> > > + TODO: display the QEMU version, both here and in our Sphinx manuals
> > > + more generally.
> > > +
> > > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
> >
> > Did you intend to actually merge the TODO comments like this into master
> > or was this meant to be resolved before you send the series?
>
> Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
> have these comments and I copied them when creating the file. I don't
> intend to try to solve that in this series.
>
> Would you like to keep the comments or should I drop them?
FWIW, the ones in those two docs are the result of a request
from Markus when we were doing the conversion of QAPI generated
docs from Texinfo to rST -- the old separate Texinfo-generated
docs ended up with a version/license statement in the generated
docs. Fixing this depends I think on the "merge the 5 manuals
into one single manual" patch; once that's done then it should
be easier to have one consistent place to note license, copyright,
version, etc.
thanks
-- PMM
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-12-16 16:21 ` Stefan Hajnoczi
2020-12-16 16:25 ` Peter Maydell
@ 2020-12-16 17:59 ` Kevin Wolf
2020-12-17 9:34 ` Stefan Hajnoczi
1 sibling, 1 reply; 9+ messages in thread
From: Kevin Wolf @ 2020-12-16 17:59 UTC (permalink / raw)
To: Stefan Hajnoczi
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
qemu-devel, Markus Armbruster, Laszlo Ersek
[-- Attachment #1: Type: text/plain, Size: 1430 bytes --]
Am 16.12.2020 um 17:21 hat Stefan Hajnoczi geschrieben:
> On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > new file mode 100644
> > > index 0000000000..caf9dad23a
> > > --- /dev/null
> > > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > @@ -0,0 +1,13 @@
> > > +QEMU Storage Daemon QMP Reference Manual
> > > +========================================
> > > +
> > > +..
> > > + TODO: the old Texinfo manual used to note that this manual
> > > + is GPL-v2-or-later. We should make that reader-visible
> > > + both here and in our Sphinx manuals more generally.
> > > +
> > > +..
> > > + TODO: display the QEMU version, both here and in our Sphinx manuals
> > > + more generally.
> > > +
> > > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
> >
> > Did you intend to actually merge the TODO comments like this into master
> > or was this meant to be resolved before you send the series?
>
> Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
> have these comments and I copied them when creating the file. I don't
> intend to try to solve that in this series.
>
> Would you like to keep the comments or should I drop them?
Ah, I see. If the same already exists in other places, I'll just merge
it as it is. Thanks!
Kevin
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page
2020-12-16 17:59 ` Kevin Wolf
@ 2020-12-17 9:34 ` Stefan Hajnoczi
0 siblings, 0 replies; 9+ messages in thread
From: Stefan Hajnoczi @ 2020-12-17 9:34 UTC (permalink / raw)
To: Kevin Wolf
Cc: Peter Maydell, Daniel P. Berrangé,
qemu-block, Kashyap Chamarthy, afrosi,
Philippe Mathieu-Daudé,
qemu-devel, Markus Armbruster, Laszlo Ersek
[-- Attachment #1: Type: text/plain, Size: 1576 bytes --]
On Wed, Dec 16, 2020 at 06:59:03PM +0100, Kevin Wolf wrote:
> Am 16.12.2020 um 17:21 hat Stefan Hajnoczi geschrieben:
> > On Tue, Dec 15, 2020 at 05:11:06PM +0100, Kevin Wolf wrote:
> > > > diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > > new file mode 100644
> > > > index 0000000000..caf9dad23a
> > > > --- /dev/null
> > > > +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst
> > > > @@ -0,0 +1,13 @@
> > > > +QEMU Storage Daemon QMP Reference Manual
> > > > +========================================
> > > > +
> > > > +..
> > > > + TODO: the old Texinfo manual used to note that this manual
> > > > + is GPL-v2-or-later. We should make that reader-visible
> > > > + both here and in our Sphinx manuals more generally.
> > > > +
> > > > +..
> > > > + TODO: display the QEMU version, both here and in our Sphinx manuals
> > > > + more generally.
> > > > +
> > > > +.. qapi-doc:: storage-daemon/qapi/qapi-schema.json
> > >
> > > Did you intend to actually merge the TODO comments like this into master
> > > or was this meant to be resolved before you send the series?
> >
> > Thanks for pointing this out. Both qemu-qmp-ref.rst and qemu-ga-ref.rst
> > have these comments and I copied them when creating the file. I don't
> > intend to try to solve that in this series.
> >
> > Would you like to keep the comments or should I drop them?
>
> Ah, I see. If the same already exists in other places, I'll just merge
> it as it is. Thanks!
Great, thanks!
Stefan
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2020-12-17 15:30 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-12-09 10:37 [PATCH v3 0/3] docs: add qemu-storage-daemon documentation Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 1/3] docs: generate qemu-storage-daemon-qmp-ref(7) man page Stefan Hajnoczi
2020-12-15 16:11 ` Kevin Wolf
2020-12-16 16:21 ` Stefan Hajnoczi
2020-12-16 16:25 ` Peter Maydell
2020-12-16 17:59 ` Kevin Wolf
2020-12-17 9:34 ` Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 2/3] docs: add qemu-storage-daemon(1) " Stefan Hajnoczi
2020-12-09 10:38 ` [PATCH v3 3/3] MAINTAINERS: add Kevin Wolf as storage daemon maintainer Stefan Hajnoczi
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).