From nobody Sun Nov 9 19:13:09 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.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 209.51.188.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 (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1551701285999565.0623115267003; Mon, 4 Mar 2019 04:08:05 -0800 (PST) Received: from localhost ([127.0.0.1]:52761 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h0mO2-00040M-0F for importer@patchew.org; Mon, 04 Mar 2019 07:08:02 -0500 Received: from eggs.gnu.org ([209.51.188.92]:46218) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h0mIm-0008QW-Nm for qemu-devel@nongnu.org; Mon, 04 Mar 2019 07:02:38 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h0mIl-0008Sm-5o for qemu-devel@nongnu.org; Mon, 04 Mar 2019 07:02:36 -0500 Received: from mx1.redhat.com ([209.132.183.28]:45004) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1h0mIk-0008JN-Jw; Mon, 04 Mar 2019 07:02:34 -0500 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 4FBCFC057F2D; Mon, 4 Mar 2019 12:02:31 +0000 (UTC) Received: from localhost (ovpn-116-85.ams2.redhat.com [10.36.116.85]) by smtp.corp.redhat.com (Postfix) with ESMTPS id DD93E6013F; Mon, 4 Mar 2019 12:02:30 +0000 (UTC) From: Cornelia Huck To: Peter Maydell Date: Mon, 4 Mar 2019 13:01:48 +0100 Message-Id: <20190304120210.31500-6-cohuck@redhat.com> In-Reply-To: <20190304120210.31500-1-cohuck@redhat.com> References: <20190304120210.31500-1-cohuck@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.32]); Mon, 04 Mar 2019 12:02:31 +0000 (UTC) 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] [PULL 05/27] s390x/vfio-ap: document hot plug/unplug of vfio-ap device 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: Tony Krowiak , qemu-s390x@nongnu.org, Cornelia Huck , qemu-devel@nongnu.org Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" From: Tony Krowiak Let's update the vfio-ap.txt document to include the hot plug/unplug support. Signed-off-by: Tony Krowiak Message-Id: <1550519397-25359-3-git-send-email-akrowiak@linux.ibm.com> Signed-off-by: Cornelia Huck --- docs/vfio-ap.txt | 61 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/docs/vfio-ap.txt b/docs/vfio-ap.txt index 12339684cd52..8cd060a01e10 100644 --- a/docs/vfio-ap.txt +++ b/docs/vfio-ap.txt @@ -440,8 +440,7 @@ unassign_control_domain 'unassign_domain' file. This may be done multiple times to unassign mor= e than one control domain. =20 -Notes: Hot plug/unplug is not currently supported for mediated AP matrix -devices, so no changes to the AP matrix will be allowed while a guest using +Notes: No changes to the AP matrix will be allowed while a guest using the mediated matrix device is running. Attempts to assign an adapter, domain or control domain will be rejected and an error (EBUSY) returned. =20 @@ -562,6 +561,54 @@ facilities: for guest usage, no AP devices can be made accessible= to a guest started without APFT installed. =20 +Hot plug a vfio-ap device into a running guest: +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +Only one vfio-ap device can be attached to the virtual machine's ap-bus, s= o a +vfio-ap device can be hot plugged if and only if no vfio-ap device is atta= ched +to the bus already, whether via the QEMU command line or a prior hot plug +action. + +To hot plug a vfio-ap device, use the QEMU device_add command: + + (qemu) device_add vfio-ap,sysfsdev=3D"$path-to-mdev" + + Where the '$path-to-mdev' value specifies the absolute path to a media= ted + device to which AP resources to be used by the guest have been assigne= d. + +Note that on Linux guests, the AP devices will be created in the +/sys/bus/ap/devices directory when the AP bus subsequently performs its pe= riodic +scan, so there may be a short delay before the AP devices are accessible o= n the +guest. + +The command will fail if: + +* A vfio-ap device has already been attached to the virtual machine's ap-b= us. + +* The CPU model features for controlling guest access to AP facilities are= not + enabled (see 'CPU model features' subsection in the previous section). + +Hot unplug a vfio-ap device from a running guest: +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D +A vfio-ap device can be unplugged from a running KVM guest if a vfio-ap de= vice +has been attached to the virtual machine's ap-bus via the QEMU command line +or a prior hot plug action. + +To hot unplug a vfio-ap device, use the QEMU device_del command: + + (qemu) device_del vfio-ap,sysfsdev=3D"$path-to-mdev" + + Where $path-to-mdev is the same as the path specified when the vfio-ap + device was attached to the virtual machine's ap-bus. + +On a Linux guest, the AP devices will be removed from the /sys/bus/ap/devi= ces +directory on the guest when the AP bus subsequently performs its periodic = scan, +so there may be a short delay before the AP devices are no longer accessib= le by +the guest. + +The command will fail if the $path-to-mdev specified on the device_del com= mand +does not match the value specified when the vfio-ap device was attached to +the virtual machine's ap-bus. + Example: Configure AP Matrixes for Three Linux Guests: =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D Let's now provide an example to illustrate how KVM guests may be given @@ -819,7 +866,11 @@ Limitations assigned lest the host be given access to the private data of the AP que= ue device, such as a private key configured specifically for the guest. =20 -* Dynamically modifying the AP matrix for a running guest (which would amo= unt to - hot(un)plug of AP devices for the guest) is currently not supported +* Dynamically assigning AP resources to or unassigning AP resources from a + mediated matrix device - see 'Configuring an AP matrix for a linux guest' + section above - while a running guest is using it is currently not suppo= rted. =20 -* Live guest migration is not supported for guests using AP devices. +* Live guest migration is not supported for guests using AP devices. If a = guest + is using AP devices, the vfio-ap device configured for the guest must be + unplugged before migrating the guest (see 'Hot unplug a vfio-ap device f= rom a + running guest' section above. --=20 2.17.2