From 155e1c82ed0da265dbc6cd499a2b2552a5388a9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Date: Fri, 20 Nov 2020 18:39:50 +0100 Subject: docs/system: Deprecate raspi2/raspi3 machine aliases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Since commit aa35ec2213b ("hw/arm/raspi: Use more specific machine names") the raspi2/raspi3 machines have been renamed as raspi2b/raspi3b. Note, rather than the raspi3b, the raspi3ap introduced in commit 5be94252d34 ("hw/arm/raspi: Add the Raspberry Pi 3 model A+") is a closer match to what QEMU models, but only provides 512 MB of RAM. As more Raspberry Pi 2/3 models are emulated, in order to avoid confusion, deprecate the raspi2/raspi3 machine aliases. ACKed-by: Peter Krempa Reviewed-by: Peter Maydell Signed-off-by: Philippe Mathieu-Daudé Message-id: 20201120173953.2539469-2-f4bug@amsat.org Signed-off-by: Peter Maydell --- docs/system/deprecated.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'docs') diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst index d984640..5653896 100644 --- a/docs/system/deprecated.rst +++ b/docs/system/deprecated.rst @@ -346,6 +346,13 @@ This machine has been renamed ``fuloong2e``. These machine types are very old and likely can not be used for live migration from old QEMU versions anymore. A newer machine type should be used instead. +Raspberry Pi ``raspi2`` and ``raspi3`` machines (since 5.2) +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +The Raspberry Pi machines come in various models (A, A+, B, B+). To be able +to distinguish which model QEMU is implementing, the ``raspi2`` and ``raspi3`` +machines have been renamed ``raspi2b`` and ``raspi3b``. + Device options -------------- -- cgit v1.1 From d9f2ac3de90d2b4bc7bfef12d69a6bfd0a4df04c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Date: Fri, 20 Nov 2020 18:39:51 +0100 Subject: docs/system/arm: Document the various raspi boards MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the following Raspberry Pi models: - raspi0 Raspberry Pi Zero (revision 1.2) - raspi1ap Raspberry Pi A+ (revision 1.1) - raspi2b Raspberry Pi 2B (revision 1.1) - raspi3ap Raspberry Pi 3A+ (revision 1.0) - raspi3b Raspberry Pi 3B (revision 1.2) Reviewed-by: Peter Maydell Signed-off-by: Philippe Mathieu-Daudé Message-id: 20201120173953.2539469-3-f4bug@amsat.org Signed-off-by: Peter Maydell --- docs/system/arm/raspi.rst | 43 +++++++++++++++++++++++++++++++++++++++++++ docs/system/target-arm.rst | 1 + 2 files changed, 44 insertions(+) create mode 100644 docs/system/arm/raspi.rst (limited to 'docs') diff --git a/docs/system/arm/raspi.rst b/docs/system/arm/raspi.rst new file mode 100644 index 0000000..922fe37 --- /dev/null +++ b/docs/system/arm/raspi.rst @@ -0,0 +1,43 @@ +Raspberry Pi boards (``raspi0``, ``raspi1ap``, ``raspi2b``, ``raspi3ap``, ``raspi3b``) +====================================================================================== + + +QEMU provides models of the following Raspberry Pi boards: + +``raspi0`` and ``raspi1ap`` + ARM1176JZF-S core, 512 MiB of RAM +``raspi2b`` + Cortex-A7 (4 cores), 1 GiB of RAM +``raspi3ap`` + Cortex-A53 (4 cores), 512 MiB of RAM +``raspi3b`` + Cortex-A53 (4 cores), 1 GiB of RAM + + +Implemented devices +------------------- + + * ARM1176JZF-S, Cortex-A7 or Cortex-A53 CPU + * Interrupt controller + * DMA controller + * Clock and reset controller (CPRMAN) + * System Timer + * GPIO controller + * Serial ports (BCM2835 AUX - 16550 based - and PL011) + * Random Number Generator (RNG) + * Frame Buffer + * USB host (USBH) + * GPIO controller + * SD/MMC host controller + * SoC thermal sensor + * USB2 host controller (DWC2 and MPHI) + * MailBox controller (MBOX) + * VideoCore firmware (property) + + +Missing devices +--------------- + + * Peripheral SPI controller (SPI) + * Analog to Digital Converter (ADC) + * Pulse Width Modulation (PWM) diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst index a0d5c57..bde4b8e 100644 --- a/docs/system/target-arm.rst +++ b/docs/system/target-arm.rst @@ -90,6 +90,7 @@ undocumented; you can get a complete list by running arm/nuvoton arm/orangepi arm/palm + arm/raspi arm/xscale arm/collie arm/sx1 -- cgit v1.1 From 12bff81b4dfa01fe7956d25f2687df46caff7041 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Date: Fri, 20 Nov 2020 18:39:52 +0100 Subject: docs/system/arm: Document OpenPOWER Witherspoon BMC model Front LEDs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the 3 front LEDs modeled on the OpenPOWER Witherspoon BMC (see commit 7cfbde5ea1c "hw/arm/aspeed: Add the 3 front LEDs drived by the PCA9552 #1"). Reviewed-by: Cédric Le Goater Signed-off-by: Philippe Mathieu-Daudé Message-id: 20201120173953.2539469-4-f4bug@amsat.org Signed-off-by: Peter Maydell --- docs/system/arm/aspeed.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'docs') diff --git a/docs/system/arm/aspeed.rst b/docs/system/arm/aspeed.rst index b7a1766..690bada 100644 --- a/docs/system/arm/aspeed.rst +++ b/docs/system/arm/aspeed.rst @@ -47,6 +47,7 @@ Supported devices * GPIO Controller (Master only) * UART * Ethernet controllers + * Front LEDs (PCA9552 on I2C bus) Missing devices -- cgit v1.1 From 75bf6e17f953feedcd260f5d6a993fbb569c9915 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= Date: Fri, 20 Nov 2020 18:39:53 +0100 Subject: docs/system/arm: Document the Sharp Zaurus SL-6000 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit List the 'tosa' machine with the XScale-based PDAs models. Signed-off-by: Philippe Mathieu-Daudé Message-id: 20201120173953.2539469-5-f4bug@amsat.org Reviewed-by: Peter Maydell Signed-off-by: Peter Maydell --- docs/system/arm/xscale.rst | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) (limited to 'docs') diff --git a/docs/system/arm/xscale.rst b/docs/system/arm/xscale.rst index 89ec93e..d2d5949 100644 --- a/docs/system/arm/xscale.rst +++ b/docs/system/arm/xscale.rst @@ -1,16 +1,22 @@ -Sharp XScale-based PDA models (``akita``, ``borzoi``, ``spitz``, ``terrier``) -============================================================================= +Sharp XScale-based PDA models (``akita``, ``borzoi``, ``spitz``, ``terrier``, ``tosa``) +======================================================================================= -The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\" -and \"Terrier\") emulation includes the following peripherals: +The Sharp Zaurus are PDAs based on XScale, able to run Linux ('SL series'). -- Intel PXA270 System-on-chip (ARMv5TE core) +The SL-6000 (\"Tosa\"), released in 2005, uses a PXA255 System-on-chip. -- NAND Flash memory +The SL-C3000 (\"Spitz\"), SL-C1000 (\"Akita\"), SL-C3100 (\"Borzoi\") and +SL-C3200 (\"Terrier\") use a PXA270. + +The clamshell PDA models emulation includes the following peripherals: + +- Intel PXA255/PXA270 System-on-chip (ARMv5TE core) + +- NAND Flash memory - not in \"Tosa\" - IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\" -- On-chip OHCI USB controller +- On-chip OHCI USB controller - not in \"Tosa\" - On-chip LCD controller -- cgit v1.1 From 4faf359accb274d37ddb0e7b68617b9297b9120e Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:33 +0000 Subject: docs: Move virtio-net-failover.rst into the system manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The virtio-net-failover documentation is currently orphan and not included in any manual; move it into the system manual, immediately following the general network emulation section. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/system/index.rst | 1 + docs/system/virtio-net-failover.rst | 68 +++++++++++++++++++++++++++++++++++++ docs/virtio-net-failover.rst | 68 ------------------------------------- 3 files changed, 69 insertions(+), 68 deletions(-) create mode 100644 docs/system/virtio-net-failover.rst delete mode 100644 docs/virtio-net-failover.rst (limited to 'docs') diff --git a/docs/system/index.rst b/docs/system/index.rst index c0f685b..d0613cd 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -21,6 +21,7 @@ Contents: monitor images net + virtio-net-failover usb ivshmem linuxboot diff --git a/docs/system/virtio-net-failover.rst b/docs/system/virtio-net-failover.rst new file mode 100644 index 0000000..6002dc5 --- /dev/null +++ b/docs/system/virtio-net-failover.rst @@ -0,0 +1,68 @@ +====================================== +QEMU virtio-net standby (net_failover) +====================================== + +This document explains the setup and usage of virtio-net standby feature which +is used to create a net_failover pair of devices. + +The general idea is that we have a pair of devices, a (vfio-)pci and a +virtio-net device. Before migration the vfio device is unplugged and data flows +through the virtio-net device, on the target side another vfio-pci device is +plugged in to take over the data-path. In the guest the net_failover kernel +module will pair net devices with the same MAC address. + +The two devices are called primary and standby device. The fast hardware based +networking device is called the primary device and the virtio-net device is the +standby device. + +Restrictions +------------ + +Currently only PCIe devices are allowed as primary devices, this restriction +can be lifted in the future with enhanced QEMU support. Also, only networking +devices are allowed as primary device. The user needs to ensure that primary +and standby devices are not plugged into the same PCIe slot. + +Usecase +------- + + Virtio-net standby allows easy migration while using a passed-through fast + networking device by falling back to a virtio-net device for the duration of + the migration. It is like a simple version of a bond, the difference is that it + requires no configuration in the guest. When a guest is live-migrated to + another host QEMU will unplug the primary device via the PCIe based hotplug + handler and traffic will go through the virtio-net device. On the target + system the primary device will be automatically plugged back and the + net_failover module registers it again as the primary device. + +Usage +----- + + The primary device can be hotplugged or be part of the startup configuration + + -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, \ + bus=root2,failover=on + + With the parameter failover=on the VIRTIO_NET_F_STANDBY feature will be enabled. + + -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1 + + failover_pair_id references the id of the virtio-net standby device. This + is only for pairing the devices within QEMU. The guest kernel module + net_failover will match devices with identical MAC addresses. + +Hotplug +------- + + Both primary and standby device can be hotplugged via the QEMU monitor. Note + that if the virtio-net device is plugged first a warning will be issued that it + couldn't find the primary device. + +Migration +--------- + + A new migration state wait-unplug was added for this feature. If failover primary + devices are present in the configuration, migration will go into this state. + It will wait until the device unplug is completed in the guest and then move into + active state. On the target system the primary devices will be automatically hotplugged + when the feature bit was negotiated for the virtio-net standby device. diff --git a/docs/virtio-net-failover.rst b/docs/virtio-net-failover.rst deleted file mode 100644 index 6002dc5..0000000 --- a/docs/virtio-net-failover.rst +++ /dev/null @@ -1,68 +0,0 @@ -====================================== -QEMU virtio-net standby (net_failover) -====================================== - -This document explains the setup and usage of virtio-net standby feature which -is used to create a net_failover pair of devices. - -The general idea is that we have a pair of devices, a (vfio-)pci and a -virtio-net device. Before migration the vfio device is unplugged and data flows -through the virtio-net device, on the target side another vfio-pci device is -plugged in to take over the data-path. In the guest the net_failover kernel -module will pair net devices with the same MAC address. - -The two devices are called primary and standby device. The fast hardware based -networking device is called the primary device and the virtio-net device is the -standby device. - -Restrictions ------------- - -Currently only PCIe devices are allowed as primary devices, this restriction -can be lifted in the future with enhanced QEMU support. Also, only networking -devices are allowed as primary device. The user needs to ensure that primary -and standby devices are not plugged into the same PCIe slot. - -Usecase -------- - - Virtio-net standby allows easy migration while using a passed-through fast - networking device by falling back to a virtio-net device for the duration of - the migration. It is like a simple version of a bond, the difference is that it - requires no configuration in the guest. When a guest is live-migrated to - another host QEMU will unplug the primary device via the PCIe based hotplug - handler and traffic will go through the virtio-net device. On the target - system the primary device will be automatically plugged back and the - net_failover module registers it again as the primary device. - -Usage ------ - - The primary device can be hotplugged or be part of the startup configuration - - -device virtio-net-pci,netdev=hostnet1,id=net1,mac=52:54:00:6f:55:cc, \ - bus=root2,failover=on - - With the parameter failover=on the VIRTIO_NET_F_STANDBY feature will be enabled. - - -device vfio-pci,host=5e:00.2,id=hostdev0,bus=root1,failover_pair_id=net1 - - failover_pair_id references the id of the virtio-net standby device. This - is only for pairing the devices within QEMU. The guest kernel module - net_failover will match devices with identical MAC addresses. - -Hotplug -------- - - Both primary and standby device can be hotplugged via the QEMU monitor. Note - that if the virtio-net device is plugged first a warning will be issued that it - couldn't find the primary device. - -Migration ---------- - - A new migration state wait-unplug was added for this feature. If failover primary - devices are present in the configuration, migration will go into this state. - It will wait until the device unplug is completed in the guest and then move into - active state. On the target system the primary devices will be automatically hotplugged - when the feature bit was negotiated for the virtio-net standby device. -- cgit v1.1 From 392d8e95c7dd3de10a20387914ac34cb12d8ff04 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:34 +0000 Subject: docs: Move cpu-hotplug.rst into the system manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The cpu-hotplug.rst documentation is currently orphan and not included in any manual; move it into the system manual. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/cpu-hotplug.rst | 142 -------------------------------------------- docs/system/cpu-hotplug.rst | 142 ++++++++++++++++++++++++++++++++++++++++++++ docs/system/index.rst | 1 + 3 files changed, 143 insertions(+), 142 deletions(-) delete mode 100644 docs/cpu-hotplug.rst create mode 100644 docs/system/cpu-hotplug.rst (limited to 'docs') diff --git a/docs/cpu-hotplug.rst b/docs/cpu-hotplug.rst deleted file mode 100644 index d0b0640..0000000 --- a/docs/cpu-hotplug.rst +++ /dev/null @@ -1,142 +0,0 @@ -=================== -Virtual CPU hotplug -=================== - -A complete example of vCPU hotplug (and hot-unplug) using QMP -``device_add`` and ``device_del``. - -vCPU hotplug ------------- - -(1) Launch QEMU as follows (note that the "maxcpus" is mandatory to - allow vCPU hotplug):: - - $ qemu-system-x86_64 -display none -no-user-config -m 2048 \ - -nodefaults -monitor stdio -machine pc,accel=kvm,usb=off \ - -smp 1,maxcpus=2 -cpu IvyBridge-IBRS \ - -qmp unix:/tmp/qmp-sock,server,nowait - -(2) Run 'qmp-shell' (located in the source tree, under: "scripts/qmp/) - to connect to the just-launched QEMU:: - - $> ./qmp-shell -p -v /tmp/qmp-sock - [...] - (QEMU) - -(3) Find out which CPU types could be plugged, and into which sockets:: - - (QEMU) query-hotpluggable-cpus - { - "execute": "query-hotpluggable-cpus", - "arguments": {} - } - { - "return": [ - { - "type": "IvyBridge-IBRS-x86_64-cpu", - "vcpus-count": 1, - "props": { - "socket-id": 1, - "core-id": 0, - "thread-id": 0 - } - }, - { - "qom-path": "/machine/unattached/device[0]", - "type": "IvyBridge-IBRS-x86_64-cpu", - "vcpus-count": 1, - "props": { - "socket-id": 0, - "core-id": 0, - "thread-id": 0 - } - } - ] - } - (QEMU) - -(4) The ``query-hotpluggable-cpus`` command returns an object for CPUs - that are present (containing a "qom-path" member) or which may be - hot-plugged (no "qom-path" member). From its output in step (3), we - can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0, - while hot-plugging a CPU into socket 1 requires passing the listed - properties to QMP ``device_add``:: - - (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0 - { - "execute": "device_add", - "arguments": { - "socket-id": 1, - "driver": "IvyBridge-IBRS-x86_64-cpu", - "id": "cpu-2", - "core-id": 0, - "thread-id": 0 - } - } - { - "return": {} - } - (QEMU) - -(5) Optionally, run QMP `query-cpus-fast` for some details about the - vCPUs:: - - (QEMU) query-cpus-fast - { - "execute": "query-cpus-fast", - "arguments": {} - } - { - "return": [ - { - "qom-path": "/machine/unattached/device[0]", - "target": "x86_64", - "thread-id": 11534, - "cpu-index": 0, - "props": { - "socket-id": 0, - "core-id": 0, - "thread-id": 0 - }, - "arch": "x86" - }, - { - "qom-path": "/machine/peripheral/cpu-2", - "target": "x86_64", - "thread-id": 12106, - "cpu-index": 1, - "props": { - "socket-id": 1, - "core-id": 0, - "thread-id": 0 - }, - "arch": "x86" - } - ] - } - (QEMU) - -vCPU hot-unplug ---------------- - -From the 'qmp-shell', invoke the QMP ``device_del`` command:: - - (QEMU) device_del id=cpu-2 - { - "execute": "device_del", - "arguments": { - "id": "cpu-2" - } - } - { - "return": {} - } - (QEMU) - -.. note:: - vCPU hot-unplug requires guest cooperation; so the ``device_del`` - command above does not guarantee vCPU removal -- it's a "request to - unplug". At this point, the guest will get a System Control - Interrupt (SCI) and calls the ACPI handler for the affected vCPU - device. Then the guest kernel will bring the vCPU offline and tell - QEMU to unplug it. diff --git a/docs/system/cpu-hotplug.rst b/docs/system/cpu-hotplug.rst new file mode 100644 index 0000000..d0b0640 --- /dev/null +++ b/docs/system/cpu-hotplug.rst @@ -0,0 +1,142 @@ +=================== +Virtual CPU hotplug +=================== + +A complete example of vCPU hotplug (and hot-unplug) using QMP +``device_add`` and ``device_del``. + +vCPU hotplug +------------ + +(1) Launch QEMU as follows (note that the "maxcpus" is mandatory to + allow vCPU hotplug):: + + $ qemu-system-x86_64 -display none -no-user-config -m 2048 \ + -nodefaults -monitor stdio -machine pc,accel=kvm,usb=off \ + -smp 1,maxcpus=2 -cpu IvyBridge-IBRS \ + -qmp unix:/tmp/qmp-sock,server,nowait + +(2) Run 'qmp-shell' (located in the source tree, under: "scripts/qmp/) + to connect to the just-launched QEMU:: + + $> ./qmp-shell -p -v /tmp/qmp-sock + [...] + (QEMU) + +(3) Find out which CPU types could be plugged, and into which sockets:: + + (QEMU) query-hotpluggable-cpus + { + "execute": "query-hotpluggable-cpus", + "arguments": {} + } + { + "return": [ + { + "type": "IvyBridge-IBRS-x86_64-cpu", + "vcpus-count": 1, + "props": { + "socket-id": 1, + "core-id": 0, + "thread-id": 0 + } + }, + { + "qom-path": "/machine/unattached/device[0]", + "type": "IvyBridge-IBRS-x86_64-cpu", + "vcpus-count": 1, + "props": { + "socket-id": 0, + "core-id": 0, + "thread-id": 0 + } + } + ] + } + (QEMU) + +(4) The ``query-hotpluggable-cpus`` command returns an object for CPUs + that are present (containing a "qom-path" member) or which may be + hot-plugged (no "qom-path" member). From its output in step (3), we + can see that ``IvyBridge-IBRS-x86_64-cpu`` is present in socket 0, + while hot-plugging a CPU into socket 1 requires passing the listed + properties to QMP ``device_add``:: + + (QEMU) device_add id=cpu-2 driver=IvyBridge-IBRS-x86_64-cpu socket-id=1 core-id=0 thread-id=0 + { + "execute": "device_add", + "arguments": { + "socket-id": 1, + "driver": "IvyBridge-IBRS-x86_64-cpu", + "id": "cpu-2", + "core-id": 0, + "thread-id": 0 + } + } + { + "return": {} + } + (QEMU) + +(5) Optionally, run QMP `query-cpus-fast` for some details about the + vCPUs:: + + (QEMU) query-cpus-fast + { + "execute": "query-cpus-fast", + "arguments": {} + } + { + "return": [ + { + "qom-path": "/machine/unattached/device[0]", + "target": "x86_64", + "thread-id": 11534, + "cpu-index": 0, + "props": { + "socket-id": 0, + "core-id": 0, + "thread-id": 0 + }, + "arch": "x86" + }, + { + "qom-path": "/machine/peripheral/cpu-2", + "target": "x86_64", + "thread-id": 12106, + "cpu-index": 1, + "props": { + "socket-id": 1, + "core-id": 0, + "thread-id": 0 + }, + "arch": "x86" + } + ] + } + (QEMU) + +vCPU hot-unplug +--------------- + +From the 'qmp-shell', invoke the QMP ``device_del`` command:: + + (QEMU) device_del id=cpu-2 + { + "execute": "device_del", + "arguments": { + "id": "cpu-2" + } + } + { + "return": {} + } + (QEMU) + +.. note:: + vCPU hot-unplug requires guest cooperation; so the ``device_del`` + command above does not guarantee vCPU removal -- it's a "request to + unplug". At this point, the guest will get a System Control + Interrupt (SCI) and calls the ACPI handler for the affected vCPU + device. Then the guest kernel will bring the vCPU offline and tell + QEMU to unplug it. diff --git a/docs/system/index.rst b/docs/system/index.rst index d0613cd..0f0f6d2 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -29,6 +29,7 @@ Contents: tls gdb managed-startup + cpu-hotplug targets security deprecated -- cgit v1.1 From 71266bb4e9468662d88739827c78fcb37285c643 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:35 +0000 Subject: docs: Move virtio-pmem.rst into the system manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/system/index.rst | 1 + docs/system/virtio-pmem.rst | 76 +++++++++++++++++++++++++++++++++++++++++++++ docs/virtio-pmem.rst | 76 --------------------------------------------- 3 files changed, 77 insertions(+), 76 deletions(-) create mode 100644 docs/system/virtio-pmem.rst delete mode 100644 docs/virtio-pmem.rst (limited to 'docs') diff --git a/docs/system/index.rst b/docs/system/index.rst index 0f0f6d2..2a5155c 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -30,6 +30,7 @@ Contents: gdb managed-startup cpu-hotplug + virtio-pmem targets security deprecated diff --git a/docs/system/virtio-pmem.rst b/docs/system/virtio-pmem.rst new file mode 100644 index 0000000..4bf5d00 --- /dev/null +++ b/docs/system/virtio-pmem.rst @@ -0,0 +1,76 @@ + +======================== +QEMU virtio pmem +======================== + + This document explains the setup and usage of the virtio pmem device + which is available since QEMU v4.1.0. + + The virtio pmem device is a paravirtualized persistent memory device + on regular (i.e non-NVDIMM) storage. + +Usecase +-------- + + Virtio pmem allows to bypass the guest page cache and directly use + host page cache. This reduces guest memory footprint as the host can + make efficient memory reclaim decisions under memory pressure. + +o How does virtio-pmem compare to the nvdimm emulation supported by QEMU? + + NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not + persist the guest writes as there are no defined semantics in the device + specification. The virtio pmem device provides guest write persistence + on non-NVDIMM host storage. + +virtio pmem usage +----------------- + + A virtio pmem device backed by a memory-backend-file can be created on + the QEMU command line as in the following example:: + + -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G + -device virtio-pmem-pci,memdev=mem1,id=nv1 + + where: + + - "object memory-backend-file,id=mem1,share,mem-path=, size=" + creates a backend file with the specified size. + + - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem + pci device whose storage is provided by above memory backend device. + + Multiple virtio pmem devices can be created if multiple pairs of "-object" + and "-device" are provided. + +Hotplug +------- + +Virtio pmem devices can be hotplugged via the QEMU monitor. First, the +memory backing has to be added via 'object_add'; afterwards, the virtio +pmem device can be added via 'device_add'. + +For example, the following commands add another 4GB virtio pmem device to +the guest:: + + (qemu) object_add memory-backend-file,id=mem2,share=on,mem-path=virtio_pmem2.img,size=4G + (qemu) device_add virtio-pmem-pci,id=virtio_pmem2,memdev=mem2 + +Guest Data Persistence +---------------------- + + Guest data persistence on non-NVDIMM requires guest userspace applications + to perform fsync/msync. This is different from a real nvdimm backend where + no additional fsync/msync is required. This is to persist guest writes in + host backing file which otherwise remains in host page cache and there is + risk of losing the data in case of power failure. + + With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides + a hint to application to perform fsync for write persistence. + +Limitations +------------ +- Real nvdimm device backend is not supported. +- virtio pmem hotunplug is not supported. +- ACPI NVDIMM features like regions/namespaces are not supported. +- ndctl command is not supported. diff --git a/docs/virtio-pmem.rst b/docs/virtio-pmem.rst deleted file mode 100644 index 4bf5d00..0000000 --- a/docs/virtio-pmem.rst +++ /dev/null @@ -1,76 +0,0 @@ - -======================== -QEMU virtio pmem -======================== - - This document explains the setup and usage of the virtio pmem device - which is available since QEMU v4.1.0. - - The virtio pmem device is a paravirtualized persistent memory device - on regular (i.e non-NVDIMM) storage. - -Usecase --------- - - Virtio pmem allows to bypass the guest page cache and directly use - host page cache. This reduces guest memory footprint as the host can - make efficient memory reclaim decisions under memory pressure. - -o How does virtio-pmem compare to the nvdimm emulation supported by QEMU? - - NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not - persist the guest writes as there are no defined semantics in the device - specification. The virtio pmem device provides guest write persistence - on non-NVDIMM host storage. - -virtio pmem usage ------------------ - - A virtio pmem device backed by a memory-backend-file can be created on - the QEMU command line as in the following example:: - - -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G - -device virtio-pmem-pci,memdev=mem1,id=nv1 - - where: - - - "object memory-backend-file,id=mem1,share,mem-path=, size=" - creates a backend file with the specified size. - - - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem - pci device whose storage is provided by above memory backend device. - - Multiple virtio pmem devices can be created if multiple pairs of "-object" - and "-device" are provided. - -Hotplug -------- - -Virtio pmem devices can be hotplugged via the QEMU monitor. First, the -memory backing has to be added via 'object_add'; afterwards, the virtio -pmem device can be added via 'device_add'. - -For example, the following commands add another 4GB virtio pmem device to -the guest:: - - (qemu) object_add memory-backend-file,id=mem2,share=on,mem-path=virtio_pmem2.img,size=4G - (qemu) device_add virtio-pmem-pci,id=virtio_pmem2,memdev=mem2 - -Guest Data Persistence ----------------------- - - Guest data persistence on non-NVDIMM requires guest userspace applications - to perform fsync/msync. This is different from a real nvdimm backend where - no additional fsync/msync is required. This is to persist guest writes in - host backing file which otherwise remains in host page cache and there is - risk of losing the data in case of power failure. - - With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides - a hint to application to perform fsync for write persistence. - -Limitations ------------- -- Real nvdimm device backend is not supported. -- virtio pmem hotunplug is not supported. -- ACPI NVDIMM features like regions/namespaces are not supported. -- ndctl command is not supported. -- cgit v1.1 From c5d7cfdaace7f547fd572b50baaa7182366513e7 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:36 +0000 Subject: docs/system/virtio-pmem.rst: Fix minor style issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The virtio-pmem documentation has some minor style issues we hadn't noticed since we weren't rendering it in our docs: * Sphinx doesn't complain about overlong title-underlining the way it complains about too-short underlining, but it looks odd; make the underlines of section headers the right length * Indent of paragraphs makes them render as blockquotes; remove the indent so they just render as normal text * Leading 'o' isn't rst markup, so it just renders as a literal "o"; reformat as a subsection heading instead * "QEMU" in the document title and section headings are a bit odd and unnecessary since this is the QEMU manual; delete or rephrase them * There's no need to specify what QEMU version the device first appeared in. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée Reviewed-by: Pankaj Gupta --- docs/system/virtio-pmem.rst | 60 ++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 30 deletions(-) (limited to 'docs') diff --git a/docs/system/virtio-pmem.rst b/docs/system/virtio-pmem.rst index 4bf5d00..c82ac06 100644 --- a/docs/system/virtio-pmem.rst +++ b/docs/system/virtio-pmem.rst @@ -1,38 +1,37 @@ -======================== -QEMU virtio pmem -======================== +=========== +virtio pmem +=========== - This document explains the setup and usage of the virtio pmem device - which is available since QEMU v4.1.0. - - The virtio pmem device is a paravirtualized persistent memory device - on regular (i.e non-NVDIMM) storage. +This document explains the setup and usage of the virtio pmem device. +The virtio pmem device is a paravirtualized persistent memory device +on regular (i.e non-NVDIMM) storage. Usecase --------- +------- - Virtio pmem allows to bypass the guest page cache and directly use - host page cache. This reduces guest memory footprint as the host can - make efficient memory reclaim decisions under memory pressure. +Virtio pmem allows to bypass the guest page cache and directly use +host page cache. This reduces guest memory footprint as the host can +make efficient memory reclaim decisions under memory pressure. -o How does virtio-pmem compare to the nvdimm emulation supported by QEMU? +How does virtio-pmem compare to the nvdimm emulation? +----------------------------------------------------- - NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not - persist the guest writes as there are no defined semantics in the device - specification. The virtio pmem device provides guest write persistence - on non-NVDIMM host storage. +NVDIMM emulation on regular (i.e. non-NVDIMM) host storage does not +persist the guest writes as there are no defined semantics in the device +specification. The virtio pmem device provides guest write persistence +on non-NVDIMM host storage. virtio pmem usage ----------------- - A virtio pmem device backed by a memory-backend-file can be created on - the QEMU command line as in the following example:: +A virtio pmem device backed by a memory-backend-file can be created on +the QEMU command line as in the following example:: -object memory-backend-file,id=mem1,share,mem-path=./virtio_pmem.img,size=4G -device virtio-pmem-pci,memdev=mem1,id=nv1 - where: +where: - "object memory-backend-file,id=mem1,share,mem-path=, size=" creates a backend file with the specified size. @@ -40,8 +39,8 @@ virtio pmem usage - "device virtio-pmem-pci,id=nvdimm1,memdev=mem1" creates a virtio pmem pci device whose storage is provided by above memory backend device. - Multiple virtio pmem devices can be created if multiple pairs of "-object" - and "-device" are provided. +Multiple virtio pmem devices can be created if multiple pairs of "-object" +and "-device" are provided. Hotplug ------- @@ -59,17 +58,18 @@ the guest:: Guest Data Persistence ---------------------- - Guest data persistence on non-NVDIMM requires guest userspace applications - to perform fsync/msync. This is different from a real nvdimm backend where - no additional fsync/msync is required. This is to persist guest writes in - host backing file which otherwise remains in host page cache and there is - risk of losing the data in case of power failure. +Guest data persistence on non-NVDIMM requires guest userspace applications +to perform fsync/msync. This is different from a real nvdimm backend where +no additional fsync/msync is required. This is to persist guest writes in +host backing file which otherwise remains in host page cache and there is +risk of losing the data in case of power failure. - With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides - a hint to application to perform fsync for write persistence. +With virtio pmem device, MAP_SYNC mmap flag is not supported. This provides +a hint to application to perform fsync for write persistence. Limitations ------------- +----------- + - Real nvdimm device backend is not supported. - virtio pmem hotunplug is not supported. - ACPI NVDIMM features like regions/namespaces are not supported. -- cgit v1.1 From 7f0cff6e3427d82f81243660d0035d647ee5ee05 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:37 +0000 Subject: docs: Split out 'pc' machine model docs into their own file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Currently target-i386.rst includes the documentation of the 'pc' machine model inline. Split it out into its own file, in a similar way to target-i386.rst; this gives us a place to put documentation of other i386 machine models, such as 'microvm'. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/system/i386/pc.rst | 7 +++++++ docs/system/target-i386.rst | 18 +++++++++++++----- 2 files changed, 20 insertions(+), 5 deletions(-) create mode 100644 docs/system/i386/pc.rst (limited to 'docs') diff --git a/docs/system/i386/pc.rst b/docs/system/i386/pc.rst new file mode 100644 index 0000000..d543c11 --- /dev/null +++ b/docs/system/i386/pc.rst @@ -0,0 +1,7 @@ +i440fx PC (``pc-i440fx``, ``pc``) +================================= + +Peripherals +~~~~~~~~~~~ + +.. include:: ../target-i386-desc.rst.inc diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst index 51be03d..1612ddb 100644 --- a/docs/system/target-i386.rst +++ b/docs/system/target-i386.rst @@ -1,14 +1,22 @@ .. _QEMU-PC-System-emulator: -x86 (PC) System emulator ------------------------- +x86 System emulator +------------------- .. _pcsys_005fdevices: -Peripherals -~~~~~~~~~~~ +Board-specific documentation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. include:: target-i386-desc.rst.inc +.. + This table of contents should be kept sorted alphabetically + by the title text of each file, which isn't the same ordering + as an alphabetical sort by filename. + +.. toctree:: + :maxdepth: 1 + + i386/pc .. include:: cpu-models-x86.rst.inc -- cgit v1.1 From e8eee8d3d90690b73caac6b0059ad02ed1f170e6 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:38 +0000 Subject: docs: Move microvm.rst into the system manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Now that target-i386.rst has a place to list documentation of machines other than the 'pc' machine, we have a place we can move the microvm documentation to. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/microvm.rst | 129 ------------------------------------------- docs/system/i386/microvm.rst | 128 ++++++++++++++++++++++++++++++++++++++++++ docs/system/target-i386.rst | 1 + 3 files changed, 129 insertions(+), 129 deletions(-) delete mode 100644 docs/microvm.rst create mode 100644 docs/system/i386/microvm.rst (limited to 'docs') diff --git a/docs/microvm.rst b/docs/microvm.rst deleted file mode 100644 index fcf41fc..0000000 --- a/docs/microvm.rst +++ /dev/null @@ -1,129 +0,0 @@ -==================== -microvm Machine Type -==================== - -``microvm`` is a machine type inspired by ``Firecracker`` and -constructed after its machine model. - -It's a minimalist machine type without ``PCI`` nor ``ACPI`` support, -designed for short-lived guests. microvm also establishes a baseline -for benchmarking and optimizing both QEMU and guest operating systems, -since it is optimized for both boot time and footprint. - - -Supported devices ------------------ - -The microvm machine type supports the following devices: - -- ISA bus -- i8259 PIC (optional) -- i8254 PIT (optional) -- MC146818 RTC (optional) -- One ISA serial port (optional) -- LAPIC -- IOAPIC (with kernel-irqchip=split by default) -- kvmclock (if using KVM) -- fw_cfg -- Up to eight virtio-mmio devices (configured by the user) - - -Limitations ------------ - -Currently, microvm does *not* support the following features: - -- PCI-only devices. -- Hotplug of any kind. -- Live migration across QEMU versions. - - -Using the microvm machine type ------------------------------- - -Machine-specific options -~~~~~~~~~~~~~~~~~~~~~~~~ - -It supports the following machine-specific options: - -- microvm.x-option-roms=bool (Set off to disable loading option ROMs) -- microvm.pit=OnOffAuto (Enable i8254 PIT) -- microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port) -- microvm.pic=OnOffAuto (Enable i8259 PIC) -- microvm.rtc=OnOffAuto (Enable MC146818 RTC) -- microvm.auto-kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline) - - -Boot options -~~~~~~~~~~~~ - -By default, microvm uses ``qboot`` as its BIOS, to obtain better boot -times, but it's also compatible with ``SeaBIOS``. - -As no current FW is able to boot from a block device using -``virtio-mmio`` as its transport, a microvm-based VM needs to be run -using a host-side kernel and, optionally, an initrd image. - - -Running a microvm-based VM -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, microvm aims for maximum compatibility, enabling both -legacy and non-legacy devices. In this example, a VM is created -without passing any additional machine-specific option, using the -legacy ``ISA serial`` device as console:: - - $ qemu-system-x86_64 -M microvm \ - -enable-kvm -cpu host -m 512m -smp 2 \ - -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \ - -nodefaults -no-user-config -nographic \ - -serial stdio \ - -drive id=test,file=test.img,format=raw,if=none \ - -device virtio-blk-device,drive=test \ - -netdev tap,id=tap0,script=no,downscript=no \ - -device virtio-net-device,netdev=tap0 - -While the example above works, you might be interested in reducing the -footprint further by disabling some legacy devices. If you're using -``KVM``, you can disable the ``RTC``, making the Guest rely on -``kvmclock`` exclusively. Additionally, if your host's CPUs have the -``TSC_DEADLINE`` feature, you can also disable both the i8259 PIC and -the i8254 PIT (make sure you're also emulating a CPU with such feature -in the guest). - -This is an example of a VM with all optional legacy features -disabled:: - - $ qemu-system-x86_64 \ - -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off \ - -enable-kvm -cpu host -m 512m -smp 2 \ - -kernel vmlinux -append "console=hvc0 root=/dev/vda" \ - -nodefaults -no-user-config -nographic \ - -chardev stdio,id=virtiocon0 \ - -device virtio-serial-device \ - -device virtconsole,chardev=virtiocon0 \ - -drive id=test,file=test.img,format=raw,if=none \ - -device virtio-blk-device,drive=test \ - -netdev tap,id=tap0,script=no,downscript=no \ - -device virtio-net-device,netdev=tap0 - - -Triggering a guest-initiated shut down -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -As the microvm machine type includes just a small set of system -devices, some x86 mechanisms for rebooting or shutting down the -system, like sending a key sequence to the keyboard or writing to an -ACPI register, doesn't have any effect in the VM. - -The recommended way to trigger a guest-initiated shut down is by -generating a ``triple-fault``, which will cause the VM to initiate a -reboot. Additionally, if the ``-no-reboot`` argument is present in the -command line, QEMU will detect this event and terminate its own -execution gracefully. - -Linux does support this mechanism, but by default will only be used -after other options have been tried and failed, causing the reboot to -be delayed by a small number of seconds. It's possible to instruct it -to try the triple-fault mechanism first, by adding ``reboot=t`` to the -kernel's command line. diff --git a/docs/system/i386/microvm.rst b/docs/system/i386/microvm.rst new file mode 100644 index 0000000..1675e37 --- /dev/null +++ b/docs/system/i386/microvm.rst @@ -0,0 +1,128 @@ +'microvm' virtual platform (``microvm``) +======================================== + +``microvm`` is a machine type inspired by ``Firecracker`` and +constructed after its machine model. + +It's a minimalist machine type without ``PCI`` nor ``ACPI`` support, +designed for short-lived guests. microvm also establishes a baseline +for benchmarking and optimizing both QEMU and guest operating systems, +since it is optimized for both boot time and footprint. + + +Supported devices +----------------- + +The microvm machine type supports the following devices: + +- ISA bus +- i8259 PIC (optional) +- i8254 PIT (optional) +- MC146818 RTC (optional) +- One ISA serial port (optional) +- LAPIC +- IOAPIC (with kernel-irqchip=split by default) +- kvmclock (if using KVM) +- fw_cfg +- Up to eight virtio-mmio devices (configured by the user) + + +Limitations +----------- + +Currently, microvm does *not* support the following features: + +- PCI-only devices. +- Hotplug of any kind. +- Live migration across QEMU versions. + + +Using the microvm machine type +------------------------------ + +Machine-specific options +~~~~~~~~~~~~~~~~~~~~~~~~ + +It supports the following machine-specific options: + +- microvm.x-option-roms=bool (Set off to disable loading option ROMs) +- microvm.pit=OnOffAuto (Enable i8254 PIT) +- microvm.isa-serial=bool (Set off to disable the instantiation an ISA serial port) +- microvm.pic=OnOffAuto (Enable i8259 PIC) +- microvm.rtc=OnOffAuto (Enable MC146818 RTC) +- microvm.auto-kernel-cmdline=bool (Set off to disable adding virtio-mmio devices to the kernel cmdline) + + +Boot options +~~~~~~~~~~~~ + +By default, microvm uses ``qboot`` as its BIOS, to obtain better boot +times, but it's also compatible with ``SeaBIOS``. + +As no current FW is able to boot from a block device using +``virtio-mmio`` as its transport, a microvm-based VM needs to be run +using a host-side kernel and, optionally, an initrd image. + + +Running a microvm-based VM +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, microvm aims for maximum compatibility, enabling both +legacy and non-legacy devices. In this example, a VM is created +without passing any additional machine-specific option, using the +legacy ``ISA serial`` device as console:: + + $ qemu-system-x86_64 -M microvm \ + -enable-kvm -cpu host -m 512m -smp 2 \ + -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \ + -nodefaults -no-user-config -nographic \ + -serial stdio \ + -drive id=test,file=test.img,format=raw,if=none \ + -device virtio-blk-device,drive=test \ + -netdev tap,id=tap0,script=no,downscript=no \ + -device virtio-net-device,netdev=tap0 + +While the example above works, you might be interested in reducing the +footprint further by disabling some legacy devices. If you're using +``KVM``, you can disable the ``RTC``, making the Guest rely on +``kvmclock`` exclusively. Additionally, if your host's CPUs have the +``TSC_DEADLINE`` feature, you can also disable both the i8259 PIC and +the i8254 PIT (make sure you're also emulating a CPU with such feature +in the guest). + +This is an example of a VM with all optional legacy features +disabled:: + + $ qemu-system-x86_64 \ + -M microvm,x-option-roms=off,pit=off,pic=off,isa-serial=off,rtc=off \ + -enable-kvm -cpu host -m 512m -smp 2 \ + -kernel vmlinux -append "console=hvc0 root=/dev/vda" \ + -nodefaults -no-user-config -nographic \ + -chardev stdio,id=virtiocon0 \ + -device virtio-serial-device \ + -device virtconsole,chardev=virtiocon0 \ + -drive id=test,file=test.img,format=raw,if=none \ + -device virtio-blk-device,drive=test \ + -netdev tap,id=tap0,script=no,downscript=no \ + -device virtio-net-device,netdev=tap0 + + +Triggering a guest-initiated shut down +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +As the microvm machine type includes just a small set of system +devices, some x86 mechanisms for rebooting or shutting down the +system, like sending a key sequence to the keyboard or writing to an +ACPI register, doesn't have any effect in the VM. + +The recommended way to trigger a guest-initiated shut down is by +generating a ``triple-fault``, which will cause the VM to initiate a +reboot. Additionally, if the ``-no-reboot`` argument is present in the +command line, QEMU will detect this event and terminate its own +execution gracefully. + +Linux does support this mechanism, but by default will only be used +after other options have been tried and failed, causing the reboot to +be delayed by a small number of seconds. It's possible to instruct it +to try the triple-fault mechanism first, by adding ``reboot=t`` to the +kernel's command line. diff --git a/docs/system/target-i386.rst b/docs/system/target-i386.rst index 1612ddb..22ba5ce 100644 --- a/docs/system/target-i386.rst +++ b/docs/system/target-i386.rst @@ -16,6 +16,7 @@ Board-specific documentation .. toctree:: :maxdepth: 1 + i386/microvm i386/pc .. include:: cpu-models-x86.rst.inc -- cgit v1.1 From 0daf34fd3a18aa2a43217c320e2a39d69e52d3f4 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:39 +0000 Subject: docs: Move pr-manager.rst into the system manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the pr-manager documentation into the system manual. Some of it (the documentation of the pr-manager-helper tool) should be in tools, but we will split it up after moving it. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/pr-manager.rst | 111 --------------------------------------------- docs/system/index.rst | 1 + docs/system/pr-manager.rst | 111 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 112 insertions(+), 111 deletions(-) delete mode 100644 docs/pr-manager.rst create mode 100644 docs/system/pr-manager.rst (limited to 'docs') diff --git a/docs/pr-manager.rst b/docs/pr-manager.rst deleted file mode 100644 index 9b1de19..0000000 --- a/docs/pr-manager.rst +++ /dev/null @@ -1,111 +0,0 @@ -====================================== -Persistent reservation managers -====================================== - -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. - -For this reason, QEMU's SCSI passthrough devices, ``scsi-block`` -and ``scsi-generic`` (both are only available on Linux) can delegate -implementation of persistent reservations to a separate object, -the "persistent reservation manager". Only PERSISTENT RESERVE OUT and -PERSISTENT RESERVE IN commands are passed to the persistent reservation -manager object; other commands are processed by QEMU as usual. - ------------------------------------------ -Defining a persistent reservation manager ------------------------------------------ - -A persistent reservation manager is an instance of a subclass of the -"pr-manager" QOM class. - -Right now only one subclass is defined, ``pr-manager-helper``, which -forwards the commands to an external privileged helper program -over Unix sockets. The helper program only allows sending persistent -reservation commands to devices for which QEMU has a file descriptor, -so that QEMU will not be able to effect persistent reservations -unless it has access to both the socket and the device. - -``pr-manager-helper`` has a single string property, ``path``, which -accepts the path to the helper program's Unix socket. For example, -the following command line defines a ``pr-manager-helper`` object and -attaches it to a SCSI passthrough device:: - - $ qemu-system-x86_64 - -device virtio-scsi \ - -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock - -drive if=none,id=hd,driver=raw,file.filename=/dev/sdb,file.pr-manager=helper0 - -device scsi-block,drive=hd - -Alternatively, using ``-blockdev``:: - - $ qemu-system-x86_64 - -device virtio-scsi \ - -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock - -blockdev node-name=hd,driver=raw,file.driver=host_device,file.filename=/dev/sdb,file.pr-manager=helper0 - -device scsi-block,drive=hd - ----------------------------------- -Invoking :program:`qemu-pr-helper` ----------------------------------- - -QEMU provides an implementation of the persistent reservation helper, -called :program:`qemu-pr-helper`. The helper should be started as a -system service and supports the following option: - --d, --daemon run in the background --q, --quiet decrease verbosity --v, --verbose increase verbosity --f, --pidfile=path PID file when running as a daemon --k, --socket=path path to the socket --T, --trace=trace-opts tracing options - -By default, the socket and PID file are placed in the runtime state -directory, for example :file:`/var/run/qemu-pr-helper.sock` and -:file:`/var/run/qemu-pr-helper.pid`. The PID file is not created -unless :option:`-d` is passed too. - -:program:`qemu-pr-helper` can also use the systemd socket activation -protocol. In this case, the systemd socket unit should specify a -Unix stream socket, like this:: - - [Socket] - ListenStream=/var/run/qemu-pr-helper.sock - -After connecting to the socket, :program:`qemu-pr-helper`` can optionally drop -root privileges, except for those capabilities that are needed for -its operation. To do this, add the following options: - --u, --user=user user to drop privileges to --g, --group=group group to drop privileges to - ---------------------------------------------- -Multipath devices and persistent reservations ---------------------------------------------- - -Proper support of persistent reservation for multipath devices requires -communication with the multipath daemon, so that the reservation is -registered and applied when a path is newly discovered or becomes online -again. :command:`qemu-pr-helper` can do this if the ``libmpathpersist`` -library was available on the system at build time. - -As of August 2017, a reservation key must be specified in ``multipath.conf`` -for ``multipathd`` to check for persistent reservation for newly -discovered paths or reinstated paths. The attribute can be added -to the ``defaults`` section or the ``multipaths`` section; for example:: - - multipaths { - multipath { - wwid XXXXXXXXXXXXXXXX - alias yellow - reservation_key 0x123abc - } - } - -Linking :program:`qemu-pr-helper` to ``libmpathpersist`` does not impede -its usage on regular SCSI devices. diff --git a/docs/system/index.rst b/docs/system/index.rst index 2a5155c..e5a3581 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -31,6 +31,7 @@ Contents: managed-startup cpu-hotplug virtio-pmem + pr-manager targets security deprecated diff --git a/docs/system/pr-manager.rst b/docs/system/pr-manager.rst new file mode 100644 index 0000000..9b1de19 --- /dev/null +++ b/docs/system/pr-manager.rst @@ -0,0 +1,111 @@ +====================================== +Persistent reservation managers +====================================== + +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. + +For this reason, QEMU's SCSI passthrough devices, ``scsi-block`` +and ``scsi-generic`` (both are only available on Linux) can delegate +implementation of persistent reservations to a separate object, +the "persistent reservation manager". Only PERSISTENT RESERVE OUT and +PERSISTENT RESERVE IN commands are passed to the persistent reservation +manager object; other commands are processed by QEMU as usual. + +----------------------------------------- +Defining a persistent reservation manager +----------------------------------------- + +A persistent reservation manager is an instance of a subclass of the +"pr-manager" QOM class. + +Right now only one subclass is defined, ``pr-manager-helper``, which +forwards the commands to an external privileged helper program +over Unix sockets. The helper program only allows sending persistent +reservation commands to devices for which QEMU has a file descriptor, +so that QEMU will not be able to effect persistent reservations +unless it has access to both the socket and the device. + +``pr-manager-helper`` has a single string property, ``path``, which +accepts the path to the helper program's Unix socket. For example, +the following command line defines a ``pr-manager-helper`` object and +attaches it to a SCSI passthrough device:: + + $ qemu-system-x86_64 + -device virtio-scsi \ + -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock + -drive if=none,id=hd,driver=raw,file.filename=/dev/sdb,file.pr-manager=helper0 + -device scsi-block,drive=hd + +Alternatively, using ``-blockdev``:: + + $ qemu-system-x86_64 + -device virtio-scsi \ + -object pr-manager-helper,id=helper0,path=/var/run/qemu-pr-helper.sock + -blockdev node-name=hd,driver=raw,file.driver=host_device,file.filename=/dev/sdb,file.pr-manager=helper0 + -device scsi-block,drive=hd + +---------------------------------- +Invoking :program:`qemu-pr-helper` +---------------------------------- + +QEMU provides an implementation of the persistent reservation helper, +called :program:`qemu-pr-helper`. The helper should be started as a +system service and supports the following option: + +-d, --daemon run in the background +-q, --quiet decrease verbosity +-v, --verbose increase verbosity +-f, --pidfile=path PID file when running as a daemon +-k, --socket=path path to the socket +-T, --trace=trace-opts tracing options + +By default, the socket and PID file are placed in the runtime state +directory, for example :file:`/var/run/qemu-pr-helper.sock` and +:file:`/var/run/qemu-pr-helper.pid`. The PID file is not created +unless :option:`-d` is passed too. + +:program:`qemu-pr-helper` can also use the systemd socket activation +protocol. In this case, the systemd socket unit should specify a +Unix stream socket, like this:: + + [Socket] + ListenStream=/var/run/qemu-pr-helper.sock + +After connecting to the socket, :program:`qemu-pr-helper`` can optionally drop +root privileges, except for those capabilities that are needed for +its operation. To do this, add the following options: + +-u, --user=user user to drop privileges to +-g, --group=group group to drop privileges to + +--------------------------------------------- +Multipath devices and persistent reservations +--------------------------------------------- + +Proper support of persistent reservation for multipath devices requires +communication with the multipath daemon, so that the reservation is +registered and applied when a path is newly discovered or becomes online +again. :command:`qemu-pr-helper` can do this if the ``libmpathpersist`` +library was available on the system at build time. + +As of August 2017, a reservation key must be specified in ``multipath.conf`` +for ``multipathd`` to check for persistent reservation for newly +discovered paths or reinstated paths. The attribute can be added +to the ``defaults`` section or the ``multipaths`` section; for example:: + + multipaths { + multipath { + wwid XXXXXXXXXXXXXXXX + alias yellow + reservation_key 0x123abc + } + } + +Linking :program:`qemu-pr-helper` to ``libmpathpersist`` does not impede +its usage on regular SCSI devices. -- cgit v1.1 From 773ee3f1ea50eb996cced930cc29b1b27bfbc6fa Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:40 +0000 Subject: docs: Split qemu-pr-helper documentation into tools manual MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the documentation of the qemu-pr-helper binary into the tools manual, and give it a manpage like our other standalone executables. Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/meson.build | 1 + docs/system/pr-manager.rst | 38 +++--------------- docs/tools/conf.py | 2 + docs/tools/index.rst | 1 + docs/tools/qemu-pr-helper.rst | 90 +++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 99 insertions(+), 33 deletions(-) create mode 100644 docs/tools/qemu-pr-helper.rst (limited to 'docs') diff --git a/docs/meson.build b/docs/meson.build index bf8204a..ebd85d5 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -60,6 +60,7 @@ if build_docs 'tools': { 'qemu-img.1': (have_tools ? 'man1' : ''), 'qemu-nbd.8': (have_tools ? 'man8' : ''), + 'qemu-pr-helper.8': (have_tools ? 'man8' : ''), 'qemu-trace-stap.1': (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''), 'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''), 'virtiofsd.1': (have_virtiofsd ? 'man1' : ''), diff --git a/docs/system/pr-manager.rst b/docs/system/pr-manager.rst index 9b1de19..3f5b9f9 100644 --- a/docs/system/pr-manager.rst +++ b/docs/system/pr-manager.rst @@ -50,39 +50,11 @@ Alternatively, using ``-blockdev``:: -blockdev node-name=hd,driver=raw,file.driver=host_device,file.filename=/dev/sdb,file.pr-manager=helper0 -device scsi-block,drive=hd ----------------------------------- -Invoking :program:`qemu-pr-helper` ----------------------------------- - -QEMU provides an implementation of the persistent reservation helper, -called :program:`qemu-pr-helper`. The helper should be started as a -system service and supports the following option: - --d, --daemon run in the background --q, --quiet decrease verbosity --v, --verbose increase verbosity --f, --pidfile=path PID file when running as a daemon --k, --socket=path path to the socket --T, --trace=trace-opts tracing options - -By default, the socket and PID file are placed in the runtime state -directory, for example :file:`/var/run/qemu-pr-helper.sock` and -:file:`/var/run/qemu-pr-helper.pid`. The PID file is not created -unless :option:`-d` is passed too. - -:program:`qemu-pr-helper` can also use the systemd socket activation -protocol. In this case, the systemd socket unit should specify a -Unix stream socket, like this:: - - [Socket] - ListenStream=/var/run/qemu-pr-helper.sock - -After connecting to the socket, :program:`qemu-pr-helper`` can optionally drop -root privileges, except for those capabilities that are needed for -its operation. To do this, add the following options: - --u, --user=user user to drop privileges to --g, --group=group group to drop privileges to +You will also need to ensure that the helper program +:command:`qemu-pr-helper` is running, and that it has been +set up to use the same socket filename as your QEMU commandline +specifies. See the qemu-pr-helper documentation or manpage for +further details. --------------------------------------------- Multipath devices and persistent reservations diff --git a/docs/tools/conf.py b/docs/tools/conf.py index 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 '], 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. -- cgit v1.1 From c6ff78563ad2971f289168c7cae6ecb0b4359516 Mon Sep 17 00:00:00 2001 From: Peter Maydell Date: Thu, 12 Nov 2020 14:40:41 +0000 Subject: docs/system/pr-manager.rst: Fix minor docs nits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix a couple of nits in pr-manager.rst: * the title marker for the top level heading is overlength * stray capital 'R' in the middle of a sentence Signed-off-by: Peter Maydell Reviewed-by: Alex Bennée --- docs/system/pr-manager.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'docs') diff --git a/docs/system/pr-manager.rst b/docs/system/pr-manager.rst index 3f5b9f9..b19a0c1 100644 --- a/docs/system/pr-manager.rst +++ b/docs/system/pr-manager.rst @@ -1,8 +1,8 @@ -====================================== +=============================== Persistent reservation managers -====================================== +=============================== -SCSI persistent Reservations allow restricting access to block devices +SCSI persistent reservations allow restricting access to block devices to specific initiators in a shared storage setup. When implementing clustering of virtual machines, it is a common requirement for virtual machines to send persistent reservation SCSI commands. However, -- cgit v1.1