diff mbox series

[v3,4/4] doc: update async vhost register/unregister

Message ID 1618909066-114980-5-git-send-email-jiayu.hu@intel.com (mailing list archive)
State Accepted, archived
Delegated to: Maxime Coquelin
Headers
Series Refactor async vhost control path |

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK
ci/intel-Testing success Testing PASS
ci/travis-robot success travis build: passed
ci/github-robot success github build: passed
ci/iol-testing warning Testing issues
ci/iol-abi-testing success Testing PASS

Commit Message

Hu, Jiayu April 20, 2021, 8:57 a.m. UTC 
  This patch is to update programmer guide for register/unregister
copy devices in vhost.

Signed-off-by: Jiayu Hu <jiayu.hu@intel.com>
---
 doc/guides/prog_guide/vhost_lib.rst | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

Comments

Maxime Coquelin April 20, 2021, 9:31 a.m. UTC | #1 
On 4/20/21 10:57 AM, Jiayu Hu wrote:
> This patch is to update programmer guide for register/unregister
> copy devices in vhost.
> 
> Signed-off-by: Jiayu Hu <jiayu.hu@intel.com>
> ---
>  doc/guides/prog_guide/vhost_lib.rst | 14 +++++++++++---
>  1 file changed, 11 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst
> index dc29229..7afa351 100644
> --- a/doc/guides/prog_guide/vhost_lib.rst
> +++ b/doc/guides/prog_guide/vhost_lib.rst
> @@ -208,9 +208,9 @@ The following is an overview of some key Vhost API functions:
>  
>  * ``rte_vhost_async_channel_register(vid, queue_id, features, ops)``
>  
> -  Register a vhost queue with async copy device channel.
> -  Following device ``features`` must be specified together with the
> -  registration:
> +  Register a vhost queue with async copy device channel after vring
> +  is enabled. Following device ``features`` must be specified together
> +  with the registration:
>  
>    * ``async_inorder``
>  
> @@ -244,6 +244,14 @@ The following is an overview of some key Vhost API functions:
>  * ``rte_vhost_async_channel_unregister(vid, queue_id)``
>  
>    Unregister the async copy device channel from a vhost queue.
> +  Unregistration will fail, if the vhost queue has in-flight
> +  packets that are not completed.
> +
> +  Unregister async copy devices in vring_state_changed() may
> +  fail, as this API tries to acquire the spinlock of vhost
> +  queue. The recommended way is to unregister async copy
> +  devices for all vhost queues in destroy_device(), when a
> +  virtio device is paused or shut down.
>  
>  * ``rte_vhost_submit_enqueue_burst(vid, queue_id, pkts, count, comp_pkts, comp_count)``
>  
> 

Reviewed-by: Maxime Coquelin <maxime.coquelin@redhat.com>

Thanks,
Maxime
diff mbox series

Patch

diff --git a/doc/guides/prog_guide/vhost_lib.rst b/doc/guides/prog_guide/vhost_lib.rst
index dc29229..7afa351 100644
--- a/doc/guides/prog_guide/vhost_lib.rst
+++ b/doc/guides/prog_guide/vhost_lib.rst
@@ -208,9 +208,9 @@  The following is an overview of some key Vhost API functions:
 
 * ``rte_vhost_async_channel_register(vid, queue_id, features, ops)``
 
-  Register a vhost queue with async copy device channel.
-  Following device ``features`` must be specified together with the
-  registration:
+  Register a vhost queue with async copy device channel after vring
+  is enabled. Following device ``features`` must be specified together
+  with the registration:
 
   * ``async_inorder``
 
@@ -244,6 +244,14 @@  The following is an overview of some key Vhost API functions:
 * ``rte_vhost_async_channel_unregister(vid, queue_id)``
 
   Unregister the async copy device channel from a vhost queue.
+  Unregistration will fail, if the vhost queue has in-flight
+  packets that are not completed.
+
+  Unregister async copy devices in vring_state_changed() may
+  fail, as this API tries to acquire the spinlock of vhost
+  queue. The recommended way is to unregister async copy
+  devices for all vhost queues in destroy_device(), when a
+  virtio device is paused or shut down.
 
 * ``rte_vhost_submit_enqueue_burst(vid, queue_id, pkts, count, comp_pkts, comp_count)``