From nobody Sat Sep 21 00:57:46 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) client-ip=208.118.235.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of gnu.org designates 208.118.235.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (208.118.235.17 [208.118.235.17]) by mx.zohomail.com with SMTPS id 15369332611301019.9339239355184; Fri, 14 Sep 2018 06:54:21 -0700 (PDT) Received: from localhost ([::1]:51840 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g0oXy-0000rx-GS for importer@patchew.org; Fri, 14 Sep 2018 09:54:10 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:34052) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1g0oX0-0000aY-AK for qemu-devel@nongnu.org; Fri, 14 Sep 2018 09:53:11 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1g0oWw-0000xy-Um for qemu-devel@nongnu.org; Fri, 14 Sep 2018 09:53:10 -0400 Received: from mx1.redhat.com ([209.132.183.28]:38488) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1g0oWw-0000sF-MM for qemu-devel@nongnu.org; Fri, 14 Sep 2018 09:53:06 -0400 Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id D279B32B669; Fri, 14 Sep 2018 13:52:59 +0000 (UTC) Received: from localhost (ovpn-112-33.ams2.redhat.com [10.36.112.33]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9985A1A91A; Fri, 14 Sep 2018 13:52:36 +0000 (UTC) From: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= To: qemu-devel@nongnu.org Date: Fri, 14 Sep 2018 17:52:30 +0400 Message-Id: <20180914135230.15178-1-marcandre.lureau@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.38]); Fri, 14 Sep 2018 13:53:04 +0000 (UTC) Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.132.183.28 Subject: [Qemu-devel] [PATCH v2] vhost-user: define conventions for vhost-user backends X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Victor Kaplansky , "Michael S . Tsirkin" , libvir-list@redhat.com, "Dr . David Alan Gilbert" , Maxime Coquelin , Gonglei , Gerd Hoffmann , Felipe Franciosi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Changpeng Liu Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail: RDMRC_1 RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" 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@redhat.com Cc: Gerd Hoffmann Cc: Daniel P. Berrang=C3=A9 Cc: Changpeng Liu Cc: Dr. David Alan Gilbert Cc: Felipe Franciosi Cc: Gonglei Cc: Maxime Coquelin Cc: Michael S. Tsirkin Cc: Victor Kaplansky Signed-off-by: Marc-Andr=C3=A9 Lureau --- 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, maste= r and slave. Master is the application that shares its virtqueues, in our case QEMU. Slave is the consumer of the virtqueues. =20 -In the current implementation QEMU is the Master, and the Slave is intende= d 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. =20 Master and slave can be either a client (i.e. connecting) or server (liste= ning) 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 br= ings 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=3DPATH + +This option specify the location of the vhost-user Unix domain socket. +It is incompatible with --fd. + +* --fd=3DFDNUM + +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. + +vhost-user-input program conventions +------------------------------------ + +Capabilities: + +input-evdev-path + + The --evdev-path command line option is supported. + +input-no-grab + + The --no-grab command line option is supported. + +* --evdev-path=3DPATH (optional) + +Specify the linux input device. + +* --no-grab (optional) + +Do no request exclusive access to the input device. + +vhost-user-gpu program conventions +---------------------------------- + +Capabilities: + +gpu-render-node + + The --render-node command line option is supported. + +gpu-virgl + + The --virgl command line option is supported. + +* --render-node=3DPATH (optional) + +Specify the GPU DRM render node. + +* --virgl (optional) + +Enable virgl rendering support. --=20 2.19.0