Merge remote-tracking branch 'remotes/pmaydell/tags/pull-target-arm-20201123' into staging

target-arm queue:
 * incorporate 'orphan' rST docs into manuals
 * linux-user/arm: Deliver SIGTRAP for UDF patterns used as breakpoints
 * target/arm: Make SYS_HEAPINFO work with RAM that doesn't start at 0
 * document raspi boards and tosa
 * docs/system: Deprecate raspi2/raspi3 machine aliases
 * docs/system/arm: Document OpenPOWER Witherspoon BMC model Front LEDs
 * MAINTAINERS: add lines for docs files for Arm boards
 * hw/intc: fix heap-buffer-overflow in rxicu_realize()
 * hw/arm: Fix bad print format specifiers
 * target/arm: fix stage 2 page-walks in 32-bit emulation

# gpg: Signature made Mon 23 Nov 2020 11:42:02 GMT
# gpg:                using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg:                issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83  15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-target-arm-20201123: (24 commits)
  docs/system/pr-manager.rst: Fix minor docs nits
  docs: Split qemu-pr-helper documentation into tools manual
  docs: Move pr-manager.rst into the system manual
  docs: Move microvm.rst into the system manual
  docs: Split out 'pc' machine model docs into their own file
  docs/system/virtio-pmem.rst: Fix minor style issues
  docs: Move virtio-pmem.rst into the system manual
  docs: Move cpu-hotplug.rst into the system manual
  docs: Move virtio-net-failover.rst into the system manual
  linux-user/arm: Deliver SIGTRAP for UDF patterns used as breakpoints
  target/arm: Make SYS_HEAPINFO work with RAM that doesn't start at 0
  docs/system/arm: Document the Sharp Zaurus SL-6000
  docs/system/arm: Document OpenPOWER Witherspoon BMC model Front LEDs
  docs/system/arm: Document the various raspi boards
  docs/system: Deprecate raspi2/raspi3 machine aliases
  MAINTAINERS: Cover system/arm/sx1.rst with OMAP machines
  MAINTAINERS: Cover system/arm/sbsa.rst with SBSA-REF machine
  MAINTAINERS: Fix system/arm/orangepi.rst path
  MAINTAINERS: Cover system/arm/nuvoton.rst with Nuvoton NPCM7xx
  MAINTAINERS: Cover system/arm/aspeed.rst with ASPEED BMC machines
  ...

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

3 files changed, 93 insertions, 0 deletions

diff --git a/docs/tools/conf.py b/docs/tools/conf.py
index 9052d17..4760d36 100644
--- a/docs/tools/conf.py
+++ b/docs/tools/conf.py
@@ -22,6 +22,8 @@ man_pages = [
      ['Fabrice Bellard'], 1),
     ('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
      ['Anthony Liguori <anthony@codemonkey.ws>'], 8),
+    ('qemu-pr-helper', 'qemu-pr-helper', 'QEMU persistent reservation helper',
+     [], 8),
     ('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
      [], 1),
     ('virtfs-proxy-helper', 'virtfs-proxy-helper',
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index 232ce9f..b99f86c 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -12,6 +12,7 @@ Contents:
 
    qemu-img
    qemu-nbd
+   qemu-pr-helper
    qemu-trace-stap
    virtfs-proxy-helper
    virtiofsd
diff --git a/docs/tools/qemu-pr-helper.rst b/docs/tools/qemu-pr-helper.rst
new file mode 100644
index 0000000..ac03618
--- /dev/null
+++ b/docs/tools/qemu-pr-helper.rst
@@ -0,0 +1,90 @@
+QEMU persistent reservation helper
+==================================
+
+Synopsis
+--------
+
+**qemu-pr-helper** [*OPTION*]
+
+Description
+-----------
+
+Implements the persistent reservation helper for QEMU.
+
+SCSI persistent reservations allow restricting access to block devices
+to specific initiators in a shared storage setup.  When implementing
+clustering of virtual machines, it is a common requirement for virtual
+machines to send persistent reservation SCSI commands.  However,
+the operating system restricts sending these commands to unprivileged
+programs because incorrect usage can disrupt regular operation of the
+storage fabric. QEMU's SCSI passthrough devices ``scsi-block``
+and ``scsi-generic`` support passing guest persistent reservation
+requests to a privileged external helper program. :program:`qemu-pr-helper`
+is that external helper; it creates a socket which QEMU can
+connect to to communicate with it.
+
+If you want to run VMs in a setup like this, this helper should be
+started as a system service, and you should read the QEMU manual
+section on "persistent reservation managers" to find out how to
+configure QEMU to connect to the socket created by
+:program:`qemu-pr-helper`.
+
+After connecting to the socket, :program:`qemu-pr-helper` can
+optionally drop root privileges, except for those capabilities that
+are needed for its operation.
+
+:program:`qemu-pr-helper` can also use the systemd socket activation
+protocol.  In this case, the systemd socket unit should specify a
+Unix stream socket, like this::
+
+    [Socket]
+    ListenStream=/var/run/qemu-pr-helper.sock
+
+Options
+-------
+
+.. program:: qemu-pr-helper
+
+.. option:: -d, --daemon
+
+  run in the background (and create a PID file)
+
+.. option:: -q, --quiet
+
+  decrease verbosity
+
+.. option:: -v, --verbose
+
+  increase verbosity
+
+.. option:: -f, --pidfile=PATH
+
+  PID file when running as a daemon. By default the PID file
+  is created in the system runtime state directory, for example
+  :file:`/var/run/qemu-pr-helper.pid`.
+
+.. option:: -k, --socket=PATH
+
+  path to the socket. By default the socket is created in
+  the system runtime state directory, for example
+  :file:`/var/run/qemu-pr-helper.sock`.
+
+.. option:: -T, --trace [[enable=]PATTERN][,events=FILE][,file=FILE]
+
+  .. include:: ../qemu-option-trace.rst.inc
+
+.. option:: -u, --user=USER
+
+  user to drop privileges to
+
+.. option:: -g, --group=GROUP
+
+  group to drop privileges to
+
+.. option:: -h, --help
+
+  Display a help message and exit.
+
+.. option:: -V, --version
+
+  Display version information and exit.