From nobody Mon Feb 9 13:57:21 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.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 (zohomail.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=intel.com ARC-Seal: i=1; a=rsa-sha256; t=1586757960; cv=none; d=zohomail.com; s=zohoarc; b=L0Z+8hCNNxHajd/mFzMVvo/jcaijaOOdDplS6mPxpwe2TiFbGM8sXdTpyEBsm6ncctk6NO72QNGGA7p7frStvXo8/GhOmBpGu75eK3I1GMN42AjsK3PMd4IvRspyxrtFscfDmvJ6m3PN8hwCDRfkZCPk3Uec3BGqCdhmAKpbNGo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1586757960; 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; bh=M+CntJuZ/zKA1GBpMJILa1a8BsYoQvx3fVg/abRY0jA=; b=i33iez6O5NpBhOmehEbdYEmyApmC7BEANrO8T3FsP+0eV/uPSGNAKzHgACwOayLM2DTNue5LN5sgrLeCfTwpO58O1hSusedHf7BhfcaTxOPGWQmZTjvl48jVlp7v64KStc2DFbyie/9JQJaH6I5h8k3RDvRLzStgSHl0eUpsnuE= ARC-Authentication-Results: i=1; mx.zohomail.com; spf=pass (zohomail.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 header.from= (p=none dis=none) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1586757960022165.85856261466597; Sun, 12 Apr 2020 23:06:00 -0700 (PDT) Received: from localhost ([::1]:40645 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jNsEI-00011T-Sl for importer@patchew.org; Mon, 13 Apr 2020 02:05:58 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:57848) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1jNsDS-0008SX-Pq for qemu-devel@nongnu.org; Mon, 13 Apr 2020 02:05:08 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1jNsDR-0001OP-C4 for qemu-devel@nongnu.org; Mon, 13 Apr 2020 02:05:06 -0400 Received: from mga04.intel.com ([192.55.52.120]:41109) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1jNsDR-0001Nv-4M for qemu-devel@nongnu.org; Mon, 13 Apr 2020 02:05:05 -0400 Received: from fmsmga008.fm.intel.com ([10.253.24.58]) by fmsmga104.fm.intel.com with ESMTP/TLS/ECDHE-RSA-AES256-GCM-SHA384; 12 Apr 2020 23:04:49 -0700 Received: from joy-optiplex-7040.sh.intel.com ([10.239.13.16]) by fmsmga008.fm.intel.com with ESMTP; 12 Apr 2020 23:04:43 -0700 IronPort-SDR: fJXSLePCJePo3pXxxxRGdMDsZEmHkHYA5HE1a+8hXpdxBhtCzmMci+qGi5S48SxvJdx2jQqF9+ 0P7r0aDgdtHA== X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False IronPort-SDR: MbFwKnGaaMwEyGnfsS5ROLnyX35cXTl0aIVx4vYCD8SaZ6Q+Nm5+ioJ8P7BmoI3lVcpfUdSGfE s40BgPxp5wWw== X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.72,377,1580803200"; d="scan'208";a="245065840" From: Yan Zhao To: intel-gvt-dev@lists.freedesktop.org Subject: [PATCH v5 3/4] vfio/mdev: add migration_version attribute for mdev (under mdev device node) Date: Mon, 13 Apr 2020 01:55:04 -0400 Message-Id: <20200413055504.27311-1-yan.y.zhao@intel.com> X-Mailer: git-send-email 2.17.1 In-Reply-To: <20200413055201.27053-1-yan.y.zhao@intel.com> References: <20200413055201.27053-1-yan.y.zhao@intel.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: FreeBSD 9.x [fuzzy] X-Received-From: 192.55.52.120 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: cjia@nvidia.com, kvm@vger.kernel.org, linux-doc@vger.kernel.org, libvir-list@redhat.com, Zhengxiao.zx@alibaba-inc.com, shuangtai.tst@alibaba-inc.com, qemu-devel@nongnu.org, kwankhede@nvidia.com, eauger@redhat.com, corbet@lwn.net, yi.l.liu@intel.com, eskultet@redhat.com, ziye.yang@intel.com, mlevitsk@redhat.com, pasic@linux.ibm.com, aik@ozlabs.ru, felipe@nutanix.com, Ken.Xue@amd.com, kevin.tian@intel.com, Yan Zhao , xin.zeng@intel.com, dgilbert@redhat.com, zhenyuw@linux.intel.com, dinechin@redhat.com, alex.williamson@redhat.com, changpeng.liu@intel.com, berrange@redhat.com, cohuck@redhat.com, linux-kernel@vger.kernel.org, zhi.a.wang@intel.com, jonathan.davies@nutanix.com, shaopeng.he@intel.com Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" 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. Currently, it is able to read/write migration_version attribute under two places: (1) under mdev_type node userspace is able to know whether two mdev devices are compatible before a mdev device is created. userspace also 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. (2) under mdev device node userspace is able to know whether two mdev devices are compatible after they are all created. But it does not need to check mdev type and device creation parameter for aggregation as device vendor driver would have incorporated those information into the migration_version attribute. __ userspace /\ \ / \write / read \ ________/__________ ___\|/_____________ | migration_version | | migration_version |-->check migration --------------------- --------------------- compatibility mdev device A mdev device B This patch is for mdev documentation about the second place (under mdev device node) 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 --- .../driver-api/vfio-mediated-device.rst | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/Documentation/driver-api/vfio-mediated-device.rst b/Documentat= ion/driver-api/vfio-mediated-device.rst index 2d1f3c0f3c8f..efbadfd51b7e 100644 --- a/Documentation/driver-api/vfio-mediated-device.rst +++ b/Documentation/driver-api/vfio-mediated-device.rst @@ -383,6 +383,7 @@ Directories and Files Under the sysfs for Each mdev Dev= ice |--- remove |--- mdev_type {link to its type} |--- vendor-specific-attributes [optional] + |--- migration_verion [optional] =20 * remove (write only) =20 @@ -394,6 +395,75 @@ Example:: =20 # echo 1 > /sys/bus/mdev/devices/$mdev_UUID/remove =20 +* migration_version (rw, optional) + It is used to check migration compatibility between two mdev devices. + Absence of this attribute means the mdev device does not support migrati= on. + + This attribute provides a way to check migration compatibility between t= wo + mdev devices from userspace after device created. The intended usage 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 use the migration_version attribute to confirm source to target + compatibility. + + Reading/Writing Attribute Data: + read(2) will fail if a mdev device does not support migration and otherw= ise + succeed and return migration_version string of the mdev device. + + This migration_version string is vendor defined and opaque to the + userspace. Vendor is free to include whatever they feel is relevan= t. + 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 w= ith + vendor specific errno. + + Errno: + -An errno on read(2) indicates the mdev devicedoes not support migration; + -An errno on write(2) indicates the mdev devices are incompatible or the + target 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: + (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: + (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) Retrieve the mdev source migration_version: + + # cat /sys/bus/mdev/devices/$mdev_UUID1/migration_version + + If reading the source migration_version generates an error, migration is= not + possible. + + (2) 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/$mdev_UUID2/migration_version + + If this write fails, the source and target migration versions are not + compatible or the target does not support migration. + + Mediated device Hot plug ------------------------ =20 --=20 2.17.1