Re: [PATCH v3 7/7] Documentation: Add reconnect process for VDUSE

[Jason Wang]

On Tue, Dec 5, 2023 at 4:35 PM Cindy Lu <lulu@xxxxxxxxxx> 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@xxxxxxxxxx>
> ---
>  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
>