From nobody Mon Feb 9 23:15:17 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=fail(p=none dis=none) header.from=intel.com ARC-Seal: i=1; a=rsa-sha256; t=1559263948; cv=none; d=zoho.com; s=zohoarc; b=X3pSnACo+sb3ITVfDwWuFZzb7trO2bgDE/oN1IiypfKC9qdIPwgR3YtnfnfngxXTvETmMJXjEuvBfEzxdbt291cCqkLm3Er1vvm/vAymZXPHuc/lK7s7xmgIht3lffxGLsXxwEv3LtI5NoTkzsWKwU8gjiEG54MfFBrOk0b94nY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1559263948; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=MPGcoPfLGI5loaowCjMv0wR3Uz8bqBhjSBOqzzGUyF0=; b=Tzd9jkNoHfAFd0tFUUwdASKtvlbRzDfBmy76FEHz15TJ4hNBtafanRm5zA6ME0jfL5DegMrfXhRAhNJdeGfh+3uEgxhUg9ikVCx3qlu1nOr9YhkNQDtI1YIwiNNlq33IpGOf5z9moP8uY89cyD+vF/4yAYWAjDvp4yVyIyg7/Og= ARC-Authentication-Results: i=1; mx.zoho.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=fail header.from= (p=none dis=none) header.from= Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 1559263948339449.56364196687616; Thu, 30 May 2019 17:52:28 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.phx2.redhat.com [10.5.11.14]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 6516083F44; Fri, 31 May 2019 00:52:26 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 0847C88B14; Fri, 31 May 2019 00:52:26 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id 828E254D3D; Fri, 31 May 2019 00:52:25 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx08.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id x4V0qNPP023720 for ; Thu, 30 May 2019 20:52:23 -0400 Received: by smtp.corp.redhat.com (Postfix) id 55E5D9085; Fri, 31 May 2019 00:52:23 +0000 (UTC) Received: from mx1.redhat.com (ext-mx17.extmail.prod.ext.phx2.redhat.com [10.5.110.46]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 570BD19493; Fri, 31 May 2019 00:52:14 +0000 (UTC) Received: from mga18.intel.com (mga18.intel.com [134.134.136.126]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 7239F3082E6A; Fri, 31 May 2019 00:52:05 +0000 (UTC) Received: from fmsmga007.fm.intel.com ([10.253.24.52]) by orsmga106.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 30 May 2019 17:52:04 -0700 Received: from joy-optiplex-7040.sh.intel.com ([10.239.13.9]) by fmsmga007.fm.intel.com with ESMTP; 30 May 2019 17:51:59 -0700 X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False X-ExtLoop1: 1 From: Yan Zhao To: intel-gvt-dev@lists.freedesktop.org Date: Thu, 30 May 2019 20:45:59 -0400 Message-Id: <20190531004559.24581-1-yan.y.zhao@intel.com> In-Reply-To: <20190531004438.24528-1-yan.y.zhao@intel.com> References: <20190531004438.24528-1-yan.y.zhao@intel.com> MIME-Version: 1.0 X-Greylist: Sender passed SPF test, Sender IP whitelisted by DNSRBL, ACL 216 matched, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.46]); Fri, 31 May 2019 00:52:07 +0000 (UTC) X-Greylist: inspected by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.46]); Fri, 31 May 2019 00:52:07 +0000 (UTC) for IP:'134.134.136.126' DOMAIN:'mga18.intel.com' HELO:'mga18.intel.com' FROM:'yan.y.zhao@intel.com' RCPT:'' X-RedHat-Spam-Score: -2.3 (RCVD_IN_DNSWL_MED, SPF_HELO_NONE, SPF_PASS) 134.134.136.126 mga18.intel.com 134.134.136.126 mga18.intel.com X-Scanned-By: MIMEDefang 2.84 on 10.5.110.46 X-Scanned-By: MIMEDefang 2.84 on 10.5.11.23 X-loop: libvir-list@redhat.com Cc: cjia@nvidia.com, kvm@vger.kernel.org, aik@ozlabs.ru, Zhengxiao.zx@alibaba-inc.com, shuangtai.tst@alibaba-inc.com, qemu-devel@nongnu.org, kwankhede@nvidia.com, eauger@redhat.com, yi.l.liu@intel.com, eskultet@redhat.com, ziye.yang@intel.com, mlevitsk@redhat.com, pasic@linux.ibm.com, libvir-list@redhat.com, felipe@nutanix.com, Ken.Xue@amd.com, kevin.tian@intel.com, Yan Zhao , dgilbert@redhat.com, zhenyuw@linux.intel.com, dinechin@redhat.com, changpeng.liu@intel.com, cohuck@redhat.com, linux-kernel@vger.kernel.org, zhi.a.wang@intel.com, jonathan.davies@nutanix.com, shaopeng.he@intel.com Subject: [libvirt] [PATCH v4 1/2] vfio/mdev: add migration_version attribute for mdev device X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.14 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.27]); Fri, 31 May 2019 00:52:26 +0000 (UTC) migration_version attribute is used to check migration compatibility between two mdev devices of the same mdev type. The key is that it's rw and its data is opaque to userspace. Userspace reads migration_version of mdev device at source side and writes the value to migration_version attribute of mdev device at target side. It judges migration compatibility according to whether the read and write operations succeed or fail. As this attribute is under mdev_type node, userspace is able to know whether two mdev devices are compatible before a mdev device is created. userspace needs to check whether the two mdev devices are of the same mdev type before checking the migration_version attribute. It also needs to check device creation parameters if aggregation is supported in future. __ userspace /\ \ / \write / read \ ________/__________ ___\|/_____________ | migration_version | | migration_version |-->check migration --------------------- --------------------- compatibility mdev device A mdev device B Cc: Alex Williamson Cc: Erik Skultety Cc: "Dr. David Alan Gilbert" Cc: Cornelia Huck Cc: "Tian, Kevin" Cc: Zhenyu Wang Cc: "Wang, Zhi A" Cc: Neo Jia Cc: Kirti Wankhede Cc: Daniel P. Berrang=C3=A9 Cc: Christophe de Dinechin Signed-off-by: Yan Zhao Reviewed-by: Cornelia Huck --- v4: fixed a typo. (Cornelia Huck) v3: 1. renamed version to migration_version (Christophe de Dinechin, Cornelia Huck, Alex Williamson) 2. let errno to be freely defined by vendor driver (Alex Williamson, Erik Skultety, Cornelia Huck, Dr. David Alan Gilbert) 3. let checking mdev_type be prerequisite of migration compatibility check. (Alex Williamson) 4. reworded example usage section. (most of this section came from Alex Williamson) 5. reworded attribute intention section (Cornelia Huck) v2: 1. added detailed intent and usage 2. made definition of version string completely private to vendor driver (Alex Williamson) 3. abandoned changes to sample mdev drivers (Alex Williamson) 4. mandatory --> optional (Cornelia Huck) 5. added description for errno (Cornelia Huck) --- Documentation/vfio-mediated-device.txt | 113 +++++++++++++++++++++++++ 1 file changed, 113 insertions(+) diff --git a/Documentation/vfio-mediated-device.txt b/Documentation/vfio-me= diated-device.txt index c3f69bcaf96e..1241e1cee64e 100644 --- a/Documentation/vfio-mediated-device.txt +++ b/Documentation/vfio-mediated-device.txt @@ -202,6 +202,7 @@ Directories and files under the sysfs for Each Physical= Device | | |--- available_instances | | |--- device_api | | |--- description + | | |--- migration_version | | |--- [devices] | |--- [] | | |--- create @@ -209,6 +210,7 @@ Directories and files under the sysfs for Each Physical= Device | | |--- available_instances | | |--- device_api | | |--- description + | | |--- migration_version | | |--- [devices] | |--- [] | |--- create @@ -216,6 +218,7 @@ Directories and files under the sysfs for Each Physical= Device | |--- available_instances | |--- device_api | |--- description + | |--- migration_version | |--- [devices] =20 * [mdev_supported_types] @@ -246,6 +249,116 @@ Directories and files under the sysfs for Each Physic= al Device This attribute should show the number of devices of type that = can be created. =20 +* migration_version + + This attribute is rw, and is optional. + It is used to check migration compatibility between two mdev devices of = the + same mdev type. Absence of this attribute means the device of type + does not support migration. + This attribute provides a way to check migration compatibility between t= wo + mdev devices from userspace even before device creation. The intended us= age is + for userspace to read the migration_version attribute from one mdev devi= ce and + then writing that value to the migration_version attribute of the other = mdev + device. The second mdev device indicates compatibility via the return co= de of + the write operation. This makes compatibility between mdev devices compl= etely + vendor-defined and opaque to userspace. Userspace should do nothing more + than verify the mdev types match and then use the migration_version attr= ibute + to confirm source to target compatibility. + + Reading/Writing Attribute Data: + read(2) will fail if device of type does not support migration= and + otherwise succeed and return migration_version string of the dev= ice of + type . + + This migration_version string is vendor defined and opaque to the + userspace. Vendor is free to include whatever they feel is relev= ant. + e.g. -. + + Restrictions on this migration_version string: + 1. It should only contain ascii characters + 2. MAX Length is PATH_MAX (4096) + + write(2) expects migration_version string of source mdev device, and will + succeed if it is determined to be compatible and otherwise fail = with + vendor specific errno. + + Errno: + -An errno on read(2) indicates the device of type does not sup= port + migration; + -An errno on write(2) indicates the devices are incompatible or the targ= et + doesn't support migration. + Vendor driver is free to define specific errno and is suggested to + print detailed error in syslog for diagnose purpose. + + Userspace should treat ANY of below conditions as two mdev devices not + compatible: + (0) The mdev devices are not of the same type + (1) any one of the two mdev devices does not have a migration_version + attribute + (2) error when reading from migration_version attribute of one mdev devi= ce + (3) error when writing migration_version string of one mdev device to + migration_version attribute of the other mdev device + + Userspace should regard two mdev devices compatible when ALL of below + conditions are met: + (0) The mdev devices are of the same type + (1) success when reading from migration_version attribute of one mdev de= vice. + (2) success when writing migration_version string of one mdev device to + migration_version attribute of the other mdev device. + + Example Usage: + (1) Compare mdev types: + + The mdev type of an instantiated device can be read from the mdev_type l= ink + within the device instance in sysfs, for example: + + # basename $(readlink -f /sys/bus/mdev/devices/$MDEV_UUID/mdev_type/) + + The mdev types available on a given host system can also be found through + /sys/class/mdev_bus, for example: + + # ls /sys/class/mdev_bus/*/mdev_supported_types/ + + Migration is only possible between devices of the same mdev type. + + (2) Retrieve the mdev source migration_version: + + The migration_version information can either be read from the mdev_type = link + on an instantiated device: + + # cat /sys/bus/mdev/devices/$UUID1/mdev_type/migration_version + + Or it can be read from the mdev type definition, for example: + + # cat /sys/class/mdev_bus/*/mdev_supported_types/$MDEV_TYPE/migration_ve= rsion + + If reading the source migration_version generates an error, migration is= not + possible. + NB, there might be several parent devices for a given mdev type on a host + system, each may support or expose different migration_versions. + Matching the specific mdev type to a parent may become important in such + configurations. + + (3) Test source migration_version at target: + + Given a migration_version as outlined above, its compatibility to an + instantiated device of the same mdev type can be tested as: + # echo $VERSION > /sys/bus/mdev/devices/$UUID2/mdev_type/migration_versi= on + + If this write fails, the source and target migration versions are not + compatible or the target does not support migration. + + Compatibility can also be tested prior to target device creation using t= he + mdev type definition for a parent device with a previously found matchin= g mdev + type, for example: + + # echo $VERSION > \ + /sys/class/mdev_bus/$PARENT/mdev_supported_types/$MDEV_TYPE/migration_ve= rsion + + Again, an error writing the migration_version indicates that an instance= of + this mdev type would not support a migration from the provided migration + version. + * [device] =20 This directory contains links to the devices of type that have= been --=20 2.17.1 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list