The following changes since commit b7c359c748a2e3ccb97a184b9739feb2cd48de2f:

Merge remote-tracking branch 'remotes/vivier2/tags/linux-user-for-5.0-pull-request' into staging (2020-01-23 14:38:43 +0000)

https://git.linaro.org/people/pmaydell/qemu-arm.git tags/pull-target-arm-20200123

for you to fetch changes up to 53c75ad8e72dc3a5102de7ed21e4990969cb0a19:

hw/arm/exynos4210: Connect serial port DMA busy signals with pl330 (2020-01-23 15:22:42 +0000)

* fix bug in PAuth emulation

* add PMU to Cortex-R5, Cortex-R5F

* qemu-nbd: Convert documentation to rST

* qemu-block-drivers: Convert documentation to rST

* Fix Exynos4210 UART DMA support

* Various minor code cleanups

Andrew Jones (1):

target/arm/arch_dump: Add SVE notes

Clement Deschamps (1):

target/arm: add PMU feature to cortex-r5 and cortex-r5f

Guenter Roeck (8):

dma/pl330: Convert to support tracing

hw/core/or-irq: Increase limit of or-lines to 48

hw/arm/exynos4210: Fix DMA initialization

hw/char/exynos4210_uart: Convert to support tracing

hw/char/exynos4210_uart: Implement post_load function

hw/char/exynos4210_uart: Implement Rx FIFO level triggers and timeouts

hw/char/exynos4210_uart: Add receive DMA support

hw/arm/exynos4210: Connect serial port DMA busy signals with pl330

Keqian Zhu (2):

hw/acpi: Remove extra indent in ACPI GED hotplug cb

hw/arm: Use helper function to trigger hotplug handler plug

Peter Maydell (3):

qemu-nbd: Convert invocation documentation to rST

docs: Create stub system manual

qemu-block-drivers: Convert to rST

From: Clement Deschamps <clement.deschamps@greensocs.com>

The PMU is not optional on cortex-r5 and cortex-r5f (see

the "Features" chapter of the Technical Reference Manual).

Signed-off-by: Clement Deschamps <clement.deschamps@greensocs.com>

Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com>

Message-id: 20200114105918.2366370-1-clement.deschamps@greensocs.com

target/arm/cpu.c | 1 +

1 file changed, 1 insertion(+)

@@ -XXX,XX +XXX,XX @@ static void cortex_r5_initfn(Object *obj)

set_feature(&cpu->env, ARM_FEATURE_V7);

set_feature(&cpu->env, ARM_FEATURE_V7MP);

set_feature(&cpu->env, ARM_FEATURE_PMSA);

+ set_feature(&cpu->env, ARM_FEATURE_PMU);

cpu->midr = 0x411fc153; /* r1p3 */

cpu->id_pfr0 = 0x0131;

cpu->id_pfr1 = 0x001;

2.20.1

The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo

format, which we present to the user as:

* a qemu-nbd manpage

* a section of the main qemu-doc HTML documentation

Convert the documentation to rST format, and present it to the user as:

* a qemu-nbd manpage

* part of the interop/ Sphinx manual

This follows the same pattern as commit 27a296fce982 did for the

qemu-ga manpage.

All the content of the old manpage is retained, except that I have

dropped the "This is free software; see the source for copying

conditions. There is NO warranty..." text that was in the old AUTHOR

section; Sphinx's manpage builder doesn't expect that much text in

the AUTHOR section, and since none of our other manpages have it it

seems easiest to delete it rather than try to figure out where else

in the manpage to put it.

The only other textual change is that I have had to give the

--nocache option its own description ("Equivalent to --cache=none")

because Sphinx doesn't have an equivalent of using item/itemx

to share a description between two options.

Some minor aspects of the formatting have changed, to suit what is

easiest for Sphinx to output. (The most notable is that Sphinx

option section option syntax doesn't support '--option foo=bar'

with bar underlined rather than bold, so we have to switch to

'--option foo=BAR' instead.)

The contents of qemu-option-trace.texi are now duplicated in

docs/interop/qemu-option-trace.rst.inc, until such time as we complete

the conversion of the other files which use it; since it has had only

3 changes in 3 years, this shouldn't be too awkward a burden.

(We use .rst.inc because if this file fragment has a .rst extension

then Sphinx complains about not seeing it in a toctree.)

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

Reviewed-by: Eric Blake <eblake@redhat.com>

Tested-by: Alex Bennée <alex.bennee@linaro.org>

Acked-by: Stefan Hajnoczi <stefanha@redhat.com>

Message-id: 20200116141511.16849-2-peter.maydell@linaro.org

