On Fri, Sep 14, 2018 at 05:52:30PM +0400, Marc-André Lureau wrote:
As discussed during "[PATCH v4 00/29] vhost-user for input & GPU" review, let's define a common set of backend conventions to help with management layer implementation, and interoperability. v2: - drop --pidfile - add some notes about daemonizing & stdin/out/err Cc: libvir-list@xxxxxxxxxx Cc: Gerd Hoffmann <kraxel@xxxxxxxxxx> Cc: Daniel P. Berrangé <berrange@xxxxxxxxxx> Cc: Changpeng Liu <changpeng.liu@xxxxxxxxx> Cc: Dr. David Alan Gilbert <dgilbert@xxxxxxxxxx> Cc: Felipe Franciosi <felipe@xxxxxxxxxxx> Cc: Gonglei <arei.gonglei@xxxxxxxxxx> Cc: Maxime Coquelin <maxime.coquelin@xxxxxxxxxx> Cc: Michael S. Tsirkin <mst@xxxxxxxxxx> Cc: Victor Kaplansky <victork@xxxxxxxxxx> Signed-off-by: Marc-André Lureau <marcandre.lureau@xxxxxxxxxx> --- docs/interop/vhost-user.txt | 109 +++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 2 deletions(-) diff --git a/docs/interop/vhost-user.txt b/docs/interop/vhost-user.txt index ba5e37d714..339b335e9c 100644 --- a/docs/interop/vhost-user.txt +++ b/docs/interop/vhost-user.txt @@ -17,8 +17,13 @@ The protocol defines 2 sides of the communication, master and slave. Master is the application that shares its virtqueues, in our case QEMU. Slave is the consumer of the virtqueues. -In the current implementation QEMU is the Master, and the Slave is intended to -be a software Ethernet switch running in user space, such as Snabbswitch. +In the current implementation QEMU is the Master, and the Slave is the +external process consuming the virtio queues, for example a software +Ethernet switch running in user space, such as Snabbswitch, or a block +device backend processing read & write to a virtual disk. In order to +facilitate interoperability between various backend implementations, +it is recommended to follow the "Backend program conventions" +described in this document. Master and slave can be either a client (i.e. connecting) or server (listening) in the socket communication. @@ -859,3 +864,103 @@ resilient for selective requests. For the message types that already solicit a reply from the client, the presence of VHOST_USER_PROTOCOL_F_REPLY_ACK or need_reply bit being set brings no behavioural change. (See the 'Communication' section for details.) + +Backend program conventions +--------------------------- + +vhost-user backends provide various services and they may need to be +configured manually depending on the use case. However, it is a good +idea to follow the conventions listed here when possible. Users, QEMU +or libvirt, can then rely on some common behaviour to avoid +heterogenous configuration and management of the backend program and +facilitate interoperability. + +In order to be discoverable, default vhost-user backends should be +located under "/usr/libexec", and be named "vhost-user-$device" where +"$device" is the device name in lower-case following the name listed +in the Linux virtio_ids.h header (ex: the VIRTIO_ID_RPROC_SERIAL +backend would be named "vhost-user-rproc-serial"). + +Mechanisms to list, and to select among alternatives implementations +or modify the default backend are not described at this point (a +distribution may use update-alternatives, for example, to list and to +pick a different default backend). + +The backend program must not daemonize itself, but it may be +daemonized by the management layer. It may also have a restricted +access to the system. + +File descriptors 0, 1 and 2 will exist, and have regular +stdin/stdout/stderr usage (they may be redirected to /dev/null by the +management layer, or to a log handler). + +The backend program must end (as quickly and cleanly as possible) when +the SIGTERM signal is received. Eventually, it may be SIGKILL by the +management layer after a few seconds. + +The following command line options have an expected behaviour. They +are mandatory, unless explicitly said differently: + +* --socket-path=PATH + +This option specify the location of the vhost-user Unix domain socket.
Will the backend program listen on this socket or connect to it?
+It is incompatible with --fd. + +* --fd=FDNUM + +When this argument is given, the backend program is started with the +vhost-user socket as file descriptor FDNUM. It is incompatible with +--socket-path. + +* --print-capabilities + +Output to stdout a line-seperated list of backend capabilities, and +then exit successfully. Other options and arguments should be ignored, +and the backend program should not perform its normal function. + +At the time of writing, there are no common capabilities. Some +device-specific capabilities are listed in the respective sections. By +convention, device-specific capabilities are prefixed by their device +name.
Ideally, this would not be needed by libvirt. QEMU capability probing is nice to have when we need to provide a helpful error message (and avoid the lengthy preparation and cleanup in case it fails), but absolutely necessary if we need to supply different command line arguments to maintain the same functionality. I was really happy to be able to delete qemu-img help parsing when we dropped support for QEMU < 1.5.0 in upstream libvirt, see commit e5261d8fe382483a85b86bfad7ba1d28dc939687 So unless the helper's command line arguments get new meaning in new versions, libvirt can just pass on all the options requested in domain XML and expect the helper to fail if it cannot satisfy them. Jano
Attachment:
signature.asc
Description: PGP signature
-- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
