RE: [PATCH] doc: update async enqueue API usage

["Hu, Jiayu" <jiayu.hu@intel.com>]

Hi Xuan,

> -----Original Message-----
> From: Ding, Xuan <xuan.ding@intel.com>
> Sent: Friday, June 17, 2022 5:34 PM
> To: maxime.coquelin@redhat.com; Xia, Chenbo <chenbo.xia@intel.com>
> Cc: dev@dpdk.org; Hu, Jiayu <jiayu.hu@intel.com>; Ding, Xuan
> <xuan.ding@intel.com>
> Subject: [PATCH] doc: update async enqueue API usage
> 
> From: Xuan Ding <xuan.ding@intel.com>
> 
> This patch updates the correct usage for async enqueue APIs.
> The rte_vhost_poll_enqueue_completed() needs to be called in time to avoid
> packet loss due to full dma ring.
> 
> Signed-off-by: Xuan Ding <xuan.ding@intel.com>
> ---
>  doc/guides/prog_guide/vhost_lib.rst | 9 +++++++++
>  1 file changed, 9 insertions(+)
> 
> diff --git a/doc/guides/prog_guide/vhost_lib.rst
> b/doc/guides/prog_guide/vhost_lib.rst
> index cd3f6caa9a..9cdd7da154 100644
> --- a/doc/guides/prog_guide/vhost_lib.rst
> +++ b/doc/guides/prog_guide/vhost_lib.rst
> @@ -488,3 +488,12 @@ For PA mode, page by page mapping may exceed
> IOMMU's max capability,  better to use 1G guest hugepage.
> 
>  For UIO driver, any VFIO related error message can be ignored.
> +
> +Async enqueue API usage
> +-----------------------

I think it's better to make it as a sub-section of "Vhost asynchronous data path".

> +
> +In async enqueue path, rte_vhost_poll_enqueue_completed() needs to be
> +called in time. Otherwise, calling rte_vhost_submit_enqueue_burst() all
> +the time will cause the DMA ring to be full, which will result in
> +packet loss eventually.

There are two main reasons of calling rte_vhost_poll_enqueue_completed() timely, IMO:
1. notify the guest of DMA copy completed packets;
2. in case of DMA ring size is smaller than vring size, it can avoid packet drop caused by
DMA ring full.

Thanks,
Jiayu


> +
> --
> 2.17.1