Makefile | 16 +-

MAINTAINERS | 1 +

docs/interop/conf.py | 4 +-

docs/interop/index.rst | 1 +

docs/interop/qemu-nbd.rst | 263 +++++++++++++++++++++++++

docs/interop/qemu-option-trace.rst.inc | 30 +++

qemu-doc.texi | 6 -

qemu-nbd.texi | 214 --------------------

qemu-option-trace.texi | 4 +

9 files changed, 313 insertions(+), 226 deletions(-)

create mode 100644 docs/interop/qemu-nbd.rst

create mode 100644 docs/interop/qemu-option-trace.rst.inc

delete mode 100644 qemu-nbd.texi

diff --git a/Makefile b/Makefile

--- a/Makefile

+++ b/Makefile

@@ -XXX,XX +XXX,XX @@ MANUAL_BUILDDIR := docs

endif

ifdef BUILD_DOCS

-DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 $(MANUAL_BUILDDIR)/interop/qemu-ga.8

+DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1

+DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8

+DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8

DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7

DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7

DOCS+=docs/qemu-block-drivers.7

@@ -XXX,XX +XXX,XX @@ ifdef CONFIG_POSIX

ifeq ($(CONFIG_TOOLS),y)

    $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"

    $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"

-    $(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"

+    $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"

endif

ifdef CONFIG_TRACE_SYSTEMTAP

    $(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1"

@@ -XXX,XX +XXX,XX @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index

# a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946

build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1")

# We assume all RST files in the manual's directory are used in it

-manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py

+manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \

+ $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \

+ $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py

$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel)

    $(call build-manual,devel,html)

@@ -XXX,XX +XXX,XX @@ $(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs)

$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)

    $(call build-manual,interop,man)

+$(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop)

+    $(call build-manual,interop,man)

+

