The documented connection sequence in xen/include/public/io/9pfs.h has
a bug: the frontend needs to wait for the backend to have published its
features before being able to allocate its rings and event-channels.

While correcting that, make it clear that there might be multiple
rings and event-channels by adding "(s)".

Signed-off-by: Juergen Gross <jgross@suse.com>
---
V4:
- patch split off (Julien Grall)
---
 xen/include/public/io/9pfs.h | 32 ++++++++++++++++++++++----------
 1 file changed, 22 insertions(+), 10 deletions(-)

diff --git a/xen/include/public/io/9pfs.h b/xen/include/public/io/9pfs.h
index 617ad9afd7..a0ce82d0a8 100644
--- a/xen/include/public/io/9pfs.h
+++ b/xen/include/public/io/9pfs.h
@@ -114,14 +114,26 @@
  *
  *    *Front*                               *Back*
  *    XenbusStateInitialising               XenbusStateInitialising
- *    - Query virtual device                - Query backend device
- *      properties.                           identification data.
- *    - Setup OS device instance.           - Publish backend features
- *    - Allocate and initialize the           and transport parameters
- *      request ring.                                      |
- *    - Publish transport parameters                       |
- *      that will be in effect during                      V
- *      this connection.                            XenbusStateInitWait
+ *                                          - Query backend device
+ *                                            identification data.
+ *                                          - Publish backend features
+ *                                            and transport parameters.
+ *                                                         |
+ *                                                         |
+ *                                                         V
+ *                                                  XenbusStateInitWait
+ *
+ *    - Query virtual device
+ *      properties.
+ *    - Query backend features and
+ *      transport parameters.
+ *    - Setup OS device instance.
+ *    - Allocate and initialize the
+ *      request ring(s) and
+ *      event-channel(s).
+ *    - Publish transport parameters
+ *      that will be in effect during
+ *      this connection.
  *                 |
  *                 |
  *                 V
@@ -129,8 +141,8 @@
  *
  *                                          - Query frontend transport
  *                                            parameters.
- *                                          - Connect to the request ring and
- *                                            event channel.
+ *                                          - Connect to the request ring(s)
+ *                                            and event channel(s).
  *                                                         |
  *                                                         |
  *                                                         V
-- 
2.35.3

On Thu, 9 Feb 2023, Juergen Gross wrote:
> The documented connection sequence in xen/include/public/io/9pfs.h has
> a bug: the frontend needs to wait for the backend to have published its
> features before being able to allocate its rings and event-channels.
> 
> While correcting that, make it clear that there might be multiple
> rings and event-channels by adding "(s)".
> 
> Signed-off-by: Juergen Gross <jgross@suse.com>

Reviewed-by: Stefano Stabellini <sstabellini@kernel.org>


> ---
> V4:
> - patch split off (Julien Grall)
> ---
>  xen/include/public/io/9pfs.h | 32 ++++++++++++++++++++++----------
>  1 file changed, 22 insertions(+), 10 deletions(-)
> 
> diff --git a/xen/include/public/io/9pfs.h b/xen/include/public/io/9pfs.h
> index 617ad9afd7..a0ce82d0a8 100644
> --- a/xen/include/public/io/9pfs.h
> +++ b/xen/include/public/io/9pfs.h
> @@ -114,14 +114,26 @@
>   *
>   *    *Front*                               *Back*
>   *    XenbusStateInitialising               XenbusStateInitialising
> - *    - Query virtual device                - Query backend device
> - *      properties.                           identification data.
> - *    - Setup OS device instance.           - Publish backend features
> - *    - Allocate and initialize the           and transport parameters
> - *      request ring.                                      |
> - *    - Publish transport parameters                       |
> - *      that will be in effect during                      V
> - *      this connection.                            XenbusStateInitWait
> + *                                          - Query backend device
> + *                                            identification data.
> + *                                          - Publish backend features
> + *                                            and transport parameters.
> + *                                                         |
> + *                                                         |
> + *                                                         V
> + *                                                  XenbusStateInitWait
> + *
> + *    - Query virtual device
> + *      properties.
> + *    - Query backend features and
> + *      transport parameters.
> + *    - Setup OS device instance.
> + *    - Allocate and initialize the
> + *      request ring(s) and
> + *      event-channel(s).
> + *    - Publish transport parameters
> + *      that will be in effect during
> + *      this connection.
>   *                 |
>   *                 |
>   *                 V
> @@ -129,8 +141,8 @@
>   *
>   *                                          - Query frontend transport
>   *                                            parameters.
> - *                                          - Connect to the request ring and
> - *                                            event channel.
> + *                                          - Connect to the request ring(s)
> + *                                            and event channel(s).
>   *                                                         |
>   *                                                         |
>   *                                                         V
> -- 
> 2.35.3
>