4e647fa085
shm_open() creates and opens a new POSIX shared memory object. A POSIX shared memory object allows creating memory backend with an associated file descriptor that can be shared with external processes (e.g. vhost-user). The new `memory-backend-shm` can be used as an alternative when `memory-backend-memfd` is not available (Linux only), since shm_open() should be provided by any POSIX-compliant operating system. This backend mimics memfd, allocating memory that is practically anonymous. In theory shm_open() requires a name, but this is allocated for a short time interval and shm_unlink() is called right after shm_open(). After that, only fd is shared with external processes (e.g., vhost-user) as if it were associated with anonymous memory. In the future we may also allow the user to specify the name to be passed to shm_open(), but for now we keep the backend simple, mimicking anonymous memory such as memfd. Acked-by: David Hildenbrand <david@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> (QAPI schema) Signed-off-by: Stefano Garzarella <sgarzare@redhat.com> Message-Id: <20240618100519.145853-1-sgarzare@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com>
131 lines
3.8 KiB
ReStructuredText
131 lines
3.8 KiB
ReStructuredText
.. _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*.
|
|
|
|
Each device will have an virtio-mmio and virtio-pci variant. See your
|
|
platform details for what sort of virtio bus to use.
|
|
|
|
.. list-table:: vhost-user devices
|
|
:widths: 20 20 60
|
|
:header-rows: 1
|
|
|
|
* - Device
|
|
- Type
|
|
- Notes
|
|
* - vhost-user-blk
|
|
- Block storage
|
|
- See contrib/vhost-user-blk
|
|
* - vhost-user-fs
|
|
- File based storage driver
|
|
- See https://gitlab.com/virtio-fs/virtiofsd
|
|
* - vhost-user-gpio
|
|
- Proxy gpio pins to host
|
|
- See https://github.com/rust-vmm/vhost-device
|
|
* - vhost-user-gpu
|
|
- GPU driver
|
|
- See contrib/vhost-user-gpu
|
|
* - vhost-user-i2c
|
|
- Proxy i2c devices to host
|
|
- See https://github.com/rust-vmm/vhost-device
|
|
* - vhost-user-input
|
|
- Generic input driver
|
|
- :ref:`vhost_user_input`
|
|
* - vhost-user-rng
|
|
- Entropy driver
|
|
- :ref:`vhost_user_rng`
|
|
* - vhost-user-scmi
|
|
- System Control and Management Interface
|
|
- See https://github.com/rust-vmm/vhost-device
|
|
* - vhost-user-snd
|
|
- Audio device
|
|
- See https://github.com/rust-vmm/vhost-device/staging
|
|
* - vhost-user-scsi
|
|
- SCSI based storage
|
|
- See contrib/vhost-user-scsi
|
|
* - vhost-user-vsock
|
|
- Socket based communication
|
|
- See https://github.com/rust-vmm/vhost-device
|
|
|
|
The referenced *daemons* are not exhaustive, any conforming backend
|
|
implementing the device and using the vhost-user protocol should work.
|
|
|
|
vhost-user-device
|
|
^^^^^^^^^^^^^^^^^
|
|
|
|
The vhost-user-device is a generic development device intended for
|
|
expert use while developing new backends. The user needs to specify
|
|
all the required parameters including:
|
|
|
|
- Device ``virtio-id``
|
|
- The ``num_vqs`` it needs and their ``vq_size``
|
|
- The ``config_size`` if needed
|
|
|
|
.. note::
|
|
To prevent user confusion you cannot currently instantiate
|
|
vhost-user-device without first patching out::
|
|
|
|
/* Reason: stop inexperienced users confusing themselves */
|
|
dc->user_creatable = false;
|
|
|
|
in ``vhost-user-device.c`` and ``vhost-user-device-pci.c`` file and
|
|
rebuilding.
|
|
|
|
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:
|
|
|
|
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``, ``memory-backend-memfd``, or
|
|
``memory-backend-shm`` 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 your daemon.
|
|
|
|
.. parsed-literal::
|
|
|
|
$ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS
|
|
|
|
Then 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 \\
|
|
...
|
|
|