$(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h

    @mkdir -p "$(MANUAL_BUILDDIR)"

    $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \

@@ -XXX,XX +XXX,XX @@ qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi

qemu.1: qemu-option-trace.texi

qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi

fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi

-qemu-nbd.8: qemu-nbd.texi qemu-option-trace.texi

docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi

docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi

scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi

@@ -XXX,XX +XXX,XX @@ pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf

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-img.texi qemu-nbd.texi qemu-options.texi \

+    qemu-img.texi qemu-options.texi \

    qemu-tech.texi qemu-option-trace.texi \

    qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \

    qemu-monitor-info.texi docs/qemu-block-drivers.texi \

diff --git a/MAINTAINERS b/MAINTAINERS

--- a/MAINTAINERS

+++ b/MAINTAINERS

@@ -XXX,XX +XXX,XX @@ F: include/block/nbd*

F: qemu-nbd.*

F: blockdev-nbd.c

F: docs/interop/nbd.txt

+F: docs/interop/qemu-nbd.rst

T: git https://repo.or.cz/qemu/ericb.git nbd

NFS

diff --git a/docs/interop/conf.py b/docs/interop/conf.py

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/conf.py

+++ b/docs/interop/conf.py

@@ -XXX,XX +XXX,XX @@ html_theme_options['description'] = u'System Emulation Management and Interopera

# (source start file, name, description, authors, manual section).

man_pages = [

('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',

- ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8)

+ ['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),

+ ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',

+ ['Anthony Liguori <anthony@codemonkey.ws>'], 8)

]

diff --git a/docs/interop/index.rst b/docs/interop/index.rst

index XXXXXXX..XXXXXXX 100644

--- a/docs/interop/index.rst

+++ b/docs/interop/index.rst

@@ -XXX,XX +XXX,XX @@ Contents:

live-block-operations

pr-helper

qemu-ga

+ qemu-nbd

vhost-user

vhost-user-gpu

diff --git a/docs/interop/qemu-nbd.rst b/docs/interop/qemu-nbd.rst

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/docs/interop/qemu-nbd.rst

@@ -XXX,XX +XXX,XX @@

+QEMU Disk Network Block Device Server

+=====================================

+

+Synopsis

+--------

+

+**qemu-nbd** [*OPTION*]... *filename*

+

+**qemu-nbd** -L [*OPTION*]...

+

+**qemu-nbd** -d *dev*

+

+Description

+-----------

+

+Export a QEMU disk image using the NBD protocol.

+

+Other uses:

+

+- Bind a /dev/nbdX block device to a QEMU server (on Linux).

+- As a client to query exports of a remote NBD server.

+

+Options

+-------

+

+.. program:: qemu-nbd

+

+*filename* is a disk image filename, or a set of block

+driver options if ``--image-opts`` is specified.

+

+*dev* is an NBD device.

+

+.. option:: --object type,id=ID,...props...

+

+ Define a new instance of the *type* object class identified by *ID*.

+ See the :manpage:`qemu(1)` manual page for full details of the properties

+ supported. The common object types that it makes sense to define are the

+ ``secret`` object, which is used to supply passwords and/or encryption

+ keys, and the ``tls-creds`` object, which is used to supply TLS

+ credentials for the qemu-nbd server or client.

+

+.. option:: -p, --port=PORT

+

+ TCP port to listen on as a server, or connect to as a client

+ (default ``10809``).

+

+.. option:: -o, --offset=OFFSET

+

+ The offset into the image.

+

+.. option:: -b, --bind=IFACE

+

+ The interface to bind to as a server, or connect to as a client

+ (default ``0.0.0.0``).

+

+.. option:: -k, --socket=PATH

+

+ Use a unix socket with path *PATH*.

+

+.. option:: --image-opts

+

+ Treat *filename* as a set of image options, instead of a plain

+ filename. If this flag is specified, the ``-f`` flag should

+ not be used, instead the :option:`format=` option should be set.

+

+.. option:: -f, --format=FMT

+

+ Force the use of the block driver for format *FMT* instead of

+ auto-detecting.

+

+.. option:: -r, --read-only

+

+ Export the disk as read-only.

+

+.. option:: -P, --partition=NUM

+

+ Deprecated: Only expose MBR partition *NUM*. Understands physical

+ partitions 1-4 and logical partition 5. New code should instead use

+ :option:`--image-opts` with the raw driver wrapping a subset of the

+ original image.

+

+.. option:: -B, --bitmap=NAME

+

+ If *filename* has a qcow2 persistent bitmap *NAME*, expose

+ that bitmap via the ``qemu:dirty-bitmap:NAME`` context

+ accessible through NBD_OPT_SET_META_CONTEXT.

+

+.. option:: -s, --snapshot

+

+ Use *filename* as an external snapshot, create a temporary

+ file with ``backing_file=``\ *filename*, redirect the write to

+ the temporary one.

+

+.. option:: -l, --load-snapshot=SNAPSHOT_PARAM

+

+ Load an internal snapshot inside *filename* and export it

+ as an read-only device, SNAPSHOT_PARAM format is

+ ``snapshot.id=[ID],snapshot.name=[NAME]`` or ``[ID_OR_NAME]``

+

+.. option:: --cache=CACHE

+

+ The cache mode to be used with the file. See the documentation of

+ the emulator's ``-drive cache=...`` option for allowed values.

+

+.. option:: -n, --nocache

+

+ Equivalent to :option:`--cache=none`.

+

+.. option:: --aio=AIO

+

+ Set the asynchronous I/O mode between ``threads`` (the default)

+ and ``native`` (Linux only).

+

+.. option:: --discard=DISCARD

+

+ Control whether ``discard`` (also known as ``trim`` or ``unmap``)

+ requests are ignored or passed to the filesystem. *DISCARD* is one of

+ ``ignore`` (or ``off``), ``unmap`` (or ``on``). The default is

+ ``ignore``.

+

+.. option:: --detect-zeroes=DETECT_ZEROES

+

+ Control the automatic conversion of plain zero writes by the OS to

+ driver-specific optimized zero write commands. *DETECT_ZEROES* is one of

+ ``off``, ``on``, or ``unmap``. ``unmap``

+ converts a zero write to an unmap operation and can only be used if

+ *DISCARD* is set to ``unmap``. The default is ``off``.

+

+.. option:: -c, --connect=DEV

+

+ Connect *filename* to NBD device *DEV* (Linux only).

+

+.. option:: -d, --disconnect

+

+ Disconnect the device *DEV* (Linux only).

+

+.. option:: -e, --shared=NUM

+

+ Allow up to *NUM* clients to share the device (default

+ ``1``). Safe for readers, but for now, consistency is not

+ guaranteed between multiple writers.

+

+.. option:: -t, --persistent

+

+ Don't exit on the last connection.

+

+.. option:: -x, --export-name=NAME

+

+ Set the NBD volume export name (default of a zero-length string).

+

+.. option:: -D, --description=DESCRIPTION

+

+ Set the NBD volume export description, as a human-readable

+ string.

+

+.. option:: -L, --list

+

+ Connect as a client and list all details about the exports exposed by

+ a remote NBD server. This enables list mode, and is incompatible

+ with options that change behavior related to a specific export (such as

+ :option:`--export-name`, :option:`--offset`, ...).

+

+.. option:: --tls-creds=ID

+

+ Enable mandatory TLS encryption for the server by setting the ID

+ of the TLS credentials object previously created with the --object

+ option; or provide the credentials needed for connecting as a client

+ in list mode.

+

+.. option:: --fork

+

+ Fork off the server process and exit the parent once the server is running.

+

+.. option:: --pid-file=PATH

+

+ Store the server's process ID in the given file.

+

+.. option:: --tls-authz=ID

+

+ Specify the ID of a qauthz object previously created with the

+ :option:`--object` option. This will be used to authorize connecting users

+ against their x509 distinguished name.

+

+.. option:: -v, --verbose

+

+ Display extra debugging information.

+

+.. option:: -h, --help

+

+ Display this 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

+

+Examples

+--------

+

+Start a server listening on port 10809 that exposes only the

+guest-visible contents of a qcow2 file, with no TLS encryption, and

+with the default export name (an empty string). The command is

+one-shot, and will block until the first successful client

+disconnects:

+

+::

+

+ qemu-nbd -f qcow2 file.qcow2

+

+Start a long-running server listening with encryption on port 10810,

+and whitelist clients with a specific X.509 certificate to connect to

+a 1 megabyte subset of a raw file, using the export name 'subset':

+

+::

+

+ qemu-nbd \

+ --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \

+ --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\

+ O=Example Org,,L=London,,ST=London,,C=GB' \

+ --tls-creds tls0 --tls-authz auth0 \

+ -t -x subset -p 10810 \

+ --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw

+

+Serve a read-only copy of just the first MBR partition of a guest

+image over a Unix socket with as many as 5 simultaneous readers, with

+a persistent process forked as a daemon:

+

+::

+

+ qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \

+ --partition=1 --read-only --format=qcow2 file.qcow2

+

+Expose the guest-visible contents of a qcow2 file via a block device

+/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for

+partitions found within), then disconnect the device when done.

