diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/interop/vhost-user.rst | 2 | ||||
| -rw-r--r-- | docs/system/device-emulation.rst | 90 | ||||
| -rw-r--r-- | docs/system/devices/ivshmem.rst (renamed from docs/system/ivshmem.rst) | 0 | ||||
| -rw-r--r-- | docs/system/devices/net.rst (renamed from docs/system/net.rst) | 0 | ||||
| -rw-r--r-- | docs/system/devices/nvme.rst (renamed from docs/system/nvme.rst) | 0 | ||||
| -rw-r--r-- | docs/system/devices/usb.rst (renamed from docs/system/usb.rst) | 0 | ||||
| -rw-r--r-- | docs/system/devices/vhost-user.rst | 59 | ||||
| -rw-r--r-- | docs/system/devices/virtio-pmem.rst (renamed from docs/system/virtio-pmem.rst) | 0 | ||||
| -rw-r--r-- | docs/system/index.rst | 6 |
9 files changed, 152 insertions, 5 deletions
diff --git a/docs/interop/vhost-user.rst b/docs/interop/vhost-user.rst index d6085f7045..7fc693521e 100644 --- a/docs/interop/vhost-user.rst +++ b/docs/interop/vhost-user.rst @@ -1,3 +1,5 @@ +.. _vhost_user_proto: + =================== Vhost-user Protocol =================== diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst new file mode 100644 index 0000000000..7afcfd8064 --- /dev/null +++ b/docs/system/device-emulation.rst @@ -0,0 +1,90 @@ +.. _device-emulation: + +Device Emulation +---------------- + +QEMU supports the emulation of a large number of devices from +peripherals such network cards and USB devices to integrated systems +on a chip (SoCs). Configuration of these is often a source of +confusion so it helps to have an understanding of some of the terms +used to describes devices within QEMU. + +Common Terms +~~~~~~~~~~~~ + +Device Front End +================ + +A device front end is how a device is presented to the guest. The type +of device presented should match the hardware that the guest operating +system is expecting to see. All devices can be specified with the +``--device`` command line option. Running QEMU with the command line +options ``--device help`` will list all devices it is aware of. Using +the command line ``--device foo,help`` will list the additional +configuration options available for that device. + +A front end is often paired with a back end, which describes how the +host's resources are used in the emulation. + +Device Buses +============ + +Most devices will exist on a BUS of some sort. Depending on the +machine model you choose (``-M foo``) a number of buses will have been +automatically created. In most cases the BUS a device is attached to +can be inferred, for example PCI devices are generally automatically +allocated to the next free address of first PCI bus found. However in +complicated configurations you can explicitly specify what bus +(``bus=ID``) a device is attached to along with its address +(``addr=N``). + +Some devices, for example a PCI SCSI host controller, will add an +additional buses to the system that other devices can be attached to. +A hypothetical chain of devices might look like: + + --device foo,bus=pci.0,addr=0,id=foo + --device bar,bus=foo.0,addr=1,id=baz + +which would be a bar device (with the ID of baz) which is attached to +the first foo bus (foo.0) at address 1. The foo device which provides +that bus is itself is attached to the first PCI bus (pci.0). + + +Device Back End +=============== + +The back end describes how the data from the emulated device will be +processed by QEMU. The configuration of the back end is usually +specific to the class of device being emulated. For example serial +devices will be backed by a ``--chardev`` which can redirect the data +to a file or socket or some other system. Storage devices are handled +by ``--blockdev`` which will specify how blocks are handled, for +example being stored in a qcow2 file or accessing a raw host disk +partition. Back ends can sometimes be stacked to implement features +like snapshots. + +While the choice of back end is generally transparent to the guest, +there are cases where features will not be reported to the guest if +the back end is unable to support it. + +Device Pass Through +=================== + +Device pass through is where the device is actually given access to +the underlying hardware. This can be as simple as exposing a single +USB device on the host system to the guest or dedicating a video card +in a PCI slot to the exclusive use of the guest. + + +Emulated Devices +~~~~~~~~~~~~~~~~ + +.. toctree:: + :maxdepth: 1 + + devices/ivshmem.rst + devices/net.rst + devices/nvme.rst + devices/usb.rst + devices/vhost-user.rst + devices/virtio-pmem.rst diff --git a/docs/system/ivshmem.rst b/docs/system/devices/ivshmem.rst index b03a48afa3..b03a48afa3 100644 --- a/docs/system/ivshmem.rst +++ b/docs/system/devices/ivshmem.rst diff --git a/docs/system/net.rst b/docs/system/devices/net.rst index 4b2640c448..4b2640c448 100644 --- a/docs/system/net.rst +++ b/docs/system/devices/net.rst diff --git a/docs/system/nvme.rst b/docs/system/devices/nvme.rst index bff72d1c24..bff72d1c24 100644 --- a/docs/system/nvme.rst +++ b/docs/system/devices/nvme.rst diff --git a/docs/system/usb.rst b/docs/system/devices/usb.rst index eeab78dcfb..eeab78dcfb 100644 --- a/docs/system/usb.rst +++ b/docs/system/devices/usb.rst diff --git a/docs/system/devices/vhost-user.rst b/docs/system/devices/vhost-user.rst new file mode 100644 index 0000000000..86128114fa --- /dev/null +++ b/docs/system/devices/vhost-user.rst @@ -0,0 +1,59 @@ +.. _vhost_user: + +vhost-user back ends +-------------------- + +vhost-user back ends are way to service the request of VirtIO devices +outside of QEMU itself. To do this there are a number of things +required. + +vhost-user device +=================== + +These are simple stub devices that ensure the VirtIO device is visible +to the guest. The code is mostly boilerplate although each device has +a ``chardev`` option which specifies the ID of the ``--chardev`` +device that connects via a socket to the vhost-user *daemon*. + +vhost-user daemon +================= + +This is a separate process that is connected to by QEMU via a socket +following the :ref:`vhost_user_proto`. There are a number of daemons +that can be built when enabled by the project although any daemon that +meets the specification for a given device can be used. + +Shared memory object +==================== + +In order for the daemon to access the VirtIO queues to process the +requests it needs access to the guest's address space. This is +achieved via the ``memory-backend-file`` or ``memory-backend-memfd`` +objects. A reference to a file-descriptor which can access this object +will be passed via the socket as part of the protocol negotiation. + +Currently the shared memory object needs to match the size of the main +system memory as defined by the ``-m`` argument. + +Example +======= + +First start you daemon. + +.. parsed-literal:: + + $ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS + +The you start your QEMU instance specifying the device, chardev and +memory objects. + +.. parsed-literal:: + + $ |qemu_system| \\ + -m 4096 \\ + -chardev socket,id=ba1,path=/var/run/foo.sock \\ + -device vhost-user-foo,chardev=ba1,$OTHER_ARGS \\ + -object memory-backend-memfd,id=mem,size=4G,share=on \\ + -numa node,memdev=mem \\ + ... + diff --git a/docs/system/virtio-pmem.rst b/docs/system/devices/virtio-pmem.rst index c82ac06731..c82ac06731 100644 --- a/docs/system/virtio-pmem.rst +++ b/docs/system/devices/virtio-pmem.rst diff --git a/docs/system/index.rst b/docs/system/index.rst index fda4b1b705..64a424ae99 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -11,15 +11,12 @@ or Hypervisor.Framework. quickstart invocation + device-emulation keys mux-chardev monitor images - net virtio-net-failover - usb - nvme - ivshmem linuxboot generic-loader guest-loader @@ -30,7 +27,6 @@ or Hypervisor.Framework. gdb managed-startup cpu-hotplug - virtio-pmem pr-manager targets security |