diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/about/deprecated.rst | 6 | ||||
| -rw-r--r-- | docs/devel/nested-papr.txt | 119 | ||||
| -rw-r--r-- | docs/devel/tracing.rst | 3 | ||||
| -rw-r--r-- | docs/interop/vhost-user.rst | 4 | ||||
| -rw-r--r-- | docs/specs/pvpanic.rst | 2 | ||||
| -rw-r--r-- | docs/system/device-emulation.rst | 1 | ||||
| -rw-r--r-- | docs/system/devices/nvme.rst | 7 | ||||
| -rw-r--r-- | docs/system/devices/vdpa-net.rst | 121 | ||||
| -rw-r--r-- | docs/system/ppc/amigang.rst | 161 | ||||
| -rw-r--r-- | docs/system/target-ppc.rst | 1 |
10 files changed, 419 insertions, 6 deletions
diff --git a/docs/about/deprecated.rst b/docs/about/deprecated.rst index 4fb86608e4..7b548519b5 100644 --- a/docs/about/deprecated.rst +++ b/docs/about/deprecated.rst @@ -237,13 +237,13 @@ The Nios II architecture is orphan. The machine is no longer in existence and has been long unmaintained in QEMU. This also holds for the TC51828 16MiB flash that it uses. -``pseries-2.1`` up to ``pseries-2.11`` (since 9.0) +``pseries-2.1`` up to ``pseries-2.12`` (since 9.0) '''''''''''''''''''''''''''''''''''''''''''''''''' -Older pseries machines before version 2.12 have undergone many changes +Older pseries machines before version 3.0 have undergone many changes to correct issues, mostly regarding migration compatibility. These are no longer maintained and removing them will make the code easier to -read and maintain. Use versions 2.12 and above as a replacement. +read and maintain. Use versions 3.0 and above as a replacement. Arm machines ``akita``, ``borzoi``, ``cheetah``, ``connex``, ``mainstone``, ``n800``, ``n810``, ``spitz``, ``terrier``, ``tosa``, ``verdex``, ``z2`` (since 9.0) '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' diff --git a/docs/devel/nested-papr.txt b/docs/devel/nested-papr.txt new file mode 100644 index 0000000000..90943650db --- /dev/null +++ b/docs/devel/nested-papr.txt @@ -0,0 +1,119 @@ +Nested PAPR API (aka KVM on PowerVM) +==================================== + +This API aims at providing support to enable nested virtualization with +KVM on PowerVM. While the existing support for nested KVM on PowerNV was +introduced with cap-nested-hv option, however, with a slight design change, +to enable this on papr/pseries, a new cap-nested-papr option is added. eg: + + qemu-system-ppc64 -cpu POWER10 -machine pseries,cap-nested-papr=true ... + +Work by: + Michael Neuling <mikey@neuling.org> + Vaibhav Jain <vaibhav@linux.ibm.com> + Jordan Niethe <jniethe5@gmail.com> + Harsh Prateek Bora <harshpb@linux.ibm.com> + Shivaprasad G Bhat <sbhat@linux.ibm.com> + Kautuk Consul <kconsul@linux.vnet.ibm.com> + +Below taken from the kernel documentation: + +Introduction +============ + +This document explains how a guest operating system can act as a +hypervisor and run nested guests through the use of hypercalls, if the +hypervisor has implemented them. The terms L0, L1, and L2 are used to +refer to different software entities. L0 is the hypervisor mode entity +that would normally be called the "host" or "hypervisor". L1 is a +guest virtual machine that is directly run under L0 and is initiated +and controlled by L0. L2 is a guest virtual machine that is initiated +and controlled by L1 acting as a hypervisor. A significant design change +wrt existing API is that now the entire L2 state is maintained within L0. + +Existing Nested-HV API +====================== + +Linux/KVM has had support for Nesting as an L0 or L1 since 2018 + +The L0 code was added:: + + commit 8e3f5fc1045dc49fd175b978c5457f5f51e7a2ce + Author: Paul Mackerras <paulus@ozlabs.org> + Date: Mon Oct 8 16:31:03 2018 +1100 + KVM: PPC: Book3S HV: Framework and hcall stubs for nested virtualization + +The L1 code was added:: + + commit 360cae313702cdd0b90f82c261a8302fecef030a + Author: Paul Mackerras <paulus@ozlabs.org> + Date: Mon Oct 8 16:31:04 2018 +1100 + KVM: PPC: Book3S HV: Nested guest entry via hypercall + +This API works primarily using a signal hcall h_enter_nested(). This +call made by the L1 to tell the L0 to start an L2 vCPU with the given +state. The L0 then starts this L2 and runs until an L2 exit condition +is reached. Once the L2 exits, the state of the L2 is given back to +the L1 by the L0. The full L2 vCPU state is always transferred from +and to L1 when the L2 is run. The L0 doesn't keep any state on the L2 +vCPU (except in the short sequence in the L0 on L1 -> L2 entry and L2 +-> L1 exit). + +The only state kept by the L0 is the partition table. The L1 registers +it's partition table using the h_set_partition_table() hcall. All +other state held by the L0 about the L2s is cached state (such as +shadow page tables). + +The L1 may run any L2 or vCPU without first informing the L0. It +simply starts the vCPU using h_enter_nested(). The creation of L2s and +vCPUs is done implicitly whenever h_enter_nested() is called. + +In this document, we call this existing API the v1 API. + +New PAPR API +=============== + +The new PAPR API changes from the v1 API such that the creating L2 and +associated vCPUs is explicit. In this document, we call this the v2 +API. + +h_enter_nested() is replaced with H_GUEST_VCPU_RUN(). Before this can +be called the L1 must explicitly create the L2 using h_guest_create() +and any associated vCPUs() created with h_guest_create_vCPU(). Getting +and setting vCPU state can also be performed using h_guest_{g|s}et +hcall. + +The basic execution flow is for an L1 to create an L2, run it, and +delete it is: + +- L1 and L0 negotiate capabilities with H_GUEST_{G,S}ET_CAPABILITIES() + (normally at L1 boot time). + +- L1 requests the L0 to create an L2 with H_GUEST_CREATE() and receives a token + +- L1 requests the L0 to create an L2 vCPU with H_GUEST_CREATE_VCPU() + +- L1 and L0 communicate the vCPU state using the H_GUEST_{G,S}ET() hcall + +- L1 requests the L0 to run the vCPU using H_GUEST_RUN_VCPU() hcall + +- L1 deletes L2 with H_GUEST_DELETE() + +For more details, please refer: + +[1] Linux Kernel documentation (upstream documentation commit): + +commit 476652297f94a2e5e5ef29e734b0da37ade94110 +Author: Michael Neuling <mikey@neuling.org> +Date: Thu Sep 14 13:06:00 2023 +1000 + + docs: powerpc: Document nested KVM on POWER + + Document support for nested KVM on POWER using the existing API as well + as the new PAPR API. This includes the new HCALL interface and how it + used by KVM. + + Signed-off-by: Michael Neuling <mikey@neuling.org> + Signed-off-by: Jordan Niethe <jniethe5@gmail.com> + Signed-off-by: Michael Ellerman <mpe@ellerman.id.au> + Link: https://msgid.link/20230914030600.16993-12-jniethe5@gmail.com diff --git a/docs/devel/tracing.rst b/docs/devel/tracing.rst index d288480db1..043bed7fd0 100644 --- a/docs/devel/tracing.rst +++ b/docs/devel/tracing.rst @@ -357,8 +357,7 @@ probes:: scripts/tracetool.py --backends=dtrace --format=stap \ --binary path/to/qemu-binary \ - --target-type system \ - --target-name x86_64 \ + --probe-prefix qemu.system.x86_64 \ --group=all \ trace-events-all \ qemu.stp diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index d1ed39dfa0..d8419fd2f1 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -1839,7 +1839,9 @@ is sent by the front-end. When the ``VHOST_USER_PROTOCOL_F_SHARED_OBJECT`` protocol feature has been successfully negotiated, this message can be submitted by the backend to remove themselves from to the virtio-dmabuf shared - table API. The shared table will remove the back-end device associated with + table API. Only the back-end owning the entry (i.e., the one that first added + it) will have permission to remove it. Otherwise, the message is ignored. + The shared table will remove the back-end device associated with the UUID. If ``VHOST_USER_PROTOCOL_F_REPLY_ACK`` is negotiated, and the back-end sets the ``VHOST_USER_NEED_REPLY`` flag, the front-end must respond with zero when operation is successfully completed, or non-zero otherwise. diff --git a/docs/specs/pvpanic.rst b/docs/specs/pvpanic.rst index f894bc1955..61a80480ed 100644 --- a/docs/specs/pvpanic.rst +++ b/docs/specs/pvpanic.rst @@ -29,6 +29,8 @@ bit 1 a guest panic has happened and will be handled by the guest; the host should record it or report it, but should not affect the execution of the guest. +bit 2 + a regular guest shutdown has happened and should be processed by the host PCI Interface ------------- diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst index f19777411c..e4a27f53c8 100644 --- a/docs/system/device-emulation.rst +++ b/docs/system/device-emulation.rst @@ -99,3 +99,4 @@ Emulated Devices devices/canokey.rst devices/usb-u2f.rst devices/igb.rst + devices/vdpa-net.rst diff --git a/docs/system/devices/nvme.rst b/docs/system/devices/nvme.rst index 4ea957baed..d2b1ca9645 100644 --- a/docs/system/devices/nvme.rst +++ b/docs/system/devices/nvme.rst @@ -81,6 +81,13 @@ There are a number of parameters available: Set the UUID of the namespace. This will be reported as a "Namespace UUID" descriptor in the Namespace Identification Descriptor List. +``nguid`` + Set the NGUID of the namespace. This will be reported as a "Namespace Globally + Unique Identifier" descriptor in the Namespace Identification Descriptor List. + It is specified as a string of hexadecimal digits containing exactly 16 bytes + or "auto" for a random value. An optional '-' separator could be used to group + bytes. If not specified the NGUID will remain all zeros. + ``eui64`` Set the EUI-64 of the namespace. This will be reported as a "IEEE Extended Unique Identifier" descriptor in the Namespace Identification Descriptor List. diff --git a/docs/system/devices/vdpa-net.rst b/docs/system/devices/vdpa-net.rst new file mode 100644 index 0000000000..323d8c926a --- /dev/null +++ b/docs/system/devices/vdpa-net.rst @@ -0,0 +1,121 @@ +vdpa net +============ + +This document explains the setup and usage of the vdpa network device. +The vdpa network device is a paravirtualized vdpa emulate device. + +Description +----------- + +VDPA net devices support dirty page bitmap mark and vring state saving and recovery. + +Users can use this VDPA device for live migration simulation testing in a nested virtualization environment. + +Registers layout +---------------- + +The vdpa device add live migrate registers layout as follow:: + + Offset Register Name Bitwidth Associated vq + 0x0 LM_LOGGING_CTRL 4bits + 0x10 LM_BASE_ADDR_LOW 32bits + 0x14 LM_BASE_ADDR_HIGH 32bits + 0x18 LM_END_ADDR_LOW 32bits + 0x1c LM_END_ADDR_HIGH 32bits + 0x20 LM_RING_STATE_OFFSET 32bits vq0 + 0x24 LM_RING_STATE_OFFSET 32bits vq1 + 0x28 LM_RING_STATE_OFFSET 32bits vq2 + ...... + 0x20+1023*4 LM_RING_STATE_OFFSET 32bits vq1023 + +These registers are extended at the end of the notify bar space. + +Architecture diagram +-------------------- +:: + + |------------------------------------------------------------------------| + | guest-L1-user-space | + | | + | |----------------------------------------| + | | [virtio-net driver] | + | | ^ guest-L2-src(iommu=on) | + | |--------------|-------------------------| + | | | qemu-L2-src(viommu) | + | [dpdk-vdpa]<->[vhost socket]<-+->[vhost-user backend(iommu=on)] | + -------------------------------------------------------------------------- + -------------------------------------------------------------------------- + | ^ guest-L1-kernel-space | + | | | + | [VFIO] | + | ^ | + | | guest-L1-src(iommu=on) | + --------|----------------------------------------------------------------- + --------|----------------------------------------------------------------- + | [vdpa net device(iommu=on)] [manager nic device] | + | | | | + | | | | + | [tap device] qemu-L1-src(viommu) | | + ------------------------------------------------+------------------------- + | + | + --------------------- | + | kernel net bridge |<----- + | virbr0 |<---------------------------------- + --------------------- | + | + | + -------------------------------------------------------------------------- | + | guest-L1-user-space | | + | | | + | |----------------------------------------| | + | | [virtio-net driver] | | + | | ^ guest-L2-dst(iommu=on) | | + | |--------------|-------------------------| | + | | | qemu-L2-dst(viommu) | | + | [dpdk-vdpa]<->[vhost socket]<-+->[vhost-user backend(iommu=on)] | | + -------------------------------------------------------------------------- | + -------------------------------------------------------------------------- | + | ^ guest-L1-kernel-space | | + | | | | + | [VFIO] | | + | ^ | | + | | guest-L1-dst(iommu=on) | | + --------|----------------------------------------------------------------- | + --------|----------------------------------------------------------------- | + | [vdpa net device(iommu=on)] [manager nic device]----------------+---- + | | | + | | | + | [tap device] qemu-L1-dst(viommu) | + -------------------------------------------------------------------------- + + +Device properties +----------------- + +The Virtio vdpa device can be configured with the following properties: + + * ``vdpa=on`` open vdpa device emulated. + +Usages +-------- +This patch add virtio sriov support and vdpa live migrate support. +You can open vdpa by set xml file as follow:: + + <qemu:commandline xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'> + <qemu:arg value='-device'/> + <qemu:arg value='intel-iommu,intremap=on,device-iotlb=on,aw-bits=48'/> + <qemu:arg value='-netdev'/> + <qemu:arg value='tap,id=hostnet1,script=no,downscript=no,vhost=off'/> + <qemu:arg value='-device'/> + <qemu:arg value='virtio-net-pci,netdev=hostnet1,id=net1,mac=56:4a:b7:4f:4d:a9,bus=pci.6,addr=0x0,iommu_platform=on,ats=on,vdpa=on'/> + </qemu:commandline> + +Limitations +----------- +1. Dependent on tap device with param ``vhost=off``. +2. Nested virtualization environment only supports ``q35`` machines. +3. Current only support split vring live migrate. + + + diff --git a/docs/system/ppc/amigang.rst b/docs/system/ppc/amigang.rst new file mode 100644 index 0000000000..ba1a3d80b9 --- /dev/null +++ b/docs/system/ppc/amigang.rst @@ -0,0 +1,161 @@ +========================================================= +AmigaNG boards (``amigaone``, ``pegasos2``, ``sam460ex``) +========================================================= + +These PowerPC machines emulate boards that are primarily used for +running Amiga like OSes (AmigaOS 4, MorphOS and AROS) but these can +also run Linux which is what this section documents. + +Eyetech AmigaOne/Mai Logic Teron (``amigaone``) +=============================================== + +The ``amigaone`` machine emulates an AmigaOne XE mainboard by Eyetech +which is a rebranded Mai Logic Teron board with modified U-Boot +firmware to support AmigaOS 4. + +Emulated devices +---------------- + + * PowerPC 7457 CPU (can also use``-cpu g3, 750cxe, 750fx`` or ``750gx``) + * Articia S north bridge + * VIA VT82C686B south bridge + * PCI VGA compatible card (guests may need other card instead) + * PS/2 keyboard and mouse + +Firmware +-------- + +A firmware binary is necessary for the boot process. It is a modified +U-Boot under GPL but its source is lost so it cannot be included in +QEMU. A binary is available at +https://www.hyperion-entertainment.com/index.php/downloads?view=files&parent=28. +The ROM image is in the last 512kB which can be extracted with the +following command: + +.. code-block:: bash + + $ tail -c 524288 updater.image > u-boot-amigaone.bin + +The BIOS emulator in the firmware is unable to run QEMU‘s standard +vgabios so ``VGABIOS-lgpl-latest.bin`` is needed instead which can be +downloaded from http://www.nongnu.org/vgabios. + +Running Linux +------------- + +There are some Linux images under the following link that work on the +``amigaone`` machine: +https://sourceforge.net/projects/amigaone-linux/files/debian-installer/. +To boot the system run: + +.. code-block:: bash + + $ qemu-system-ppc -machine amigaone -bios u-boot-amigaone.bin \ + -cdrom "A1 Linux Net Installer.iso" \ + -device ati-vga,model=rv100,romfile=VGABIOS-lgpl-latest.bin + +From the firmware menu that appears select ``Boot sequence`` → +``Amiga Multiboot Options`` and set ``Boot device 1`` to +``Onboard VIA IDE CDROM``. Then hit escape until the main screen appears again, +hit escape once more and from the exit menu that appears select either +``Save settings and exit`` or ``Use settings for this session only``. It may +take a long time loading the kernel into memory but eventually it boots and the +installer becomes visible. The ``ati-vga`` RV100 emulation is not +complete yet so only frame buffer works, DRM and 3D is not available. + +Genesi/bPlan Pegasos II (``pegasos2``) +====================================== + +The ``pegasos2`` machine emulates the Pegasos II sold by Genesi and +designed by bPlan. Its schematics are available at +https://www.powerdeveloper.org/platforms/pegasos/schematics. + +Emulated devices +---------------- + + * PowerPC 7457 CPU (can also use``-cpu g3`` or ``750cxe``) + * Marvell MV64361 Discovery II north bridge + * VIA VT8231 south bridge + * PCI VGA compatible card (guests may need other card instead) + * PS/2 keyboard and mouse + +Firmware +-------- + +The Pegasos II board has an Open Firmware compliant ROM based on +SmartFirmware with some changes that are not open-sourced therefore +the ROM binary cannot be included in QEMU. An updater was available +from bPlan, it can be found in the `Internet Archive +<http://web.archive.org/web/20071021223056/http://www.bplan-gmbh.de/up050404/up050404>`_. +The ROM image can be extracted from it with the following command: + +.. code-block:: bash + + $ tail -c +85581 up050404 | head -c 524288 > pegasos2.rom + +Running Linux +------------- + +The PowerPC version of Debian 8.11 supported Pegasos II. The BIOS +emulator in the firmware binary is unable to run QEMU‘s standard +vgabios so it needs to be disabled. To boot the system run: + +.. code-block:: bash + + $ qemu-system-ppc -machine pegasos2 -bios pegasos2.rom \ + -cdrom debian-8.11.0-powerpc-netinst.iso \ + -device VGA,romfile="" -serial stdio + +At the firmware ``ok`` prompt enter ``boot cd install/pegasos``. + +Alternatively, it is possible to boot the kernel directly without +firmware ROM using the QEMU built-in minimal Virtual Open Firmware +(VOF) emulation which is also supported on ``pegasos2``. For this, +extract the kernel ``install/powerpc/vmlinuz-chrp.initrd`` from the CD +image, then run: + +.. code-block:: bash + + $ qemu-system-ppc -machine pegasos2 -serial stdio \ + -kernel vmlinuz-chrp.initrd -append "---" \ + -cdrom debian-8.11.0-powerpc-netinst.iso + +aCube Sam460ex (``sam460ex``) +============================= + +The ``sam460ex`` machine emulates the Sam460ex board by aCube which is +based on the AMCC PowerPC 460EX SoC (that despite its name has a +PPC440 CPU core). + +Firmware +-------- + +The board has a firmware based on an older U-Boot version with +modifications to support booting AmigaOS 4. The firmware ROM is +included with QEMU. + +Emulated devices +---------------- + + * PowerPC 460EX SoC + * M41T80 serial RTC chip + * Silicon Motion SM501 display parts (identical to SM502 on real board) + * Silicon Image SiI3112 2 port SATA controller + * USB keyboard and mouse + +Running Linux +------------- + +The only Linux distro that supported Sam460ex out of box was CruxPPC +2.x. It can be booted by running: + +.. code-block:: bash + + $ qemu-system-ppc -machine sam460ex -serial stdio \ + -drive if=none,id=cd,format=raw,file=crux-ppc-2.7a.iso \ + -device ide-cd,drive=cd,bus=ide.1 + +There are some other kernels and instructions for booting other +distros on aCube's product page at +https://www.acube-systems.biz/index.php?page=hardware&pid=5 +but those are untested. diff --git a/docs/system/target-ppc.rst b/docs/system/target-ppc.rst index 4f6eb93b17..87bf412ce5 100644 --- a/docs/system/target-ppc.rst +++ b/docs/system/target-ppc.rst @@ -17,6 +17,7 @@ help``. .. toctree:: :maxdepth: 1 + ppc/amigang ppc/embedded ppc/powermac ppc/powernv |