On Tue, Dec 5, 2023 at 4:35 PM Cindy Lu <lulu@redhat.com> wrote:
>
> Add a document explaining the reconnect process, including what the
> Userspace App needs to do and how it works with the kernel.
>
> Signed-off-by: Cindy Lu <lulu@redhat.com>
> ---
> Documentation/userspace-api/vduse.rst | 30 +++++++++++++++++++++++++++
> 1 file changed, 30 insertions(+)
>
> diff --git a/Documentation/userspace-api/vduse.rst b/Documentation/userspace-api/vduse.rst
> index bdb880e01132..ec66e573f6da 100644
> --- a/Documentation/userspace-api/vduse.rst
> +++ b/Documentation/userspace-api/vduse.rst
> @@ -231,3 +231,33 @@ able to start the dataplane processing as follows:
> after the used ring is filled.
>
> For more details on the uAPI, please see include/uapi/linux/vduse.h.
> +
> +HOW VDUSE devices reconnectoin works
> +----------------
> +0. Userspace APP checks if the device /dev/vduse/vduse_name exists.
> + If it does not exist, need to create the instance.
> + If it does exist, it means this is a reconnect and the program proceeds to step 3.
> +
> +1. Create a new VDUSE instance with ioctl(VDUSE_CREATE_DEV) on
> + /dev/vduse/control.
> +
> +2. When the ioctl(VDUSE_CREATE_DEV) function is called, the kernel allocates memory
> + to synchronize the reconnect information.
This is the implementation details and I guess this doc only focuses
on the uAPI. So there's no need to describe it here.
> +
> +3. Userspace App need to mmap the pages to userspace
> +
> + When connecting for the first time, the userspace app must save the reconnect
> + information (struct vhost_reconnect_data) in mapped pages
This looks vague. We need to describe what kind of information that
needs to be saved and when to save.
Thanks
> +
> + If this is reconnect,If the purpose is to reconnect, the userspace application
> + must verify if the saved information is suitable for reconnection. Additionally,
> + the userspace application is required to set the "reconnected" bit in the
> + "struct vhost_reconnect_data" to "VDUSE_RECONNECT". The kernel will use this bit
> + to identify if the userspace application is reconnect.
> +
> +4. Start the userspace App.
> + userspace APP will call ioctl VDUSE_VQ_GET_INFO to sync the vq information.
> + Additionally, the APP must save the vq reconnect information (struct vdpa_vq_state)
> + in mapped pages while running.
> +
> +5. When the Userspace App exits, it is necessary to unmap all the reconnect pages.
> --
> 2.34.3
>