From: Jonathan Corbet <corbet@lwn.net>
To: Jason Gunthorpe <jgg@nvidia.com>,
Alex Williamson <alex.williamson@redhat.com>,
linux-doc@vger.kernel.org
Cc: Cornelia Huck <cohuck@redhat.com>,
kvm@vger.kernel.org, Kirti Wankhede <kwankhede@nvidia.com>,
Max Gurtovoy <mgurtovoy@nvidia.com>,
Shameer Kolothum <shameerali.kolothum.thodi@huawei.com>,
Yishai Hadas <yishaih@nvidia.com>
Subject: Re: [PATCH RFC] vfio: Documentation for the migration region
Date: Mon, 22 Nov 2021 13:31:14 -0700 [thread overview]
Message-ID: <875yskvsod.fsf@meer.lwn.net> (raw)
In-Reply-To: <0-v1-0ec87874bede+123-vfio_mig_doc_jgg@nvidia.com>
Jason Gunthorpe <jgg@nvidia.com> writes:
> Provide some more complete documentation for the migration region's
> behavior, specifically focusing on the device_state bits and the whole
> system view from a VMM.
>
> Signed-off-by: Jason Gunthorpe <jgg@nvidia.com>
> ---
> Documentation/driver-api/vfio.rst | 208 +++++++++++++++++++++++++++++-
> 1 file changed, 207 insertions(+), 1 deletion(-)
>
> Alex/Cornelia, here is the first draft of the requested documentation I promised
>
> We think it includes all the feedback from hns, Intel and NVIDIA on this mechanism.
>
> Our thinking is that NDMA would be implemented like this:
>
> +#define VFIO_DEVICE_STATE_NDMA (1 << 3)
>
> And a .add_capability ops will be used to signal to userspace driver support:
>
> +#define VFIO_REGION_INFO_CAP_MIGRATION_NDMA 6
>
> I've described DIRTY TRACKING as a seperate concept here. With the current
> uAPI this would be controlled by VFIO_IOMMU_DIRTY_PAGES_FLAG_START, with our
> change in direction this would be per-tracker control, but no semantic change.
>
> Upon some agreement we'll include this patch in the next iteration of the mlx5 driver
> along with the NDMA bits.
>
> Thanks,
> Jason
>
> diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst
> index c663b6f978255b..b28c6fb89ee92f 100644
> --- a/Documentation/driver-api/vfio.rst
> +++ b/Documentation/driver-api/vfio.rst
> @@ -242,7 +242,213 @@ group and can access them as follows::
> VFIO User API
> -------------------------------------------------------------------------------
>
> -Please see include/linux/vfio.h for complete API documentation.
> +Please see include/uapi/linux/vfio.h for complete API documentation.
> +
> +-------------------------------------------------------------------------------
> +
> +VFIO migration driver API
> +-------------------------------------------------------------------------------
> +
> +VFIO drivers that support migration implement a migration control register
> +called device_state in the struct vfio_device_migration_info which is in its
> +VFIO_REGION_TYPE_MIGRATION region.
> +
> +The device_state triggers device action both when bits are set/cleared and
> +continuous behavior for each bit. For VMMs they can also control if the VCPUs in
> +a VM are executing (VCPU RUNNING) and if the IOMMU is logging DMAs (DIRTY
> +TRACKING). These two controls are not part of the device_state register, KVM
> +will be used to control the VCPU and VFIO_IOMMU_DIRTY_PAGES_FLAG_START on the
> +container controls dirty tracking.
> +
> +Along with the device_state the migration driver provides a data window which
> +allows streaming migration data into or out of the device.
> +
> +A lot of flexibility is provided to userspace in how it operates these bits. The
> +reference flow for saving device state in a live migration, with all features:
> +
> + RUNNING, VCPU_RUNNING
> + Normal operating state
> + RUNNING, DIRTY TRACKING, VCPU RUNNING
> + Log DMAs
> + Stream all memory
So I'd recommend actually building the docs and looking at the result;
this will not render the way you expect it to. I'd suggest using a
literal block for preformatted sections like this.
Thanks,
jon
next prev parent reply other threads:[~2021-11-22 20:31 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-11-22 19:53 [PATCH RFC] vfio: Documentation for the migration region Jason Gunthorpe
2021-11-22 20:31 ` Jonathan Corbet [this message]
2021-11-23 0:20 ` Jason Gunthorpe
2021-11-23 7:22 ` Akira Yokosawa
2021-11-23 14:21 ` Cornelia Huck
2021-11-23 16:53 ` Jason Gunthorpe
2021-11-24 16:55 ` Cornelia Huck
2021-11-24 18:40 ` Jason Gunthorpe
2021-11-25 12:27 ` Cornelia Huck
2021-11-25 16:14 ` Jason Gunthorpe
2021-11-26 12:56 ` Cornelia Huck
2021-11-26 13:06 ` Jason Gunthorpe
2021-11-26 15:01 ` Cornelia Huck
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=875yskvsod.fsf@meer.lwn.net \
--to=corbet@lwn.net \
--cc=alex.williamson@redhat.com \
--cc=cohuck@redhat.com \
--cc=jgg@nvidia.com \
--cc=kvm@vger.kernel.org \
--cc=kwankhede@nvidia.com \
--cc=linux-doc@vger.kernel.org \
--cc=mgurtovoy@nvidia.com \
--cc=shameerali.kolothum.thodi@huawei.com \
--cc=yishaih@nvidia.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).