Hi On Fri, Oct 5, 2018 at 5:51 PM Ján Tomko <jtomko@xxxxxxxxxx> wrote: > > 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? Connect (if we ever need to support the listen mode, we can have another option) > > >+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. qemu-img is not exchangeable, and provides a fixed/growing set of functions. Here the goal is to allow vhost-user backend to be implemented by various parties, with various capabilities. For example, "virgl" support may not be implemented. This --print-capabilities is a simple way to check what the backend implements. All the capabilities currently have a corresponding program argument, which should be listed in --help. But it's not necessarily the case for all future capabilities (for example, migration, etc..) I agree that libvirt may not need to check the capabilities for now, and instead rely on a runtime/starting error. thanks -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
