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

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

target/arm/cpu.c | 1 +

1 file changed, 1 insertion(+)

diff --git a/target/arm/cpu.c b/target/arm/cpu.c

index XXXXXXX..XXXXXXX 100644

--- a/target/arm/cpu.c

+++ b/target/arm/cpu.c

@@ -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

From: Vincent Dehors <vincent.dehors@smile.fr>

In the PAC computation, sbox was applied over wrong bits.

As this is a 4-bit sbox, bit index should be incremented by 4 instead of 16.

Test vector from QARMA paper (https://eprint.iacr.org/2016/444.pdf) was

used to verify one computation of the pauth_computepac() function which

uses sbox2.

Launchpad: https://bugs.launchpad.net/bugs/1859713

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>

Signed-off-by: Vincent DEHORS <vincent.dehors@smile.fr>

Signed-off-by: Adrien GRASSEIN <adrien.grassein@smile.fr>

Message-id: 20200116230809.19078-2-richard.henderson@linaro.org

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

target/arm/pauth_helper.c | 4 ++--

1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/target/arm/pauth_helper.c b/target/arm/pauth_helper.c

index XXXXXXX..XXXXXXX 100644

--- a/target/arm/pauth_helper.c

+++ b/target/arm/pauth_helper.c

@@ -XXX,XX +XXX,XX @@ static uint64_t pac_sub(uint64_t i)

uint64_t o = 0;

int b;

- for (b = 0; b < 64; b += 16) {

+ for (b = 0; b < 64; b += 4) {

o |= (uint64_t)sub[(i >> b) & 0xf] << b;

}

return o;

@@ -XXX,XX +XXX,XX @@ static uint64_t pac_inv_sub(uint64_t i)

uint64_t o = 0;

int b;

- for (b = 0; b < 64; b += 16) {

+ for (b = 0; b < 64; b += 4) {

o |= (uint64_t)inv_sub[(i >> b) & 0xf] << b;

}

return o;

--

2.20.1

From: Richard Henderson <richard.henderson@linaro.org>

We were incorrectly requiring ARMv8.4 support for the pauth

tests, but Pointer Authentication is an ARMv8.3 extension.

Further, hiding the required architecture within asm() is

not correct.

Correct the architecture version requested, and specify it

in the cflags of the (cross-) compiler rather than in the asm.

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

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

Message-id: 20200116230809.19078-3-richard.henderson@linaro.org

[PMM: tweaked commit message]

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

tests/tcg/aarch64/Makefile.target | 1 +

tests/tcg/aarch64/pauth-1.c | 2 --

tests/tcg/aarch64/pauth-2.c | 2 --

3 files changed, 1 insertion(+), 4 deletions(-)

diff --git a/tests/tcg/aarch64/Makefile.target b/tests/tcg/aarch64/Makefile.target

index XXXXXXX..XXXXXXX 100644

--- a/tests/tcg/aarch64/Makefile.target

+++ b/tests/tcg/aarch64/Makefile.target

@@ -XXX,XX +XXX,XX @@ run-fcvt: fcvt

# Pauth Tests

AARCH64_TESTS += pauth-1 pauth-2

run-pauth-%: QEMU_OPTS += -cpu max

+pauth-%: CFLAGS += -march=armv8.3-a

# Semihosting smoke test for linux-user

AARCH64_TESTS += semihosting

diff --git a/tests/tcg/aarch64/pauth-1.c b/tests/tcg/aarch64/pauth-1.c

index XXXXXXX..XXXXXXX 100644

--- a/tests/tcg/aarch64/pauth-1.c

+++ b/tests/tcg/aarch64/pauth-1.c

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

#include <sys/prctl.h>

#include <stdio.h>

-asm(".arch armv8.4-a");

-

#ifndef PR_PAC_RESET_KEYS

#define PR_PAC_RESET_KEYS 54

#define PR_PAC_APDAKEY (1 << 2)

diff --git a/tests/tcg/aarch64/pauth-2.c b/tests/tcg/aarch64/pauth-2.c

index XXXXXXX..XXXXXXX 100644

--- a/tests/tcg/aarch64/pauth-2.c

+++ b/tests/tcg/aarch64/pauth-2.c

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

#include <stdint.h>

#include <assert.h>

-asm(".arch armv8.4-a");

-

void do_test(uint64_t value)

{

uint64_t salt1, salt2;

--

2.20.1

From: Richard Henderson <richard.henderson@linaro.org>

This is the test vector from the QARMA paper, run through PACGA.

Suggested-by: Vincent Dehors <vincent.dehors@smile.fr>

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

Message-id: 20200116230809.19078-4-richard.henderson@linaro.org

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

tests/tcg/aarch64/Makefile.softmmu-target | 5 ++-

tests/tcg/aarch64/system/pauth-3.c | 40 +++++++++++++++++++++++

2 files changed, 44 insertions(+), 1 deletion(-)

create mode 100644 tests/tcg/aarch64/system/pauth-3.c

diff --git a/tests/tcg/aarch64/Makefile.softmmu-target b/tests/tcg/aarch64/Makefile.softmmu-target

index XXXXXXX..XXXXXXX 100644

--- a/tests/tcg/aarch64/Makefile.softmmu-target

+++ b/tests/tcg/aarch64/Makefile.softmmu-target

@@ -XXX,XX +XXX,XX @@ run-memory-replay: memory-replay run-memory-record

          $(QEMU_OPTS) memory, \

     "$< on $(TARGET_NAME)")

-EXTRA_TESTS+=memory-record memory-replay

+run-pauth-3: pauth-3

+pauth-3: CFLAGS += -march=armv8.3-a

+

+EXTRA_TESTS+=memory-record memory-replay pauth-3

diff --git a/tests/tcg/aarch64/system/pauth-3.c b/tests/tcg/aarch64/system/pauth-3.c

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/tests/tcg/aarch64/system/pauth-3.c

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

+#include <inttypes.h>

+#include <minilib.h>

+

+int main()

+{

+ /*

+ * Test vector from QARMA paper (https://eprint.iacr.org/2016/444.pdf)

+ * to verify one computation of the pauth_computepac() function,

+ * which uses sbox2.

+ *

+ * Use PACGA, because it returns the most bits from ComputePAC.

+ * We still only get the most significant 32-bits of the result.

+ */

+

+ static const uint64_t d[5] = {

+ 0xfb623599da6e8127ull,

+ 0x477d469dec0b8762ull,

+ 0x84be85ce9804e94bull,

+ 0xec2802d4e0a488e9ull,

+ 0xc003b93999b33765ull & 0xffffffff00000000ull

+ };

+ uint64_t r;

+

+ asm("msr apgakeyhi_el1, %[w0]\n\t"

+ "msr apgakeylo_el1, %[k0]\n\t"

+ "pacga %[r], %[P], %[T]"

+ : [r] "=r"(r)

+ : [P] "r" (d[0]),

+ [T] "r" (d[1]),

+ [w0] "r" (d[2]),

+ [k0] "r" (d[3]));

+

+ if (r == d[4]) {

+ ml_printf("OK\n");

+ return 0;

+ } else {

+ ml_printf("FAIL: %lx != %lx\n", r, d[4]);

+ return 1;

+ }

+}

--

2.20.1

From: Richard Henderson <richard.henderson@linaro.org>

Perform the set of operations and test described in LP 1859713.

Suggested-by: Adrien GRASSEIN <adrien.grassein@smile.fr>

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

Message-id: 20200116230809.19078-5-richard.henderson@linaro.org

[PMM: fixed hard-coded tabs]

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

tests/tcg/aarch64/Makefile.target | 2 +-

tests/tcg/aarch64/pauth-4.c | 25 +++++++++++++++++++++++++

2 files changed, 26 insertions(+), 1 deletion(-)

create mode 100644 tests/tcg/aarch64/pauth-4.c

diff --git a/tests/tcg/aarch64/Makefile.target b/tests/tcg/aarch64/Makefile.target

index XXXXXXX..XXXXXXX 100644

--- a/tests/tcg/aarch64/Makefile.target

+++ b/tests/tcg/aarch64/Makefile.target

@@ -XXX,XX +XXX,XX @@ run-fcvt: fcvt

    $(call diff-out,$<,$(AARCH64_SRC)/fcvt.ref)

# Pauth Tests

-AARCH64_TESTS += pauth-1 pauth-2

+AARCH64_TESTS += pauth-1 pauth-2 pauth-4

run-pauth-%: QEMU_OPTS += -cpu max

pauth-%: CFLAGS += -march=armv8.3-a

diff --git a/tests/tcg/aarch64/pauth-4.c b/tests/tcg/aarch64/pauth-4.c

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/tests/tcg/aarch64/pauth-4.c

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

+#include <stdint.h>

+#include <assert.h>

+

+int main()

+{

+ uintptr_t x, y;

+

+ asm("mov %0, lr\n\t"

+ "pacia %0, sp\n\t" /* sigill if pauth not supported */

+ "eor %0, %0, #4\n\t" /* corrupt single bit */

+ "mov %1, %0\n\t"

+ "autia %1, sp\n\t" /* validate corrupted pointer */

+ "xpaci %0\n\t" /* strip pac from corrupted pointer */

+ : "=r"(x), "=r"(y));

+

+ /*

+ * Once stripped, the corrupted pointer is of the form 0x0000...wxyz.

+ * We expect the autia to indicate failure, producing a pointer of the

+ * form 0x000e....wxyz. Use xpaci and != for the test, rather than

+ * extracting explicit bits from the top, because the location of the

+ * error code "e" depends on the configuration of virtual memory.

+ */

+ assert(x != y);

+ return 0;

+}

--

2.20.1

From: Keqian Zhu <zhukeqian1@huawei.com>

There is extra indent in ACPI GED hotplug cb that should be

deleted.

Reviewed-by: Igor Mammedov <imammedo@redhat.com>

Signed-off-by: Keqian Zhu <zhukeqian1@huawei.com>

Message-id: 20200120012755.44581-2-zhukeqian1@huawei.com

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

hw/acpi/generic_event_device.c | 2 +-

1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/hw/acpi/generic_event_device.c b/hw/acpi/generic_event_device.c

index XXXXXXX..XXXXXXX 100644

--- a/hw/acpi/generic_event_device.c

+++ b/hw/acpi/generic_event_device.c

@@ -XXX,XX +XXX,XX @@ static void acpi_ged_device_plug_cb(HotplugHandler *hotplug_dev,

AcpiGedState *s = ACPI_GED(hotplug_dev);

if (object_dynamic_cast(OBJECT(dev), TYPE_PC_DIMM)) {

- acpi_memory_plug_cb(hotplug_dev, &s->memhp_state, dev, errp);

+ acpi_memory_plug_cb(hotplug_dev, &s->memhp_state, dev, errp);

} else {

error_setg(errp, "virt: device plug request for unsupported device"

" type: %s", object_get_typename(OBJECT(dev)));

--

2.20.1

From: Keqian Zhu <zhukeqian1@huawei.com>

We can use existing helper function to trigger hotplug handler

plug, which makes code clearer.

Reviewed-by: Igor Mammedov <imammedo@redhat.com>

Signed-off-by: Keqian Zhu <zhukeqian1@huawei.com>

Message-id: 20200120012755.44581-3-zhukeqian1@huawei.com

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

---

hw/arm/virt.c | 6 +++---

1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/hw/arm/virt.c b/hw/arm/virt.c

index XXXXXXX..XXXXXXX 100644

--- a/hw/arm/virt.c

+++ b/hw/arm/virt.c

@@ -XXX,XX +XXX,XX @@ static void virt_memory_pre_plug(HotplugHandler *hotplug_dev, DeviceState *dev,

static void virt_memory_plug(HotplugHandler *hotplug_dev,

DeviceState *dev, Error **errp)

{

- HotplugHandlerClass *hhc;

VirtMachineState *vms = VIRT_MACHINE(hotplug_dev);

Error *local_err = NULL;

@@ -XXX,XX +XXX,XX @@ static void virt_memory_plug(HotplugHandler *hotplug_dev,

goto out;

}

- hhc = HOTPLUG_HANDLER_GET_CLASS(vms->acpi_dev);

- hhc->plug(HOTPLUG_HANDLER(vms->acpi_dev), dev, &error_abort);

+ hotplug_handler_plug(HOTPLUG_HANDLER(vms->acpi_dev),

+ dev, &error_abort);

+

out:

error_propagate(errp, local_err);

}

--

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.)

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

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

index XXXXXXX..XXXXXXX 100644

--- 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

index XXXXXXX..XXXXXXX 100644

--- 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

deleted file mode 100644

index XXXXXXX..XXXXXXX

--- a/qemu-nbd.texi

+++ /dev/null

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

-@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

We want a user-facing manual which contains system emulation

documentation. Create an empty one which we can populate.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

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

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

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

---

Makefile | 10 +++++++++-

docs/index.html.in | 1 +

docs/system/conf.py | 15 +++++++++++++++

docs/system/index.rst | 16 ++++++++++++++++

4 files changed, 41 insertions(+), 1 deletion(-)

create mode 100644 docs/system/conf.py

create mode 100644 docs/system/index.rst

diff --git a/Makefile b/Makefile

index XXXXXXX..XXXXXXX 100644

--- a/Makefile

+++ b/Makefile

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

    $(call clean-manual,devel)

    $(call clean-manual,interop)

    $(call clean-manual,specs)

+    $(call clean-manual,system)

    for d in $(TARGET_DIRS); do \

    rm -rf $$d || exit 1 ; \

done

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

install-sphinxdocs: sphinxdocs

    $(call install-manual,interop)

    $(call install-manual,specs)

+    $(call install-manual,system)

install-doc: $(DOCS) install-sphinxdocs

    $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"

@@ -XXX,XX +XXX,XX @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak

# and handles "don't rebuild things unless necessary" itself.

# The '.doctrees' files are cached information to speed this up.

.PHONY: sphinxdocs

-sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop/index.html $(MANUAL_BUILDDIR)/specs/index.html

+sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \

+ $(MANUAL_BUILDDIR)/interop/index.html \

+ $(MANUAL_BUILDDIR)/specs/index.html \

+ $(MANUAL_BUILDDIR)/system/index.html

# Canned command to build a single manual

# Arguments: $1 = manual name, $2 = Sphinx builder ('html' or 'man')

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

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

    $(call build-manual,specs,html)

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

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

+

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

    $(call build-manual,interop,man)

diff --git a/docs/index.html.in b/docs/index.html.in

index XXXXXXX..XXXXXXX 100644

--- a/docs/index.html.in

+++ b/docs/index.html.in

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

<li><a href="qemu-ga-ref.html">Guest Agent Protocol Reference</a></li>

<li><a href="interop/index.html">System Emulation Management and Interoperability Guide</a></li>

<li><a href="specs/index.html">System Emulation Guest Hardware Specifications</a></li>

+ <li><a href="system/index.html">System Emulation User's Guide</a></li>

</ul>

</body>

</html>

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

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null

+++ b/docs/system/conf.py

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

+# -*- coding: utf-8 -*-

+#

+# QEMU documentation build configuration file for the 'system' manual.

+#

+# This includes the top level conf file and then makes any necessary tweaks.

+import sys

+import os

+

+qemu_docdir = os.path.abspath("..")

+parent_config = os.path.join(qemu_docdir, "conf.py")

+exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))

+

+# This slightly misuses the 'description', but is the best way to get

+# the manual title to appear in the sidebar.

+html_theme_options['description'] = u'System Emulation User''s Guide'

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

new file mode 100644

index XXXXXXX..XXXXXXX

--- /dev/null