+Access to bind qemu-nbd to an /dev/nbd device generally requires root

+privileges, and may also require the execution of ``modprobe nbd``

+to enable the kernel NBD client module. *CAUTION*: Do not use

+this method to mount filesystems from an untrusted guest image - a

+malicious guest may have prepared the image to attempt to trigger

+kernel bugs in partition probing or file system mounting.

+

+::

+

+ qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2

+ qemu-nbd -d /dev/nbd0

+

+Query a remote server to see details about what export(s) it is

+serving on port 10809, and authenticating via PSK:

+

+::

+

+ qemu-nbd \

+ --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \

+ --tls-creds tls0 -L -b remote.example.com

+

+See also

+--------

+

+:manpage:`qemu(1)`, :manpage:`qemu-img(1)`

diff --git a/docs/interop/qemu-option-trace.rst.inc b/docs/interop/qemu-option-trace.rst.inc

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/docs/interop/qemu-option-trace.rst.inc

@@ -XXX,XX +XXX,XX @@

+..

+ The contents of this file must be kept in sync with qemu-option-trace.texi

+ until all the users of the texi file have been converted to rst and

+ the texi file can be removed.

+

+Specify tracing options.

+

+.. option:: [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 :option:`-trace` option multiple times.

+

+ Use :option:`-trace help` to print a list of names of trace points.

+

+.. option:: 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.

+

+.. option:: file=FILE

+

+ Log output traces to *FILE*.

+ This option is only available if QEMU has been compiled with

+ the ``simple`` tracing backend.

diff --git a/qemu-doc.texi b/qemu-doc.texi

index XXXXXXX..XXXXXXX 100644

--- a/qemu-doc.texi

+++ b/qemu-doc.texi

@@ -XXX,XX +XXX,XX @@ encrypted disk images.

* disk_images_snapshot_mode:: Snapshot mode

* vm_snapshots:: VM snapshots

* qemu_img_invocation:: qemu-img Invocation

-* qemu_nbd_invocation:: qemu-nbd Invocation

* disk_images_formats:: Disk image file formats

* host_drives:: Using host drives

* disk_images_fat_images:: Virtual FAT disk images

@@ -XXX,XX +XXX,XX @@ state is not saved or restored properly (in particular USB).

@include qemu-img.texi

-@node qemu_nbd_invocation

-@subsection @code{qemu-nbd} Invocation

-@include qemu-nbd.texi

@include docs/qemu-block-drivers.texi

@node pcsys_network

diff --git a/qemu-nbd.texi b/qemu-nbd.texi

--- a/qemu-nbd.texi

-@example

-@c man begin SYNOPSIS

-@command{qemu-nbd} [OPTION]... @var{filename}

-@command{qemu-nbd} @option{-L} [OPTION]...

-@command{qemu-nbd} @option{-d} @var{dev}

-@c man end

-@end example

-

-@c man begin DESCRIPTION

-

-Export a QEMU disk image using the NBD protocol.

-

-Other uses:

-@itemize

-@item

-Bind a /dev/nbdX block device to a QEMU server (on Linux).

-@item

-As a client to query exports of a remote NBD server.

-@end itemize

-

-@c man end

-

-@c man begin OPTIONS

-@var{filename} is a disk image filename, or a set of block

-driver options if @option{--image-opts} is specified.

-

-@var{dev} is an NBD device.

-

-@table @option

-@item --object type,id=@var{id},...props...

-Define a new instance of the @var{type} object class identified by @var{id}.

-See the @code{qemu(1)} manual page for full details of the properties

-supported. The common object types that it makes sense to define are the

-@code{secret} object, which is used to supply passwords and/or encryption

-keys, and the @code{tls-creds} object, which is used to supply TLS

-credentials for the qemu-nbd server or client.

-@item -p, --port=@var{port}

-The TCP port to listen on as a server, or connect to as a client

-(default @samp{10809}).

-@item -o, --offset=@var{offset}

-The offset into the image.

-@item -b, --bind=@var{iface}

-The interface to bind to as a server, or connect to as a client

-(default @samp{0.0.0.0}).

-@item -k, --socket=@var{path}

-Use a unix socket with path @var{path}.

-@item --image-opts

-Treat @var{filename} as a set of image options, instead of a plain

-filename. If this flag is specified, the @var{-f} flag should

-not be used, instead the '@code{format=}' option should be set.

-@item -f, --format=@var{fmt}

-Force the use of the block driver for format @var{fmt} instead of

-auto-detecting.

-@item -r, --read-only

-Export the disk as read-only.

-@item -P, --partition=@var{num}

-Deprecated: Only expose MBR partition @var{num}. Understands physical

-partitions 1-4 and logical partition 5. New code should instead use

-@option{--image-opts} with the raw driver wrapping a subset of the

-original image.

-@item -B, --bitmap=@var{name}

-If @var{filename} has a qcow2 persistent bitmap @var{name}, expose

-that bitmap via the ``qemu:dirty-bitmap:@var{name}'' context

-accessible through NBD_OPT_SET_META_CONTEXT.

-@item -s, --snapshot

-Use @var{filename} as an external snapshot, create a temporary

-file with backing_file=@var{filename}, redirect the write to

-the temporary one.

-@item -l, --load-snapshot=@var{snapshot_param}

-Load an internal snapshot inside @var{filename} and export it

-as an read-only device, @var{snapshot_param} format is

-'snapshot.id=[ID],snapshot.name=[NAME]' or '[ID_OR_NAME]'

-@item -n, --nocache

-@itemx --cache=@var{cache}

-The cache mode to be used with the file. See the documentation of

-the emulator's @code{-drive cache=...} option for allowed values.

-@item --aio=@var{aio}

-Set the asynchronous I/O mode between @samp{threads} (the default)

-and @samp{native} (Linux only).

-@item --discard=@var{discard}

-Control whether @dfn{discard} (also known as @dfn{trim} or @dfn{unmap})

-requests are ignored or passed to the filesystem. @var{discard} is one of

-@samp{ignore} (or @samp{off}), @samp{unmap} (or @samp{on}). The default is

-@samp{ignore}.

-@item --detect-zeroes=@var{detect-zeroes}

-Control the automatic conversion of plain zero writes by the OS to

-driver-specific optimized zero write commands. @var{detect-zeroes} is one of

-@samp{off}, @samp{on} or @samp{unmap}. @samp{unmap}

-converts a zero write to an unmap operation and can only be used if

-@var{discard} is set to @samp{unmap}. The default is @samp{off}.

-@item -c, --connect=@var{dev}

-Connect @var{filename} to NBD device @var{dev} (Linux only).

-@item -d, --disconnect

-Disconnect the device @var{dev} (Linux only).

-@item -e, --shared=@var{num}

-Allow up to @var{num} clients to share the device (default

-@samp{1}). Safe for readers, but for now, consistency is not

-guaranteed between multiple writers.

-@item -t, --persistent

-Don't exit on the last connection.

-@item -x, --export-name=@var{name}

-Set the NBD volume export name (default of a zero-length string).

-@item -D, --description=@var{description}

-Set the NBD volume export description, as a human-readable

-string.

-@item -L, --list

-Connect as a client and list all details about the exports exposed by

-a remote NBD server. This enables list mode, and is incompatible

-with options that change behavior related to a specific export (such as

-@option{--export-name}, @option{--offset}, ...).

-@item --tls-creds=ID

-Enable mandatory TLS encryption for the server by setting the ID

-of the TLS credentials object previously created with the --object

-option; or provide the credentials needed for connecting as a client

-in list mode.

-@item --fork

-Fork off the server process and exit the parent once the server is running.

-@item --pid-file=PATH

-Store the server's process ID in the given file.

-@item --tls-authz=ID

-Specify the ID of a qauthz object previously created with the

---object option. This will be used to authorize connecting users

-against their x509 distinguished name.

-@item -v, --verbose

-Display extra debugging information.

-@item -h, --help

-Display this help and exit.

-@item -V, --version

-Display version information and exit.

-@item -T, --trace [[enable=]@var{pattern}][,events=@var{file}][,file=@var{file}]

-@findex --trace

-@include qemu-option-trace.texi

-@end table

-

-@c man end

-

-@c man begin EXAMPLES

-Start a server listening on port 10809 that exposes only the

-guest-visible contents of a qcow2 file, with no TLS encryption, and

-with the default export name (an empty string). The command is

-one-shot, and will block until the first successful client

-disconnects:

-

-@example

-qemu-nbd -f qcow2 file.qcow2

-@end example

-

-Start a long-running server listening with encryption on port 10810,

-and whitelist clients with a specific X.509 certificate to connect to

-a 1 megabyte subset of a raw file, using the export name 'subset':

-

-@example

-qemu-nbd \

- --object tls-creds-x509,id=tls0,endpoint=server,dir=/path/to/qemutls \

- --object 'authz-simple,id=auth0,identity=CN=laptop.example.com,,\

- O=Example Org,,L=London,,ST=London,,C=GB' \

- --tls-creds tls0 --tls-authz auth0 \

- -t -x subset -p 10810 \

- --image-opts driver=raw,offset=1M,size=1M,file.driver=file,file.filename=file.raw

-@end example

-

-Serve a read-only copy of just the first MBR partition of a guest

-image over a Unix socket with as many as 5 simultaneous readers, with

-a persistent process forked as a daemon:

-

-@example

-qemu-nbd --fork --persistent --shared=5 --socket=/path/to/sock \

- --partition=1 --read-only --format=qcow2 file.qcow2

-@end example

-

-Expose the guest-visible contents of a qcow2 file via a block device

-/dev/nbd0 (and possibly creating /dev/nbd0p1 and friends for

-partitions found within), then disconnect the device when done.

-Access to bind qemu-nbd to an /dev/nbd device generally requires root

-privileges, and may also require the execution of @code{modprobe nbd}

-to enable the kernel NBD client module. @emph{CAUTION}: Do not use

-this method to mount filesystems from an untrusted guest image - a

-malicious guest may have prepared the image to attempt to trigger

-kernel bugs in partition probing or file system mounting.

-

-@example

-qemu-nbd -c /dev/nbd0 -f qcow2 file.qcow2

-qemu-nbd -d /dev/nbd0

-@end example

-

-Query a remote server to see details about what export(s) it is

-serving on port 10809, and authenticating via PSK:

-

-@example

-qemu-nbd \

- --object tls-creds-psk,id=tls0,dir=/tmp/keys,username=eblake,endpoint=client \

- --tls-creds tls0 -L -b remote.example.com

-@end example

-

-@c man end

-

-@ignore

-

-@setfilename qemu-nbd

-@settitle QEMU Disk Network Block Device Server

-

-@c man begin AUTHOR

-Copyright (C) 2006 Anthony Liguori <anthony@codemonkey.ws>.

-This is free software; see the source for copying conditions. There is NO

-warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

-@c man end

-

-@c man begin SEEALSO

-qemu(1), qemu-img(1)

-@c man end

-

-@end ignore

diff --git a/qemu-option-trace.texi b/qemu-option-trace.texi

index XXXXXXX..XXXXXXX 100644

--- a/qemu-option-trace.texi

+++ b/qemu-option-trace.texi

@@ -XXX,XX +XXX,XX @@

+@c The contents of this file must be kept in sync with qemu-option-trace.rst.inc

+@c until all the users of the texi file have been converted to rst and

+@c the texi file can be removed.

+

Specify tracing options.

@table @option

2.20.1

The qemu-block-drivers documentation is currently in

docs/qemu-block-drivers.texi in Texinfo format, which we present

to the user as:

* a qemu-block-drivers manpage

* a section of the main qemu-doc HTML documentation

Convert the documentation to rST format, and present it to

the user as:

* a qemu-block-drivers manpage

* part of the system/ Sphinx manual

This follows the same pattern we've done for qemu-ga and qemu-nbd.

We have to drop a cross-reference from the documentation of the

-cdrom option back to the qemu-block-drivers documentation, since

they're no longer within the same texinfo document.

As noted in a comment, the manpage output is slightly compromised

due to limitations in Sphinx. In an ideal world, the HTML output

would have the various headings like 'Disk image file formats'

as top-level section headings (which then appear in the overall

system manual's table-of-contents), and it would not have the

section headings which make sense only for the manpage like

'synopsis', 'description', and 'see also'. Unfortunately, the

mechanism Sphinx provides for restricting pieces of documentation

is limited to the point of being flawed: the 'only::' directive

is implemented as a filter that is applied at a very late stage

in the document processing pipeline, rather than as an early

equivalent of an #ifdef. This means that Sphinx's process of

identifying which section heading markup styles are which levels

of heading gets confused if the 'only::' directive contains

section headings which would affect the heading-level of a

later heading. I have opted to prioritise making the HTML format

look better, with the compromise being that in the manpage

the 'Disk image file formats' &c headings are top-level headings

rather than being sub-headings under the traditional 'Description'

top-level section title.

Reviewed-by: Alex Bennée <alex.bennee@linaro.org>

Tested-by: Alex Bennée <alex.bennee@linaro.org>

Acked-by: Stefan Hajnoczi <stefanha@redhat.com>

Message-id: 20200116141511.16849-4-peter.maydell@linaro.org

Makefile | 11 +-

docs/qemu-block-drivers.texi | 889 --------------------------

docs/system/conf.py | 7 +

docs/system/index.rst | 1 +

docs/system/qemu-block-drivers.rst | 985 +++++++++++++++++++++++++++++

qemu-doc.texi | 12 -

qemu-options.hx | 2 +-

7 files changed, 1000 insertions(+), 907 deletions(-)

delete mode 100644 docs/qemu-block-drivers.texi

create mode 100644 docs/system/qemu-block-drivers.rst

diff --git a/Makefile b/Makefile

--- a/Makefile

+++ b/Makefile

@@ -XXX,XX +XXX,XX @@ ifdef BUILD_DOCS

DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8

DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8

+DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7

DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7

DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7

-DOCS+=docs/qemu-block-drivers.7

DOCS+=docs/qemu-cpu-models.7

DOCS+=$(MANUAL_BUILDDIR)/index.html

ifdef CONFIG_VIRTFS

@@ -XXX,XX +XXX,XX @@ distclean: clean

    rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt

    rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf

    rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html

-    rm -f docs/qemu-block-drivers.7

    rm -f docs/qemu-cpu-models.7

    rm -rf .doctrees

    $(call clean-manual,devel)

@@ -XXX,XX +XXX,XX @@ ifdef CONFIG_POSIX

    $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"

    $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"

    $(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"

-    $(INSTALL_DATA) docs/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"

+    $(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"

    $(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"

ifeq ($(CONFIG_TOOLS),y)

    $(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"

@@ -XXX,XX +XXX,XX @@ $(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)

$(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop)

    $(call build-manual,interop,man)

+$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7: $(call manual-deps,system)

+    $(call build-manual,system,man)

+

$(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h

    @mkdir -p "$(MANUAL_BUILDDIR)"

    $(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \

@@ -XXX,XX +XXX,XX @@ qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi

qemu.1: qemu-option-trace.texi

qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi

fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi

-docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi

docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi

scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi

@@ -XXX,XX +XXX,XX @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \

    qemu-img.texi qemu-options.texi \

    qemu-tech.texi qemu-option-trace.texi \

    qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \

-    qemu-monitor-info.texi docs/qemu-block-drivers.texi \

+    qemu-monitor-info.texi \

    docs/qemu-cpu-models.texi docs/security.texi

docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \

diff --git a/docs/qemu-block-drivers.texi b/docs/qemu-block-drivers.texi

deleted file mode 100644

index XXXXXXX..XXXXXXX

--- a/docs/qemu-block-drivers.texi

+++ /dev/null

@@ -XXX,XX +XXX,XX @@

-@c man begin SYNOPSIS

-QEMU block driver reference manual

-@c man end

-@set qemu_system qemu-system-x86_64

-@c man begin DESCRIPTION

-

-@node disk_images_formats

-@subsection Disk image file formats

-

-QEMU supports many image file formats that can be used with VMs as well as with

-any of the tools (like @code{qemu-img}). This includes the preferred formats

-raw and qcow2 as well as formats that are supported for compatibility with

-older QEMU versions or other hypervisors.

-

-Depending on the image format, different options can be passed to

-@code{qemu-img create} and @code{qemu-img convert} using the @code{-o} option.

-This section describes each format and the options that are supported for it.

-

-@table @option

-@item raw

-

-Raw disk image format. This format has the advantage of

-being simple and easily exportable to all other emulators. If your

-file system supports @emph{holes} (for example in ext2 or ext3 on

-Linux or NTFS on Windows), then only the written sectors will reserve

-space. Use @code{qemu-img info} to know the real size used by the

-image or @code{ls -ls} on Unix/Linux.

-

-Supported options:

-@table @code

-@item preallocation

-Preallocation mode (allowed values: @code{off}, @code{falloc}, @code{full}).

-@code{falloc} mode preallocates space for image by calling posix_fallocate().

-@code{full} mode preallocates space for image by writing data to underlying

-storage. This data may or may not be zero, depending on the storage location.

-@end table

-

-@item qcow2

-QEMU image format, the most versatile format. Use it to have smaller

-images (useful if your filesystem does not supports holes, for example

-on Windows), zlib based compression and support of multiple VM

-snapshots.

-

-Supported options:

-@table @code

-@item compat

-Determines the qcow2 version to use. @code{compat=0.10} uses the

-traditional image format that can be read by any QEMU since 0.10.

-@code{compat=1.1} enables image format extensions that only QEMU 1.1 and

-newer understand (this is the default). Amongst others, this includes

-zero clusters, which allow efficient copy-on-read for sparse images.

-

-@item backing_file

-File name of a base image (see @option{create} subcommand)

-@item backing_fmt

-Image format of the base image

-@item encryption

-This option is deprecated and equivalent to @code{encrypt.format=aes}

-

-@item encrypt.format

-

-If this is set to @code{luks}, it requests that the qcow2 payload (not

-qcow2 header) be encrypted using the LUKS format. The passphrase to

-use to unlock the LUKS key slot is given by the @code{encrypt.key-secret}

-parameter. LUKS encryption parameters can be tuned with the other

-@code{encrypt.*} parameters.

-

-If this is set to @code{aes}, the image is encrypted with 128-bit AES-CBC.

-The encryption key is given by the @code{encrypt.key-secret} parameter.

-This encryption format is considered to be flawed by modern cryptography

-standards, suffering from a number of design problems:

-

-@itemize @minus

-@item The AES-CBC cipher is used with predictable initialization vectors based

-on the sector number. This makes it vulnerable to chosen plaintext attacks

-which can reveal the existence of encrypted data.

-@item The user passphrase is directly used as the encryption key. A poorly

-chosen or short passphrase will compromise the security of the encryption.

-@item In the event of the passphrase being compromised there is no way to

-change the passphrase to protect data in any qcow images. The files must

-be cloned, using a different encryption passphrase in the new file. The

-original file must then be securely erased using a program like shred,

-though even this is ineffective with many modern storage technologies.

-@end itemize

-

-The use of this is no longer supported in system emulators. Support only

-remains in the command line utilities, for the purposes of data liberation

-and interoperability with old versions of QEMU. The @code{luks} format

-should be used instead.

-

-@item encrypt.key-secret

-

-Provides the ID of a @code{secret} object that contains the passphrase

-(@code{encrypt.format=luks}) or encryption key (@code{encrypt.format=aes}).

-

-@item encrypt.cipher-alg

-

-Name of the cipher algorithm and key length. Currently defaults

-to @code{aes-256}. Only used when @code{encrypt.format=luks}.

-

-@item encrypt.cipher-mode

-

-Name of the encryption mode to use. Currently defaults to @code{xts}.

-Only used when @code{encrypt.format=luks}.

-

-@item encrypt.ivgen-alg

-

-Name of the initialization vector generator algorithm. Currently defaults

-to @code{plain64}. Only used when @code{encrypt.format=luks}.

-

-@item encrypt.ivgen-hash-alg

-

-Name of the hash algorithm to use with the initialization vector generator

-(if required). Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.

-

-@item encrypt.hash-alg

-

-Name of the hash algorithm to use for PBKDF algorithm

-Defaults to @code{sha256}. Only used when @code{encrypt.format=luks}.

-

-@item encrypt.iter-time

-

-Amount of time, in milliseconds, to use for PBKDF algorithm per key slot.

-Defaults to @code{2000}. Only used when @code{encrypt.format=luks}.

-

-@item cluster_size

-Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster

-sizes can improve the image file size whereas larger cluster sizes generally

-provide better performance.

-